{"openapi":"3.1.0","info":{"title":"CoreCited API","version":"1.0.0","description":"Read-only access to your AI search visibility data: per-engine visibility, Core vs Carousel stability, share of voice and cited sources. Available on the Agency plan and above."},"servers":[{"url":"https://corecited.com"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"tags":[{"name":"Brands","description":"The brands in your workspace."},{"name":"Brand data","description":"Measurements for one brand."}],"paths":{"/api/v1/brands":{"get":{"operationId":"listBrands","summary":"List brands","description":"Start here. Every other endpoint takes a brand id, and this is where you get one.\n\nReturns all brands in the workspace the key belongs to, oldest first. There is no pagination; a workspace holds at most a few dozen brands.","tags":["Brands"],"parameters":[],"responses":{"200":{"description":"Every brand in the workspace, with the ids the other endpoints need.","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute for this workspace.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) when the current minute ends.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"Every brand in the workspace, oldest first.","type":"array","items":{"type":"object","properties":{"id":{"description":"The brand's id.","type":"string"},"name":{"description":"The brand name.","type":"string"},"domain":{"description":"The website as entered during setup, often a full URL.","type":"string"},"createdAt":{"description":"When the brand was added. ISO 8601 timestamp, UTC.","type":"string"}},"required":["id","name","domain","createdAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"example":{"data":[{"id":"7d1c2b9e-4a3f-4e61-9b2a-0c5d8e7f6a14","name":"Acme Resume","domain":"https://www.acmeresume.com/","createdAt":"2026-08-02T09:14:31.482Z"}]}}}},"401":{"description":"missing_key: No key was sent in Authorization or x-api-key. | invalid_key: The key is malformed, unknown, or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"…"}}}}},"402":{"description":"plan_required: The workspace is not on a plan that includes API access. This is checked on every request, so it also happens after a downgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"plan_required","message":"…"}}}}},"429":{"description":"rate_limited: The workspace used up its requests for the current minute. All keys share one limit.","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute for this workspace.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) when the current minute ends.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the limit resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"…"}}}}},"500":{"description":"internal: Something failed on our side. The response carries no detail by design.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal","message":"…"}}}}}}}},"/api/v1/brands/{brandId}/visibility":{"get":{"operationId":"getVisibility","summary":"Get visibility","description":"The same numbers as the dashboard. Each engine's score is the percentage of the brand's tracked prompts in which that engine named the brand in the latest weekly cycle.\n\nAI answers move from week to week even when nothing real changed. Each score therefore comes with a drift band built from its trailing history, and isSignificant is true only when the score leaves that band. Build alerts on isSignificant, not on raw score changes.\n\nScores update once a week, when the brand's cycle runs. Polling more often returns the same data.","tags":["Brand data"],"parameters":[{"name":"brandId","in":"path","required":true,"description":"A brand id from GET /api/v1/brands.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The latest visibility score per engine, its drift band, the trend and sentiment.","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute for this workspace.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) when the current minute ends.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"brand":{"description":"The brand this response is about.","type":"object","properties":{"id":{"description":"The brand's id. Use it in every /brands/{brandId}/… path.","type":"string"},"name":{"description":"The brand name as configured in CoreCited.","type":"string"},"domain":{"description":"The brand's website exactly as entered during setup. This is often a full URL such as https://www.example.com/, not a bare host.","type":"string"}},"required":["id","name","domain"],"additionalProperties":false},"overallVisibility":{"description":"The mean of the latest per-engine scores, one decimal. 0 when nothing has run yet.","type":"number"},"perEngine":{"description":"The latest score for each engine that has one.","type":"array","items":{"type":"object","properties":{"slug":{"description":"Engine slug: chatgpt, claude, gemini, perplexity, ai_overview, ai_mode, deepseek, grok. Which ones appear depends on the plan and on what has run.","type":"string"},"isWebGrounded":{"description":"True when the engine searches the web before answering (Perplexity, Google's AI surfaces). Only these return citations.","type":"boolean"},"score":{"description":"Visibility in the latest cycle: the percentage of this brand's tracked prompts in which the engine named the brand. 0–100, one decimal.","type":"number"},"date":{"description":"The cycle this score belongs to. YYYY-MM-DD.","type":"string"},"bandLow":{"description":"Lower edge of the normal drift band, in percentage points. null while warming up.","anyOf":[{"type":"number"},{"type":"null"}]},"bandHigh":{"description":"Upper edge of the normal drift band, in percentage points. null while warming up.","anyOf":[{"type":"number"},{"type":"null"}]},"isSignificant":{"description":"True when this score falls OUTSIDE the drift band, a real change rather than ordinary week-to-week noise. Always false while warming up.","type":"boolean"},"isWarmingUp":{"description":"True until 4 prior weekly scores exist for this engine. Until then there is no band and nothing is flagged.","type":"boolean"},"noAnswerRate":{"description":"Percentage of recent runs where the surface served no answer at all (common for Google AI Overviews). Those runs are excluded from the score. null when it never happened.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["slug","isWebGrounded","score","date","bandLow","bandHigh","isSignificant","isWarmingUp","noAnswerRate"],"additionalProperties":false}},"trend":{"description":"Score history keyed by engine slug, oldest point first, one point per engine per day. Drawn from the 120 most recent stored scores across all engines combined, so with more engines each series is shorter.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"object","properties":{"date":{"description":"Cycle date, YYYY-MM-DD.","type":"string"},"score":{"description":"Visibility that cycle, 0–100.","type":"number"}},"required":["date","score"],"additionalProperties":false}}},"alerts":{"description":"Engines whose latest score is a significant change (isSignificant = true). Empty in a normal week.","type":"array","items":{"type":"object","properties":{"slug":{"description":"Engine slug.","type":"string"},"score":{"description":"The score that fell outside its band.","type":"number"}},"required":["slug","score"],"additionalProperties":false}},"signals":{"description":"Sentiment and position of the brand across successful runs in the last 14 days.","type":"object","properties":{"netSentiment":{"description":"Net sentiment, −100 to +100: (positive − negative) ÷ all brand mentions × 100, rounded. null with no mentions.","anyOf":[{"type":"number"},{"type":"null"}]},"positive":{"description":"Brand mentions classified positive.","type":"number"},"neutral":{"description":"Brand mentions classified neutral.","type":"number"},"negative":{"description":"Brand mentions classified negative.","type":"number"},"avgPosition":{"description":"Mean position of the brand in answers that name it (1 = named first). Lower is better. null with no mentions.","anyOf":[{"type":"number"},{"type":"null"}]},"mentions":{"description":"Brand mentions counted.","type":"number"}},"required":["netSentiment","positive","neutral","negative","avgPosition","mentions"],"additionalProperties":false}},"required":["brand","overallVisibility","perEngine","trend","alerts","signals"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"brand":{"id":"7d1c2b9e-4a3f-4e61-9b2a-0c5d8e7f6a14","name":"Acme Resume","domain":"https://www.acmeresume.com/"},"overallVisibility":44,"perEngine":[{"slug":"chatgpt","isWebGrounded":false,"score":58,"date":"2026-09-21","bandLow":31.2,"bandHigh":52.8,"isSignificant":true,"isWarmingUp":false,"noAnswerRate":null},{"slug":"ai_overview","isWebGrounded":true,"score":30,"date":"2026-09-21","bandLow":null,"bandHigh":null,"isSignificant":false,"isWarmingUp":true,"noAnswerRate":40}],"trend":{"chatgpt":[{"date":"2026-09-14","score":40},{"date":"2026-09-21","score":58}],"ai_overview":[{"date":"2026-09-21","score":30}]},"alerts":[{"slug":"chatgpt","score":58}],"signals":{"netSentiment":53,"positive":9,"neutral":5,"negative":1,"avgPosition":2.4,"mentions":15}}}}}},"401":{"description":"missing_key: No key was sent in Authorization or x-api-key. | invalid_key: The key is malformed, unknown, or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"…"}}}}},"402":{"description":"plan_required: The workspace is not on a plan that includes API access. This is checked on every request, so it also happens after a downgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"plan_required","message":"…"}}}}},"404":{"description":"not_found: The brand id is not a UUID, does not exist, or belongs to another workspace. These cases are deliberately indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"…"}}}}},"429":{"description":"rate_limited: The workspace used up its requests for the current minute. All keys share one limit.","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute for this workspace.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) when the current minute ends.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the limit resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"…"}}}}},"500":{"description":"internal: Something failed on our side. The response carries no detail by design.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal","message":"…"}}}}}}}},"/api/v1/brands/{brandId}/stability":{"get":{"operationId":"getStability","summary":"Get Core vs Carousel","description":"Being named once is luck. This endpoint tells you whether a brand is in the stable core of an answer, meaning it is named week after week, or rotating through it.\n\nEach name is classified by the share of weekly cycles it appeared in: core at 70% or more, emerging from 40%, carousel below that. A placement needs 4 cycles to mean anything, so check isWarmingUp before acting on it.","tags":["Brand data"],"parameters":[{"name":"brandId","in":"path","required":true,"description":"A brand id from GET /api/v1/brands.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"For every prompt and engine: who holds a durable position, and where your brand sits.","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute for this workspace.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) when the current minute ends.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"brand":{"description":"The brand this response is about.","type":"object","properties":{"id":{"description":"The brand's id. Use it in every /brands/{brandId}/… path.","type":"string"},"name":{"description":"The brand name as configured in CoreCited.","type":"string"},"domain":{"description":"The brand's website exactly as entered during setup. This is often a full URL such as https://www.example.com/, not a bare host.","type":"string"}},"required":["id","name","domain"],"additionalProperties":false},"minCycles":{"description":"Cycles needed before a placement means anything. Currently 4 (four weekly cycles).","type":"number"},"prompts":{"description":"Active prompts that have at least one cycle of data. Paused prompts are left out.","type":"array","items":{"type":"object","properties":{"promptId":{"description":"The prompt's id.","type":"string"},"promptText":{"description":"The question as tracked.","type":"string"},"engines":{"description":"One entry per engine this prompt has stability data for, alphabetical by slug.","type":"array","items":{"type":"object","properties":{"slug":{"description":"Engine slug: chatgpt, claude, gemini, perplexity, ai_overview, ai_mode, deepseek, grok. Which ones appear depends on the plan and on what has run.","type":"string"},"cyclesObserved":{"description":"Weekly cycles this prompt has run on this engine.","type":"number"},"isWarmingUp":{"description":"True while cyclesObserved is below minCycles. Treat placements as provisional until then.","type":"boolean"},"brandPlacement":{"description":"Where your brand sits. core: named in at least 70% of cycles. emerging: 40–70%. carousel: under 40%. absent: never named.","type":"string","enum":["core","emerging","carousel","absent"]},"brandStability":{"description":"Your brand's share of cycles, 0–1. 0 when absent.","type":"number"},"core":{"description":"Names in the durable core (at least 70% of cycles), most stable first, at most 5.","type":"array","items":{"type":"object","properties":{"entity":{"description":"The brand name as the engine wrote it.","type":"string"},"stability":{"description":"Share of observed cycles this name appeared in, 0–1.","type":"number"}},"required":["entity","stability"],"additionalProperties":false}},"carousel":{"description":"Every other name seen, including emerging ones, most stable first.","type":"array","items":{"type":"object","properties":{"entity":{"description":"The brand name as the engine wrote it.","type":"string"},"stability":{"description":"Share of observed cycles this name appeared in, 0–1.","type":"number"}},"required":["entity","stability"],"additionalProperties":false}}},"required":["slug","cyclesObserved","isWarmingUp","brandPlacement","brandStability","core","carousel"],"additionalProperties":false}}},"required":["promptId","promptText","engines"],"additionalProperties":false}}},"required":["brand","minCycles","prompts"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"brand":{"id":"7d1c2b9e-4a3f-4e61-9b2a-0c5d8e7f6a14","name":"Acme Resume","domain":"https://www.acmeresume.com/"},"minCycles":4,"prompts":[{"promptId":"c0a8f2d4-1b6e-4c3a-8f9d-2e7b5a1c4d90","promptText":"What is the best resume builder for career changers?","engines":[{"slug":"claude","cyclesObserved":6,"isWarmingUp":false,"brandPlacement":"carousel","brandStability":0.333,"core":[{"entity":"Zety","stability":1},{"entity":"Enhancv","stability":0.833}],"carousel":[{"entity":"Kickresume","stability":0.5},{"entity":"Acme Resume","stability":0.333}]}]}]}}}}},"401":{"description":"missing_key: No key was sent in Authorization or x-api-key. | invalid_key: The key is malformed, unknown, or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"…"}}}}},"402":{"description":"plan_required: The workspace is not on a plan that includes API access. This is checked on every request, so it also happens after a downgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"plan_required","message":"…"}}}}},"404":{"description":"not_found: The brand id is not a UUID, does not exist, or belongs to another workspace. These cases are deliberately indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"…"}}}}},"429":{"description":"rate_limited: The workspace used up its requests for the current minute. All keys share one limit.","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute for this workspace.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) when the current minute ends.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the limit resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"…"}}}}},"500":{"description":"internal: Something failed on our side. The response carries no detail by design.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal","message":"…"}}}}}}}},"/api/v1/brands/{brandId}/competitors":{"get":{"operationId":"getCompetitors","summary":"Get share of voice","description":"Share of voice is estimated from a finite number of answers, so every percentage comes with a 95% confidence interval.\n\nWhen two intervals overlap, the gap between those names is noise. tiedWithBrand and leaders say this directly, so you don't have to compute it. Do not present a ranking closer than noiseFloorPp as a real ranking.","tags":["Brand data"],"parameters":[{"name":"brandId","in":"path","required":true,"description":"A brand id from GET /api/v1/brands.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Your brand against each tracked competitor over 14 days, with confidence intervals.","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute for this workspace.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) when the current minute ends.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"brand":{"description":"The brand this response is about.","type":"object","properties":{"id":{"description":"The brand's id. Use it in every /brands/{brandId}/… path.","type":"string"},"name":{"description":"The brand name as configured in CoreCited.","type":"string"},"domain":{"description":"The brand's website exactly as entered during setup. This is often a full URL such as https://www.example.com/, not a bare host.","type":"string"}},"required":["id","name","domain"],"additionalProperties":false},"shareOfVoice":{"description":"Your brand and each competitor, most mentions first.","type":"array","items":{"type":"object","properties":{"name":{"description":"Your brand or a tracked competitor.","type":"string"},"isBrand":{"description":"True for your own brand's row.","type":"boolean"},"mentions":{"description":"Times this name was mentioned in successful runs over the last 14 days.","type":"number"},"sovPct":{"description":"Share of voice: this name's mentions ÷ all mentions counted, as a percentage.","type":"number"},"lowPct":{"description":"Lower bound of the 95% Wilson confidence interval for sovPct.","type":"number"},"highPct":{"description":"Upper bound of the 95% Wilson confidence interval for sovPct.","type":"number"},"halfWidthPp":{"description":"Half the interval's width, in percentage points.","type":"number"},"tiedWithBrand":{"description":"True when this row's interval overlaps yours, so the gap between you is noise. Always false on your own row.","type":"boolean"},"tiedForLead":{"description":"True when this row is statistically tied with the top row.","type":"boolean"}},"required":["name","isBrand","mentions","sovPct","lowPct","highPct","halfWidthPp","tiedWithBrand","tiedForLead"],"additionalProperties":false}},"totalMentions":{"description":"All mentions counted, the denominator of sovPct.","type":"number"},"noiseFloorPp":{"description":"The smallest gap in percentage points that means anything at this sample size. Do not rank names closer than this.","type":"number"},"leaders":{"description":"Names statistically tied for the lead. More than one means there is no real #1.","type":"array","items":{"type":"string"}}},"required":["brand","shareOfVoice","totalMentions","noiseFloorPp","leaders"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"brand":{"id":"7d1c2b9e-4a3f-4e61-9b2a-0c5d8e7f6a14","name":"Acme Resume","domain":"https://www.acmeresume.com/"},"shareOfVoice":[{"name":"Zety","isBrand":false,"mentions":41,"sovPct":43.2,"lowPct":33.7,"highPct":53.2,"halfWidthPp":9.8,"tiedWithBrand":false,"tiedForLead":true},{"name":"Enhancv","isBrand":false,"mentions":33,"sovPct":34.7,"lowPct":25.9,"highPct":44.7,"halfWidthPp":9.4,"tiedWithBrand":false,"tiedForLead":true},{"name":"Acme Resume","isBrand":true,"mentions":12,"sovPct":12.6,"lowPct":7.4,"highPct":20.8,"halfWidthPp":6.7,"tiedWithBrand":false,"tiedForLead":false},{"name":"Kickresume","isBrand":false,"mentions":9,"sovPct":9.5,"lowPct":5.1,"highPct":17,"halfWidthPp":6,"tiedWithBrand":true,"tiedForLead":false}],"totalMentions":95,"noiseFloorPp":19.8,"leaders":["Zety","Enhancv"]}}}}},"401":{"description":"missing_key: No key was sent in Authorization or x-api-key. | invalid_key: The key is malformed, unknown, or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"…"}}}}},"402":{"description":"plan_required: The workspace is not on a plan that includes API access. This is checked on every request, so it also happens after a downgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"plan_required","message":"…"}}}}},"404":{"description":"not_found: The brand id is not a UUID, does not exist, or belongs to another workspace. These cases are deliberately indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"…"}}}}},"429":{"description":"rate_limited: The workspace used up its requests for the current minute. All keys share one limit.","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute for this workspace.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) when the current minute ends.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the limit resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"…"}}}}},"500":{"description":"internal: Something failed on our side. The response carries no detail by design.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal","message":"…"}}}}}}}},"/api/v1/brands/{brandId}/sources":{"get":{"operationId":"getSources","summary":"Get cited sources","description":"The top 20 domains cited in the brand's answers over the last 14 days, sorted by gap: how many more competitor mentions than yours appeared in the answers that cited them.\n\nA high gap is a lead. It points to a page that AI engines trust and that talks about your rivals, which makes it the place to get mentioned. Only web-grounded engines (Perplexity and Google's AI surfaces) return citations; ChatGPT, Claude and Gemini name brands without links.","tags":["Brand data"],"parameters":[{"name":"brandId","in":"path","required":true,"description":"A brand id from GET /api/v1/brands.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The domains AI answers cite, and which of them feed your competitors instead of you.","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute for this workspace.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) when the current minute ends.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"brand":{"description":"The brand this response is about.","type":"object","properties":{"id":{"description":"The brand's id. Use it in every /brands/{brandId}/… path.","type":"string"},"name":{"description":"The brand name as configured in CoreCited.","type":"string"},"domain":{"description":"The brand's website exactly as entered during setup. This is often a full URL such as https://www.example.com/, not a bare host.","type":"string"}},"required":["id","name","domain"],"additionalProperties":false},"sources":{"description":"The top 20 cited domains, biggest gap first, then most cited. Only web-grounded engines return citations.","type":"array","items":{"type":"object","properties":{"domain":{"description":"The cited host, without www.","type":"string"},"count":{"description":"Citations of this domain in successful runs over the last 14 days.","type":"number"},"sourceType":{"description":"The most common classification of this domain's citations: ugc, forum, corporate, listicle, review, news, docs or other.","type":"string"},"competitorMentions":{"description":"Competitor mentions in the answers that cited this domain. Each answer counts once per domain.","type":"number"},"brandMentions":{"description":"Your brand's mentions in the answers that cited this domain. Each answer counts once per domain.","type":"number"},"gap":{"description":"competitorMentions − brandMentions. A high gap marks a source that feeds your rivals and not you.","type":"number"},"isOwnDomain":{"description":"True when the cited domain is your brand's own site.","type":"boolean"}},"required":["domain","count","sourceType","competitorMentions","brandMentions","gap","isOwnDomain"],"additionalProperties":false}}},"required":["brand","sources"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"brand":{"id":"7d1c2b9e-4a3f-4e61-9b2a-0c5d8e7f6a14","name":"Acme Resume","domain":"https://www.acmeresume.com/"},"sources":[{"domain":"reddit.com","count":18,"sourceType":"forum","competitorMentions":27,"brandMentions":2,"gap":25,"isOwnDomain":false},{"domain":"acmeresume.com","count":6,"sourceType":"corporate","competitorMentions":3,"brandMentions":6,"gap":-3,"isOwnDomain":true}]}}}}},"401":{"description":"missing_key: No key was sent in Authorization or x-api-key. | invalid_key: The key is malformed, unknown, or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"…"}}}}},"402":{"description":"plan_required: The workspace is not on a plan that includes API access. This is checked on every request, so it also happens after a downgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"plan_required","message":"…"}}}}},"404":{"description":"not_found: The brand id is not a UUID, does not exist, or belongs to another workspace. These cases are deliberately indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"…"}}}}},"429":{"description":"rate_limited: The workspace used up its requests for the current minute. All keys share one limit.","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute for this workspace.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) when the current minute ends.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the limit resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"…"}}}}},"500":{"description":"internal: Something failed on our side. The response carries no detail by design.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal","message":"…"}}}}}}}},"/api/v1/brands/{brandId}/prompts":{"get":{"operationId":"listPrompts","summary":"List prompts","description":"Every prompt configured for the brand, oldest first, including paused ones (isActive = false). The ids match the promptId values in the stability endpoint.","tags":["Brand data"],"parameters":[{"name":"brandId","in":"path","required":true,"description":"A brand id from GET /api/v1/brands.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The buyer questions tracked for the brand, active and paused.","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute for this workspace.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) when the current minute ends.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"brand":{"description":"The brand this response is about.","type":"object","properties":{"id":{"description":"The brand's id. Use it in every /brands/{brandId}/… path.","type":"string"},"name":{"description":"The brand name as configured in CoreCited.","type":"string"},"domain":{"description":"The brand's website exactly as entered during setup. This is often a full URL such as https://www.example.com/, not a bare host.","type":"string"}},"required":["id","name","domain"],"additionalProperties":false},"prompts":{"description":"Every prompt for the brand, active and paused, oldest first.","type":"array","items":{"type":"object","properties":{"id":{"description":"The prompt's id.","type":"string"},"text":{"description":"The question, exactly as sent to each engine.","type":"string"},"isActive":{"description":"False when the prompt is paused. Paused prompts are not run.","type":"boolean"},"createdAt":{"description":"When the prompt was added. ISO 8601 timestamp, UTC.","type":"string"}},"required":["id","text","isActive","createdAt"],"additionalProperties":false}}},"required":["brand","prompts"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"brand":{"id":"7d1c2b9e-4a3f-4e61-9b2a-0c5d8e7f6a14","name":"Acme Resume","domain":"https://www.acmeresume.com/"},"prompts":[{"id":"c0a8f2d4-1b6e-4c3a-8f9d-2e7b5a1c4d90","text":"What is the best resume builder for career changers?","isActive":true,"createdAt":"2026-08-02T09:20:05.117Z"},{"id":"5e2b7c1a-9d4f-4a8e-b3c6-7f0e1d2a3b4c","text":"Which resume builders are free to download?","isActive":false,"createdAt":"2026-08-02T09:20:05.117Z"}]}}}}},"401":{"description":"missing_key: No key was sent in Authorization or x-api-key. | invalid_key: The key is malformed, unknown, or has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"…"}}}}},"402":{"description":"plan_required: The workspace is not on a plan that includes API access. This is checked on every request, so it also happens after a downgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"plan_required","message":"…"}}}}},"404":{"description":"not_found: The brand id is not a UUID, does not exist, or belongs to another workspace. These cases are deliberately indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"…"}}}}},"429":{"description":"rate_limited: The workspace used up its requests for the current minute. All keys share one limit.","headers":{"X-RateLimit-Limit":{"description":"Requests allowed per minute for this workspace.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) when the current minute ends.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the limit resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"…"}}}}},"500":{"description":"internal: Something failed on our side. The response carries no detail by design.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"internal","message":"…"}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer <key>"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Alternative to the Bearer header."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"description":"Stable, machine-readable. Branch on this.","type":"string","enum":["missing_key","invalid_key","plan_required","not_found","rate_limited","internal"]},"message":{"description":"Human-readable. Wording may change; do not parse it.","type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}