{"openapi":"3.1.0","info":{"title":"PromptedBrand API","version":"2026-10-01","description":"AI visibility data: how AI answer engines mention your brand."},"servers":[{"url":"https://api.promptedbrand.com"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An API key, `pb_live_…`"}}},"paths":{"/v1/brands":{"get":{"operationId":"listBrands","summary":"List brands","description":"The brands this key can read: one for a workspace key, every client for an agency key. When you try the API signed in, the brands where you have API access.","tags":["Brands"],"parameters":[],"responses":{"200":{"description":"A list of `brand` objects.","content":{"application/json":{"example":{"object":"list","data":[{"id":"brd_8f2kq1d9a0e44b6c9a1f0e2d3c4b5a69","object":"brand","name":"Northwind","domain":"northwind.com","engines":["chatgpt","perplexity","gemini"],"markets":["US"],"created":"2026-09-19T16:52:37Z"}],"has_more":false,"next_cursor":null}}}},"401":{"description":"unauthorized: Missing or revoked API key."},"429":{"description":"rate_limited: Too many requests; see Retry-After."}}}},"/v1/brands/{brand_id}/visibility":{"get":{"operationId":"retrieveVisibility","summary":"Retrieve visibility","description":"How visible a brand is in AI answers over a period: the score, the change against the previous period of the same length, share of voice, a time series and a breakdown per engine. The numbers match the Overview and Answer engine insights screens.","tags":["Visibility"],"parameters":[{"name":"brand_id","in":"path","required":true,"description":"The brand to report on. List brands with `GET /v1/brands`.","schema":{"type":"string"}},{"name":"start_date","in":"query","required":false,"description":"First day, `YYYY-MM-DD`. Default: 30 days ago.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":false,"description":"Last day, inclusive. Default: today. At most 365 days after `start_date`.","schema":{"type":"string","format":"date"}},{"name":"engines","in":"query","required":false,"description":"Comma-separated engine ids. Default: every engine the brand tracks.","schema":{"type":"string","description":"Comma-separated"}},{"name":"granularity","in":"query","required":false,"description":"Bucket size for `series`. Default `day`.","schema":{"type":"string","enum":["day","week","month"]}},{"name":"topic_id","in":"query","required":false,"description":"Only count prompts in this topic (`top_…`).","schema":{"type":"string"}},{"name":"include_competitors","in":"query","required":false,"description":"Add a `competitors` array with the same numbers per tracked competitor. Default `false`.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"A `visibility` object.","content":{"application/json":{"example":{"object":"visibility","brand_id":"brd_8f2kq1d9a0e44b6c9a1f0e2d3c4b5a69","period":{"start":"2026-09-01","end":"2026-09-30"},"granularity":"week","visibility":66.8,"change":2.6,"share_of_voice":0.31,"answers":480,"series":[{"date":"2026-09-01","visibility":63.1},{"date":"2026-09-08","visibility":64.9},{"date":"2026-09-15","visibility":65.7},{"date":"2026-09-22","visibility":66.8}],"by_engine":[{"engine":"chatgpt","visibility":71.4,"avg_position":1.8},{"engine":"perplexity","visibility":64,"avg_position":2.3}]}}}},"400":{"description":"invalid_request: Dates malformed, reversed or over 365 days apart."},"401":{"description":"unauthorized: Missing or revoked API key."},"404":{"description":"not_found: No brand with that id that this key can read."},"429":{"description":"rate_limited: Too many requests; see Retry-After."}}}},"/v1/prompts":{"get":{"operationId":"listPrompts","summary":"List prompts","description":"The questions tracked for a brand, newest first.","tags":["Prompts"],"parameters":[{"name":"brand_id","in":"query","required":false,"description":"The brand to read. Optional when your key covers one brand; required for agency keys and when trying the API signed in.","schema":{"type":"string"}},{"name":"topic_id","in":"query","required":false,"description":"Only prompts in this topic (`top_…`).","schema":{"type":"string"}},{"name":"tracked","in":"query","required":false,"description":"`true` for tracked prompts only, `false` for untracked. Default: both.","schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"How many items to return, 1 to 100. Default 20.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A list of `prompt` objects.","content":{"application/json":{"example":{"object":"list","data":[{"id":"prm_5c1e…","object":"prompt","text":"best trail running shoes for beginners","topic":{"id":"top_9a2b…","name":"Trail running shoes"},"intent":"commercial","tracked":true,"created":"2026-09-19T16:50:02Z"}],"has_more":true,"next_cursor":"MjAyNi0wOS0xOVQxNjo1MDowMi4wMDBa…"}}}},"401":{"description":"unauthorized: Missing or revoked API key."},"404":{"description":"not_found: No brand with that id that this key can read."},"429":{"description":"rate_limited: Too many requests; see Retry-After."}}}},"/v1/answers":{"get":{"operationId":"listAnswers","summary":"List answers","description":"Every AI answer collected for a brand, newest first, with the brands it mentions (in order) and the sources it cites.","tags":["Answers"],"parameters":[{"name":"brand_id","in":"query","required":false,"description":"The brand to read. Optional when your key covers one brand; required for agency keys and when trying the API signed in.","schema":{"type":"string"}},{"name":"prompt_id","in":"query","required":false,"description":"Only answers to this prompt.","schema":{"type":"string"}},{"name":"engine","in":"query","required":false,"description":"Only answers from this engine.","schema":{"type":"string","enum":["chatgpt","perplexity","gemini","google_ai_overviews","claude","deepseek","meta_ai"]}},{"name":"start_date","in":"query","required":false,"description":"First day, `YYYY-MM-DD`. Default: 30 days ago.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":false,"description":"Last day, inclusive. Default: today. At most 365 days after `start_date`.","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","required":false,"description":"How many items to return, 1 to 100. Default 20.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A list of `answer` objects.","content":{"application/json":{"example":{"object":"list","data":[{"id":"ans_77d0…","object":"answer","prompt_id":"prm_5c1e…","engine":"perplexity","created":"2026-10-10T04:12:44Z","text":"For beginners, **Northwind Trail One** is a safe pick…","mentions":[{"brand":"Northwind","is_you":true,"position":1,"sentiment":"positive"},{"brand":"Patagonia","is_you":false,"position":2,"sentiment":"neutral"}],"citations":[{"url":"https://www.runnersworld.com/…","domain":"runnersworld.com","type":"earned"}]}],"has_more":true,"next_cursor":"…"}}}},"400":{"description":"invalid_request: A filter is malformed."},"401":{"description":"unauthorized: Missing or revoked API key."},"404":{"description":"not_found: No brand with that id that this key can read."},"429":{"description":"rate_limited: Too many requests; see Retry-After."}}}},"/v1/citations":{"get":{"operationId":"listCitations","summary":"List cited domains","description":"The domains AI answers cite for a brand’s prompts over a period, most cited first, and how often they’re cited next to you.","tags":["Citations"],"parameters":[{"name":"brand_id","in":"query","required":false,"description":"The brand to read. Optional when your key covers one brand; required for agency keys and when trying the API signed in.","schema":{"type":"string"}},{"name":"start_date","in":"query","required":false,"description":"First day, `YYYY-MM-DD`. Default: 30 days ago.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":false,"description":"Last day, inclusive. Default: today. At most 365 days after `start_date`.","schema":{"type":"string","format":"date"}},{"name":"type","in":"query","required":false,"description":"Only this kind of source.","schema":{"type":"string","enum":["owned","competitor","review","earned","ugc"]}},{"name":"limit","in":"query","required":false,"description":"How many items to return, 1 to 100. Default 20.","schema":{"type":"integer"}}],"responses":{"200":{"description":"A list of `cited_domain` objects.","content":{"application/json":{"example":{"object":"list","data":[{"object":"cited_domain","domain":"outdoorgearlab.com","type":"review","citations":42,"answers_with_you":11}],"has_more":false,"next_cursor":null}}}},"401":{"description":"unauthorized: Missing or revoked API key."},"404":{"description":"not_found: No brand with that id that this key can read."},"429":{"description":"rate_limited: Too many requests; see Retry-After."}}}},"/v1/competitors":{"get":{"operationId":"listCompetitors","summary":"List competitors","description":"The competitors tracked for a brand, with their visibility over the last 30 days.","tags":["Competitors"],"parameters":[{"name":"brand_id","in":"query","required":false,"description":"The brand to read. Optional when your key covers one brand; required for agency keys and when trying the API signed in.","schema":{"type":"string"}}],"responses":{"200":{"description":"A list of `competitor` objects.","content":{"application/json":{"example":{"object":"list","data":[{"id":"cmp_31aa…","object":"competitor","name":"Patagonia","domain":"patagonia.com","visibility":66.6}],"has_more":false,"next_cursor":null}}}},"401":{"description":"unauthorized: Missing or revoked API key."},"404":{"description":"not_found: No brand with that id that this key can read."},"429":{"description":"rate_limited: Too many requests; see Retry-After."}}}},"/v1/opportunities":{"get":{"operationId":"listOpportunities","summary":"List opportunities","description":"Ranked gaps where the brand could be named or cited: content gaps, sites to get listed on, technical blocks and wrong facts, with an estimated gain.","tags":["Opportunities"],"parameters":[{"name":"brand_id","in":"query","required":false,"description":"The brand to read. Optional when your key covers one brand; required for agency keys and when trying the API signed in.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Default `open`.","schema":{"type":"string","enum":["open","in_progress","done","dismissed"]}},{"name":"limit","in":"query","required":false,"description":"How many items to return, 1 to 100. Default 20.","schema":{"type":"integer"}}],"responses":{"200":{"description":"A list of `opportunity` objects, largest estimated gain first.","content":{"application/json":{"example":{"object":"list","data":[{"id":"opp_0d1f…","object":"opportunity","type":"citation","subject":"outdoorgearlab.com","impact":"high","gain":3.2,"effort_minutes":120,"status":"open","created":"2026-10-10T05:01:12Z"}],"has_more":false,"next_cursor":null}}}},"401":{"description":"unauthorized: Missing or revoked API key."},"404":{"description":"not_found: No brand with that id that this key can read."},"429":{"description":"rate_limited: Too many requests; see Retry-After."}}}},"/v1/scans":{"get":{"operationId":"listScans","summary":"List scans","description":"Scan runs for a brand, newest first: the first scan, daily scans and manual ones.","tags":["Scans"],"parameters":[{"name":"brand_id","in":"query","required":false,"description":"The brand to read. Optional when your key covers one brand; required for agency keys and when trying the API signed in.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many items to return, 1 to 100. Default 20.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A list of `scan` objects.","content":{"application/json":{"example":{"object":"list","data":[{"id":"scn_71bd…","object":"scan","kind":"daily","status":"done","engines":["chatgpt","perplexity"],"answers_total":50,"answers_done":50,"started":"2026-10-14T04:00:03Z","finished":"2026-10-14T04:06:41Z"}],"has_more":true,"next_cursor":"…"}}}},"401":{"description":"unauthorized: Missing or revoked API key."},"404":{"description":"not_found: No brand with that id that this key can read."},"429":{"description":"rate_limited: Too many requests; see Retry-After."}}}},"/v1/scans/{scan_id}":{"get":{"operationId":"retrieveScan","summary":"Retrieve a scan","description":"One scan run and its progress. Poll it while `status` is `running`.","tags":["Scans"],"parameters":[{"name":"scan_id","in":"path","required":true,"description":"The scan, `scn_…`.","schema":{"type":"string"}}],"responses":{"200":{"description":"A `scan` object (fields as in List scans).","content":{"application/json":{"example":{"id":"scn_71bd…","object":"scan","brand_id":"brd_8f2kq1…","kind":"daily","status":"running","engines":["chatgpt","perplexity"],"answers_total":50,"answers_done":31,"started":"2026-10-14T04:00:03Z","finished":null}}}},"401":{"description":"unauthorized: Missing or revoked API key."},"404":{"description":"not_found: No scan with that id that this key can read."},"429":{"description":"rate_limited: Too many requests; see Retry-After."}}}}}}