{"openapi":"3.1.0","info":{"title":"Should I Bid API","version":"1.0.0","summary":"Google Ads keyword intent analysis: bidding decisions (bid / test / skip) and 0-100 scores from live Google results.","description":"The REST API of Should I Bid: the same engine, credit rules and guardrails as the app and the Claude connector (https://shouldibid.app/mcp).\n\nAuthentication: an API key `sib_live_…`, created in the app (Integrations), sent ONLY in the `Authorization: Bearer` header — never in the URL.\nAccess: included in every paid Should I Bid plan. An account without a paid plan gets `403 forbidden` with `details.reason = \"plan_required\"` and `details.upgrade_url`.\nLimits per account: 120 reads and 10 writes per minute; suggestions 5 per minute and 30 per day; 200 keywords per launch; one external analysis at a time; a daily credit cap (default 200 credits per 24 h).\nResponses are never cached and carry an `X-Request-Id` header.","termsOfService":"https://shouldibid.app/conditions-utilisation","contact":{"name":"Should I Bid","url":"https://shouldibid.app/developpeurs"}},"externalDocs":{"description":"Developer documentation","url":"https://shouldibid.app/developpeurs"},"servers":[{"url":"https://shouldibid.app/api/v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"Account","description":"Credits, plan, companies and products."},{"name":"Suggestions","description":"Vision keyword ideas (free)."},{"name":"Analyses","description":"Quotes, launches, progress and results."},{"name":"Meta","description":"This document."}],"paths":{"/account":{"get":{"operationId":"account","tags":["Account"],"summary":"Account overview","description":"Plan, available credits (same formula as the real reservation), today's cap for external launches, configured companies with their product ids, and the permissions of the key.\n\nRequired permission: `read`.","responses":{"200":{"description":"Account overview.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. `error.code` is stable: see the list in the Error schema and the developer docs.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error. `error.code` is stable: see the list in the Error schema and the developer docs.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analyses":{"get":{"operationId":"list_analyses","tags":["Analyses"],"summary":"List analyses","description":"Past and running keyword analyses of the account (newest first), with status, keyword count and average score.\n\nRequired permission: `read`.","parameters":[{"name":"status","in":"query","required":false,"description":"Only analyses with this status.","schema":{"description":"Only analyses with this status.","type":"string","enum":["pending","in_progress","completed","completed_with_errors","failed","cancelled"]}},{"name":"company_id","in":"query","required":false,"description":"Only analyses of this company (see get_account).","schema":{"description":"Only analyses of this company (see get_account).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"}},{"name":"search","in":"query","required":false,"description":"Text contained in the analysis name.","schema":{"description":"Text contained in the analysis name.","type":"string","maxLength":100}},{"name":"limit","in":"query","required":false,"description":"Page size (default 10, max 50).","schema":{"description":"Page size (default 10, max 50).","type":"integer","minimum":1,"maximum":50}},{"name":"offset","in":"query","required":false,"description":"Pagination offset (default 0).","schema":{"description":"Pagination offset (default 0).","type":"integer","minimum":0,"maximum":10000}}],"responses":{"200":{"description":"A page of analyses.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. `error.code` is stable: see the list in the Error schema and the developer docs.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error. `error.code` is stable: see the list in the Error schema and the developer docs.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"launch","tags":["Analyses"],"summary":"Launch an analysis (uses credits)","description":"Launch a keyword analysis with the app's engine. Spends credits: 1 per keyword, charged after analysis (Vision launches from a suggestion batch: only keywords scoring 50+ are charged). max_credits is required and caps the reservation. At most 200 keywords; one external analysis at a time per account (409 otherwise).\n\nRequired permission: `analyses:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company_id":{"description":"Company to analyze for (default: the only configured company; Vision: the suggestion batch company).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"keywords":{"description":"Keywords to analyze (max 200 per launch). With suggestion_batch_id: a subset of the batch ideas (default: all).","minItems":1,"maxItems":1000,"type":"array","items":{"type":"string"}},"suggestion_batch_id":{"description":"Vision mode: batch returned by suggest_keywords (valid 24 h, one launch).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"country":{"description":"Google market (default FR).","type":"string","enum":["FR","US","UK","DE","ES","IT","CA"]},"language":{"description":"Search language (default: the country language).","type":"string","enum":["fr","en","de","es","it"]},"device":{"description":"Device for the Google results (default desktop).","type":"string","enum":["desktop","mobile","tablet"]},"product_id":{"description":"Target one product of the company (see get_account).","type":"string","minLength":1,"maxLength":100},"name":{"description":"Analysis name (default: generated).","type":"string","minLength":1,"maxLength":120},"max_credits":{"type":"integer","minimum":1,"maximum":100000,"description":"Maximum credits the user explicitly agreed to reserve for this launch (use the estimate)."}},"required":["max_credits"]}}}},"responses":{"201":{"description":"The launched analysis.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. `error.code` is stable: see the list in the Error schema and the developer docs.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error. `error.code` is stable: see the list in the Error schema and the developer docs.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analyses/estimate":{"post":{"operationId":"estimate","tags":["Analyses"],"summary":"Estimate an analysis","description":"Quote an analysis WITHOUT launching anything: cleaned keyword list, credits to reserve, available balance, today's remaining cap and blockers.\n\nRequired permission: `read`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company_id":{"description":"Company to analyze for (default: the only configured company; Vision: the suggestion batch company).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"keywords":{"description":"Keywords to analyze (max 200 per launch). With suggestion_batch_id: a subset of the batch ideas (default: all).","minItems":1,"maxItems":1000,"type":"array","items":{"type":"string"}},"suggestion_batch_id":{"description":"Vision mode: batch returned by suggest_keywords (valid 24 h, one launch).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"country":{"description":"Google market (default FR).","type":"string","enum":["FR","US","UK","DE","ES","IT","CA"]},"language":{"description":"Search language (default: the country language).","type":"string","enum":["fr","en","de","es","it"]},"device":{"description":"Device for the Google results (default desktop).","type":"string","enum":["desktop","mobile","tablet"]},"product_id":{"description":"Target one product of the company (see get_account).","type":"string","minLength":1,"maxLength":100},"name":{"description":"Analysis name (default: generated).","type":"string","minLength":1,"maxLength":120}}}}}},"responses":{"200":{"description":"The quote.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. `error.code` is stable: see the list in the Error schema and the developer docs.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error. `error.code` is stable: see the list in the Error schema and the developer docs.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analyses/{analysis_id}":{"get":{"operationId":"get_analysis","tags":["Analyses"],"summary":"Analysis results","description":"Progress and results of one analysis: bid / test / skip counts, score bands, credits charged, and the keywords sorted by score (paginated).\n\nRequired permission: `read`.","parameters":[{"name":"analysis_id","in":"path","required":true,"description":"Analysis id (from list_analyses or a launch).","schema":{"type":"string","format":"uuid"}},{"name":"keywords_limit","in":"query","required":false,"description":"Keywords returned (default 25, max 200, 0 = summary only).","schema":{"description":"Keywords returned (default 25, max 200, 0 = summary only).","type":"integer","minimum":0,"maximum":200}},{"name":"keywords_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100000}},{"name":"sort","in":"query","required":false,"description":"Keyword order (default score_desc).","schema":{"description":"Keyword order (default score_desc).","type":"string","enum":["score_desc","score_asc","keyword"]}},{"name":"bid_decision","in":"query","required":false,"description":"Only keywords with this bidding decision.","schema":{"description":"Only keywords with this bidding decision.","type":"string","enum":["bid","test","skip"]}},{"name":"verdict","in":"query","required":false,"description":"Only keywords in this score band.","schema":{"description":"Only keywords in this score band.","type":"string","enum":["recommended","examine","avoid"]}}],"responses":{"200":{"description":"The analysis, its progress and a page of keywords.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. `error.code` is stable: see the list in the Error schema and the developer docs.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error. `error.code` is stable: see the list in the Error schema and the developer docs.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analyses/{analysis_id}/cancel":{"post":{"operationId":"cancel","tags":["Analyses"],"summary":"Cancel an analysis","description":"Stop a running analysis. Keywords not analyzed yet are not charged.\n\nRequired permission: `analyses:write`.","parameters":[{"name":"analysis_id","in":"path","required":true,"description":"Analysis id (from list_analyses or a launch).","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The analysis is cancelled.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. `error.code` is stable: see the list in the Error schema and the developer docs.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error. `error.code` is stable: see the list in the Error schema and the developer docs.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analyses/{analysis_id}/keywords/{keyword_id}":{"get":{"operationId":"get_keyword","tags":["Analyses"],"summary":"Keyword details","description":"Full result for one keyword: score, bidding decision, sub-scores, search intent, reasoning, ad advice, and the advertisers and top results seen on Google (third-party texts under third_party_text).\n\nRequired permission: `read`.","parameters":[{"name":"analysis_id","in":"path","required":true,"description":"Analysis id (from list_analyses or a launch).","schema":{"type":"string","format":"uuid"}},{"name":"keyword_id","in":"path","required":true,"description":"Keyword id (from the analysis results).","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The keyword result.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. `error.code` is stable: see the list in the Error schema and the developer docs.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error. `error.code` is stable: see the list in the Error schema and the developer docs.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/suggestions":{"post":{"operationId":"suggest","tags":["Suggestions"],"summary":"Suggest keywords (Vision)","description":"Commercial Google Ads keyword ideas from 1 to 3 sources (company products or public web pages). Free (no credits), at most 5 per minute and 30 per day. Returns a suggestion_batch_id, valid 24 hours for ONE launch.\n\nRequired permission: `read`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company_id":{"description":"Company to generate ideas for (default: the only configured company).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"sources":{"minItems":1,"maxItems":3,"type":"array","items":{"anyOf":[{"type":"object","properties":{"product_id":{"type":"string","minLength":1,"maxLength":100,"description":"A product id of the company (see get_account)."}},"required":["product_id"]},{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri","description":"A public web page (https)."},"name":{"type":"string","maxLength":200}},"required":["url"]}]},"description":"1 to 3 sources: company products and/or web pages."},"categories":{"description":"Idea categories (default: all four).","minItems":1,"maxItems":4,"type":"array","items":{"type":"string","enum":["branded","non_branded","generic","question"]}},"max_keywords":{"description":"Maximum ideas (default 30).","type":"integer","minimum":1,"maximum":50},"language":{"description":"Language of the keywords (target market, default fr).","type":"string","enum":["fr","en","de","es","it"]}},"required":["sources"]}}}},"responses":{"200":{"description":"New ideas, already analyzed ideas with their score, and the suggestion batch id.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. `error.code` is stable: see the list in the Error schema and the developer docs.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error. `error.code` is stable: see the list in the Error schema and the developer docs.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/openapi.json":{"get":{"operationId":"openapi","tags":["Meta"],"summary":"This OpenAPI document","description":"The machine-readable description of this API. Public: no key needed.","responses":{"200":{"description":"OpenAPI 3.1 document.","headers":{"X-Request-Id":{"description":"Identifier of the request, to give to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}}},"security":[]}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key `sib_live_` + 64 hexadecimal characters, created in Should I Bid › Integrations."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["unauthorized","forbidden","insufficient_scope","api_disabled","not_found","method_not_allowed","invalid_request","payload_too_large","rate_limited","insufficient_credits","daily_cap_reached","analysis_in_progress","too_many_keywords","max_credits_exceeded","company_required","suggestion_batch_invalid","unavailable","internal"]},"message":{"type":"string"},"details":{"type":"object"},"request_id":{"type":"string"}}}}}}}}