{"info":{"title":"Temso Public API","version":"1.0.0","description":"REST API for exporting Temso project analytics, responses, mentions, sources, and traffic data."},"servers":[{"url":"https://api.temso.ai/v1","description":"Production"}],"tags":[{"name":"Projects","description":"Projects your API key can access. Call List projects first to discover the project IDs used by every other endpoint."},{"name":"Configuration","description":"Project setup that drives data collection: prompts, prompt tags, personas, offerings, and monitors (frequency + tracked models)."},{"name":"Brands","description":"Your own brand and tracked competitors, plus the brand mentions extracted from AI responses."},{"name":"Responses","description":"Raw AI responses collected for your prompts — the data behind all visibility analytics."},{"name":"Sources","description":"URLs and domains the AI models cited, with per-URL/domain analytics, top domains, and presence/citation time series."},{"name":"Analytics","description":"Pre-aggregated metrics matching the views in the Temso app and the CSV exports."},{"name":"Reports","description":"AI visibility reports generated in a project, including their full content and structured data."},{"name":"Traffic ingestion","description":"Event ingestion used by Temso traffic integrations (e.g. the Cloudflare Worker generated during setup). You don't call these endpoints directly when consuming the API."},{"name":"Publishing","description":"Webhook publish subscriptions and confirmations used by the Temso Zapier app. You don't call these endpoints directly when consuming the API."}],"openapi":"3.1.1","paths":{"/projects":{"get":{"operationId":"projects.list","summary":"List Projects","description":"Returns the projects this API key can access. Call this first to discover the project IDs used by every other endpoint.","tags":["Projects"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Project ID. Pass this as `projectId` in project-scoped endpoints."},"name":{"type":"string","description":"Project display name."}},"required":["id","name"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/prompts":{"get":{"operationId":"prompts.list","summary":"List Prompts","description":"Returns the prompts configured in a project with their metadata and associations (persona, offering, topic, tags). Use the returned IDs to filter analytics and response endpoints.","tags":["Configuration"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"page","in":"query","schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"promptId":{"type":"string","description":"Prompt ID. Use it in `filter[...]` params and to join analytics."},"text":{"type":"string","description":"The prompt text sent to the AI models."},"language":{"type":"string","description":"ISO 639-1 language code the prompt runs in.","examples":["en"]},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code the prompt runs for.","examples":["US"]},"type":{"type":"string","description":"Prompt type: informational, navigational, commercial, or transactional."},"isBranded":{"type":"boolean","description":"Whether the prompt mentions a brand by name."},"isPaused":{"type":"boolean","description":"Whether the prompt is currently paused from collection."},"origin":{"type":"string","description":"How the prompt was created: keyword, persona, offering, offering_persona, topic, or manual. Empty when unset."},"keywords":{"type":"array","items":{"type":"string"},"description":"Keywords assigned to the prompt."},"personaId":{"type":"string","description":"Associated persona ID. Empty when none."},"offeringId":{"type":"string","description":"Associated offering ID. Empty when none."},"topicId":{"type":"string","description":"Associated topic ID. Empty when none."},"tagIds":{"type":"array","items":{"type":"string"},"description":"Prompt tag IDs assigned to the prompt."},"monitorId":{"type":"string","description":"ID of the monitor the prompt belongs to."},"createdAt":{"type":"string","description":"ISO 8601 timestamp when the prompt was created."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp when the prompt was last updated."}},"required":["promptId","text","language","country","type","isBranded","isPaused","origin","keywords","personaId","offeringId","topicId","tagIds","monitorId","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/prompts/responses":{"get":{"operationId":"prompts.responses","summary":"List AI Responses","description":"Returns one row per AI response collected for the project's prompts in the date range, including prompt metadata and a response preview. Pass filter[runId] to isolate the responses of one monitor run. Use Get Response Content to fetch the full model output for a response.","tags":["Responses"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs — limits to responses where at least one of these brands was mentioned"},"runId":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Run ID of one monitor execution. Limits results to the rows that run produced; every row exposes its runId.","examples":["665f1c2e9b1d4a3f8c0e7a11"]}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"responseId":{"type":"string","description":"Unique response ID. Join key for mentions and sources."},"runId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ID of the monitor run that produced this response. Every response of one execution shares it; pass it as filter[runId] to isolate that run. Null for responses collected before run tracking existed."},"promptText":{"type":"string","description":"The prompt that was sent to the AI model."},"preview":{"type":"string","description":"Preview of the AI model response."},"model":{"type":"string","description":"Model key the response came from.","examples":["openai/chatgpt"]},"country":{"type":"string","description":"Country code the prompt was run for.","examples":["US"]},"language":{"type":"string","description":"Language code the prompt was run in.","examples":["en"]},"presence":{"type":"number","description":"Fraction of your own brands mentioned in the response (0–1)."},"totalSources":{"type":"number","description":"Number of sources the response cited."},"createdAt":{"type":"string","description":"ISO 8601 timestamp when the response was collected."},"promptType":{"type":"string","description":"Prompt type: informational, navigational, commercial, or transactional."},"isBranded":{"type":"boolean","description":"Whether the prompt mentions a brand by name."},"keywords":{"type":"array","items":{"type":"string"},"description":"Keywords assigned to the prompt."}},"required":["responseId","runId","promptText","preview","model","country","language","presence","totalSources","createdAt","promptType","isBranded","keywords"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/prompts/responses/{responseId}/content":{"get":{"operationId":"prompts.responseContent","summary":"Get Response Content","description":"Returns the full AI response content for one response, including the model's markdown output and URL citation annotations. Use List AI Responses first to find response IDs.","tags":["Responses"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"responseId","in":"path","required":true,"schema":{"type":"string","description":"Response ID returned by List AI Responses"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"responseId":{"type":"string","description":"Unique response ID."},"runId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ID of the monitor run that produced this response. Null for responses collected before run tracking existed."},"promptText":{"type":"string","description":"The prompt that was sent to the AI model."},"responseText":{"type":"string","description":"Full markdown text returned by the AI model."},"annotations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Annotation type.","examples":["url_citation"]},"url":{"type":"string","description":"Cited source URL."},"title":{"type":"string","description":"Cited source title. Empty when unavailable."},"content":{"type":"string","description":"Cited source excerpt. Empty when unavailable."},"cited":{"type":"boolean","description":"Whether the annotation was cited by the model."}},"required":["type","url","title","content","cited"]},"description":"URL citation annotations attached to the response."},"fanOutQueries":{"type":"array","items":{"type":"string"},"description":"Search queries used to fan out the prompt. Empty when not applicable."},"createdAt":{"type":"string","description":"ISO 8601 timestamp when the response was collected."}},"required":["responseId","runId","promptText","responseText","annotations","fanOutQueries","createdAt"]}},"required":["data"]}}}}}}},"/projects/{projectId}/prompt-tags":{"get":{"operationId":"promptTags.list","summary":"List Prompt Tags","description":"Returns the prompt tags configured in a project. Use the returned IDs in `filter[promptTagIds]`.","tags":["Configuration"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"page","in":"query","schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"tagId":{"type":"string","description":"Prompt tag ID. Use it in `filter[promptTagIds]`."},"name":{"type":"string","description":"Tag display name."},"color":{"type":"string","description":"Tag color (hex or token)."},"createdAt":{"type":"string","description":"ISO 8601 timestamp when the tag was created."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp when the tag was last updated."}},"required":["tagId","name","color","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/personas":{"get":{"operationId":"personas.list","summary":"List Personas","description":"Returns the personas configured in a project. Use the returned IDs in `filter[personaIds]`.","tags":["Configuration"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"page","in":"query","schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"personaId":{"type":"string","description":"Persona ID. Use it in `filter[personaIds]`."},"name":{"type":"string","description":"Persona name."},"description":{"type":"string","description":"Persona description."},"createdAt":{"type":"string","description":"ISO 8601 timestamp when the persona was created."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp when the persona was last updated."}},"required":["personaId","name","description","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/offerings":{"get":{"operationId":"offerings.list","summary":"List Offerings","description":"Returns the offerings configured in a project. Use the returned IDs in `filter[offeringIds]`.","tags":["Configuration"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"page","in":"query","schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"offeringId":{"type":"string","description":"Offering ID. Use it in `filter[offeringIds]`."},"name":{"type":"string","description":"Offering name."},"description":{"type":"string","description":"Offering description. Empty when unset."},"brandId":{"type":"string","description":"ID of the brand this offering belongs to."},"createdAt":{"type":"string","description":"ISO 8601 timestamp when the offering was created."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp when the offering was last updated."}},"required":["offeringId","name","description","brandId","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/monitors":{"get":{"operationId":"monitors.list","summary":"List Monitors","description":"Returns the project's monitors with their settings and tracked models. A monitor defines the collection frequency and the set of AI models prompts are run against.","tags":["Configuration"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"page","in":"query","schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"monitorId":{"type":"string","description":"Monitor ID. Matches `monitorId` on prompts."},"name":{"type":"string","description":"Monitor name."},"description":{"type":"string","description":"Monitor description. Empty when unset."},"frequency":{"type":"string","description":"Collection frequency: DAILY, EVERY_2_DAYS, or WEEKLY."},"isPaused":{"type":"boolean","description":"Whether the monitor is currently paused."},"models":{"type":"array","items":{"type":"string"},"description":"Tracked AI model keys for this monitor.","examples":[["openai/chatgpt","google/ai-overview"]]},"lastRunAt":{"type":"string","description":"ISO 8601 timestamp of the last collection run. Empty when never run."},"createdAt":{"type":"string","description":"ISO 8601 timestamp when the monitor was created."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp when the monitor was last updated."}},"required":["monitorId","name","description","frequency","isPaused","models","lastRunAt","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/brands":{"get":{"operationId":"brands.list","summary":"List Brands","description":"Returns the accepted brands tracked in a project — your own brand first, then competitors sorted by name. Use the returned brand IDs to filter analytics and mention endpoints.","tags":["Brands"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"page","in":"query","schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"brandId":{"type":"string","description":"Brand ID. Use it in `filter[brandIds]` on other endpoints."},"brandName":{"type":"string","description":"Brand display name."},"isOwnBrand":{"type":"boolean","description":"True for your own brand, false for competitors."},"website":{"type":"string","description":"Brand website URL. Empty string when not set."}},"required":["brandId","brandName","isOwnBrand","website"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/brands/suggestions":{"get":{"operationId":"brands.suggestions","summary":"List Suggested Competitors","description":"Returns competitor brands Temso has surfaced but that haven't been accepted into tracking yet. Accept them in the app to include them in analytics.","tags":["Brands"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"page","in":"query","schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"brandId":{"type":"string","description":"Suggested brand ID. Accept it in the app to start tracking it."},"brandName":{"type":"string","description":"Suggested brand display name."},"website":{"type":"string","description":"Suggested brand website URL. Empty when not set."},"description":{"type":"string","description":"Why the brand was suggested / what it is. Empty when unavailable."}},"required":["brandId","brandName","website","description"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/brands/mentions":{"get":{"operationId":"brands.mentions","summary":"List Brand Mentions","description":"Returns one row per brand mention extracted from AI responses in the date range, with position, sentiment, and perception attributes. Covers your own brand and tracked competitors; use filter[brandIds] to narrow to specific brands.","tags":["Brands"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"responseId":{"type":"string","description":"ID of the AI response the mention was extracted from."},"brandId":{"type":"string","description":"ID of the mentioned brand."},"brandName":{"type":"string","description":"Name of the mentioned brand."},"isOwnBrand":{"type":"boolean","description":"True for your own brand, false for competitors."},"model":{"type":"string","description":"Model key the response came from.","examples":["openai/chatgpt"]},"position":{"type":"number","description":"1-based position of the brand's first occurrence relative to other brand mentions in the response."},"sentiment":{"type":"string","description":"Sentiment of the mention: positive, neutral, or negative. Empty when not evaluated."},"perception":{"type":"array","items":{"type":"string"},"description":"Perception attributes ascribed to the brand (e.g. reliable, affordable)."},"createdAt":{"type":"string","description":"ISO 8601 timestamp when the response was collected."}},"required":["responseId","brandId","brandName","isOwnBrand","model","position","sentiment","perception","createdAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/sources":{"get":{"operationId":"sources.list","summary":"List Sources","description":"Returns one row per source citation from AI responses in the date range — the URLs models referenced when answering. Use it to analyze which domains and pages drive AI answers in your space. Pass filter[runId] to isolate the citations of one monitor run.","tags":["Sources"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs — limits to sources tied to responses where at least one of these brands was mentioned"},"runId":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Run ID of one monitor execution. Limits results to the rows that run produced; every row exposes its runId.","examples":["665f1c2e9b1d4a3f8c0e7a11"]}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"responseId":{"type":"string","description":"ID of the AI response that cited this source."},"runId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ID of the monitor run that produced the citing response; pass it as filter[runId] to isolate that run. Null for sources collected before run tracking existed."},"url":{"type":"string","description":"Full URL of the cited source."},"domain":{"type":"string","description":"Domain of the cited source.","examples":["example.com"]},"position":{"type":"number","description":"1-based position of the citation within the response."},"type":{"type":"string","description":"Page type classification (e.g. ARTICLE, LISTICLE, COMPARISON, GUIDE, PRODUCT). Empty when not classified."},"domainRank":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Global popularity rank of the domain. Null when unknown."},"urlRank":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Popularity rank of the specific URL. Null when unknown."},"createdAt":{"type":"string","description":"ISO 8601 timestamp when the response was collected."}},"required":["responseId","runId","url","domain","position","type","domainRank","urlRank","createdAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/sources/urls":{"get":{"operationId":"sources.urls","summary":"Get Source URL Analytics","description":"Returns per-URL citation analytics over the date range — appearances, citation rate, average position, and the brands mentioned alongside each URL. Export-equivalent of the source URLs CSV.","tags":["Sources"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"},"domainContains":{"type":"string","description":"Only URLs whose domain contains this substring."},"urlContains":{"type":"string","description":"Only URLs whose full URL contains this substring."},"types":{"type":"string","description":"Comma-separated URL types to include."}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"Sort field (e.g. responseCount, avgPosition).","examples":["responseCount"]},"allowEmptyValue":true,"allowReserved":true},{"name":"order","in":"query","required":false,"schema":{"type":"string","description":"Sort order: asc or desc."},"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"urlId":{"type":"string","description":"Source URL ID."},"url":{"type":"string","description":"Full URL."},"domain":{"type":"string","description":"Domain of the URL.","examples":["example.com"]},"title":{"type":"string","description":"Page title. Empty when unknown."},"type":{"type":"string","description":"Page type (e.g. news, blog). Empty when unknown."},"responseCount":{"type":"number","description":"Responses that cited this URL in range."},"presence":{"type":"number","description":"Percentage of responses citing this URL (0–100)."},"citedCount":{"type":"number","description":"Responses where this URL was an actual citation."},"cited":{"type":"number","description":"Percentage of appearances that were citations (0–100)."},"avgPosition":{"type":"number","description":"Average citation position."},"urlRank":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Page-specific popularity rank. Null when unknown."},"domainRank":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Domain popularity rank. Null when unknown."},"models":{"type":"array","items":{"type":"string"},"description":"Model keys whose responses cited this URL."},"brandMentions":{"type":"array","items":{"type":"string"},"description":"Brand IDs mentioned in responses citing this URL."},"firstSeen":{"type":"string","description":"ISO 8601 timestamp first cited."},"lastSeen":{"type":"string","description":"ISO 8601 timestamp last cited."}},"required":["urlId","url","domain","title","type","responseCount","presence","citedCount","cited","avgPosition","urlRank","domainRank","models","brandMentions","firstSeen","lastSeen"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/sources/domains":{"get":{"operationId":"sources.domains","summary":"Get Source Domain Analytics","description":"Returns per-domain citation analytics over the date range — appearances, citation rate, URL counts, and the brands mentioned. Export-equivalent of the source domains CSV.","tags":["Sources"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"},"domainContains":{"type":"string","description":"Only domains containing this substring."},"domainCategories":{"type":"string","description":"Comma-separated domain categories to include."}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"Sort field (e.g. responseCount, avgPosition).","examples":["responseCount"]},"allowEmptyValue":true,"allowReserved":true},{"name":"order","in":"query","required":false,"schema":{"type":"string","description":"Sort order: asc or desc."},"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","description":"Domain (stable identifier).","examples":["example.com"]},"urlCount":{"type":"number","description":"Unique URLs cited from this domain."},"responseCount":{"type":"number","description":"Responses citing this domain in range."},"presence":{"type":"number","description":"Percentage of responses citing this domain (0–100)."},"citedCount":{"type":"number","description":"Responses where a URL from this domain was an actual citation."},"cited":{"type":"number","description":"Percentage of appearances that were citations (0–100)."},"avgPosition":{"type":"number","description":"Average citation position across the domain's URLs."},"domainRank":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Domain popularity rank. Null when unknown."},"category":{"type":"string","description":"Domain category. Empty when unknown."},"models":{"type":"array","items":{"type":"string"},"description":"Model keys whose responses cited this domain."},"brandMentions":{"type":"array","items":{"type":"string"},"description":"Brand IDs mentioned in responses citing this domain."},"firstSeen":{"type":"string","description":"ISO 8601 timestamp first cited."},"lastSeen":{"type":"string","description":"ISO 8601 timestamp last cited."}},"required":["domain","urlCount","responseCount","presence","citedCount","cited","avgPosition","domainRank","category","models","brandMentions","firstSeen","lastSeen"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/sources/top-domains":{"get":{"operationId":"sources.topDomains","summary":"Get Top Domains","description":"Returns the most-cited source domains over the date range, ranked by citation count.","tags":["Sources"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","description":"Cited domain.","examples":["example.com"]},"count":{"type":"number","description":"Number of citations in range."}},"required":["domain","count"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/sources/presence-time-series":{"get":{"operationId":"sources.presenceTimeSeries","summary":"Get Source Presence Time Series","description":"Returns the daily percentage of responses citing your brand's own domains over the date range. Defaults to your own brand; pass `filter[brandIds]` to scope to specific brands.","tags":["Sources"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Day (YYYY-MM-DD).","examples":["2026-01-15"]},"percentage":{"type":"number","description":"Metric value for the day, as a percentage (0–100)."},"totalResponses":{"type":"number","description":"Responses collected that day."}},"required":["date","percentage","totalResponses"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/sources/citation-time-series":{"get":{"operationId":"sources.citationTimeSeries","summary":"Get Citation Time Series","description":"Returns the daily percentage of responses that cited your brand's own domains as actual citations over the date range.","tags":["Sources"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Day (YYYY-MM-DD).","examples":["2026-01-15"]},"percentage":{"type":"number","description":"Metric value for the day, as a percentage (0–100)."},"totalResponses":{"type":"number","description":"Responses collected that day."}},"required":["date","percentage","totalResponses"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/sources/urls/{urlId}":{"get":{"operationId":"sources.urlDetail","summary":"Get Source URL Detail","description":"Returns an aggregated summary for a single source URL over the date range.","tags":["Sources"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"urlId","in":"path","required":true,"schema":{"type":"string","description":"Source URL ID (see Get Source URL Analytics)."}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier: URL ID for URLs, domain string for domains."},"kind":{"type":"string","description":"Either 'url' or 'domain'."},"label":{"type":"string","description":"Display label (the URL or domain)."},"title":{"type":"string","description":"Page title for URLs. Empty when unavailable."},"domain":{"type":"string","description":"Domain.","examples":["example.com"]},"responseCount":{"type":"number","description":"Responses citing this source in range."},"presence":{"type":"number","description":"Percentage of responses citing this source (0–100)."},"cited":{"type":"number","description":"Percentage of appearances that were citations (0–100)."},"avgPosition":{"type":"number","description":"Average citation position."},"promptCount":{"type":"number","description":"Distinct prompts whose responses cited this source."},"urlCount":{"type":"number","description":"Unique URLs (domain summaries only). 0 for URL summaries."},"models":{"type":"array","items":{"type":"string"},"description":"Model keys whose responses cited this source."},"brandMentions":{"type":"array","items":{"type":"string"},"description":"Brand IDs mentioned alongside this source."},"type":{"type":"string","description":"URL page type. Empty when unknown."},"category":{"type":"string","description":"Domain category. Empty when unknown."},"rank":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Popularity rank. Null when unknown."},"firstSeen":{"type":"string","description":"ISO 8601 timestamp first cited. Empty when unknown."},"lastSeen":{"type":"string","description":"ISO 8601 timestamp last cited. Empty when unknown."}},"required":["id","kind","label","title","domain","responseCount","presence","cited","avgPosition","promptCount","urlCount","models","brandMentions","type","category","rank","firstSeen","lastSeen"]}},"required":["data"]}}}}}}},"/projects/{projectId}/sources/domains/{domain}":{"get":{"operationId":"sources.domainDetail","summary":"Get Source Domain Detail","description":"Returns an aggregated summary for a single source domain over the date range.","tags":["Sources"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"domain","in":"path","required":true,"schema":{"type":"string","description":"Domain to summarize.","examples":["example.com"]}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier: URL ID for URLs, domain string for domains."},"kind":{"type":"string","description":"Either 'url' or 'domain'."},"label":{"type":"string","description":"Display label (the URL or domain)."},"title":{"type":"string","description":"Page title for URLs. Empty when unavailable."},"domain":{"type":"string","description":"Domain.","examples":["example.com"]},"responseCount":{"type":"number","description":"Responses citing this source in range."},"presence":{"type":"number","description":"Percentage of responses citing this source (0–100)."},"cited":{"type":"number","description":"Percentage of appearances that were citations (0–100)."},"avgPosition":{"type":"number","description":"Average citation position."},"promptCount":{"type":"number","description":"Distinct prompts whose responses cited this source."},"urlCount":{"type":"number","description":"Unique URLs (domain summaries only). 0 for URL summaries."},"models":{"type":"array","items":{"type":"string"},"description":"Model keys whose responses cited this source."},"brandMentions":{"type":"array","items":{"type":"string"},"description":"Brand IDs mentioned alongside this source."},"type":{"type":"string","description":"URL page type. Empty when unknown."},"category":{"type":"string","description":"Domain category. Empty when unknown."},"rank":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Popularity rank. Null when unknown."},"firstSeen":{"type":"string","description":"ISO 8601 timestamp first cited. Empty when unknown."},"lastSeen":{"type":"string","description":"ISO 8601 timestamp last cited. Empty when unknown."}},"required":["id","kind","label","title","domain","responseCount","presence","cited","avgPosition","promptCount","urlCount","models","brandMentions","type","category","rank","firstSeen","lastSeen"]}},"required":["data"]}}}}}}},"/projects/{projectId}/analytics/visibility":{"get":{"operationId":"analytics.visibility","summary":"Get Visibility","description":"Returns your brand's daily visibility score over the date range, with the underlying response and mention counts. Use it to chart visibility trends or detect drops.","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Day the score was computed for (YYYY-MM-DD).","examples":["2026-01-15"]},"visibilityScore":{"type":"number","description":"Your brand's visibility score for that day."},"totalResponses":{"type":"number","description":"Number of AI responses collected that day."},"totalMentions":{"type":"number","description":"Number of times your brand was mentioned that day."}},"required":["date","visibilityScore","totalResponses","totalMentions"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/analytics/share-of-voice":{"get":{"operationId":"analytics.shareOfVoice","summary":"Get Share of Voice","description":"Returns daily mention counts per brand over the date range — one row per brand per day. Divide a brand's mentions by the day's total to compute its share of voice.","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Day the mentions were counted for (YYYY-MM-DD).","examples":["2026-01-15"]},"brandName":{"type":"string","description":"Brand display name."},"isOwnBrand":{"type":"boolean","description":"True for your own brand, false for competitors."},"mentions":{"type":"number","description":"Number of times the brand was mentioned on that day."}},"required":["date","brandName","isOwnBrand","mentions"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/analytics/brand-rankings":{"get":{"operationId":"analytics.brandRankings","summary":"Get Brand Rankings","description":"Returns aggregated per-brand performance over the date range: visibility, presence, share of voice, and mention/response counts for your own brand and competitors. This is the data behind the brand ranking view in the app.","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"brandId":{"type":"string","description":"Brand ID."},"brandName":{"type":"string","description":"Brand display name."},"isOwnBrand":{"type":"boolean","description":"True for your own brand, false for competitors."},"avgPresence":{"type":"number","description":"Fraction of responses that mention the brand (0–1)."},"avgPosition":{"type":"number","description":"Average position of the brand's mention within responses (lower is better)."},"sourcePresence":{"type":"number","description":"Percentage of responses citing a source that belongs to the brand (0–100)."},"totalMentions":{"type":"number","description":"Total number of mentions of the brand in the date range."},"totalResponses":{"type":"number","description":"Total number of responses evaluated for the brand in the date range."},"shareOfVoice":{"type":"number","description":"Brand's share of all brand mentions, as a percentage (0–100)."}},"required":["brandId","brandName","isOwnBrand","avgPresence","avgPosition","sourcePresence","totalMentions","totalResponses","shareOfVoice"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/analytics/prompt-brand-rankings":{"get":{"operationId":"analytics.promptBrandRankings","summary":"Get Prompt Brand Rankings","description":"Returns per-brand visibility, mention order, mentions, and share of voice grouped by prompt. The project's own brand is always included alongside the requested competitors.","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"competitorBrandIds":{"type":"string","minLength":1,"description":"Comma-separated competitor brand IDs. The own brand is included automatically."},"promptIds":{"type":"string","description":"Comma-separated prompt IDs. Combined with other filters using AND."},"competitorLeadsBy":{"enum":["visibility","avgPosition","shareOfVoice"],"type":"string","description":"Return only prompts where a requested competitor beats the own brand on this metric."}},"required":["startDate","endDate","competitorBrandIds"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"promptId":{"type":"string","description":"Prompt ID."},"prompt":{"type":"string","description":"Prompt text."},"language":{"type":"string","description":"ISO 639-1 language code."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code."},"totalResponses":{"type":"number","description":"Responses collected for this prompt in the date range."},"brands":{"type":"array","items":{"type":"object","properties":{"brandId":{"type":"string","description":"Brand ID."},"brandName":{"type":"string","description":"Brand display name."},"isOwnBrand":{"type":"boolean","description":"True for your own brand."},"avgPresence":{"type":"number","description":"Fraction of this prompt's responses mentioning the brand (0–1)."},"avgPosition":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Average order among brand mentions; lower is better. Null when the brand was not mentioned."},"totalMentions":{"type":"number","description":"Brand mentions for this prompt."},"shareOfVoice":{"type":"number","description":"Brand's share of all accepted-brand mentions for this prompt (0–100)."}},"required":["brandId","brandName","isOwnBrand","avgPresence","avgPosition","totalMentions","shareOfVoice"]}}},"required":["promptId","prompt","language","country","totalResponses","brands"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/analytics/prompts":{"get":{"operationId":"analytics.prompts","summary":"Get Prompt Analytics","description":"Returns per-prompt performance over the date range: response and mention counts, visibility, presence, average position, and the brands mentioned. This is the export-equivalent of the prompt analytics CSV.","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"promptId":{"type":"string","description":"Prompt ID."},"text":{"type":"string","description":"Prompt text."},"language":{"type":"string","description":"ISO 639-1 language code."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code."},"type":{"type":"string","description":"Prompt type."},"isBranded":{"type":"boolean","description":"Whether the prompt mentions a brand by name."},"totalResponses":{"type":"number","description":"AI responses collected for the prompt in range."},"totalMentions":{"type":"number","description":"Own-brand mentions across those responses."},"visibilityScore":{"type":"number","description":"Visibility score for the prompt."},"presence":{"type":"number","description":"Fraction of responses mentioning your brand (0–1)."},"avgPosition":{"type":"number","description":"Average position of your brand's mention."},"mentionedBrandIds":{"type":"array","items":{"type":"string"},"description":"All brand IDs mentioned across the prompt's responses."},"searchVolume":{"type":"number","description":"Monthly search volume for the prompt's keywords. 0 when unknown."}},"required":["promptId","text","language","country","type","isBranded","totalResponses","totalMentions","visibilityScore","presence","avgPosition","mentionedBrandIds","searchVolume"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/analytics/responses":{"get":{"operationId":"analytics.responses","summary":"Get Response Analytics","description":"Returns one row per AI response with visibility metrics — presence, own/total sources, mention counts, and the brands mentioned. This is the export-equivalent of the response analytics CSV. Use Get Response Content for the full model output.","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"responseId":{"type":"string","description":"Response ID. Join key for mentions and sources."},"promptId":{"type":"string","description":"ID of the prompt that produced the response."},"promptText":{"type":"string","description":"The prompt text sent to the model."},"preview":{"type":"string","description":"Preview of the AI response."},"model":{"type":"string","description":"Model key.","examples":["openai/chatgpt"]},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code."},"language":{"type":"string","description":"ISO 639-1 language code."},"presence":{"type":"number","description":"Fraction of your own brands mentioned in the response (0–1)."},"totalSources":{"type":"number","description":"Number of sources cited."},"ownSources":{"type":"number","description":"Number of cited sources belonging to your brand."},"totalMentions":{"type":"number","description":"Number of your accepted brands mentioned in the response."},"ownBrandMentioned":{"type":"boolean","description":"Whether your own brand was mentioned."},"mentionedBrandIds":{"type":"array","items":{"type":"string"},"description":"IDs of accepted brands mentioned in the response."},"createdAt":{"type":"string","description":"ISO 8601 timestamp when the response was collected."}},"required":["responseId","promptId","promptText","preview","model","country","language","presence","totalSources","ownSources","totalMentions","ownBrandMentioned","mentionedBrandIds","createdAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/analytics/model-usage":{"get":{"operationId":"analytics.modelUsage","summary":"Get Model Usage","description":"Returns the number of AI responses collected per model over the date range.","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string","description":"Model key.","examples":["openai/chatgpt"]},"count":{"type":"number","description":"Number of responses collected from this model in range."}},"required":["model","count"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/analytics/cross-model-performance":{"get":{"operationId":"analytics.crossModelPerformance","summary":"Get Cross-Model Performance","description":"Returns your brand's response and mention counts broken down per model, for comparing visibility across models.","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string","description":"Model key.","examples":["openai/chatgpt"]},"totalResponses":{"type":"number","description":"Responses collected from this model in range."},"totalMentions":{"type":"number","description":"Own-brand mentions in this model's responses."}},"required":["model","totalResponses","totalMentions"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/analytics/performance-breakdown":{"get":{"operationId":"analytics.performanceBreakdown","summary":"Get Performance Breakdown","description":"Returns your brand's visibility broken down by a dimension — language, country, offering, persona, or models — over the date range.","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"},"dimension":{"enum":["language","country","offering","persona","models"],"type":"string","description":"Dimension to break down by: language, country, offering, persona, or models."}},"required":["startDate","endDate","dimension"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"segment":{"type":"string","description":"Segment value for the chosen dimension (e.g. a country code, persona ID, or model key)."},"totalResponses":{"type":"number","description":"Responses collected for the segment in range."},"totalMentions":{"type":"number","description":"Own-brand mentions for the segment."},"presence":{"type":"number","description":"Fraction of the segment's responses mentioning your brand (0–1)."}},"required":["segment","totalResponses","totalMentions","presence"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/analytics/brand-perception":{"get":{"operationId":"analytics.brandPerception","summary":"Get Brand Perception","description":"Returns how each brand is described in AI responses — the share of mentions carrying each perception attribute (e.g. reliable, innovative) — for your own brand and competitors.","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"brandId":{"type":"string","description":"Brand ID."},"brandName":{"type":"string","description":"Brand display name."},"isOwnBrand":{"type":"boolean","description":"True for your own brand, false for competitors."},"perceptions":{"type":"array","items":{"type":"object","properties":{"attribute":{"type":"string","description":"Perception attribute (e.g. reliable, innovative, affordable)."},"share":{"type":"number","description":"Share of the brand's mentions carrying this attribute (0–1)."}},"required":["attribute","share"]},"description":"Per-attribute perception shares for the brand."}},"required":["brandId","brandName","isOwnBrand","perceptions"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/analytics/perception-sources":{"get":{"operationId":"analytics.perceptionSources","summary":"Get Perception Sources","description":"Returns the source URLs backing a specific perception attribute for your own brand — the citations that contributed to how your brand is perceived.","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"},"attribute":{"type":"string","description":"Perception attribute to fetch sources for (see Get Brand Perception)."}},"required":["startDate","endDate","attribute"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"Sort order: asc or desc (by appearances)."},"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Full source URL."},"domain":{"type":"string","description":"Source domain.","examples":["example.com"]},"urlPath":{"type":"string","description":"Path portion of the URL."},"title":{"type":"string","description":"Source title. Empty when unavailable."},"type":{"type":"string","description":"Source page type. Empty when unknown."},"models":{"type":"array","items":{"type":"string"},"description":"Model keys whose responses cited this source."},"appearances":{"type":"number","description":"Number of responses citing the source."},"lastSeen":{"type":"string","description":"ISO 8601 timestamp the source was last cited."}},"required":["url","domain","urlPath","title","type","models","appearances","lastSeen"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/analytics/sentiment":{"get":{"operationId":"analytics.sentiment","summary":"Get Sentiment","description":"Returns the sentiment distribution (positive / neutral / negative) of mentions for your own brand and competitors over the date range.","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"brandId":{"type":"string","description":"Brand ID."},"brandName":{"type":"string","description":"Brand display name."},"isOwnBrand":{"type":"boolean","description":"True for your own brand, false for competitors."},"totalMentions":{"type":"number","description":"Total mentions of the brand in range."},"sentiments":{"type":"array","items":{"type":"object","properties":{"sentiment":{"type":"string","description":"Sentiment label: positive, neutral, or negative."},"count":{"type":"number","description":"Mentions with this sentiment."},"share":{"type":"number","description":"Share of the brand's mentions with this sentiment (0–1)."}},"required":["sentiment","count","share"]},"description":"Sentiment distribution for the brand."}},"required":["brandId","brandName","isOwnBrand","totalMentions","sentiments"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/analytics/sentiment-sources":{"get":{"operationId":"analytics.sentimentSources","summary":"Get Sentiment Sources","description":"Returns the source URLs backing a specific sentiment for your own brand — the citations behind positive, neutral, or negative mentions.","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"},"sentiment":{"enum":["positive","neutral","negative"],"type":"string","description":"Sentiment to fetch sources for."}},"required":["startDate","endDate","sentiment"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"Sort order: asc or desc (by appearances)."},"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"description":"Page number (1-indexed, default: 1)","examples":[1]},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":1000,"description":"Items per page (default: 50, max: 1000)","examples":[50]},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Full source URL."},"domain":{"type":"string","description":"Source domain.","examples":["example.com"]},"urlPath":{"type":"string","description":"Path portion of the URL."},"title":{"type":"string","description":"Source title. Empty when unavailable."},"type":{"type":"string","description":"Source page type. Empty when unknown."},"models":{"type":"array","items":{"type":"string"},"description":"Model keys whose responses cited this source."},"appearances":{"type":"number","description":"Number of responses citing the source."},"lastSeen":{"type":"string","description":"ISO 8601 timestamp the source was last cited."}},"required":["url","domain","urlPath","title","type","models","appearances","lastSeen"]}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}}}}},"/projects/{projectId}/analytics/mention-sources":{"get":{"operationId":"analytics.mentionSources","summary":"Get Mention-Source Flow","description":"Returns the flow between cited source domains and the brands they mention as a graph (nodes + weighted links) — the data behind the mention-sources Sankey diagram.","tags":["Analytics"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"filter","in":"query","required":true,"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","examples":["2026-01-01"]},"endDate":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","examples":["2026-03-19"]},"languages":{"type":"string","description":"Comma-separated ISO 639-1 language codes","examples":["en,de"]},"countries":{"type":"string","description":"Comma-separated ISO 3166-1 alpha-2 country codes","examples":["US,DE"]},"models":{"type":"string","description":"Comma-separated model keys. Supported keys: microsoft/copilot-search, google/ai-overview, google/ai-mode, perplexity/search, gemini/search, openai/chatgpt","examples":["microsoft/copilot-search,google/ai-overview,google/ai-mode,perplexity/search,gemini/search,openai/chatgpt"]},"promptTypes":{"type":"string","description":"Comma-separated prompt types: informational, navigational, commercial, transactional","examples":["informational,navigational"]},"isBranded":{"type":"string","description":"Filter to prompts that mention a brand by name: true or false","examples":["true"]},"personaIds":{"type":"string","description":"Comma-separated persona IDs"},"offeringIds":{"type":"string","description":"Comma-separated offering IDs"},"promptTagIds":{"type":"string","description":"Comma-separated prompt tag IDs"},"brandIds":{"type":"string","description":"Comma-separated brand IDs (defaults to all accepted brands)"}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Node ID — a domain (for source nodes) or brand ID (for brand nodes)."},"type":{"type":"string","description":"Node type: domain or brand."},"label":{"type":"string","description":"Human-readable node label."},"isOwnBrand":{"type":"boolean","description":"True when a brand node is your own brand."}},"required":["id","type","label","isOwnBrand"]},"description":"Graph nodes: cited source domains and the brands they mention."},"links":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","description":"Source node ID (a domain)."},"target":{"type":"string","description":"Target node ID (a brand)."},"value":{"type":"number","description":"Number of mentions flowing from the domain to the brand."}},"required":["source","target","value"]},"description":"Weighted links from source domains to mentioned brands."}},"required":["nodes","links"]}},"required":["data"]}}}}}}},"/traffic/ingest/worker/{sourceId}":{"post":{"operationId":"traffic.ingestWorker","summary":"Ingest Traffic Events","description":"Accepts batches of request events (1–500 per call) from a Cloudflare Worker installed at your edge, used by the Temso traffic integration to attribute AI-driven visits. Requires an API key with the traffic:ingest scope; the worker generated during setup calls this endpoint for you — you don't need to call it when consuming the API.","tags":["Traffic ingestion"],"parameters":[{"name":"sourceId","in":"path","required":true,"schema":{"type":"string","minLength":1,"description":"The traffic source ID assigned during setup"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"timestamp":{"type":"integer","description":"Unix milliseconds when the batch was sent. Used for idempotent retries."},"events":{"type":"array","items":{"type":"object","properties":{"ts":{"type":"integer","description":"Unix milliseconds when the request was observed at the edge"},"ua":{"type":"string","maxLength":512,"description":"User-agent header of the request"},"method":{"type":"string","maxLength":8,"description":"HTTP method of the request","examples":["GET"]},"url":{"type":"string","maxLength":2048,"description":"Full URL that was requested"},"status":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code returned to the client"},"country":{"anyOf":[{"type":"string","minLength":2,"maxLength":2},{"type":"null"}],"description":"ISO 3166-1 alpha-2 country code of the client, null when unknown"},"asn":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Autonomous system number of the client network, null when unknown"},"referer":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"Referer header of the request, null when absent"},"ip":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"Raw client IP. Hashed and prefix-anonymized server-side, then discarded."}},"required":["ts","ua","method","url","status","country","asn","referer"]},"minItems":1,"maxItems":500}},"required":["timestamp","events"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"number","description":"Number of events stored from this batch."},"dropped":{"type":"number","description":"Number of events rejected (malformed or filtered)."},"idempotent":{"type":"boolean","description":"True when the batch was already processed and skipped."},"revoked":{"type":"boolean","description":"True when the traffic source has been revoked; stop sending events."}},"required":["accepted","dropped","idempotent","revoked"]}}}}}}},"/zapier/projects":{"get":{"operationId":"zapier.projects","summary":"List Projects (Zapier)","description":"Projects this API key can publish to, used by the Temso Zapier app to validate the connection and populate the project dropdown. Requires the content:publish scope.","tags":["Publishing"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Project ID."},"name":{"type":"string","description":"Project display name."}},"required":["id","name"]}}},"required":["data"]}}}}}}},"/projects/{projectId}/zapier/subscriptions":{"post":{"operationId":"zapier.subscribe","summary":"Create Publish Subscription","description":"Subscribes a webhook URL to article publishes in a project (used by the Temso Zapier app when a Zap is turned on). Publish payloads are POSTed to the URL as contract v1. Returns the subscription ID needed to unsubscribe.","tags":["Publishing"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"targetUrl":{"type":"string","format":"uri","description":"The URL Temso POSTs publish payloads to (e.g. the Zapier-generated hook URL)."}},"required":["targetUrl"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Subscription ID. Pass it to the unsubscribe endpoint."}},"required":["id"]}}}}}}},"/projects/{projectId}/zapier/subscriptions/{subscriptionId}":{"delete":{"operationId":"zapier.unsubscribe","summary":"Delete Publish Subscription","description":"Removes a publish subscription (used by the Temso Zapier app when a Zap is turned off). Publish payloads stop being delivered to the subscribed URL.","tags":["Publishing"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}},{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string","description":"Subscription ID returned when subscribing."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}}}}},"/projects/{projectId}/zapier/publish-samples":{"get":{"operationId":"zapier.publishSamples","summary":"List Publish Payload Samples","description":"Returns recent article publishes rendered as contract v1 payload samples (used by the Temso Zapier app so fields can be mapped in the Zap editor without a real publish). Falls back to a static sample when the project has no publishes yet.","tags":["Publishing"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":{}},"description":"Contract v1 publish payloads, newest first, each with a unique publicationId."}},"required":["data"]}}}}}}},"/projects/{projectId}/zapier/publish-confirmations":{"post":{"operationId":"zapier.confirmPublish","summary":"Confirm Publish","description":"Confirms that a delivered publish payload was applied at the destination (used by the Temso Zapier app's Confirm publication action). Drives the publication to succeeded and records the external post. Replays with the same idempotency key are no-ops.","tags":["Publishing"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","description":"Project ID (see List Projects)"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"publicationId":{"type":"string","description":"The publicationId from the delivered payload."},"remoteState":{"enum":["draft","published"],"type":"string","description":"State the destination applied: draft or published."},"externalId":{"type":"string","minLength":1,"description":"The destination's ID for the created/updated post."},"externalUrl":{"type":"string","format":"uri","description":"Public URL of the post at the destination."},"idempotencyKey":{"type":"string","minLength":1,"description":"Receiver-chosen key (e.g. the created post ID). Replays with the same key are no-ops."}},"required":["publicationId","remoteState","idempotencyKey"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"publicationId":{"type":"string"},"operationState":{"type":"string"},"remoteState":{"type":"string","description":"Remote state after confirmation."}},"required":["publicationId","operationState"]}}}}}}}}}