{"openapi":"3.0.3","info":{"title":"Peec AI Customer API","description":"Development documentation","version":"1.0.0","contact":{"name":"Peec AI Team","email":"support@peec.ai"}},"servers":[{"url":"https://api.peec.ai/customer/v1"}],"components":{"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"},"APIKeyQuery":{"type":"apiKey","in":"query","name":"api_key"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{}},"paths":{"/reports/brands":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Brands Report","description":"Get a report on Brands.\n\n## Prompt Scope\n\nThe report covers every prompt in the project that has not been deleted, archived prompts included, so history stays intact after a prompt is archived. Use a `prompt_id` filter to narrow it.\n\n## Aggregation Formulas\n\nWhen aggregating results across multiple rows/dimensions, use the following formulas:\n\n- **sentiment**: `((sum(sentiment_sum) / sum(sentiment_count)) / 2 + 0.5) * 100`\n- **position**: `sum(position_sum) / sum(position_count)`\n- **visibility**: `sum(visibility_count) / sum(visibility_total)`\n- **share_of_voice**: `mention_count / sum(mention_count)`\n- **win_rate**: `sum(win_count) / sum(visibility_total)`\n\n## `filters` vs `having`\n\n`filters` are **pre-aggregation** row filters (applied as WHERE before GROUP BY). They shrink both the numerator and the denominator of ratio metrics. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `brand_id`. Note that `brand_id` in `filters` shrinks `share_of_voice`'s denominator too — so filtering to one brand collapses SoV to 1.0. Use `having` for `brand_id` if you want SoV preserved.\n\n`having` are **post-aggregation** row filters (applied as HAVING after GROUP BY). They select which aggregated rows are returned and do **not** shrink ratio-metric denominators. Filtering `{field: \"brand_id\", values: [X]}` here returns only brand X's row, but `share_of_voice` still divides X's mentions by mentions across all in-scope brands — so SoV stays in [0, 1]. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `brand_id`.\n\nPopulation fields (`model_id` etc.) are also allowed in `having` but require the matching value in `dimensions` so the column appears in GROUP BY; otherwise the request is rejected.\n\nWhen `dimensions` are requested, the `share_of_voice` denominator follows the same grouping as the numerator. Requesting `prompt_id` as a dimension produces per-(brand × prompt) rows whose `share_of_voice` is the brand's mentions in that prompt divided by all brands' mentions in that prompt.","tags":["Reports"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":500000},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"dimensions":{"example":["tag_id","model_id"],"description":"Dimensions to break down the report by.","type":"array","items":{"type":"string","enum":["prompt_id","model_id","model_channel_id","tag_id","topic_id","date","week","month","country_code","chat_id"]}},"filters":{"description":"Pre-aggregation row filters (applied as WHERE before grouping). Shrinks both the numerator and the denominator of ratio metrics. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `brand_id`. Filtering by `brand_id` here also shrinks `share_of_voice`'s denominator — so SoV collapses to 1.0 when scoping to a single brand. If you want SoV preserved (X's share against all in-scope brands), put `brand_id` in `having` instead. Multiple filters are AND'd.","example":[{"field":"model_id","operator":"in","values":["gpt-4o-search"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["shopping_category_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]}]}},"having":{"description":"Post-aggregation row filters (applied as HAVING after grouping). Selects which aggregated rows are returned without shrinking ratio-metric denominators. Multiple filters are AND'd together.\n\nPopulation fields — `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id` — and `brand_id` take `{field, operator, values}` with operator `in` or `not_in`. Population fields require the matching value in `dimensions` so the column appears in GROUP BY.\n\nMetric fields — `visibility`, `share_of_voice`, `win_rate`, `sentiment`, `position` — take `{field, operator, value}` with operator `gt`, `gte`, `lt` or `lte`, and need no matching `dimensions` entry. Each compares against the metric in the unit this endpoint returns it: `visibility`, `share_of_voice` and `win_rate` as a 0-1 ratio, `sentiment` as a 0-100 score, `position` as a rank where 1 is best. Values are validated against that unit, so a percentage where a ratio belongs is rejected rather than silently matching nothing. Two predicates on one field make a range; stating the same edge of a field twice, or a range no row could satisfy, is rejected. A row whose metric is undefined — no position or sentiment samples in the window — matches neither.\n\nA metric predicate tests whichever row the grouping produces, so the same predicate asks a different question at each grouping: with `dimensions: [\"prompt_id\"]` it selects the prompts that individually pass, and with no dimensions it tests the brand's rolled-up totals.","example":[{"field":"brand_id","operator":"in","values":["kw_abc123"]},{"field":"visibility","operator":"gte","value":0.1},{"field":"visibility","operator":"lte","value":0.9}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["visibility","share_of_voice","sentiment","position","win_rate"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"number"}},"required":["field","operator","value"],"description":"Filters aggregated rows on a computed metric, in the same unit the report returns it: visibility, share_of_voice and win_rate as a 0-1 ratio, sentiment as a 0-100 score, position as a rank where 1 is best. Each field's value is validated against that unit, so a percentage where a ratio belongs is rejected rather than matching nothing. Combine two predicates for a range; stating the same bound twice, or a range no row can satisfy, is rejected. A row whose metric is undefined — no position or sentiment samples in the window — matches neither.","example":{"field":"visibility","operator":"gte","value":0.5}}]}},"order_by":{"description":"Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied.","example":[{"field":"visibility","direction":"desc"}],"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["visibility","visibility_count","mention_count","sentiment","position","share_of_voice","win_rate","date","week","month"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]}},"required":["field"]}},"include_previous_period":{"description":"Legacy comparison switch. When true without explicit comparison dates, each row gains a `previous` object computed over the adjacent equal-length window. Supplying previous_start_date and previous_end_date enables comparison over that exact window without this flag.","type":"boolean"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":500000},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"dimensions":{"example":["tag_id","model_id"],"description":"Dimensions to break down the report by.","type":"array","items":{"type":"string","enum":["prompt_id","model_id","model_channel_id","tag_id","topic_id","date","week","month","country_code","chat_id"]}},"filters":{"description":"Pre-aggregation row filters (applied as WHERE before grouping). Shrinks both the numerator and the denominator of ratio metrics. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `brand_id`. Filtering by `brand_id` here also shrinks `share_of_voice`'s denominator — so SoV collapses to 1.0 when scoping to a single brand. If you want SoV preserved (X's share against all in-scope brands), put `brand_id` in `having` instead. Multiple filters are AND'd.","example":[{"field":"model_id","operator":"in","values":["gpt-4o-search"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["shopping_category_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]}]}},"having":{"description":"Post-aggregation row filters (applied as HAVING after grouping). Selects which aggregated rows are returned without shrinking ratio-metric denominators. Multiple filters are AND'd together.\n\nPopulation fields — `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id` — and `brand_id` take `{field, operator, values}` with operator `in` or `not_in`. Population fields require the matching value in `dimensions` so the column appears in GROUP BY.\n\nMetric fields — `visibility`, `share_of_voice`, `win_rate`, `sentiment`, `position` — take `{field, operator, value}` with operator `gt`, `gte`, `lt` or `lte`, and need no matching `dimensions` entry. Each compares against the metric in the unit this endpoint returns it: `visibility`, `share_of_voice` and `win_rate` as a 0-1 ratio, `sentiment` as a 0-100 score, `position` as a rank where 1 is best. Values are validated against that unit, so a percentage where a ratio belongs is rejected rather than silently matching nothing. Two predicates on one field make a range; stating the same edge of a field twice, or a range no row could satisfy, is rejected. A row whose metric is undefined — no position or sentiment samples in the window — matches neither.\n\nA metric predicate tests whichever row the grouping produces, so the same predicate asks a different question at each grouping: with `dimensions: [\"prompt_id\"]` it selects the prompts that individually pass, and with no dimensions it tests the brand's rolled-up totals.","example":[{"field":"brand_id","operator":"in","values":["kw_abc123"]},{"field":"visibility","operator":"gte","value":0.1},{"field":"visibility","operator":"lte","value":0.9}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["visibility","share_of_voice","sentiment","position","win_rate"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"number"}},"required":["field","operator","value"],"description":"Filters aggregated rows on a computed metric, in the same unit the report returns it: visibility, share_of_voice and win_rate as a 0-1 ratio, sentiment as a 0-100 score, position as a rank where 1 is best. Each field's value is validated against that unit, so a percentage where a ratio belongs is rejected rather than matching nothing. Combine two predicates for a range; stating the same bound twice, or a range no row can satisfy, is rejected. A row whose metric is undefined — no position or sentiment samples in the window — matches neither.","example":{"field":"visibility","operator":"gte","value":0.5}}]}},"order_by":{"description":"Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied.","example":[{"field":"visibility","direction":"desc"}],"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["visibility","visibility_count","mention_count","sentiment","position","share_of_voice","win_rate","date","week","month"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]}},"required":["field"]}},"include_previous_period":{"description":"Legacy comparison switch. When true without explicit comparison dates, each row gains a `previous` object computed over the adjacent equal-length window. Supplying previous_start_date and previous_end_date enables comparison over that exact window without this flag.","type":"boolean"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":500000},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"dimensions":{"example":["tag_id","model_id"],"description":"Dimensions to break down the report by.","type":"array","items":{"type":"string","enum":["prompt_id","model_id","model_channel_id","tag_id","topic_id","date","week","month","country_code","chat_id"]}},"filters":{"description":"Pre-aggregation row filters (applied as WHERE before grouping). Shrinks both the numerator and the denominator of ratio metrics. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `brand_id`. Filtering by `brand_id` here also shrinks `share_of_voice`'s denominator — so SoV collapses to 1.0 when scoping to a single brand. If you want SoV preserved (X's share against all in-scope brands), put `brand_id` in `having` instead. Multiple filters are AND'd.","example":[{"field":"model_id","operator":"in","values":["gpt-4o-search"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["shopping_category_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]}]}},"having":{"description":"Post-aggregation row filters (applied as HAVING after grouping). Selects which aggregated rows are returned without shrinking ratio-metric denominators. Multiple filters are AND'd together.\n\nPopulation fields — `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id` — and `brand_id` take `{field, operator, values}` with operator `in` or `not_in`. Population fields require the matching value in `dimensions` so the column appears in GROUP BY.\n\nMetric fields — `visibility`, `share_of_voice`, `win_rate`, `sentiment`, `position` — take `{field, operator, value}` with operator `gt`, `gte`, `lt` or `lte`, and need no matching `dimensions` entry. Each compares against the metric in the unit this endpoint returns it: `visibility`, `share_of_voice` and `win_rate` as a 0-1 ratio, `sentiment` as a 0-100 score, `position` as a rank where 1 is best. Values are validated against that unit, so a percentage where a ratio belongs is rejected rather than silently matching nothing. Two predicates on one field make a range; stating the same edge of a field twice, or a range no row could satisfy, is rejected. A row whose metric is undefined — no position or sentiment samples in the window — matches neither.\n\nA metric predicate tests whichever row the grouping produces, so the same predicate asks a different question at each grouping: with `dimensions: [\"prompt_id\"]` it selects the prompts that individually pass, and with no dimensions it tests the brand's rolled-up totals.","example":[{"field":"brand_id","operator":"in","values":["kw_abc123"]},{"field":"visibility","operator":"gte","value":0.1},{"field":"visibility","operator":"lte","value":0.9}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["visibility","share_of_voice","sentiment","position","win_rate"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"number"}},"required":["field","operator","value"],"description":"Filters aggregated rows on a computed metric, in the same unit the report returns it: visibility, share_of_voice and win_rate as a 0-1 ratio, sentiment as a 0-100 score, position as a rank where 1 is best. Each field's value is validated against that unit, so a percentage where a ratio belongs is rejected rather than matching nothing. Combine two predicates for a range; stating the same bound twice, or a range no row can satisfy, is rejected. A row whose metric is undefined — no position or sentiment samples in the window — matches neither.","example":{"field":"visibility","operator":"gte","value":0.5}}]}},"order_by":{"description":"Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied.","example":[{"field":"visibility","direction":"desc"}],"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["visibility","visibility_count","mention_count","sentiment","position","share_of_voice","win_rate","date","week","month"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]}},"required":["field"]}},"include_previous_period":{"description":"Legacy comparison switch. When true without explicit comparison dates, each row gains a `previous` object computed over the adjacent equal-length window. Supplying previous_start_date and previous_end_date enables comparison over that exact window without this flag.","type":"boolean"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"object","properties":{"id":{"type":"string","example":"kw_915e742b-396d-4a86-ad57-8bc84e8c2232"},"name":{"type":"string","example":"Peec AI"}},"required":["id","name"]},"prompt":{"type":"object","properties":{"id":{"type":"string","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d"}},"required":["id"]},"model":{"deprecated":true,"description":"Deprecated: use model_channel instead","type":"object","properties":{"id":{"type":"string","example":"gpt-4o-search"}},"required":["id"]},"model_channel":{"type":"object","properties":{"id":{"type":"string","example":"openai-1"}},"required":["id"]},"tag":{"type":"object","properties":{"id":{"type":"string","example":"tg_23abec5b-100a-4261-9ee7-1effe68f0149"}},"required":["id"]},"topic":{"type":"object","properties":{"id":{"type":"string","example":"to_e6b8cdd3-a51b-4d94-a866-28dbe6b830a6"}},"required":["id"]},"country_code":{"example":"US","type":"string"},"chat":{"type":"object","properties":{"id":{"type":"string","example":"ch_abc123"}},"required":["id"]},"date":{"example":"2025-03-15","type":"string"},"week":{"example":"2025-03-10","description":"Start (Monday) of the ISO week bucket.","type":"string"},"month":{"example":"2025-03-01","description":"First day of the month bucket.","type":"string"},"share_of_voice":{"example":0.15,"description":"Share of total mentions attributed to this brand within the row's dimension grouping. The denominator sums mentions across all brands within the same dimension values (e.g. when grouping by `prompt_id`, across all brands within that prompt). Pre-aggregation `filters` shrink both numerator and denominator together — filtering by `brand_id` here collapses SoV to 1.0. Post-aggregation `having` (e.g. `brand_id`) selects which rows are returned without shrinking the denominator, so SoV stays in [0, 1].","type":"number"},"mention_count":{"type":"number","example":42},"visibility":{"type":"number","example":0.5},"visibility_count":{"type":"number","example":5},"visibility_total":{"type":"number","example":10},"win_rate":{"example":0.2,"description":"The share of chats where the brand is ranked first (0-1 ratio). A chat counts when the brand is named before every other brand in the answer, tracked or not. The denominator is `visibility_total`.","type":"number","minimum":0,"maximum":1},"win_count":{"example":2,"type":"number"},"sentiment":{"example":50,"type":"number"},"sentiment_sum":{"example":0,"type":"number"},"sentiment_count":{"example":10,"type":"number"},"position":{"example":1.5,"type":"number"},"position_sum":{"example":15,"type":"number"},"position_count":{"example":10,"type":"number"},"previous":{"description":"Same metrics computed over the requested comparison window, present when explicit comparison dates or include_previous_period enabled comparison and a matching row existed in it.","type":"object","properties":{"date":{"example":"2025-03-15","type":"string"},"share_of_voice":{"example":0.15,"description":"Share of total mentions attributed to this brand within the row's dimension grouping. The denominator sums mentions across all brands within the same dimension values (e.g. when grouping by `prompt_id`, across all brands within that prompt). Pre-aggregation `filters` shrink both numerator and denominator together — filtering by `brand_id` here collapses SoV to 1.0. Post-aggregation `having` (e.g. `brand_id`) selects which rows are returned without shrinking the denominator, so SoV stays in [0, 1].","type":"number"},"mention_count":{"type":"number","example":42},"visibility":{"type":"number","example":0.5},"visibility_count":{"type":"number","example":5},"visibility_total":{"type":"number","example":10},"win_rate":{"example":0.2,"description":"The share of chats where the brand is ranked first (0-1 ratio). A chat counts when the brand is named before every other brand in the answer, tracked or not. The denominator is `visibility_total`.","type":"number","minimum":0,"maximum":1},"win_count":{"example":2,"type":"number"},"sentiment":{"example":50,"type":"number"},"sentiment_sum":{"example":0,"type":"number"},"sentiment_count":{"example":10,"type":"number"},"position":{"example":1.5,"type":"number"},"position_sum":{"example":15,"type":"number"},"position_count":{"example":10,"type":"number"}},"required":["mention_count","visibility","visibility_count","visibility_total"]}},"required":["brand","mention_count","visibility","visibility_count","visibility_total"]}}},"required":["data"],"description":"Success"}}}}},"operationId":"postReportsBrands"}},"/reports/domains":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Domains Report","description":"Get a report on Source Domains.\n\n## Prompt Scope\n\nThe report covers every prompt in the project that has not been deleted, archived prompts included, so history stays intact after a prompt is archived. Use a `prompt_id` filter to narrow it.\n\n## Aggregation Formulas\n\nWhen aggregating results across multiple rows/dimensions, use the following formulas:\n\n- **citation_rate**: `sum(citation_count) / sum(retrieval_count)`\n- **retrieval_rate**: `sum(retrieval_count) / sum(total_chat_count)`\n- **retrieval_percentage**: `sum(retrieved_chat_count) / sum(total_chat_count)`\n- **cited_percentage**: `sum(cited_chat_count) / sum(total_chat_count)`\n\n## `filters` vs `having`\n\n`filters` are **pre-aggregation** row filters (applied as WHERE before GROUP BY) on the source-row table. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`, `url_tag_id`, `domain_tag_id`.\n- Population (`model_id`, `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`) shrink both numerator and denominator (`total_chat_count`).\n- Source-side (`domain`, `domain_classification`, `url`, `url_classification`) and per-row mentioned-brand predicates (`mentioned_brand_id`, `mentioned_brand_count`, `gap`) shrink the source-row scope feeding aggregation. `total_chat_count` is computed from a chat-level table that doesn't carry these columns, so the denominator narrows only on chat-level fields.\n\n`having` are **post-aggregation** row filters (applied as HAVING after GROUP BY). Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`. They select which aggregated rows are returned and do not affect denominators.","tags":["Reports"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"dimensions":{"example":["tag_id","model_id"],"description":"Dimensions to break down the report by.","type":"array","items":{"type":"string","enum":["prompt_id","model_id","model_channel_id","tag_id","topic_id","date","week","month","country_code","chat_id"]}},"filters":{"description":"Pre-aggregation row filters (applied as WHERE before grouping). Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`, `url_tag_id`, `domain_tag_id`. Population fields (model/country/prompt/tag/topic/chat) shrink both numerator and denominator. Source-side fields and per-row mentioned-brand predicates shrink the source-row scope feeding aggregation; `total_chat_count` comes from a chat-level table that doesn't carry these columns, so they narrow the numerator only. Multiple filters are AND'd.","example":[{"field":"model_id","operator":"in","values":["gpt-4o-search"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or a custom domain classification name.","example":["CORPORATE","EDITORIAL","INSTITUTIONAL","OTHER","REFERENCE","UGC","COMPETITOR","OWN","RELATED"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, REVIEW, OTHER) or a custom URL classification name.","example":["HOMEPAGE","CATEGORY_PAGE","PRODUCT_PAGE","LISTICLE","COMPARISON","PROFILE","ALTERNATIVE","DISCUSSION","HOW_TO_GUIDE","ARTICLE","REVIEW","OTHER"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_count"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["gap"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["url_tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Source tag ids. `in` keeps URLs carrying any of them, `has_all` keeps URLs carrying every one of them, `not_in` keeps URLs carrying none of them.","example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Source tag ids. `in` keeps sources on domains carrying any of them, `has_all` keeps sources on domains carrying every one of them, `not_in` keeps sources on domains carrying none of them.","example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"]}},"required":["field","operator","values"]}]}},"having":{"description":"Post-aggregation row filters (applied as HAVING after grouping). Select which aggregated domain rows are returned. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap` — population fields require the matching value in `dimensions`. Multiple filters are AND'd.","example":[{"field":"domain","operator":"in","values":["example.com"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or a custom domain classification name.","example":["CORPORATE","EDITORIAL","INSTITUTIONAL","OTHER","REFERENCE","UGC","COMPETITOR","OWN","RELATED"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_count"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["gap"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]}]}},"order_by":{"description":"Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied.","example":[{"field":"citation_rate","direction":"desc"}],"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["citation_rate","retrieval_count","citation_count","date","week","month"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]}},"required":["field"]}}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"dimensions":{"example":["tag_id","model_id"],"description":"Dimensions to break down the report by.","type":"array","items":{"type":"string","enum":["prompt_id","model_id","model_channel_id","tag_id","topic_id","date","week","month","country_code","chat_id"]}},"filters":{"description":"Pre-aggregation row filters (applied as WHERE before grouping). Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`, `url_tag_id`, `domain_tag_id`. Population fields (model/country/prompt/tag/topic/chat) shrink both numerator and denominator. Source-side fields and per-row mentioned-brand predicates shrink the source-row scope feeding aggregation; `total_chat_count` comes from a chat-level table that doesn't carry these columns, so they narrow the numerator only. Multiple filters are AND'd.","example":[{"field":"model_id","operator":"in","values":["gpt-4o-search"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or a custom domain classification name.","example":["CORPORATE","EDITORIAL","INSTITUTIONAL","OTHER","REFERENCE","UGC","COMPETITOR","OWN","RELATED"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, REVIEW, OTHER) or a custom URL classification name.","example":["HOMEPAGE","CATEGORY_PAGE","PRODUCT_PAGE","LISTICLE","COMPARISON","PROFILE","ALTERNATIVE","DISCUSSION","HOW_TO_GUIDE","ARTICLE","REVIEW","OTHER"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_count"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["gap"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["url_tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Source tag ids. `in` keeps URLs carrying any of them, `has_all` keeps URLs carrying every one of them, `not_in` keeps URLs carrying none of them.","example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Source tag ids. `in` keeps sources on domains carrying any of them, `has_all` keeps sources on domains carrying every one of them, `not_in` keeps sources on domains carrying none of them.","example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"]}},"required":["field","operator","values"]}]}},"having":{"description":"Post-aggregation row filters (applied as HAVING after grouping). Select which aggregated domain rows are returned. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap` — population fields require the matching value in `dimensions`. Multiple filters are AND'd.","example":[{"field":"domain","operator":"in","values":["example.com"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or a custom domain classification name.","example":["CORPORATE","EDITORIAL","INSTITUTIONAL","OTHER","REFERENCE","UGC","COMPETITOR","OWN","RELATED"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_count"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["gap"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]}]}},"order_by":{"description":"Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied.","example":[{"field":"citation_rate","direction":"desc"}],"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["citation_rate","retrieval_count","citation_count","date","week","month"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]}},"required":["field"]}}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"dimensions":{"example":["tag_id","model_id"],"description":"Dimensions to break down the report by.","type":"array","items":{"type":"string","enum":["prompt_id","model_id","model_channel_id","tag_id","topic_id","date","week","month","country_code","chat_id"]}},"filters":{"description":"Pre-aggregation row filters (applied as WHERE before grouping). Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`, `url_tag_id`, `domain_tag_id`. Population fields (model/country/prompt/tag/topic/chat) shrink both numerator and denominator. Source-side fields and per-row mentioned-brand predicates shrink the source-row scope feeding aggregation; `total_chat_count` comes from a chat-level table that doesn't carry these columns, so they narrow the numerator only. Multiple filters are AND'd.","example":[{"field":"model_id","operator":"in","values":["gpt-4o-search"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or a custom domain classification name.","example":["CORPORATE","EDITORIAL","INSTITUTIONAL","OTHER","REFERENCE","UGC","COMPETITOR","OWN","RELATED"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, REVIEW, OTHER) or a custom URL classification name.","example":["HOMEPAGE","CATEGORY_PAGE","PRODUCT_PAGE","LISTICLE","COMPARISON","PROFILE","ALTERNATIVE","DISCUSSION","HOW_TO_GUIDE","ARTICLE","REVIEW","OTHER"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_count"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["gap"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["url_tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Source tag ids. `in` keeps URLs carrying any of them, `has_all` keeps URLs carrying every one of them, `not_in` keeps URLs carrying none of them.","example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Source tag ids. `in` keeps sources on domains carrying any of them, `has_all` keeps sources on domains carrying every one of them, `not_in` keeps sources on domains carrying none of them.","example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"]}},"required":["field","operator","values"]}]}},"having":{"description":"Post-aggregation row filters (applied as HAVING after grouping). Select which aggregated domain rows are returned. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap` — population fields require the matching value in `dimensions`. Multiple filters are AND'd.","example":[{"field":"domain","operator":"in","values":["example.com"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or a custom domain classification name.","example":["CORPORATE","EDITORIAL","INSTITUTIONAL","OTHER","REFERENCE","UGC","COMPETITOR","OWN","RELATED"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_count"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["gap"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]}]}},"order_by":{"description":"Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied.","example":[{"field":"citation_rate","direction":"desc"}],"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["citation_rate","retrieval_count","citation_count","date","week","month"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]}},"required":["field"]}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","example":"example.com"},"classification":{"nullable":true,"description":"Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or the name of a custom domain classification.","example":"UGC","type":"string"},"prompt":{"type":"object","properties":{"id":{"type":"string","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d"}},"required":["id"]},"model":{"deprecated":true,"description":"Deprecated: use model_channel instead","type":"object","properties":{"id":{"type":"string","example":"gpt-4o-search"}},"required":["id"]},"model_channel":{"type":"object","properties":{"id":{"type":"string","example":"openai-1"}},"required":["id"]},"tag":{"type":"object","properties":{"id":{"type":"string","example":"tg_23abec5b-100a-4261-9ee7-1effe68f0149"}},"required":["id"]},"topic":{"type":"object","properties":{"id":{"type":"string","example":"to_e6b8cdd3-a51b-4d94-a866-28dbe6b830a6"}},"required":["id"]},"country_code":{"example":"US","type":"string"},"chat":{"type":"object","properties":{"id":{"type":"string","example":"ch_abc123"}},"required":["id"]},"date":{"type":"string"},"week":{"example":"2025-03-10","description":"Start (Monday) of the ISO week bucket.","type":"string"},"month":{"example":"2025-03-01","description":"First day of the month bucket.","type":"string"},"usage_rate":{"type":"number","example":0.8,"deprecated":true,"description":"Deprecated: use retrieved_percentage or retrieval_rate instead"},"citation_avg":{"type":"number","example":2.5,"deprecated":true,"description":"Deprecated: use citation_rate instead"},"retrieved_percentage":{"type":"number","example":0.6},"cited_percentage":{"type":"number","example":0.4,"description":"Share of chats in scope that cite at least one URL from this domain inline, from 0 to 1. Each chat counts once, however often it cites the domain"},"retrieval_rate":{"type":"number","example":1.2},"citation_rate":{"type":"number","example":1.5},"retrieval_count":{"type":"number","example":24,"description":"Total number of distinct URL retrievals from this domain across all chats"},"citation_count":{"type":"number","example":12,"description":"Total number of citations from this domain"},"retrieved_chat_count":{"type":"number","example":18,"description":"Number of distinct chats in which at least one URL from this domain was retrieved"},"cited_chat_count":{"type":"number","example":12,"description":"Number of distinct chats that cite at least one URL from this domain inline"},"total_chat_count":{"type":"number","example":30,"description":"Total number of chats in scope for this row, used as the denominator for `retrieval_rate` and `retrieval_percentage`. Pre-aggregation `filters` shrink this count; post-aggregation `having` filters (e.g. `domain`, `domain_classification`) do not."},"mentioned_brands":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]},"description":"Brand IDs mentioned alongside URLs from this domain"}},"required":["domain","classification","usage_rate","citation_avg","retrieved_percentage","cited_percentage","retrieval_rate","citation_rate","retrieval_count","citation_count","retrieved_chat_count","cited_chat_count","total_chat_count","mentioned_brands"]}}},"required":["data"],"description":"Success"}}}}},"operationId":"postReportsDomains"}},"/reports/links":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Links Report","description":"Get a report on the domains AI answers linked to in their own text. A link is a URL the answer wrote into its prose; it is never one of the sources the answer retrieved or cited, which the domains report covers.\n\n## Prompt Scope\n\nThe report covers every prompt in the project that has not been deleted, archived prompts included, so history stays intact after a prompt is archived. Use a `prompt_id` filter to narrow it.\n\n## Aggregation Formulas\n\nWhen aggregating results across multiple rows/dimensions:\n\n- **linked_percentage**: `sum(linked_chat_count) / sum(total_chat_count)`, only across rows that do not split the same chats (not across `url` rows of one domain).\n- **average_link_position** is not additive across rows. Request the coarser breakdown instead.","tags":["Reports"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"dimensions":{"example":["prompt_id"],"description":"Dimensions to break down the report by. `url` breaks each linked domain down into the pages linked.","type":"array","items":{"type":"string","enum":["prompt_id","model_id","model_channel_id","tag_id","topic_id","date","week","month","country_code","chat_id","url"]}},"filters":{"description":"Row filters applied before aggregation. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `url`. Population fields (model/country/prompt/tag/topic/chat) shrink both the linked chats and `total_chat_count`; `domain` and `url` narrow the linked chats only. Multiple filters are AND'd.","example":[{"field":"model_channel_id","operator":"in","values":["openai-0"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]}]}},"order_by":{"description":"Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied.","example":[{"field":"linked_chat_count","direction":"desc"}],"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["linked_chat_count","link_count","average_link_position","date","week","month"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]}},"required":["field"]}}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"dimensions":{"example":["prompt_id"],"description":"Dimensions to break down the report by. `url` breaks each linked domain down into the pages linked.","type":"array","items":{"type":"string","enum":["prompt_id","model_id","model_channel_id","tag_id","topic_id","date","week","month","country_code","chat_id","url"]}},"filters":{"description":"Row filters applied before aggregation. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `url`. Population fields (model/country/prompt/tag/topic/chat) shrink both the linked chats and `total_chat_count`; `domain` and `url` narrow the linked chats only. Multiple filters are AND'd.","example":[{"field":"model_channel_id","operator":"in","values":["openai-0"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]}]}},"order_by":{"description":"Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied.","example":[{"field":"linked_chat_count","direction":"desc"}],"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["linked_chat_count","link_count","average_link_position","date","week","month"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]}},"required":["field"]}}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"dimensions":{"example":["prompt_id"],"description":"Dimensions to break down the report by. `url` breaks each linked domain down into the pages linked.","type":"array","items":{"type":"string","enum":["prompt_id","model_id","model_channel_id","tag_id","topic_id","date","week","month","country_code","chat_id","url"]}},"filters":{"description":"Row filters applied before aggregation. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `url`. Population fields (model/country/prompt/tag/topic/chat) shrink both the linked chats and `total_chat_count`; `domain` and `url` narrow the linked chats only. Multiple filters are AND'd.","example":[{"field":"model_channel_id","operator":"in","values":["openai-0"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]}]}},"order_by":{"description":"Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied.","example":[{"field":"linked_chat_count","direction":"desc"}],"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["linked_chat_count","link_count","average_link_position","date","week","month"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]}},"required":["field"]}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","example":"acme.com"},"url":{"description":"The linked page, when the `url` dimension is set.","example":"https://acme.com/pricing","type":"string"},"classification":{"type":"string","description":"OWN, COMPETITOR or RELATED when the domain belongs to a tracked brand, the name of a custom domain classification, or OTHER.","example":"COMPETITOR"},"prompt":{"type":"object","properties":{"id":{"type":"string","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d"}},"required":["id"]},"model":{"deprecated":true,"description":"Deprecated: use model_channel instead","type":"object","properties":{"id":{"type":"string","example":"gpt-4o-search"}},"required":["id"]},"model_channel":{"type":"object","properties":{"id":{"type":"string","example":"openai-1"}},"required":["id"]},"tag":{"type":"object","properties":{"id":{"type":"string","example":"tg_23abec5b-100a-4261-9ee7-1effe68f0149"}},"required":["id"]},"topic":{"type":"object","properties":{"id":{"type":"string","example":"to_e6b8cdd3-a51b-4d94-a866-28dbe6b830a6"}},"required":["id"]},"country_code":{"example":"US","type":"string"},"chat":{"type":"object","properties":{"id":{"type":"string","example":"ch_abc123"}},"required":["id"]},"date":{"type":"string"},"week":{"example":"2025-03-10","description":"Start (Monday) of the ISO week bucket.","type":"string"},"month":{"example":"2025-03-01","description":"First day of the month bucket.","type":"string"},"linked_chat_count":{"type":"number","example":18,"description":"Number of distinct chats whose answer linked to this domain in its own text."},"linked_percentage":{"type":"number","example":0.6,"description":"`linked_chat_count / total_chat_count`, from 0 to 1."},"link_count":{"type":"number","example":24,"description":"Total number of links to this domain across those chats. An answer can link to the same page more than once."},"average_link_position":{"type":"number","example":1.4,"description":"Average rank of this domain's links among each answer's links, where 1 is the first link in the answer."},"total_chat_count":{"type":"number","example":30,"description":"Total number of chats in scope for this row, the denominator for `linked_percentage`. Population filters shrink it; `domain` and `url` filters do not."}},"required":["domain","classification","linked_chat_count","linked_percentage","link_count","average_link_position","total_chat_count"]}}},"required":["data"],"description":"Success"}}}}},"operationId":"postReportsLinks"}},"/reports/urls":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get URLs Report","description":"Get a report on Source URLs.\n\n## Prompt Scope\n\nThe report covers every prompt in the project that has not been deleted, archived prompts included, so history stays intact after a prompt is archived. Use a `prompt_id` filter to narrow it.\n\n## Aggregation Formulas\n\nWhen aggregating results across multiple rows/dimensions, use the following formula:\n\n- **citation_rate**: `sum(citation_count) / sum(retrieval_count)`\n- **citation_position**: `sum(citation_position_sum) / sum(citation_position_count)`\n\n## `filters` vs `having`\n\n`filters` are **pre-aggregation** row filters (applied as WHERE before GROUP BY) on the source-row table. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`, `url_tag_id`, `domain_tag_id`.\n- Population (`model_id`, `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`) shrink both numerator and denominator scope.\n- Source-side (`domain`, `domain_classification`, `url`, `url_classification`) and per-row mentioned-brand predicates (`mentioned_brand_id`, `mentioned_brand_count`, `gap`) shrink the source-row scope feeding aggregation.\n\n`having` are **post-aggregation** row filters (applied as HAVING after GROUP BY). Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`.\n\n`citation_rate` is computed per row from numerator (`citation_count`) and denominator (`retrieval_count`) inside the same aggregation group, so neither filter placement can collapse it. The shared fields exist in both `filters` and `having` — use `filters` to prune source rows before aggregation (typically more efficient), use `having` to operate on the aggregated `mentioned_brands` union for entity-wide selection.","tags":["Reports"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"dimensions":{"example":["tag_id","model_id"],"description":"Dimensions to break down the report by.","type":"array","items":{"type":"string","enum":["prompt_id","model_id","model_channel_id","tag_id","topic_id","date","week","month","country_code","chat_id"]}},"filters":{"description":"Pre-aggregation row filters (applied as WHERE before grouping). Restrict which raw source-rows feed into the per-URL aggregation. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`, `url_tag_id`, `domain_tag_id`. Multiple filters are AND'd.","example":[{"field":"model_id","operator":"in","values":["gpt-4o-search"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or a custom domain classification name.","example":["CORPORATE","EDITORIAL","INSTITUTIONAL","OTHER","REFERENCE","UGC","COMPETITOR","OWN","RELATED"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, REVIEW, OTHER) or a custom URL classification name.","example":["HOMEPAGE","CATEGORY_PAGE","PRODUCT_PAGE","LISTICLE","COMPARISON","PROFILE","ALTERNATIVE","DISCUSSION","HOW_TO_GUIDE","ARTICLE","REVIEW","OTHER"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_count"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["gap"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["url_tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Source tag ids. `in` keeps URLs carrying any of them, `has_all` keeps URLs carrying every one of them, `not_in` keeps URLs carrying none of them.","example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Source tag ids. `in` keeps sources on domains carrying any of them, `has_all` keeps sources on domains carrying every one of them, `not_in` keeps sources on domains carrying none of them.","example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"]}},"required":["field","operator","values"]}]}},"having":{"description":"Post-aggregation row filters (applied as HAVING after grouping). Select which aggregated URL rows are returned. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap` — population fields require the matching value in `dimensions`. Multiple filters are AND'd.","example":[{"field":"url","operator":"in","values":["https://example.com/page"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or a custom domain classification name.","example":["CORPORATE","EDITORIAL","INSTITUTIONAL","OTHER","REFERENCE","UGC","COMPETITOR","OWN","RELATED"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, REVIEW, OTHER) or a custom URL classification name.","example":["HOMEPAGE","CATEGORY_PAGE","PRODUCT_PAGE","LISTICLE","COMPARISON","PROFILE","ALTERNATIVE","DISCUSSION","HOW_TO_GUIDE","ARTICLE","REVIEW","OTHER"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_count"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["gap"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]}]}},"order_by":{"description":"Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied.","example":[{"field":"retrieval_count","direction":"desc"}],"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["retrieval_count","retrievals","citation_count","citation_rate","citation_position","date","week","month"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]}},"required":["field"]}}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"dimensions":{"example":["tag_id","model_id"],"description":"Dimensions to break down the report by.","type":"array","items":{"type":"string","enum":["prompt_id","model_id","model_channel_id","tag_id","topic_id","date","week","month","country_code","chat_id"]}},"filters":{"description":"Pre-aggregation row filters (applied as WHERE before grouping). Restrict which raw source-rows feed into the per-URL aggregation. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`, `url_tag_id`, `domain_tag_id`. Multiple filters are AND'd.","example":[{"field":"model_id","operator":"in","values":["gpt-4o-search"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or a custom domain classification name.","example":["CORPORATE","EDITORIAL","INSTITUTIONAL","OTHER","REFERENCE","UGC","COMPETITOR","OWN","RELATED"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, REVIEW, OTHER) or a custom URL classification name.","example":["HOMEPAGE","CATEGORY_PAGE","PRODUCT_PAGE","LISTICLE","COMPARISON","PROFILE","ALTERNATIVE","DISCUSSION","HOW_TO_GUIDE","ARTICLE","REVIEW","OTHER"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_count"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["gap"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["url_tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Source tag ids. `in` keeps URLs carrying any of them, `has_all` keeps URLs carrying every one of them, `not_in` keeps URLs carrying none of them.","example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Source tag ids. `in` keeps sources on domains carrying any of them, `has_all` keeps sources on domains carrying every one of them, `not_in` keeps sources on domains carrying none of them.","example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"]}},"required":["field","operator","values"]}]}},"having":{"description":"Post-aggregation row filters (applied as HAVING after grouping). Select which aggregated URL rows are returned. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap` — population fields require the matching value in `dimensions`. Multiple filters are AND'd.","example":[{"field":"url","operator":"in","values":["https://example.com/page"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or a custom domain classification name.","example":["CORPORATE","EDITORIAL","INSTITUTIONAL","OTHER","REFERENCE","UGC","COMPETITOR","OWN","RELATED"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, REVIEW, OTHER) or a custom URL classification name.","example":["HOMEPAGE","CATEGORY_PAGE","PRODUCT_PAGE","LISTICLE","COMPARISON","PROFILE","ALTERNATIVE","DISCUSSION","HOW_TO_GUIDE","ARTICLE","REVIEW","OTHER"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_count"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["gap"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]}]}},"order_by":{"description":"Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied.","example":[{"field":"retrieval_count","direction":"desc"}],"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["retrieval_count","retrievals","citation_count","citation_rate","citation_position","date","week","month"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]}},"required":["field"]}}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"dimensions":{"example":["tag_id","model_id"],"description":"Dimensions to break down the report by.","type":"array","items":{"type":"string","enum":["prompt_id","model_id","model_channel_id","tag_id","topic_id","date","week","month","country_code","chat_id"]}},"filters":{"description":"Pre-aggregation row filters (applied as WHERE before grouping). Restrict which raw source-rows feed into the per-URL aggregation. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`, `url_tag_id`, `domain_tag_id`. Multiple filters are AND'd.","example":[{"field":"model_id","operator":"in","values":["gpt-4o-search"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or a custom domain classification name.","example":["CORPORATE","EDITORIAL","INSTITUTIONAL","OTHER","REFERENCE","UGC","COMPETITOR","OWN","RELATED"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, REVIEW, OTHER) or a custom URL classification name.","example":["HOMEPAGE","CATEGORY_PAGE","PRODUCT_PAGE","LISTICLE","COMPARISON","PROFILE","ALTERNATIVE","DISCUSSION","HOW_TO_GUIDE","ARTICLE","REVIEW","OTHER"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_count"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["gap"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["url_tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Source tag ids. `in` keeps URLs carrying any of them, `has_all` keeps URLs carrying every one of them, `not_in` keeps URLs carrying none of them.","example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Source tag ids. `in` keeps sources on domains carrying any of them, `has_all` keeps sources on domains carrying every one of them, `not_in` keeps sources on domains carrying none of them.","example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"]}},"required":["field","operator","values"]}]}},"having":{"description":"Post-aggregation row filters (applied as HAVING after grouping). Select which aggregated URL rows are returned. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap` — population fields require the matching value in `dimensions`. Multiple filters are AND'd.","example":[{"field":"url","operator":"in","values":["https://example.com/page"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["country_code"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["domain_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or a custom domain classification name.","example":["CORPORATE","EDITORIAL","INSTITUTIONAL","OTHER","REFERENCE","UGC","COMPETITOR","OWN","RELATED"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["url_classification"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Built-in classification (HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, REVIEW, OTHER) or a custom URL classification name.","example":["HOMEPAGE","CATEGORY_PAGE","PRODUCT_PAGE","LISTICLE","COMPARISON","PROFILE","ALTERNATIVE","DISCUSSION","HOW_TO_GUIDE","ARTICLE","REVIEW","OTHER"]}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["mentioned_brand_count"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]},{"type":"object","properties":{"field":{"type":"string","enum":["gap"]},"operator":{"type":"string","enum":["gt","gte","lt","lte"]},"value":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["field","operator","value"]}]}},"order_by":{"description":"Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied.","example":[{"field":"retrieval_count","direction":"desc"}],"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["retrieval_count","retrievals","citation_count","citation_rate","citation_position","date","week","month"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]}},"required":["field"]}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","example":"https://example.com/blog/page1#header"},"classification":{"nullable":true,"description":"Built-in classification (HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, REVIEW, OTHER) or the name of a custom URL classification.","example":"HOMEPAGE","type":"string"},"title":{"nullable":true,"type":"string"},"channel_title":{"description":"Channel or author name (e.g. YouTube channel, subreddit)","nullable":true,"type":"string"},"prompt":{"type":"object","properties":{"id":{"type":"string","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d"}},"required":["id"]},"model":{"deprecated":true,"description":"Deprecated: use model_channel instead","type":"object","properties":{"id":{"type":"string","example":"gpt-4o-search"}},"required":["id"]},"model_channel":{"type":"object","properties":{"id":{"type":"string","example":"openai-1"}},"required":["id"]},"tag":{"type":"object","properties":{"id":{"type":"string","example":"tg_23abec5b-100a-4261-9ee7-1effe68f0149"}},"required":["id"]},"topic":{"type":"object","properties":{"id":{"type":"string","example":"to_e6b8cdd3-a51b-4d94-a866-28dbe6b830a6"}},"required":["id"]},"country_code":{"example":"US","type":"string"},"chat":{"type":"object","properties":{"id":{"type":"string","example":"ch_abc123"}},"required":["id"]},"date":{"type":"string"},"week":{"example":"2025-03-10","description":"Start (Monday) of the ISO week bucket.","type":"string"},"month":{"example":"2025-03-01","description":"First day of the month bucket.","type":"string"},"usage_count":{"type":"number","example":8,"deprecated":true,"description":"Deprecated: use retrieval_count instead"},"citation_count":{"type":"number","example":4},"citation_avg":{"type":"number","example":2.5,"deprecated":true,"description":"Deprecated: use citation_rate instead"},"retrievals":{"type":"number","example":8,"deprecated":true,"description":"Deprecated: use retrieval_count instead"},"retrieval_count":{"type":"number","example":8,"description":"Total number of distinct chats that retrieved this URL"},"citation_rate":{"type":"number","example":0.5},"citation_position":{"example":2.4,"description":"Average rank of this URL among the sources each chat cited inline, ordered by first inline citation; 1 is the first source cited. Averaged over the chats that cited this URL, and null when none did. Returned only when citation position is enabled for the project.","nullable":true,"type":"number"},"citation_position_sum":{"example":12,"description":"Sum of this URL's per-chat citation ranks; divide by citation_position_count to aggregate citation_position across results.","type":"number"},"citation_position_count":{"example":5,"description":"Number of chats that cited this URL inline.","type":"number"},"mentioned_brands":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]},"description":"Brand IDs mentioned alongside this URL"}},"required":["url","classification","title","usage_count","citation_count","citation_avg","retrievals","retrieval_count","citation_rate","mentioned_brands"]}}},"required":["data"],"description":"Success"}}}}},"operationId":"postReportsUrls"}},"/sources/urls/content":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get URL Content","description":"Return the scraped markdown content of a source URL. Use the URLs report to discover URLs.","tags":["Reports"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"url":{"type":"string","format":"uri","example":"https://example.com/blog/page1"},"max_length":{"default":100000,"description":"Maximum number of characters of content to return. Defaults to 100,000. If the stored content is longer, the response will be truncated and truncated=true.","example":100000,"type":"integer","minimum":1,"maximum":20000000}},"required":["url"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"url":{"type":"string","format":"uri","example":"https://example.com/blog/page1"},"max_length":{"default":100000,"description":"Maximum number of characters of content to return. Defaults to 100,000. If the stored content is longer, the response will be truncated and truncated=true.","example":100000,"type":"integer","minimum":1,"maximum":20000000}},"required":["url"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"url":{"type":"string","format":"uri","example":"https://example.com/blog/page1"},"max_length":{"default":100000,"description":"Maximum number of characters of content to return. Defaults to 100,000. If the stored content is longer, the response will be truncated and truncated=true.","example":100000,"type":"integer","minimum":1,"maximum":20000000}},"required":["url"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"url":{"type":"string","example":"https://example.com/blog/page1"},"title":{"nullable":true,"type":"string"},"domain":{"type":"string","example":"example.com"},"channel_title":{"nullable":true,"description":"Channel or author name (e.g. YouTube channel, subreddit) or null","type":"string"},"classification":{"nullable":true,"description":"Domain-level classification of the source","type":"string","enum":["CORPORATE","EDITORIAL","INSTITUTIONAL","OTHER","REFERENCE","UGC","COMPETITOR","OWN","RELATED"]},"url_classification":{"nullable":true,"description":"Page-level classification (HOMEPAGE, LISTICLE, COMPARISON, ...)","type":"string","enum":["HOMEPAGE","CATEGORY_PAGE","PRODUCT_PAGE","LISTICLE","COMPARISON","PROFILE","ALTERNATIVE","DISCUSSION","HOW_TO_GUIDE","ARTICLE","REVIEW","OTHER"]},"content":{"nullable":true,"description":"Markdown content of the page. Null if the URL is tracked but scraping hasn't completed yet.","type":"string"},"content_length":{"type":"number","description":"Original character length of the stored content before truncation. 0 when content is null."},"truncated":{"type":"boolean","description":"True if content was truncated to max_length. Re-request with a larger max_length to get more."},"content_updated_at":{"nullable":true,"description":"ISO timestamp of when the content was last scraped","type":"string"}},"required":["url","title","domain","channel_title","classification","url_classification","content","content_length","truncated","content_updated_at"]}},"required":["data"],"description":"Success"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postSourcesUrlsContent"}},"/queries/search":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Fanout Search Queries","description":"List the fanout search queries of a project","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"filters":{"description":"Filter results by specific fields. Multiple filters are AND'd together.","example":[{"field":"prompt_id","operator":"in","values":["pr_abc123"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]}]}}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"filters":{"description":"Filter results by specific fields. Multiple filters are AND'd together.","example":[{"field":"prompt_id","operator":"in","values":["pr_abc123"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]}]}}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"filters":{"description":"Filter results by specific fields. Multiple filters are AND'd together.","example":[{"field":"prompt_id","operator":"in","values":["pr_abc123"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]}]}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"prompt":{"type":"object","properties":{"id":{"type":"string","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d"}},"required":["id"]},"chat":{"type":"object","properties":{"id":{"type":"string","example":"ch_61184892-36ad-4e1a-8178-3a83608f7711"}},"required":["id"]},"model":{"type":"object","properties":{"id":{"type":"string","example":"gpt-4o-search"}},"required":["id"],"deprecated":true,"description":"Deprecated: use model_channel instead"},"model_channel":{"type":"object","properties":{"id":{"type":"string","example":"openai-1"}},"required":["id"]},"date":{"type":"string","example":"2025-09-17"},"query":{"type":"object","properties":{"index":{"type":"number","example":0},"text":{"type":"string","example":"What is Peec?"}},"required":["index","text"]}},"required":["prompt","chat","model","model_channel","date","query"]}},"total_count":{"type":"number","example":42,"description":"Total number of matching search queries, ignoring pagination"},"totalCount":{"type":"number","example":42,"description":"Total number of matching search queries, ignoring pagination","deprecated":true}},"required":["data","total_count","totalCount"],"description":"Success"}}}}},"operationId":"postQueriesSearch"}},"/queries/shopping":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Fanout Shopping Queries","description":"List the fanout shopping queries of a project","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"filters":{"description":"Filter results by specific fields. Multiple filters are AND'd together.","example":[{"field":"prompt_id","operator":"in","values":["pr_abc123"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]}]}}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"filters":{"description":"Filter results by specific fields. Multiple filters are AND'd together.","example":[{"field":"prompt_id","operator":"in","values":["pr_abc123"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]}]}}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"filters":{"description":"Filter results by specific fields. Multiple filters are AND'd together.","example":[{"field":"prompt_id","operator":"in","values":["pr_abc123"]}],"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["model_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}}},"required":["field","operator","values"],"deprecated":true,"description":"Deprecated: use model_channel_id filter instead"},{"type":"object","properties":{"field":{"type":"string","enum":["model_channel_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["tag_id"]},"operator":{"type":"string","enum":["in","not_in","has_all"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["topic_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["prompt_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]},{"type":"object","properties":{"field":{"type":"string","enum":["chat_id"]},"operator":{"type":"string","enum":["in","not_in"]},"values":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["field","operator","values"]}]}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"prompt":{"type":"object","properties":{"id":{"type":"string","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d"}},"required":["id"]},"chat":{"type":"object","properties":{"id":{"type":"string","example":"ch_61184892-36ad-4e1a-8178-3a83608f7711"}},"required":["id"]},"model":{"type":"object","properties":{"id":{"type":"string","example":"gpt-4o-search"}},"required":["id"],"deprecated":true,"description":"Deprecated: use model_channel instead"},"model_channel":{"type":"object","properties":{"id":{"type":"string","example":"openai-1"}},"required":["id"]},"date":{"type":"string","example":"2025-09-17"},"query":{"type":"object","properties":{"text":{"type":"string","example":"What is Peec?"},"products":{"type":"array","items":{"type":"string"},"example":["Peec AI","Peec Pro"]}},"required":["text","products"]}},"required":["prompt","chat","model","model_channel","date","query"]}},"total_count":{"type":"number","example":42,"description":"Total number of matching shopping queries, ignoring pagination"},"totalCount":{"type":"number","example":42,"description":"Total number of matching shopping queries, ignoring pagination","deprecated":true}},"required":["data","total_count","totalCount"],"description":"Success"}}}}},"operationId":"postQueriesShopping"}},"/products/list":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Products","description":"List a project's products with headline metrics (mention_count, win_count, avg_position, avg_rating, visibility, share_of_voice) over the date range, filterable by category, merchant, brand, country, model channel, topic, and tag. Paginated.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"product_ids":{"description":"Filter to these product ids.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"brand_ids":{"description":"Filter to products of these brands (global_brand_id).","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"category_ids":{"description":"Filter to products in any of these categories (OR — a product matches if it falls under at least one). Category ids roll up: selecting a parent also matches products in its descendant categories.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"merchant_ids":{"description":"Filter to products sold through these merchants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"chat_scope":{"description":"Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.","type":"string","enum":["all","shopping"]},"source":{"type":"string","enum":["CATALOG","LLM"]},"search":{"type":"string"},"order_by":{"default":"visibility","type":"string","enum":["visibility","win_rate","avg_position","avg_rating","mention_count","name"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"product_ids":{"description":"Filter to these product ids.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"brand_ids":{"description":"Filter to products of these brands (global_brand_id).","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"category_ids":{"description":"Filter to products in any of these categories (OR — a product matches if it falls under at least one). Category ids roll up: selecting a parent also matches products in its descendant categories.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"merchant_ids":{"description":"Filter to products sold through these merchants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"chat_scope":{"description":"Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.","type":"string","enum":["all","shopping"]},"source":{"type":"string","enum":["CATALOG","LLM"]},"search":{"type":"string"},"order_by":{"default":"visibility","type":"string","enum":["visibility","win_rate","avg_position","avg_rating","mention_count","name"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"product_ids":{"description":"Filter to these product ids.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"brand_ids":{"description":"Filter to products of these brands (global_brand_id).","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"category_ids":{"description":"Filter to products in any of these categories (OR — a product matches if it falls under at least one). Category ids roll up: selecting a parent also matches products in its descendant categories.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"merchant_ids":{"description":"Filter to products sold through these merchants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"chat_scope":{"description":"Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.","type":"string","enum":["all","shopping"]},"source":{"type":"string","enum":["CATALOG","LLM"]},"search":{"type":"string"},"order_by":{"default":"visibility","type":"string","enum":["visibility","win_rate","avg_position","avg_rating","mention_count","name"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Products with headline metrics over the date range","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"brand":{"type":"string"},"source":{"type":"string","enum":["CATALOG","LLM"]},"image_url":{"nullable":true,"type":"string"},"price_range":{"type":"object","additionalProperties":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]}},"categories":{"type":"array","items":{"type":"string"}},"mention_count":{"type":"number"},"win_count":{"type":"number"},"avg_position":{"nullable":true,"type":"number"},"avg_rating":{"nullable":true,"type":"number"},"visibility":{"type":"number"},"share_of_voice":{"type":"number"}},"required":["id","name","brand","source","image_url","price_range","categories","mention_count","win_count","avg_position","avg_rating","visibility","share_of_voice"]}},"total_count":{"type":"number"}},"required":["data","total_count"],"description":"Products with headline metrics over the date range"}}}}},"operationId":"postProductsList"}},"/products/detail":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Product","description":"Get one product's detail over a date range: headline metrics (visibility, win_rate, avg_position, avg_rating, mention_count) plus a delta for each against the immediately preceding equal-length period, the catalog metadata (brand, description, image, source, first-seen date), the effective price range with any overrides, and the median AI-mention price. Visibility is divided by the product's relevant-prompt chats, not all shopping chats. avg_rating is the mean 0–5 star rating across the product's AI mentions (null when none carried a rating). Returns data: null when the product is not in the project.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"product_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string"}},"merchant_ids":{"description":"Scope the response to chats where this product is sold through one of these merchants — the per-merchant view of rating, price, and mentions. The QFO breakdowns scope through those chats too; only the visibility denominator stays merchant-free.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"chat_scope":{"description":"Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.","type":"string","enum":["all","shopping"]}},"required":["product_id"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"product_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string"}},"merchant_ids":{"description":"Scope the response to chats where this product is sold through one of these merchants — the per-merchant view of rating, price, and mentions. The QFO breakdowns scope through those chats too; only the visibility denominator stays merchant-free.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"chat_scope":{"description":"Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.","type":"string","enum":["all","shopping"]}},"required":["product_id"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"product_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string"}},"merchant_ids":{"description":"Scope the response to chats where this product is sold through one of these merchants — the per-merchant view of rating, price, and mentions. The QFO breakdowns scope through those chats too; only the visibility denominator stays merchant-free.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"chat_scope":{"description":"Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.","type":"string","enum":["all","shopping"]}},"required":["product_id"]}}}},"responses":{"200":{"description":"A single product's detail metrics over the date range, with deltas against the immediately preceding period. `data` is null when the product does not exist in the project. Beyond the always-present identity and headline metrics, `data` carries optional extras — description, image, price/currency maps, the QFO breakdowns (fanout_queries, shopping_queries, and their *_terms n-gram variants, each capped at 25 entries) that surface the top queries and terms that mentioned this product, and `variants` (the product's live catalog variants — id, name, and a per-currency price_map — capped at 50 with no pagination).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"nullable":true,"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"brand":{"type":"string"},"source":{"type":"string","enum":["CATALOG","LLM"]},"first_seen_at":{"type":"string"},"visibility":{"type":"number"},"visibility_delta":{"nullable":true,"type":"number"},"win_rate":{"type":"number"},"win_rate_delta":{"nullable":true,"type":"number"},"avg_position":{"nullable":true,"type":"number"},"avg_position_delta":{"nullable":true,"type":"number"},"avg_rating":{"nullable":true,"type":"number"},"avg_rating_delta":{"nullable":true,"type":"number"},"mention_count":{"type":"number"},"mention_count_delta":{"nullable":true,"type":"number"},"description":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"price_range":{"type":"object","additionalProperties":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]}},"price_override":{"type":"object","additionalProperties":{"type":"object","properties":{"min":{"nullable":true,"type":"number"},"max":{"nullable":true,"type":"number"}},"required":["min","max"]}},"ai_price_map":{"type":"object","additionalProperties":{"type":"number"}},"ai_price_delta_map":{"type":"object","additionalProperties":{"type":"number"}},"fanout_queries":{"type":"array","items":{"type":"object","properties":{"query_text":{"type":"string"},"distinct_chat_count":{"type":"number"},"distinct_chat_count_previous":{"type":"number"},"delta":{"nullable":true,"type":"number"}},"required":["query_text","distinct_chat_count","distinct_chat_count_previous","delta"]}},"shopping_queries":{"type":"array","items":{"type":"object","properties":{"query_text":{"type":"string"},"distinct_chat_count":{"type":"number"},"distinct_chat_count_previous":{"type":"number"},"delta":{"nullable":true,"type":"number"}},"required":["query_text","distinct_chat_count","distinct_chat_count_previous","delta"]}},"fanout_query_terms":{"type":"array","items":{"type":"object","properties":{"term":{"type":"string"},"distinct_chat_count":{"type":"number"},"distinct_chat_count_previous":{"type":"number"},"delta":{"nullable":true,"type":"number"}},"required":["term","distinct_chat_count","distinct_chat_count_previous","delta"]}},"shopping_query_terms":{"type":"array","items":{"type":"object","properties":{"term":{"type":"string"},"distinct_chat_count":{"type":"number"},"distinct_chat_count_previous":{"type":"number"},"delta":{"nullable":true,"type":"number"}},"required":["term","distinct_chat_count","distinct_chat_count_previous","delta"]}},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"price_map":{"type":"object","additionalProperties":{"type":"number"}},"priceMap":{"type":"object","additionalProperties":{"type":"number"},"deprecated":true,"description":"Deprecated: use price_map instead"}},"required":["id","name","price_map","priceMap"]}}},"required":["id","name","brand","first_seen_at","visibility","visibility_delta","win_rate","win_rate_delta","avg_position","avg_position_delta","avg_rating","avg_rating_delta","mention_count","mention_count_delta"]},"primary_currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["data"],"description":"A single product's detail metrics over the date range, with deltas against the immediately preceding period. `data` is null when the product does not exist in the project. Beyond the always-present identity and headline metrics, `data` carries optional extras — description, image, price/currency maps, the QFO breakdowns (fanout_queries, shopping_queries, and their *_terms n-gram variants, each capped at 25 entries) that surface the top queries and terms that mentioned this product, and `variants` (the product's live catalog variants — id, name, and a per-currency price_map — capped at 50 with no pagination)."}}}}},"operationId":"postProductsDetail"}},"/actions/list":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Actions","description":"The project's actions, the ones Peec generated and the ones the customer wrote themselves alike: what to do, on which page or site, and how much impact it is expected to have if it is done. `created_by` says which of the two an action is, and only a customer's own can be deleted or reshaped. Filters combine with AND, except `targets`, `groups`, `archetypes` and `platforms`, which combine with OR across the four. The action detail endpoint carries a single action's steps, brief, evidence and impacted prompts.","tags":["Actions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"types":{"description":"Defaults to every published type. `TEMPLATE_ACTION` is a per-platform playbook filled in for one page; `CONTENT_BRIEF` and `CATEGORY_SITUATION_BRIEF` are net-new content to write; `CONTRADICTIONS_EXTERNAL_SOURCES` requests correction of one third-party source page that conflicts with a verified brand fact; `CONTRADICTIONS_OWNED_SOURCES` corrects one source page on a domain the brand owns; `SEO_ISSUE` and `ROBOTS_TXT` are technical fixes to a site the brand controls; `PDP_OPTIMISATION` improves one product page; `MANUAL_ACTION` is work a customer described themselves that matches none of the other shapes; `CONTENT_OPTIMISATION` improves an existing page the brand owns, and appears only on projects with content optimisation enabled — the optimize content endpoint returns its article and suggestions.","type":"array","items":{"type":"string","enum":["TEMPLATE_ACTION","CONTENT_BRIEF","CATEGORY_SITUATION_BRIEF","CONTRADICTIONS_EXTERNAL_SOURCES","CONTRADICTIONS_OWNED_SOURCES","SEO_ISSUE","ROBOTS_TXT","PDP_OPTIMISATION","MANUAL_ACTION","CONTENT_OPTIMISATION"]}},"statuses":{"description":"Defaults to every status. `PENDING` is a suggestion nobody has decided on, `PLANNED` is an action you wrote and have not started, `ACCEPTED` is in progress, `COMPLETED` is done, `REJECTED` was declined, `EXPIRED` was left untouched for 30 days and closed automatically.","type":"array","items":{"type":"string","enum":["PENDING","PLANNED","ACCEPTED","REJECTED","COMPLETED","EXPIRED"]}},"categories":{"description":"The off-site playbook a template action follows (the upper-case values), or the audit check an `SEO_ISSUE` came from (the lower-case ones). `agent_readiness` is the AI agent readiness audit, which covers files written for AI agents such as llms.txt. A playbook is orthogonal to the group, so the same one appears across groups, and narrowing by both means the intersection. Content briefs and `ROBOTS_TXT` actions carry none and match nothing here.","type":"array","items":{"type":"string","enum":["EDITORIAL_PITCH","LISTICLE_COMPARISON_INCLUSION","REVIEW_DIRECTORY_OPTIMIZATION","COMMUNITY_ENGAGEMENT","SOCIAL_CONTENT","accessibility","agent_readiness","canonical","crawlability","dom_health","blocked","not_found","other","rate_limited","unavailable","metadata","performance","retrievability","schema","semantic_html","structure","structured_data"]}},"domains":{"example":["example.com"],"description":"The site an `SEO_ISSUE` was raised against. Every other type carries none and matches nothing here.","type":"array","items":{"type":"string"}},"topic_ids":{"example":["to_a1b2c3"],"description":"Only actions on these topics (see the topics endpoint).","type":"array","items":{"type":"string"}},"model_channel_ids":{"example":["openai-0"],"description":"Only actions affecting these AI engine channels (see the model channels endpoint).","type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"country_codes":{"example":["US"],"description":"ISO 3166-1 alpha-2 markets. An action carrying no markets is not scoped to one, so every selection matches it.","type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}},"targets":{"description":"`owned` means the action lands on a page the brand controls; `earned` means a third-party page, which covers editorial coverage and community posts alike. A UGC action is `earned` even when the brand writes the post itself.","type":"array","items":{"type":"string","enum":["owned","earned"]}},"groups":{"description":"The kind of surface the action lands on.","type":"array","items":{"type":"string","enum":["OWNED","EDITORIAL","REFERENCE","UGC","OTHER"]}},"archetypes":{"description":"The kind of page a content brief says to create. Template actions carry no archetype and match nothing here, so this narrows the answer to content briefs.","type":"array","items":{"type":"string","enum":["HOMEPAGE","CATEGORY_PAGE","PRODUCT_PAGE","LISTICLE","COMPARISON","PROFILE","ALTERNATIVE","DISCUSSION","HOW_TO_GUIDE","ARTICLE","REVIEW","OTHER"]}},"platforms":{"example":["reddit.com"],"description":"Registrable domain of a third-party action. Own-site actions carry none and match nothing here.","type":"array","items":{"type":"string"}},"order_by":{"default":"impact","description":"`impact` is the order the Actions page ranks by, strongest expected gain first. `created_at` reads newest first, which is how to find what Peec generated since the last read.","type":"string","enum":["impact","created_at"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"types":{"description":"Defaults to every published type. `TEMPLATE_ACTION` is a per-platform playbook filled in for one page; `CONTENT_BRIEF` and `CATEGORY_SITUATION_BRIEF` are net-new content to write; `CONTRADICTIONS_EXTERNAL_SOURCES` requests correction of one third-party source page that conflicts with a verified brand fact; `CONTRADICTIONS_OWNED_SOURCES` corrects one source page on a domain the brand owns; `SEO_ISSUE` and `ROBOTS_TXT` are technical fixes to a site the brand controls; `PDP_OPTIMISATION` improves one product page; `MANUAL_ACTION` is work a customer described themselves that matches none of the other shapes; `CONTENT_OPTIMISATION` improves an existing page the brand owns, and appears only on projects with content optimisation enabled — the optimize content endpoint returns its article and suggestions.","type":"array","items":{"type":"string","enum":["TEMPLATE_ACTION","CONTENT_BRIEF","CATEGORY_SITUATION_BRIEF","CONTRADICTIONS_EXTERNAL_SOURCES","CONTRADICTIONS_OWNED_SOURCES","SEO_ISSUE","ROBOTS_TXT","PDP_OPTIMISATION","MANUAL_ACTION","CONTENT_OPTIMISATION"]}},"statuses":{"description":"Defaults to every status. `PENDING` is a suggestion nobody has decided on, `PLANNED` is an action you wrote and have not started, `ACCEPTED` is in progress, `COMPLETED` is done, `REJECTED` was declined, `EXPIRED` was left untouched for 30 days and closed automatically.","type":"array","items":{"type":"string","enum":["PENDING","PLANNED","ACCEPTED","REJECTED","COMPLETED","EXPIRED"]}},"categories":{"description":"The off-site playbook a template action follows (the upper-case values), or the audit check an `SEO_ISSUE` came from (the lower-case ones). `agent_readiness` is the AI agent readiness audit, which covers files written for AI agents such as llms.txt. A playbook is orthogonal to the group, so the same one appears across groups, and narrowing by both means the intersection. Content briefs and `ROBOTS_TXT` actions carry none and match nothing here.","type":"array","items":{"type":"string","enum":["EDITORIAL_PITCH","LISTICLE_COMPARISON_INCLUSION","REVIEW_DIRECTORY_OPTIMIZATION","COMMUNITY_ENGAGEMENT","SOCIAL_CONTENT","accessibility","agent_readiness","canonical","crawlability","dom_health","blocked","not_found","other","rate_limited","unavailable","metadata","performance","retrievability","schema","semantic_html","structure","structured_data"]}},"domains":{"example":["example.com"],"description":"The site an `SEO_ISSUE` was raised against. Every other type carries none and matches nothing here.","type":"array","items":{"type":"string"}},"topic_ids":{"example":["to_a1b2c3"],"description":"Only actions on these topics (see the topics endpoint).","type":"array","items":{"type":"string"}},"model_channel_ids":{"example":["openai-0"],"description":"Only actions affecting these AI engine channels (see the model channels endpoint).","type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"country_codes":{"example":["US"],"description":"ISO 3166-1 alpha-2 markets. An action carrying no markets is not scoped to one, so every selection matches it.","type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}},"targets":{"description":"`owned` means the action lands on a page the brand controls; `earned` means a third-party page, which covers editorial coverage and community posts alike. A UGC action is `earned` even when the brand writes the post itself.","type":"array","items":{"type":"string","enum":["owned","earned"]}},"groups":{"description":"The kind of surface the action lands on.","type":"array","items":{"type":"string","enum":["OWNED","EDITORIAL","REFERENCE","UGC","OTHER"]}},"archetypes":{"description":"The kind of page a content brief says to create. Template actions carry no archetype and match nothing here, so this narrows the answer to content briefs.","type":"array","items":{"type":"string","enum":["HOMEPAGE","CATEGORY_PAGE","PRODUCT_PAGE","LISTICLE","COMPARISON","PROFILE","ALTERNATIVE","DISCUSSION","HOW_TO_GUIDE","ARTICLE","REVIEW","OTHER"]}},"platforms":{"example":["reddit.com"],"description":"Registrable domain of a third-party action. Own-site actions carry none and match nothing here.","type":"array","items":{"type":"string"}},"order_by":{"default":"impact","description":"`impact` is the order the Actions page ranks by, strongest expected gain first. `created_at` reads newest first, which is how to find what Peec generated since the last read.","type":"string","enum":["impact","created_at"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"types":{"description":"Defaults to every published type. `TEMPLATE_ACTION` is a per-platform playbook filled in for one page; `CONTENT_BRIEF` and `CATEGORY_SITUATION_BRIEF` are net-new content to write; `CONTRADICTIONS_EXTERNAL_SOURCES` requests correction of one third-party source page that conflicts with a verified brand fact; `CONTRADICTIONS_OWNED_SOURCES` corrects one source page on a domain the brand owns; `SEO_ISSUE` and `ROBOTS_TXT` are technical fixes to a site the brand controls; `PDP_OPTIMISATION` improves one product page; `MANUAL_ACTION` is work a customer described themselves that matches none of the other shapes; `CONTENT_OPTIMISATION` improves an existing page the brand owns, and appears only on projects with content optimisation enabled — the optimize content endpoint returns its article and suggestions.","type":"array","items":{"type":"string","enum":["TEMPLATE_ACTION","CONTENT_BRIEF","CATEGORY_SITUATION_BRIEF","CONTRADICTIONS_EXTERNAL_SOURCES","CONTRADICTIONS_OWNED_SOURCES","SEO_ISSUE","ROBOTS_TXT","PDP_OPTIMISATION","MANUAL_ACTION","CONTENT_OPTIMISATION"]}},"statuses":{"description":"Defaults to every status. `PENDING` is a suggestion nobody has decided on, `PLANNED` is an action you wrote and have not started, `ACCEPTED` is in progress, `COMPLETED` is done, `REJECTED` was declined, `EXPIRED` was left untouched for 30 days and closed automatically.","type":"array","items":{"type":"string","enum":["PENDING","PLANNED","ACCEPTED","REJECTED","COMPLETED","EXPIRED"]}},"categories":{"description":"The off-site playbook a template action follows (the upper-case values), or the audit check an `SEO_ISSUE` came from (the lower-case ones). `agent_readiness` is the AI agent readiness audit, which covers files written for AI agents such as llms.txt. A playbook is orthogonal to the group, so the same one appears across groups, and narrowing by both means the intersection. Content briefs and `ROBOTS_TXT` actions carry none and match nothing here.","type":"array","items":{"type":"string","enum":["EDITORIAL_PITCH","LISTICLE_COMPARISON_INCLUSION","REVIEW_DIRECTORY_OPTIMIZATION","COMMUNITY_ENGAGEMENT","SOCIAL_CONTENT","accessibility","agent_readiness","canonical","crawlability","dom_health","blocked","not_found","other","rate_limited","unavailable","metadata","performance","retrievability","schema","semantic_html","structure","structured_data"]}},"domains":{"example":["example.com"],"description":"The site an `SEO_ISSUE` was raised against. Every other type carries none and matches nothing here.","type":"array","items":{"type":"string"}},"topic_ids":{"example":["to_a1b2c3"],"description":"Only actions on these topics (see the topics endpoint).","type":"array","items":{"type":"string"}},"model_channel_ids":{"example":["openai-0"],"description":"Only actions affecting these AI engine channels (see the model channels endpoint).","type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"country_codes":{"example":["US"],"description":"ISO 3166-1 alpha-2 markets. An action carrying no markets is not scoped to one, so every selection matches it.","type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}},"targets":{"description":"`owned` means the action lands on a page the brand controls; `earned` means a third-party page, which covers editorial coverage and community posts alike. A UGC action is `earned` even when the brand writes the post itself.","type":"array","items":{"type":"string","enum":["owned","earned"]}},"groups":{"description":"The kind of surface the action lands on.","type":"array","items":{"type":"string","enum":["OWNED","EDITORIAL","REFERENCE","UGC","OTHER"]}},"archetypes":{"description":"The kind of page a content brief says to create. Template actions carry no archetype and match nothing here, so this narrows the answer to content briefs.","type":"array","items":{"type":"string","enum":["HOMEPAGE","CATEGORY_PAGE","PRODUCT_PAGE","LISTICLE","COMPARISON","PROFILE","ALTERNATIVE","DISCUSSION","HOW_TO_GUIDE","ARTICLE","REVIEW","OTHER"]}},"platforms":{"example":["reddit.com"],"description":"Registrable domain of a third-party action. Own-site actions carry none and match nothing here.","type":"array","items":{"type":"string"}},"order_by":{"default":"impact","description":"`impact` is the order the Actions page ranks by, strongest expected gain first. `created_at` reads newest first, which is how to find what Peec generated since the last read.","type":"string","enum":["impact","created_at"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]},"limit":{"default":1000,"type":"integer","minimum":1,"maximum":10000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","example":"01a0422f-e0c4-7820-85a1-31515a321f15"},"type":{"type":"string","enum":["TEMPLATE_ACTION","CONTENT_BRIEF","CATEGORY_SITUATION_BRIEF","CONTRADICTIONS_EXTERNAL_SOURCES","CONTRADICTIONS_OWNED_SOURCES","SEO_ISSUE","ROBOTS_TXT","PDP_OPTIMISATION","MANUAL_ACTION","CONTENT_OPTIMISATION"]},"status":{"type":"string","enum":["PENDING","PLANNED","ACCEPTED","REJECTED","COMPLETED","EXPIRED"]},"title":{"type":"string","example":"Add a pricing comparison table to the plans page"},"group":{"type":"string","enum":["OWNED","EDITORIAL","REFERENCE","UGC","OTHER"]},"category":{"nullable":true,"example":"EDITORIAL_PITCH","description":"The off-site playbook a template action follows, or the audit check an `SEO_ISSUE` came from — normally one of the values the `categories` filter accepts. Null on content briefs and `ROBOTS_TXT` actions.","type":"string"},"target":{"type":"string","enum":["owned","earned"]},"archetype":{"nullable":true,"description":"The kind of page a content brief says to create. Null on template actions, and on content briefs generated before Peec recorded it.","type":"string","enum":["HOMEPAGE","CATEGORY_PAGE","PRODUCT_PAGE","LISTICLE","COMPARISON","PROFILE","ALTERNATIVE","DISCUSSION","HOW_TO_GUIDE","ARTICLE","REVIEW","OTHER"]},"platform":{"nullable":true,"example":"reddit.com","description":"Registrable domain of the third-party site. Null on own-site actions.","type":"string"},"topic_id":{"nullable":true,"example":"to_a1b2c3","type":"string"},"source":{"type":"string","example":"https://example.com/pricing","description":"The page the action targets. Not always a url: a content brief describes a page that does not exist yet and carries the sentinel `content-brief` (`situation-brief` on a `CATEGORY_SITUATION_BRIEF`), an `SEO_ISSUE` names the audit that raised it and puts its target in `domain`, and a `ROBOTS_TXT` action carries a bare hostname."},"domain":{"nullable":true,"example":"example.com","description":"The site an `SEO_ISSUE` was raised against, which is what it applies to rather than a single page. Null on every other type.","type":"string"},"country_codes":{"type":"array","items":{"type":"string"},"description":"Markets the action is scoped to. Empty when it applies to every market the project tracks."},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"impact":{"type":"string","enum":["VERY_LOW","LOW","MEDIUM","HIGH","VERY_HIGH"],"description":"How much the action is expected to gain if it is completed, banded against every action in the project, so it reads the same whatever the filters are. On an `SEO_ISSUE` the band comes from the issue's severity instead. This is the impact the app shows, and the only measure of expected gain the API publishes."},"step_count":{"type":"number","description":"How many steps the action has."},"completed_step_count":{"type":"number"},"created_at":{"type":"string","example":"2026-08-20T10:12:00.000Z"},"status_updated_at":{"nullable":true,"description":"When the status last changed. Null while still `PENDING`. On a `COMPLETED` action this is when the work was done, which the customer can backdate with `completed_at`.","type":"string"},"created_by":{"type":"string","enum":["peec","customer"],"description":"Who wrote the action. Only a `customer` one can be deleted or have its `kind` changed; a `peec` one is declined through the status endpoint instead."},"priority":{"nullable":true,"description":"How much the customer says the action matters. It fills the same bars `impact` fills on a generated action, and is null on one nobody has set.","type":"string","enum":["none","low","medium","high"]},"assignee_user_id":{"nullable":true,"description":"The project member the work is on. Null when unassigned.","type":"string"},"due_on":{"nullable":true,"example":"2026-10-31","description":"Calendar day in the project's timezone.","type":"string"},"tag_ids":{"type":"array","items":{"type":"string"},"description":"Tags the customer filed the action under."}},"required":["id","type","status","title","group","category","target","archetype","platform","topic_id","source","domain","country_codes","model_channel_ids","impact","step_count","completed_step_count","created_at","status_updated_at","created_by","priority","assignee_user_id","due_on","tag_ids"]}},"total_count":{"type":"number","example":42,"description":"Actions matching the filters, ignoring pagination."}},"required":["data","total_count"],"description":"Success"}}}}},"operationId":"postActionsList"}},"/actions/detail":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Action","description":"One action in full: what to do, the fields the customer owns on it — notes, priority, assignee, due date, tags and repeat — the steps to work through, the content brief when there is one with its sections, the competitor demand behind it, the prompts it affects and the terms competitors use on the topic. A site audit action carries no brief and no opportunity, and its description and steps are the whole fix. An id this project has no published action for is a 404, whether it belongs to another project, to an action type this API does not publish for the project, or to nothing at all. A content optimisation carries its article, suggestions and score on the optimize content endpoint instead.","tags":["Actions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"action_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","example":"01a0422f-e0c4-7820-85a1-31515a321f15"}},"required":["action_id"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"action_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","example":"01a0422f-e0c4-7820-85a1-31515a321f15"}},"required":["action_id"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"action_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","example":"01a0422f-e0c4-7820-85a1-31515a321f15"}},"required":["action_id"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","example":"01a0422f-e0c4-7820-85a1-31515a321f15"},"type":{"type":"string","enum":["TEMPLATE_ACTION","CONTENT_BRIEF","CATEGORY_SITUATION_BRIEF","CONTRADICTIONS_EXTERNAL_SOURCES","CONTRADICTIONS_OWNED_SOURCES","SEO_ISSUE","ROBOTS_TXT","PDP_OPTIMISATION","MANUAL_ACTION","CONTENT_OPTIMISATION"]},"status":{"type":"string","enum":["PENDING","PLANNED","ACCEPTED","REJECTED","COMPLETED","EXPIRED"]},"title":{"type":"string","example":"Add a pricing comparison table to the plans page"},"group":{"type":"string","enum":["OWNED","EDITORIAL","REFERENCE","UGC","OTHER"]},"category":{"nullable":true,"example":"EDITORIAL_PITCH","description":"The off-site playbook a template action follows, or the audit check an `SEO_ISSUE` came from — normally one of the values the `categories` filter accepts. Null on content briefs and `ROBOTS_TXT` actions.","type":"string"},"target":{"type":"string","enum":["owned","earned"]},"archetype":{"nullable":true,"description":"The kind of page a content brief says to create. Null on template actions, and on content briefs generated before Peec recorded it.","type":"string","enum":["HOMEPAGE","CATEGORY_PAGE","PRODUCT_PAGE","LISTICLE","COMPARISON","PROFILE","ALTERNATIVE","DISCUSSION","HOW_TO_GUIDE","ARTICLE","REVIEW","OTHER"]},"platform":{"nullable":true,"example":"reddit.com","description":"Registrable domain of the third-party site. Null on own-site actions.","type":"string"},"topic_id":{"nullable":true,"example":"to_a1b2c3","type":"string"},"source":{"type":"string","example":"https://example.com/pricing","description":"The page the action targets. Not always a url: a content brief describes a page that does not exist yet and carries the sentinel `content-brief` (`situation-brief` on a `CATEGORY_SITUATION_BRIEF`), an `SEO_ISSUE` names the audit that raised it and puts its target in `domain`, and a `ROBOTS_TXT` action carries a bare hostname."},"domain":{"nullable":true,"example":"example.com","description":"The site an `SEO_ISSUE` was raised against, which is what it applies to rather than a single page. Null on every other type.","type":"string"},"country_codes":{"type":"array","items":{"type":"string"},"description":"Markets the action is scoped to. Empty when it applies to every market the project tracks."},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"impact":{"type":"string","enum":["VERY_LOW","LOW","MEDIUM","HIGH","VERY_HIGH"],"description":"How much the action is expected to gain if it is completed, banded against every action in the project, so it reads the same whatever the filters are. On an `SEO_ISSUE` the band comes from the issue's severity instead. This is the impact the app shows, and the only measure of expected gain the API publishes."},"step_count":{"type":"number","description":"How many steps the action has."},"completed_step_count":{"type":"number"},"created_at":{"type":"string","example":"2026-08-20T10:12:00.000Z"},"status_updated_at":{"nullable":true,"description":"When the status last changed. Null while still `PENDING`. On a `COMPLETED` action this is when the work was done, which the customer can backdate with `completed_at`.","type":"string"},"created_by":{"type":"string","enum":["peec","customer"],"description":"Who wrote the action. Only a `customer` one can be deleted or have its `kind` changed; a `peec` one is declined through the status endpoint instead."},"priority":{"nullable":true,"description":"How much the customer says the action matters. It fills the same bars `impact` fills on a generated action, and is null on one nobody has set.","type":"string","enum":["none","low","medium","high"]},"assignee_user_id":{"nullable":true,"description":"The project member the work is on. Null when unassigned.","type":"string"},"due_on":{"nullable":true,"example":"2026-10-31","description":"Calendar day in the project's timezone.","type":"string"},"tag_ids":{"type":"array","items":{"type":"string"},"description":"Tags the customer filed the action under."},"description":{"type":"object","properties":{"text":{"type":"string"},"sources":{"type":"array","items":{"type":"string"}}},"required":["text","sources"]},"kind":{"nullable":true,"description":"What the customer wrote the action as, which is what decided its type and group. Null on an action Peec generated, whose shape came from what it found rather than from a choice.","type":"string","enum":["CONTENT_OPTIMIZATION","CONTENT_CREATION","MENTION","TECHNICAL","PRODUCT_PAGE","OTHER"]},"notes":{"nullable":true,"description":"Working notes the customer keeps beside the action.","type":"string"},"page_url":{"nullable":true,"example":"https://example.com/pricing","description":"The page the action lands on, where `source` can instead carry a sentinel or a hostname. Null when the action names no page.","type":"string"},"language_codes":{"nullable":true,"description":"Null when the action is not scoped to a language.","type":"array","items":{"type":"string"}},"repeat":{"nullable":true,"description":"How often the work comes round again.","type":"object","properties":{"every":{"type":"number"},"unit":{"type":"string","enum":["day","week","month","year"]}},"required":["every","unit"]},"time_range":{"nullable":true,"description":"The window the action's own measurements are read over.","type":"string","enum":["7d","28d","90d","all"]},"steps":{"description":"The work to do on a template action, and on a content brief the material it was written from. This endpoint always returns it; the MCP tool omits it unless asked.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","PLANNED","ACCEPTED","REJECTED","COMPLETED","EXPIRED"]},"group_title":{"nullable":true,"description":"Heading for a multi-option step. Null on a single-option step, which stands alone.","type":"string"},"gap_type":{"nullable":true,"example":"community_phrases","description":"What a content brief's step holds — the fan-out prompts, the community phrases, themes or discussions, the winning sources, the brand context, or the brief's own points. A brief's steps are the material it was written from rather than work to do, and this is the only thing that says which is which. Null on a template action, whose steps are the work itself.","type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"text":{"type":"string"},"score":{"type":"number"},"completed":{"type":"boolean"}},"required":["id","label","text","score","completed"]}}},"required":["id","status","group_title","gap_type","options"]}},"content_brief_outline":{"nullable":true,"description":"Content briefs only, and null on a brief written before Peec recorded an outline. Everything past `points` arrived together and is null or empty on an outline written before that.","type":"object","properties":{"title":{"type":"string"},"points":{"type":"array","items":{"type":"string"},"description":"The points to cover as plain headings, parallel to `outline_points` and in the same order."},"brief":{"nullable":true,"description":"The whole brief as one markdown document.","type":"string"},"summary":{"nullable":true,"description":"One line on what the page is for.","type":"string"},"overview":{"nullable":true,"type":"string"},"h1_options":{"type":"array","items":{"type":"string"},"description":"Headlines to choose between."},"meta_title":{"nullable":true,"type":"string"},"meta_description":{"nullable":true,"type":"string"},"usp":{"nullable":true,"description":"How the brand should sound: the argument to hold to, the proof to cite, and the terms to avoid.","type":"object","properties":{"spine":{"type":"string"},"proof_points":{"type":"array","items":{"type":"string"}},"never_write_terms":{"type":"array","items":{"type":"string"}},"register_lines":{"type":"array","items":{"type":"string"}}},"required":["spine","proof_points","never_write_terms","register_lines"]},"brand_context":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"]},"description":"First-party facts the writer may draw on. Competitors are deliberately absent."},"language":{"nullable":true,"type":"object","properties":{"code":{"type":"string","example":"de","description":"ISO 639-1."},"name":{"type":"string","example":"German"}},"required":["code","name"]},"outline_points":{"description":"The brief section by section: what each one argues, the questions it answers and the evidence behind it. This endpoint always returns it; the MCP tool omits it unless asked.","type":"array","items":{"type":"object","properties":{"plan_index":{"type":"number","description":"1-based position of the plan point this was written from."},"label":{"type":"string"},"direction":{"type":"string"},"angle":{"type":"string"},"questions":{"type":"array","items":{"type":"string"}},"bullets":{"type":"array","items":{"type":"string"}},"brand_grounding":{"type":"string","description":"The only first-party brand claim this point may make."},"evidence":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","example":"winning_source"},"source":{"nullable":true,"description":"Null for the evidence kinds carrying no attribution.","type":"string"},"text":{"type":"string"}},"required":["kind","source","text"]}}},"required":["plan_index","label","direction","angle","questions","bullets","brand_grounding","evidence"]}}},"required":["title","points","brief","summary","overview","h1_options","meta_title","meta_description","usp","brand_context","language"]},"opportunity":{"nullable":true,"description":"The competitor demand behind a content brief. Null on other types.","type":"object","properties":{"target_citation_count":{"type":"number"},"page_type":{"type":"string","enum":["HOMEPAGE","CATEGORY_PAGE","PRODUCT_PAGE","LISTICLE","COMPARISON","PROFILE","ALTERNATIVE","DISCUSSION","HOW_TO_GUIDE","ARTICLE","REVIEW","OTHER"]},"page_type_label":{"type":"string"},"topic_name":{"type":"string"}},"required":["target_citation_count","page_type","page_type_label","topic_name"]},"impacted_prompts":{"description":"The prompts this action affects. For source-correction actions, own_coverage_score is the owned domains' share of all citations for that prompt in the action's analysis window. Other types use their documented page-coverage score. This endpoint always returns the field; the MCP tool omits it unless asked.","type":"array","items":{"type":"object","properties":{"prompt_id":{"type":"string"},"prompt_text":{"type":"string"},"own_coverage_score":{"type":"number"},"source_coverage_score":{"nullable":true,"type":"number"}},"required":["prompt_id","prompt_text","own_coverage_score","source_coverage_score"]}},"ngrams":{"description":"Terms competitors use on this topic that the brand's own pages do not. This endpoint always returns it; the MCP tool omits it unless asked.","type":"array","items":{"type":"object","properties":{"gram":{"type":"string"},"count":{"type":"number"}},"required":["gram","count"]}}},"required":["id","type","status","title","group","category","target","archetype","platform","topic_id","source","domain","country_codes","model_channel_ids","impact","step_count","completed_step_count","created_at","status_updated_at","created_by","priority","assignee_user_id","due_on","tag_ids","description","kind","notes","page_url","language_codes","repeat","time_range","content_brief_outline","opportunity"]}},"required":["data"],"description":"Success"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postActionsDetail"}},"/actions/platforms":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Action Platforms","description":"The third-party sites a project has actions on, as values for the action list's `platforms` filter. A platform is whichever domain AI engines cite for this brand, so the set is per project and open-ended. Own-site actions carry no platform and are absent here.","tags":["Actions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","example":"reddit.com","description":"Registrable domain of the third-party site."}},"required":["platform"]},"description":"Alphabetical."}},"required":["data"],"description":"Success"}}}}},"operationId":"postActionsPlatforms"}},"/actions/create":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Create Actions","description":"Record work the customer decided to do themselves as actions, in the same shape as the ones Peec generates, so they sort, filter and move through the same statuses. The kind picked decides an action's type and group. The linked topic and prompts are resolved against the project, and an item naming one it does not hold lands in `rejected` on its own — the batch never fails as a whole.","tags":["Actions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"actions":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"description":{"description":"What the action is for. `html` is the formatting the app's editor renders; `text` is what everything else reads.","type":"object","properties":{"text":{"type":"string","maxLength":10000},"html":{"type":"string","maxLength":10000}},"required":["text"]},"notes":{"description":"Working notes kept beside the action. Null clears them.","nullable":true,"type":"object","properties":{"text":{"type":"string","maxLength":10000},"html":{"type":"string","maxLength":10000}},"required":["text"]},"topic_id":{"description":"Topic the action is scoped to, from the topics endpoint. Null clears it.","example":"to_a1b2c3","nullable":true,"type":"string","minLength":1},"prompt_ids":{"description":"Prompts this action is meant to move, from the prompts endpoint. Replaces the whole list.","example":["pr_a1b2c3"],"maxItems":100,"type":"array","items":{"type":"string"}},"steps":{"description":"The work to do, replacing the whole step list.","maxItems":100,"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":10000,"description":"What to do, as one line.","example":"Add a pricing comparison table"},"description":{"description":"Detail below the step's own line.","type":"string","maxLength":10000},"completed":{"type":"boolean"},"section":{"description":"Heading this step sits under. Steps naming the same one are grouped together, in the order they first appear; steps naming none sit in the default list above every group.","example":"Before publishing","type":"string","minLength":1,"maxLength":80}},"required":["title"]}},"priority":{"description":"How much the action matters. It fills the same impact bars a generated action fills from its predicted lift, which is what lets the two sort together.","type":"string","enum":["none","low","medium","high"]},"country_codes":{"description":"ISO 3166-1 alpha-2 markets the action is scoped to. Null means every market the project tracks.","nullable":true,"maxItems":100,"type":"array","items":{"type":"string"}},"language_codes":{"nullable":true,"maxItems":100,"type":"array","items":{"type":"string"}},"tag_ids":{"maxItems":100,"type":"array","items":{"type":"string"}},"category":{"nullable":true,"type":"string"},"assignee_user_id":{"description":"The project member who owns the work. Null unassigns it.","nullable":true,"type":"string"},"due_on":{"description":"Calendar day in the project's timezone. Null clears it.","example":"2026-10-31","nullable":true,"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"repeat":{"description":"How often the work comes round again. Completing an action you wrote opens its next round as a new `PENDING` action, due one interval after this one (or after the day it was completed, when no `due_on` is set), and this one stops repeating. Null makes it one-off.","nullable":true,"type":"object","properties":{"every":{"type":"integer","minimum":1,"maximum":12},"unit":{"type":"string","enum":["day","week","month","year"]}},"required":["every","unit"]},"time_range":{"description":"The window the action's own measurements are read over.","nullable":true,"type":"string","enum":["7d","28d","90d","all"]},"title":{"type":"string","minLength":1,"maxLength":250,"example":"Add a pricing comparison table"},"kind":{"type":"string","enum":["CONTENT_OPTIMIZATION","CONTENT_CREATION","MENTION","TECHNICAL","PRODUCT_PAGE","OTHER"],"description":"What the work is, which decides the action's type and group so it files beside the generated ones: `CONTENT_OPTIMIZATION` (Content optimization), `CONTENT_CREATION` (Create content), `MENTION` (Improve a mention), `TECHNICAL` (Fix a technical issue), `PRODUCT_PAGE` (Improve a product page), `OTHER` (Something else)."},"status":{"default":"PLANNED","description":"Where the action starts. Defaults to `PLANNED`, to do and not started; `ACCEPTED` is in progress, `COMPLETED` is done, `REJECTED` was declined. `PENDING` is accepted and lands as `PLANNED`.","type":"string","enum":["PENDING","PLANNED","ACCEPTED","REJECTED","COMPLETED"]},"completed_at":{"description":"When the work was done, as an ISO 8601 date-time with an offset. Only a `COMPLETED` action takes one; it may be up to five years back and never in the future. Omitted means now. It is the date the action marks on the impact chart.","example":"2026-09-30T09:00:00Z","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"page_url":{"default":"","description":"The page the action lands on. Empty means it names no page. On an owned-page kind this is also the page the action is measured against.","example":"https://example.com/pricing","type":"string","maxLength":2048}},"required":["title","kind"]},"description":"Up to 50 actions to write."}},"required":["actions"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"actions":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"description":{"description":"What the action is for. `html` is the formatting the app's editor renders; `text` is what everything else reads.","type":"object","properties":{"text":{"type":"string","maxLength":10000},"html":{"type":"string","maxLength":10000}},"required":["text"]},"notes":{"description":"Working notes kept beside the action. Null clears them.","nullable":true,"type":"object","properties":{"text":{"type":"string","maxLength":10000},"html":{"type":"string","maxLength":10000}},"required":["text"]},"topic_id":{"description":"Topic the action is scoped to, from the topics endpoint. Null clears it.","example":"to_a1b2c3","nullable":true,"type":"string","minLength":1},"prompt_ids":{"description":"Prompts this action is meant to move, from the prompts endpoint. Replaces the whole list.","example":["pr_a1b2c3"],"maxItems":100,"type":"array","items":{"type":"string"}},"steps":{"description":"The work to do, replacing the whole step list.","maxItems":100,"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":10000,"description":"What to do, as one line.","example":"Add a pricing comparison table"},"description":{"description":"Detail below the step's own line.","type":"string","maxLength":10000},"completed":{"type":"boolean"},"section":{"description":"Heading this step sits under. Steps naming the same one are grouped together, in the order they first appear; steps naming none sit in the default list above every group.","example":"Before publishing","type":"string","minLength":1,"maxLength":80}},"required":["title"]}},"priority":{"description":"How much the action matters. It fills the same impact bars a generated action fills from its predicted lift, which is what lets the two sort together.","type":"string","enum":["none","low","medium","high"]},"country_codes":{"description":"ISO 3166-1 alpha-2 markets the action is scoped to. Null means every market the project tracks.","nullable":true,"maxItems":100,"type":"array","items":{"type":"string"}},"language_codes":{"nullable":true,"maxItems":100,"type":"array","items":{"type":"string"}},"tag_ids":{"maxItems":100,"type":"array","items":{"type":"string"}},"category":{"nullable":true,"type":"string"},"assignee_user_id":{"description":"The project member who owns the work. Null unassigns it.","nullable":true,"type":"string"},"due_on":{"description":"Calendar day in the project's timezone. Null clears it.","example":"2026-10-31","nullable":true,"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"repeat":{"description":"How often the work comes round again. Completing an action you wrote opens its next round as a new `PENDING` action, due one interval after this one (or after the day it was completed, when no `due_on` is set), and this one stops repeating. Null makes it one-off.","nullable":true,"type":"object","properties":{"every":{"type":"integer","minimum":1,"maximum":12},"unit":{"type":"string","enum":["day","week","month","year"]}},"required":["every","unit"]},"time_range":{"description":"The window the action's own measurements are read over.","nullable":true,"type":"string","enum":["7d","28d","90d","all"]},"title":{"type":"string","minLength":1,"maxLength":250,"example":"Add a pricing comparison table"},"kind":{"type":"string","enum":["CONTENT_OPTIMIZATION","CONTENT_CREATION","MENTION","TECHNICAL","PRODUCT_PAGE","OTHER"],"description":"What the work is, which decides the action's type and group so it files beside the generated ones: `CONTENT_OPTIMIZATION` (Content optimization), `CONTENT_CREATION` (Create content), `MENTION` (Improve a mention), `TECHNICAL` (Fix a technical issue), `PRODUCT_PAGE` (Improve a product page), `OTHER` (Something else)."},"status":{"default":"PLANNED","description":"Where the action starts. Defaults to `PLANNED`, to do and not started; `ACCEPTED` is in progress, `COMPLETED` is done, `REJECTED` was declined. `PENDING` is accepted and lands as `PLANNED`.","type":"string","enum":["PENDING","PLANNED","ACCEPTED","REJECTED","COMPLETED"]},"completed_at":{"description":"When the work was done, as an ISO 8601 date-time with an offset. Only a `COMPLETED` action takes one; it may be up to five years back and never in the future. Omitted means now. It is the date the action marks on the impact chart.","example":"2026-09-30T09:00:00Z","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"page_url":{"default":"","description":"The page the action lands on. Empty means it names no page. On an owned-page kind this is also the page the action is measured against.","example":"https://example.com/pricing","type":"string","maxLength":2048}},"required":["title","kind"]},"description":"Up to 50 actions to write."}},"required":["actions"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"actions":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"description":{"description":"What the action is for. `html` is the formatting the app's editor renders; `text` is what everything else reads.","type":"object","properties":{"text":{"type":"string","maxLength":10000},"html":{"type":"string","maxLength":10000}},"required":["text"]},"notes":{"description":"Working notes kept beside the action. Null clears them.","nullable":true,"type":"object","properties":{"text":{"type":"string","maxLength":10000},"html":{"type":"string","maxLength":10000}},"required":["text"]},"topic_id":{"description":"Topic the action is scoped to, from the topics endpoint. Null clears it.","example":"to_a1b2c3","nullable":true,"type":"string","minLength":1},"prompt_ids":{"description":"Prompts this action is meant to move, from the prompts endpoint. Replaces the whole list.","example":["pr_a1b2c3"],"maxItems":100,"type":"array","items":{"type":"string"}},"steps":{"description":"The work to do, replacing the whole step list.","maxItems":100,"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":10000,"description":"What to do, as one line.","example":"Add a pricing comparison table"},"description":{"description":"Detail below the step's own line.","type":"string","maxLength":10000},"completed":{"type":"boolean"},"section":{"description":"Heading this step sits under. Steps naming the same one are grouped together, in the order they first appear; steps naming none sit in the default list above every group.","example":"Before publishing","type":"string","minLength":1,"maxLength":80}},"required":["title"]}},"priority":{"description":"How much the action matters. It fills the same impact bars a generated action fills from its predicted lift, which is what lets the two sort together.","type":"string","enum":["none","low","medium","high"]},"country_codes":{"description":"ISO 3166-1 alpha-2 markets the action is scoped to. Null means every market the project tracks.","nullable":true,"maxItems":100,"type":"array","items":{"type":"string"}},"language_codes":{"nullable":true,"maxItems":100,"type":"array","items":{"type":"string"}},"tag_ids":{"maxItems":100,"type":"array","items":{"type":"string"}},"category":{"nullable":true,"type":"string"},"assignee_user_id":{"description":"The project member who owns the work. Null unassigns it.","nullable":true,"type":"string"},"due_on":{"description":"Calendar day in the project's timezone. Null clears it.","example":"2026-10-31","nullable":true,"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"repeat":{"description":"How often the work comes round again. Completing an action you wrote opens its next round as a new `PENDING` action, due one interval after this one (or after the day it was completed, when no `due_on` is set), and this one stops repeating. Null makes it one-off.","nullable":true,"type":"object","properties":{"every":{"type":"integer","minimum":1,"maximum":12},"unit":{"type":"string","enum":["day","week","month","year"]}},"required":["every","unit"]},"time_range":{"description":"The window the action's own measurements are read over.","nullable":true,"type":"string","enum":["7d","28d","90d","all"]},"title":{"type":"string","minLength":1,"maxLength":250,"example":"Add a pricing comparison table"},"kind":{"type":"string","enum":["CONTENT_OPTIMIZATION","CONTENT_CREATION","MENTION","TECHNICAL","PRODUCT_PAGE","OTHER"],"description":"What the work is, which decides the action's type and group so it files beside the generated ones: `CONTENT_OPTIMIZATION` (Content optimization), `CONTENT_CREATION` (Create content), `MENTION` (Improve a mention), `TECHNICAL` (Fix a technical issue), `PRODUCT_PAGE` (Improve a product page), `OTHER` (Something else)."},"status":{"default":"PLANNED","description":"Where the action starts. Defaults to `PLANNED`, to do and not started; `ACCEPTED` is in progress, `COMPLETED` is done, `REJECTED` was declined. `PENDING` is accepted and lands as `PLANNED`.","type":"string","enum":["PENDING","PLANNED","ACCEPTED","REJECTED","COMPLETED"]},"completed_at":{"description":"When the work was done, as an ISO 8601 date-time with an offset. Only a `COMPLETED` action takes one; it may be up to five years back and never in the future. Omitted means now. It is the date the action marks on the impact chart.","example":"2026-09-30T09:00:00Z","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"page_url":{"default":"","description":"The page the action lands on. Empty means it names no page. On an owned-page kind this is also the page the action is measured against.","example":"https://example.com/pricing","type":"string","maxLength":2048}},"required":["title","kind"]},"description":"Up to 50 actions to write."}},"required":["actions"]}}}},"responses":{"200":{"description":"Per-item results, `index` naming the position in the request.","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number"},"action_id":{"type":"string"},"title":{"type":"string"}},"required":["index","action_id","title"]}},"rejected":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number"},"reason":{"type":"string","enum":["invalid"]},"message":{"type":"string"}},"required":["index","reason","message"]}}},"required":["created","rejected"],"description":"Per-item results, `index` naming the position in the request."}}}}},"operationId":"postActionsCreate"}},"/actions/update":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Update Actions","description":"Rewrite the fields a customer owns, on actions they wrote or ones Peec generated. An edit is stored beside the generated wording rather than in it, so a regeneration cannot discard it. Only a customer's own action can change shape: the type and group of a generated one say what Peec found, and an item trying to move them lands in `rejected`. A field the item leaves out keeps what it held; `null` clears the ones that can be cleared, and an item naming no field at all is rejected rather than recorded as an edit. Ids the project publishes no action under are returned in `skipped` — the batch never fails as a whole. A content optimisation is reachable only on a project with content optimisation enabled; elsewhere its id is returned in `skipped`.","tags":["Actions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"actions":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The action to rewrite, from list_actions.","example":"01a0422f-e0c4-7820-85a1-31515a321f15"},"description":{"description":"What the action is for. `html` is the formatting the app's editor renders; `text` is what everything else reads.","type":"object","properties":{"text":{"type":"string","maxLength":10000},"html":{"type":"string","maxLength":10000}},"required":["text"]},"notes":{"description":"Working notes kept beside the action. Null clears them.","nullable":true,"type":"object","properties":{"text":{"type":"string","maxLength":10000},"html":{"type":"string","maxLength":10000}},"required":["text"]},"topic_id":{"description":"Topic the action is scoped to, from the topics endpoint. Null clears it.","example":"to_a1b2c3","nullable":true,"type":"string","minLength":1},"prompt_ids":{"description":"Prompts this action is meant to move, from the prompts endpoint. Replaces the whole list.","example":["pr_a1b2c3"],"maxItems":100,"type":"array","items":{"type":"string"}},"steps":{"description":"The work to do, replacing the whole step list.","maxItems":100,"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":10000,"description":"What to do, as one line.","example":"Add a pricing comparison table"},"description":{"description":"Detail below the step's own line.","type":"string","maxLength":10000},"completed":{"type":"boolean"},"section":{"description":"Heading this step sits under. Steps naming the same one are grouped together, in the order they first appear; steps naming none sit in the default list above every group.","example":"Before publishing","type":"string","minLength":1,"maxLength":80}},"required":["title"]}},"priority":{"description":"How much the action matters. It fills the same impact bars a generated action fills from its predicted lift, which is what lets the two sort together.","type":"string","enum":["none","low","medium","high"]},"country_codes":{"description":"ISO 3166-1 alpha-2 markets the action is scoped to. Null means every market the project tracks.","nullable":true,"maxItems":100,"type":"array","items":{"type":"string"}},"language_codes":{"nullable":true,"maxItems":100,"type":"array","items":{"type":"string"}},"tag_ids":{"maxItems":100,"type":"array","items":{"type":"string"}},"category":{"nullable":true,"type":"string"},"assignee_user_id":{"description":"The project member who owns the work. Null unassigns it.","nullable":true,"type":"string"},"due_on":{"description":"Calendar day in the project's timezone. Null clears it.","example":"2026-10-31","nullable":true,"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"repeat":{"description":"How often the work comes round again. Completing an action you wrote opens its next round as a new `PENDING` action, due one interval after this one (or after the day it was completed, when no `due_on` is set), and this one stops repeating. Null makes it one-off.","nullable":true,"type":"object","properties":{"every":{"type":"integer","minimum":1,"maximum":12},"unit":{"type":"string","enum":["day","week","month","year"]}},"required":["every","unit"]},"time_range":{"description":"The window the action's own measurements are read over.","nullable":true,"type":"string","enum":["7d","28d","90d","all"]},"title":{"type":"string","minLength":1,"maxLength":250},"kind":{"description":"What the work is. Only an action the customer wrote can change shape — a generated one keeps the type and group Peec found it under. One of: `CONTENT_OPTIMIZATION` (Content optimization), `CONTENT_CREATION` (Create content), `MENTION` (Improve a mention), `TECHNICAL` (Fix a technical issue), `PRODUCT_PAGE` (Improve a product page), `OTHER` (Something else).","type":"string","enum":["CONTENT_OPTIMIZATION","CONTENT_CREATION","MENTION","TECHNICAL","PRODUCT_PAGE","OTHER"]},"page_url":{"description":"The page the action lands on. Empty means it names no page. On an owned-page kind this is also the page the action is measured against.","type":"string","maxLength":2048}},"required":["action_id"]}}},"required":["actions"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"actions":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The action to rewrite, from list_actions.","example":"01a0422f-e0c4-7820-85a1-31515a321f15"},"description":{"description":"What the action is for. `html` is the formatting the app's editor renders; `text` is what everything else reads.","type":"object","properties":{"text":{"type":"string","maxLength":10000},"html":{"type":"string","maxLength":10000}},"required":["text"]},"notes":{"description":"Working notes kept beside the action. Null clears them.","nullable":true,"type":"object","properties":{"text":{"type":"string","maxLength":10000},"html":{"type":"string","maxLength":10000}},"required":["text"]},"topic_id":{"description":"Topic the action is scoped to, from the topics endpoint. Null clears it.","example":"to_a1b2c3","nullable":true,"type":"string","minLength":1},"prompt_ids":{"description":"Prompts this action is meant to move, from the prompts endpoint. Replaces the whole list.","example":["pr_a1b2c3"],"maxItems":100,"type":"array","items":{"type":"string"}},"steps":{"description":"The work to do, replacing the whole step list.","maxItems":100,"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":10000,"description":"What to do, as one line.","example":"Add a pricing comparison table"},"description":{"description":"Detail below the step's own line.","type":"string","maxLength":10000},"completed":{"type":"boolean"},"section":{"description":"Heading this step sits under. Steps naming the same one are grouped together, in the order they first appear; steps naming none sit in the default list above every group.","example":"Before publishing","type":"string","minLength":1,"maxLength":80}},"required":["title"]}},"priority":{"description":"How much the action matters. It fills the same impact bars a generated action fills from its predicted lift, which is what lets the two sort together.","type":"string","enum":["none","low","medium","high"]},"country_codes":{"description":"ISO 3166-1 alpha-2 markets the action is scoped to. Null means every market the project tracks.","nullable":true,"maxItems":100,"type":"array","items":{"type":"string"}},"language_codes":{"nullable":true,"maxItems":100,"type":"array","items":{"type":"string"}},"tag_ids":{"maxItems":100,"type":"array","items":{"type":"string"}},"category":{"nullable":true,"type":"string"},"assignee_user_id":{"description":"The project member who owns the work. Null unassigns it.","nullable":true,"type":"string"},"due_on":{"description":"Calendar day in the project's timezone. Null clears it.","example":"2026-10-31","nullable":true,"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"repeat":{"description":"How often the work comes round again. Completing an action you wrote opens its next round as a new `PENDING` action, due one interval after this one (or after the day it was completed, when no `due_on` is set), and this one stops repeating. Null makes it one-off.","nullable":true,"type":"object","properties":{"every":{"type":"integer","minimum":1,"maximum":12},"unit":{"type":"string","enum":["day","week","month","year"]}},"required":["every","unit"]},"time_range":{"description":"The window the action's own measurements are read over.","nullable":true,"type":"string","enum":["7d","28d","90d","all"]},"title":{"type":"string","minLength":1,"maxLength":250},"kind":{"description":"What the work is. Only an action the customer wrote can change shape — a generated one keeps the type and group Peec found it under. One of: `CONTENT_OPTIMIZATION` (Content optimization), `CONTENT_CREATION` (Create content), `MENTION` (Improve a mention), `TECHNICAL` (Fix a technical issue), `PRODUCT_PAGE` (Improve a product page), `OTHER` (Something else).","type":"string","enum":["CONTENT_OPTIMIZATION","CONTENT_CREATION","MENTION","TECHNICAL","PRODUCT_PAGE","OTHER"]},"page_url":{"description":"The page the action lands on. Empty means it names no page. On an owned-page kind this is also the page the action is measured against.","type":"string","maxLength":2048}},"required":["action_id"]}}},"required":["actions"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"actions":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The action to rewrite, from list_actions.","example":"01a0422f-e0c4-7820-85a1-31515a321f15"},"description":{"description":"What the action is for. `html` is the formatting the app's editor renders; `text` is what everything else reads.","type":"object","properties":{"text":{"type":"string","maxLength":10000},"html":{"type":"string","maxLength":10000}},"required":["text"]},"notes":{"description":"Working notes kept beside the action. Null clears them.","nullable":true,"type":"object","properties":{"text":{"type":"string","maxLength":10000},"html":{"type":"string","maxLength":10000}},"required":["text"]},"topic_id":{"description":"Topic the action is scoped to, from the topics endpoint. Null clears it.","example":"to_a1b2c3","nullable":true,"type":"string","minLength":1},"prompt_ids":{"description":"Prompts this action is meant to move, from the prompts endpoint. Replaces the whole list.","example":["pr_a1b2c3"],"maxItems":100,"type":"array","items":{"type":"string"}},"steps":{"description":"The work to do, replacing the whole step list.","maxItems":100,"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":10000,"description":"What to do, as one line.","example":"Add a pricing comparison table"},"description":{"description":"Detail below the step's own line.","type":"string","maxLength":10000},"completed":{"type":"boolean"},"section":{"description":"Heading this step sits under. Steps naming the same one are grouped together, in the order they first appear; steps naming none sit in the default list above every group.","example":"Before publishing","type":"string","minLength":1,"maxLength":80}},"required":["title"]}},"priority":{"description":"How much the action matters. It fills the same impact bars a generated action fills from its predicted lift, which is what lets the two sort together.","type":"string","enum":["none","low","medium","high"]},"country_codes":{"description":"ISO 3166-1 alpha-2 markets the action is scoped to. Null means every market the project tracks.","nullable":true,"maxItems":100,"type":"array","items":{"type":"string"}},"language_codes":{"nullable":true,"maxItems":100,"type":"array","items":{"type":"string"}},"tag_ids":{"maxItems":100,"type":"array","items":{"type":"string"}},"category":{"nullable":true,"type":"string"},"assignee_user_id":{"description":"The project member who owns the work. Null unassigns it.","nullable":true,"type":"string"},"due_on":{"description":"Calendar day in the project's timezone. Null clears it.","example":"2026-10-31","nullable":true,"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"repeat":{"description":"How often the work comes round again. Completing an action you wrote opens its next round as a new `PENDING` action, due one interval after this one (or after the day it was completed, when no `due_on` is set), and this one stops repeating. Null makes it one-off.","nullable":true,"type":"object","properties":{"every":{"type":"integer","minimum":1,"maximum":12},"unit":{"type":"string","enum":["day","week","month","year"]}},"required":["every","unit"]},"time_range":{"description":"The window the action's own measurements are read over.","nullable":true,"type":"string","enum":["7d","28d","90d","all"]},"title":{"type":"string","minLength":1,"maxLength":250},"kind":{"description":"What the work is. Only an action the customer wrote can change shape — a generated one keeps the type and group Peec found it under. One of: `CONTENT_OPTIMIZATION` (Content optimization), `CONTENT_CREATION` (Create content), `MENTION` (Improve a mention), `TECHNICAL` (Fix a technical issue), `PRODUCT_PAGE` (Improve a product page), `OTHER` (Something else).","type":"string","enum":["CONTENT_OPTIMIZATION","CONTENT_CREATION","MENTION","TECHNICAL","PRODUCT_PAGE","OTHER"]},"page_url":{"description":"The page the action lands on. Empty means it names no page. On an owned-page kind this is also the page the action is measured against.","type":"string","maxLength":2048}},"required":["action_id"]}}},"required":["actions"]}}}},"responses":{"200":{"description":"Per-item results","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string"}},"required":["action_id"]}},"skipped":{"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string"},"reason":{"type":"string","enum":["not_found"]}},"required":["action_id","reason"]}},"rejected":{"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string"},"reason":{"type":"string","enum":["duplicate_id","no_change","invalid"]},"message":{"type":"string"}},"required":["action_id","reason","message"]}}},"required":["updated","skipped","rejected"],"description":"Per-item results"}}}}},"operationId":"postActionsUpdate"}},"/actions/delete":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Delete Actions","description":"Remove actions the customer wrote themselves. A generated action reads here exactly as a missing one does and lands in `skipped`: those are declined or dismissed through the status endpoint instead, so the list keeps a record of what Peec suggested and the customer turned down.","tags":["Actions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"action_ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"Up to 50 action ids, from list_actions.","example":["01a0422f-e0c4-7820-85a1-31515a321f15"]}},"required":["action_ids"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"action_ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"Up to 50 action ids, from list_actions.","example":["01a0422f-e0c4-7820-85a1-31515a321f15"]}},"required":["action_ids"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"action_ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"Up to 50 action ids, from list_actions.","example":["01a0422f-e0c4-7820-85a1-31515a321f15"]}},"required":["action_ids"]}}}},"responses":{"200":{"description":"Per-item results","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string"}},"required":["action_id"]}},"skipped":{"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string"},"reason":{"type":"string","enum":["not_found"]}},"required":["action_id","reason"]}}},"required":["deleted","skipped"],"description":"Per-item results"}}}}},"operationId":"postActionsDelete"}},"/actions/status":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Update Action Status","description":"Move actions to a status by id: accept, reject, complete, delete, or send one back to `PENDING`. Ids the project publishes no action under are returned in `skipped` — the batch never fails as a whole. An action that is already deleted reads as absent unless the key is a platform admin one. A content optimisation is reachable only on a project with content optimisation enabled; elsewhere its id is returned in `skipped`. Send `completed_at` with `COMPLETED` to record when the work was actually done.","tags":["Actions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"action_ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"Up to 50 action ids, from list_actions.","example":["01a0422f-e0c4-7820-85a1-31515a321f15"]},"status":{"type":"string","enum":["PENDING","PLANNED","ACCEPTED","REJECTED","COMPLETED","DELETED"]},"completed_at":{"description":"When the work was done, as an ISO 8601 date-time with an offset. Only a `COMPLETED` action takes one; it may be up to five years back and never in the future. Omitted means now. It is the date the action marks on the impact chart.","example":"2026-09-30T09:00:00Z","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["action_ids","status"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"action_ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"Up to 50 action ids, from list_actions.","example":["01a0422f-e0c4-7820-85a1-31515a321f15"]},"status":{"type":"string","enum":["PENDING","PLANNED","ACCEPTED","REJECTED","COMPLETED","DELETED"]},"completed_at":{"description":"When the work was done, as an ISO 8601 date-time with an offset. Only a `COMPLETED` action takes one; it may be up to five years back and never in the future. Omitted means now. It is the date the action marks on the impact chart.","example":"2026-09-30T09:00:00Z","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["action_ids","status"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"action_ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"Up to 50 action ids, from list_actions.","example":["01a0422f-e0c4-7820-85a1-31515a321f15"]},"status":{"type":"string","enum":["PENDING","PLANNED","ACCEPTED","REJECTED","COMPLETED","DELETED"]},"completed_at":{"description":"When the work was done, as an ISO 8601 date-time with an offset. Only a `COMPLETED` action takes one; it may be up to five years back and never in the future. Omitted means now. It is the date the action marks on the impact chart.","example":"2026-09-30T09:00:00Z","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["action_ids","status"]}}}},"responses":{"200":{"description":"Per-item status results","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string"}},"required":["action_id"]}},"skipped":{"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string"},"reason":{"type":"string","enum":["not_found"]}},"required":["action_id","reason"]}},"rejected":{"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string"},"reason":{"type":"string","enum":["duplicate_id"]},"message":{"type":"string"}},"required":["action_id","reason","message"]}}},"required":["updated","skipped","rejected"],"description":"Per-item status results"}}}}},"operationId":"postActionsStatus"}},"/actions/steps/completion":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Set Action Step Completion","description":"Record which of an action's steps are done. Each entry names one action and either sets `completed` for every step it holds, or lists the steps to write; a step in turn either sets `completed` for all of its options or names them individually, each with its own value, so one call can tick some and untick others. An action is all or nothing: anything Peec cannot apply leaves every step on it untouched and comes back under `skipped` or `rejected`, so a partly-written action is never a state you have to read back. Other actions in the same call are unaffected. The action's own status is never changed by this endpoint, including when every step on it is complete. An action that is already deleted reads as absent unless the key is a platform admin one. A content optimisation is reachable only on a project with content optimisation enabled; elsewhere its id is returned in `skipped`.","tags":["Actions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"actions":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","example":"01a0422f-e0c4-7820-85a1-31515a321f15","description":"The action the steps belong to. Name it once and list every step written on it, rather than repeating the action per step."},"completed":{"description":"Sets every option the action holds. Naming steps is how to write part of an action, and is also the only form that fails loudly on a step id Peec has regenerated — setting the whole action applies to whatever it holds at the time of the write.","type":"boolean"},"steps":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"step_id":{"type":"string","example":"3f1c8a92-4d5b-4e77-9c21-8ab0f6d21e10","description":"A step id from the action detail read. Steps are addressed by id rather than by position, so an action Peec has since regenerated fails as `step_not_found` instead of writing the wrong work."},"completed":{"description":"Sets every option in the step at once, which is what the step's own checkbox does.","type":"boolean"},"options":{"description":"Sets named options individually, each with its own value, so one call can tick some and untick others.","minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"option_id":{"type":"string","example":"9d4e2b71-6c8a-4f13-b5d0-1e7a3c9f2b84","description":"An option id from the action detail read."},"completed":{"type":"boolean","description":"`true` marks this option done, `false` puts it back."}},"required":["option_id","completed"]}}},"required":["step_id"]}}},"required":["action_id"]}}},"required":["actions"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"actions":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","example":"01a0422f-e0c4-7820-85a1-31515a321f15","description":"The action the steps belong to. Name it once and list every step written on it, rather than repeating the action per step."},"completed":{"description":"Sets every option the action holds. Naming steps is how to write part of an action, and is also the only form that fails loudly on a step id Peec has regenerated — setting the whole action applies to whatever it holds at the time of the write.","type":"boolean"},"steps":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"step_id":{"type":"string","example":"3f1c8a92-4d5b-4e77-9c21-8ab0f6d21e10","description":"A step id from the action detail read. Steps are addressed by id rather than by position, so an action Peec has since regenerated fails as `step_not_found` instead of writing the wrong work."},"completed":{"description":"Sets every option in the step at once, which is what the step's own checkbox does.","type":"boolean"},"options":{"description":"Sets named options individually, each with its own value, so one call can tick some and untick others.","minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"option_id":{"type":"string","example":"9d4e2b71-6c8a-4f13-b5d0-1e7a3c9f2b84","description":"An option id from the action detail read."},"completed":{"type":"boolean","description":"`true` marks this option done, `false` puts it back."}},"required":["option_id","completed"]}}},"required":["step_id"]}}},"required":["action_id"]}}},"required":["actions"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"actions":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","example":"01a0422f-e0c4-7820-85a1-31515a321f15","description":"The action the steps belong to. Name it once and list every step written on it, rather than repeating the action per step."},"completed":{"description":"Sets every option the action holds. Naming steps is how to write part of an action, and is also the only form that fails loudly on a step id Peec has regenerated — setting the whole action applies to whatever it holds at the time of the write.","type":"boolean"},"steps":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"step_id":{"type":"string","example":"3f1c8a92-4d5b-4e77-9c21-8ab0f6d21e10","description":"A step id from the action detail read. Steps are addressed by id rather than by position, so an action Peec has since regenerated fails as `step_not_found` instead of writing the wrong work."},"completed":{"description":"Sets every option in the step at once, which is what the step's own checkbox does.","type":"boolean"},"options":{"description":"Sets named options individually, each with its own value, so one call can tick some and untick others.","minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"option_id":{"type":"string","example":"9d4e2b71-6c8a-4f13-b5d0-1e7a3c9f2b84","description":"An option id from the action detail read."},"completed":{"type":"boolean","description":"`true` marks this option done, `false` puts it back."}},"required":["option_id","completed"]}}},"required":["step_id"]}}},"required":["action_id"]}}},"required":["actions"]}}}},"responses":{"200":{"description":"Per-item completion results","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string"}},"required":["action_id"]}},"skipped":{"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string"},"reason":{"type":"string","enum":["not_found"]}},"required":["action_id","reason"]}},"rejected":{"type":"array","items":{"type":"object","properties":{"action_id":{"type":"string"},"reason":{"type":"string","enum":["step_not_found","option_not_found","duplicate_id","duplicate_step_id","not_completable"],"description":"`step_not_found` and `option_not_found` name a step or option the action does not hold — usually an id from before Peec regenerated it. `duplicate_id` and `duplicate_step_id` mean the same action, or the same step within one action, appeared more than once in this call. `not_completable` is a content brief, whose steps are the material the brief was written from rather than work to do."},"message":{"type":"string"}},"required":["action_id","reason","message"]}}},"required":["updated","skipped","rejected"],"description":"Per-item completion results"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postActionsStepsCompletion"}},"/products/attributes":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Shopping Attributes","description":"The LLM-extracted attribute comparison grid for a product (scope=product) or the whole catalog (scope=overview), split by tab into characteristics, facts, and dimensions. Columns are competing brands (compare_by=brand) or competing products (compare_by=product, scope=product only). Deltas are computed against an explicit comparison window (previous_start_date/previous_end_date) or the equal-length window immediately before.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"scope":{"default":"product","description":"`product` compares one product (needs product_id); `overview` compares the whole catalog.","type":"string","enum":["product","overview"]},"compare_by":{"default":"brand","description":"Grid columns: competing `brand`s, or competing `product`s. `product` is only valid when scope=product.","type":"string","enum":["brand","product"]},"tab":{"default":"characteristics","description":"`characteristics` (qualitative values), `facts` (true/false), `dimensions` (ordinal ratings).","type":"string","enum":["characteristics","facts","dimensions"]},"product_id":{"description":"Required when scope=product.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"category_ids":{"description":"Filter to products in any of these category ids (from list_categories); selecting a parent also matches its descendants. e.g. [\"3f2504e0-4f89-41d3-9a0c-0305e82c3301\"].","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"description":"Filter to chats from these countries (ISO 3166-1 alpha-2), e.g. [\"US\", \"GB\"]. Omit for all countries.","type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}},"model_ids":{"description":"Filter to these model ids (from list_models), e.g. [\"gpt-4o\"]. Omit for all models.","type":"array","items":{"type":"string","enum":["chatgpt","microsoft-copilot","sonar-api","grok-api","gpt-4o-search","sonar","google-ai-overview","google-ai-mode","gemini-2-5-flash","gemini-3-1-flash-lite","gemini-3-1-flash-lite-search","claude-sonnet-4","claude-sonnet-4-6","claude-sonnet-5","claude-haiku-4-5","grok-2-1212","gpt-4o","qwen-3-6-plus","qwen-3-7-plus","gpt-3-5-turbo","gemini-1-5-flash","deepseek-r1","deepseek-v4-pro","llama-3-3-70b-instruct","gpt-5-1","gemini-2-5-flash-preview-05-20","claude-3-5-sonnet","chatgpt-ui","gpt-5-search","gpt-5-6-luna","perplexity-ui","gemini-ui","grok-4","grok-4-3","grok-4-6","grok-ui","microsoft-copilot-ui","claude-3-5-haiku","llama-3-1-sonar-small-128k-online","amazon-rufus","mistral-small-4","mistral-medium-3-5","muse-spark-1-2","muse-spark-1-3","naver-ai-briefing-ui","claude-opus-5","claude-fable-5-1","gpt-6-astra","gpt-5-6-sol","gpt-5-6-terra","gpt-6-luna","gpt-6-sol","claude-opus-5-5","gpt-6-1-sol","ernie-ui","claude-haiku-5-5","muse-wonder-1-0","gemini-4-argon"]}},"model_channel_ids":{"description":"Filter to these model channel ids (from list_model_channels), e.g. [\"openai-0\"]. Omit for all engines.","type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"description":"Filter to prompts under any of these topic ids (from list_topics), e.g. [\"to_a1b2c3\"].","type":"array","items":{"type":"string"}},"tag_ids":{"description":"Filter to prompts carrying these tag ids (from list_tags; combine with tag_operator), e.g. [\"tg_a1b2c3\"].","type":"array","items":{"type":"string"}},"tag_operator":{"description":"Match prompts carrying any (or, default) or all (and) of tag_ids.","type":"string","enum":["and","or"]},"search":{"description":"Substring match on dimension name (and value, characteristics).","type":"string"},"competitor_count":{"description":"Grid columns; default 6. `0` disables competitor lookup.","type":"integer","minimum":0,"maximum":20},"values_per_group":{"description":"Characteristics tab only; default 12.","type":"integer","minimum":1,"maximum":50},"limit":{"description":"Page size over dimension groups.","type":"integer","minimum":1,"maximum":100},"offset":{"description":"Number of dimension groups to skip for pagination, e.g. 0.","type":"integer","minimum":0,"maximum":9007199254740991}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"scope":{"default":"product","description":"`product` compares one product (needs product_id); `overview` compares the whole catalog.","type":"string","enum":["product","overview"]},"compare_by":{"default":"brand","description":"Grid columns: competing `brand`s, or competing `product`s. `product` is only valid when scope=product.","type":"string","enum":["brand","product"]},"tab":{"default":"characteristics","description":"`characteristics` (qualitative values), `facts` (true/false), `dimensions` (ordinal ratings).","type":"string","enum":["characteristics","facts","dimensions"]},"product_id":{"description":"Required when scope=product.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"category_ids":{"description":"Filter to products in any of these category ids (from list_categories); selecting a parent also matches its descendants. e.g. [\"3f2504e0-4f89-41d3-9a0c-0305e82c3301\"].","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"description":"Filter to chats from these countries (ISO 3166-1 alpha-2), e.g. [\"US\", \"GB\"]. Omit for all countries.","type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}},"model_ids":{"description":"Filter to these model ids (from list_models), e.g. [\"gpt-4o\"]. Omit for all models.","type":"array","items":{"type":"string","enum":["chatgpt","microsoft-copilot","sonar-api","grok-api","gpt-4o-search","sonar","google-ai-overview","google-ai-mode","gemini-2-5-flash","gemini-3-1-flash-lite","gemini-3-1-flash-lite-search","claude-sonnet-4","claude-sonnet-4-6","claude-sonnet-5","claude-haiku-4-5","grok-2-1212","gpt-4o","qwen-3-6-plus","qwen-3-7-plus","gpt-3-5-turbo","gemini-1-5-flash","deepseek-r1","deepseek-v4-pro","llama-3-3-70b-instruct","gpt-5-1","gemini-2-5-flash-preview-05-20","claude-3-5-sonnet","chatgpt-ui","gpt-5-search","gpt-5-6-luna","perplexity-ui","gemini-ui","grok-4","grok-4-3","grok-4-6","grok-ui","microsoft-copilot-ui","claude-3-5-haiku","llama-3-1-sonar-small-128k-online","amazon-rufus","mistral-small-4","mistral-medium-3-5","muse-spark-1-2","muse-spark-1-3","naver-ai-briefing-ui","claude-opus-5","claude-fable-5-1","gpt-6-astra","gpt-5-6-sol","gpt-5-6-terra","gpt-6-luna","gpt-6-sol","claude-opus-5-5","gpt-6-1-sol","ernie-ui","claude-haiku-5-5","muse-wonder-1-0","gemini-4-argon"]}},"model_channel_ids":{"description":"Filter to these model channel ids (from list_model_channels), e.g. [\"openai-0\"]. Omit for all engines.","type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"description":"Filter to prompts under any of these topic ids (from list_topics), e.g. [\"to_a1b2c3\"].","type":"array","items":{"type":"string"}},"tag_ids":{"description":"Filter to prompts carrying these tag ids (from list_tags; combine with tag_operator), e.g. [\"tg_a1b2c3\"].","type":"array","items":{"type":"string"}},"tag_operator":{"description":"Match prompts carrying any (or, default) or all (and) of tag_ids.","type":"string","enum":["and","or"]},"search":{"description":"Substring match on dimension name (and value, characteristics).","type":"string"},"competitor_count":{"description":"Grid columns; default 6. `0` disables competitor lookup.","type":"integer","minimum":0,"maximum":20},"values_per_group":{"description":"Characteristics tab only; default 12.","type":"integer","minimum":1,"maximum":50},"limit":{"description":"Page size over dimension groups.","type":"integer","minimum":1,"maximum":100},"offset":{"description":"Number of dimension groups to skip for pagination, e.g. 0.","type":"integer","minimum":0,"maximum":9007199254740991}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"scope":{"default":"product","description":"`product` compares one product (needs product_id); `overview` compares the whole catalog.","type":"string","enum":["product","overview"]},"compare_by":{"default":"brand","description":"Grid columns: competing `brand`s, or competing `product`s. `product` is only valid when scope=product.","type":"string","enum":["brand","product"]},"tab":{"default":"characteristics","description":"`characteristics` (qualitative values), `facts` (true/false), `dimensions` (ordinal ratings).","type":"string","enum":["characteristics","facts","dimensions"]},"product_id":{"description":"Required when scope=product.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"category_ids":{"description":"Filter to products in any of these category ids (from list_categories); selecting a parent also matches its descendants. e.g. [\"3f2504e0-4f89-41d3-9a0c-0305e82c3301\"].","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"description":"Filter to chats from these countries (ISO 3166-1 alpha-2), e.g. [\"US\", \"GB\"]. Omit for all countries.","type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}},"model_ids":{"description":"Filter to these model ids (from list_models), e.g. [\"gpt-4o\"]. Omit for all models.","type":"array","items":{"type":"string","enum":["chatgpt","microsoft-copilot","sonar-api","grok-api","gpt-4o-search","sonar","google-ai-overview","google-ai-mode","gemini-2-5-flash","gemini-3-1-flash-lite","gemini-3-1-flash-lite-search","claude-sonnet-4","claude-sonnet-4-6","claude-sonnet-5","claude-haiku-4-5","grok-2-1212","gpt-4o","qwen-3-6-plus","qwen-3-7-plus","gpt-3-5-turbo","gemini-1-5-flash","deepseek-r1","deepseek-v4-pro","llama-3-3-70b-instruct","gpt-5-1","gemini-2-5-flash-preview-05-20","claude-3-5-sonnet","chatgpt-ui","gpt-5-search","gpt-5-6-luna","perplexity-ui","gemini-ui","grok-4","grok-4-3","grok-4-6","grok-ui","microsoft-copilot-ui","claude-3-5-haiku","llama-3-1-sonar-small-128k-online","amazon-rufus","mistral-small-4","mistral-medium-3-5","muse-spark-1-2","muse-spark-1-3","naver-ai-briefing-ui","claude-opus-5","claude-fable-5-1","gpt-6-astra","gpt-5-6-sol","gpt-5-6-terra","gpt-6-luna","gpt-6-sol","claude-opus-5-5","gpt-6-1-sol","ernie-ui","claude-haiku-5-5","muse-wonder-1-0","gemini-4-argon"]}},"model_channel_ids":{"description":"Filter to these model channel ids (from list_model_channels), e.g. [\"openai-0\"]. Omit for all engines.","type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"description":"Filter to prompts under any of these topic ids (from list_topics), e.g. [\"to_a1b2c3\"].","type":"array","items":{"type":"string"}},"tag_ids":{"description":"Filter to prompts carrying these tag ids (from list_tags; combine with tag_operator), e.g. [\"tg_a1b2c3\"].","type":"array","items":{"type":"string"}},"tag_operator":{"description":"Match prompts carrying any (or, default) or all (and) of tag_ids.","type":"string","enum":["and","or"]},"search":{"description":"Substring match on dimension name (and value, characteristics).","type":"string"},"competitor_count":{"description":"Grid columns; default 6. `0` disables competitor lookup.","type":"integer","minimum":0,"maximum":20},"values_per_group":{"description":"Characteristics tab only; default 12.","type":"integer","minimum":1,"maximum":50},"limit":{"description":"Page size over dimension groups.","type":"integer","minimum":1,"maximum":100},"offset":{"description":"Number of dimension groups to skip for pagination, e.g. 0.","type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"competitors":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"global_brand_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"domain":{"type":"string"},"mentions":{"type":"number"}},"required":["global_brand_id","name","domain","mentions"]},{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"brand_name":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"mentions":{"type":"number"}},"required":["product_id","name","brand_name","image_url","mentions"]}]}},"total_groups":{"type":"number"},"tab":{"type":"string","enum":["characteristics"]},"groups":{"type":"array","items":{"type":"object","properties":{"dimension_id":{"type":"string"},"name":{"type":"string"},"total_mentions":{"type":"number"},"total_mentions_delta":{"nullable":true,"type":"number"},"value_count":{"type":"number"},"values":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"mentions":{"type":"number"},"mentions_delta":{"nullable":true,"type":"number"},"competitor_mentions":{"type":"array","items":{"type":"number"}}},"required":["value","mentions","mentions_delta","competitor_mentions"]}}},"required":["dimension_id","name","total_mentions","total_mentions_delta","value_count","values"]}}},"required":["competitors","total_groups","tab","groups"]},{"type":"object","properties":{"competitors":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"global_brand_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"domain":{"type":"string"},"mentions":{"type":"number"}},"required":["global_brand_id","name","domain","mentions"]},{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"brand_name":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"mentions":{"type":"number"}},"required":["product_id","name","brand_name","image_url","mentions"]}]}},"total_groups":{"type":"number"},"tab":{"type":"string","enum":["facts"]},"groups":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"dimension_id":{"type":"string"},"name":{"type":"string"},"total_mentions":{"type":"number"},"total_mentions_delta":{"nullable":true,"type":"number"},"value_type":{"type":"string","enum":["BOOLEAN"]},"unit":{"nullable":true,"type":"string"},"own":{"type":"object","properties":{"true_count":{"type":"number"},"false_count":{"type":"number"},"unrecognized_count":{"type":"number"}},"required":["true_count","false_count","unrecognized_count"]},"competitor_values":{"type":"array","items":{"type":"object","properties":{"true_count":{"type":"number"},"false_count":{"type":"number"},"unrecognized_count":{"type":"number"}},"required":["true_count","false_count","unrecognized_count"]}}},"required":["dimension_id","name","total_mentions","total_mentions_delta","value_type","unit","own","competitor_values"]},{"type":"object","properties":{"dimension_id":{"type":"string"},"name":{"type":"string"},"total_mentions":{"type":"number"},"total_mentions_delta":{"nullable":true,"type":"number"},"value_type":{"type":"string","enum":["NUMERIC"]},"unit":{"nullable":true,"type":"string"},"own":{"nullable":true,"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"average":{"type":"number"},"median":{"type":"number"}},"required":["min","max","average","median"]},"competitor_values":{"type":"array","items":{"nullable":true,"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"average":{"type":"number"},"median":{"type":"number"}},"required":["min","max","average","median"]}}},"required":["dimension_id","name","total_mentions","total_mentions_delta","value_type","unit","own","competitor_values"]}]}}},"required":["competitors","total_groups","tab","groups"]},{"type":"object","properties":{"competitors":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"global_brand_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"domain":{"type":"string"},"mentions":{"type":"number"}},"required":["global_brand_id","name","domain","mentions"]},{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"brand_name":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"mentions":{"type":"number"}},"required":["product_id","name","brand_name","image_url","mentions"]}]}},"total_groups":{"type":"number"},"tab":{"type":"string","enum":["dimensions"]},"groups":{"type":"array","items":{"type":"object","properties":{"dimension_id":{"type":"string"},"name":{"type":"string"},"total_mentions":{"type":"number"},"total_mentions_delta":{"nullable":true,"type":"number"},"own":{"nullable":true,"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"average":{"type":"number"},"median":{"type":"number"}},"required":["min","max","average","median"]},"competitor_values":{"type":"array","items":{"nullable":true,"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"average":{"type":"number"},"median":{"type":"number"}},"required":["min","max","average","median"]}}},"required":["dimension_id","name","total_mentions","total_mentions_delta","own","competitor_values"]}}},"required":["competitors","total_groups","tab","groups"]}]}}}}},"operationId":"postProductsAttributes"}},"/products/summary":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Shopping Summary","description":"Return aggregate shopping metrics over a date range. Delta fields compare against an explicit previous window or the auto-derived previous period.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"category_ids":{"description":"Filter by shopping categories. Parent categories include descendants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"merchant_ids":{"description":"Filter to products sold through these merchants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"brand_ids":{"description":"Keep only products whose own brand is one of these.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"product_ids":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"chat_scope":{"description":"Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.","type":"string","enum":["all","shopping"]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"category_ids":{"description":"Filter by shopping categories. Parent categories include descendants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"merchant_ids":{"description":"Filter to products sold through these merchants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"brand_ids":{"description":"Keep only products whose own brand is one of these.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"product_ids":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"chat_scope":{"description":"Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.","type":"string","enum":["all","shopping"]}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"category_ids":{"description":"Filter by shopping categories. Parent categories include descendants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"merchant_ids":{"description":"Filter to products sold through these merchants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"brand_ids":{"description":"Keep only products whose own brand is one of these.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"product_ids":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"chat_scope":{"description":"Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.","type":"string","enum":["all","shopping"]}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"avg_visibility":{"type":"number"},"avg_visibility_delta":{"nullable":true,"type":"number"},"avg_win_rate":{"type":"number"},"avg_win_rate_delta":{"nullable":true,"type":"number"},"avg_position":{"nullable":true,"type":"number"},"avg_position_delta":{"nullable":true,"type":"number"}},"required":["avg_visibility","avg_visibility_delta","avg_win_rate","avg_win_rate_delta","avg_position","avg_position_delta"],"description":"Success"}}}}},"operationId":"postProductsSummary"}},"/products/trend":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Shopping Trend","description":"Return a product or brand shopping time series over a date range. Requires bucket and exactly one of product_ids or brand_ids.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"category_ids":{"description":"Filter by shopping categories. Parent categories include descendants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"merchant_ids":{"description":"Filter to products sold through these merchants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"bucket":{"type":"string","enum":["day","week","month"],"description":"Time-bucket granularity."},"brand_ids":{"description":"Global brands to chart.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"product_ids":{"description":"Products to chart.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"chat_scope":{"description":"Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.","type":"string","enum":["all","shopping"]}},"required":["bucket"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"category_ids":{"description":"Filter by shopping categories. Parent categories include descendants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"merchant_ids":{"description":"Filter to products sold through these merchants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"bucket":{"type":"string","enum":["day","week","month"],"description":"Time-bucket granularity."},"brand_ids":{"description":"Global brands to chart.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"product_ids":{"description":"Products to chart.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"chat_scope":{"description":"Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.","type":"string","enum":["all","shopping"]}},"required":["bucket"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"category_ids":{"description":"Filter by shopping categories. Parent categories include descendants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"merchant_ids":{"description":"Filter to products sold through these merchants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"bucket":{"type":"string","enum":["day","week","month"],"description":"Time-bucket granularity."},"brand_ids":{"description":"Global brands to chart.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"product_ids":{"description":"Products to chart.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"chat_scope":{"description":"Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.","type":"string","enum":["all","shopping"]}},"required":["bucket"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"entity_type":{"type":"string","enum":["product","brand"]},"series":{"type":"array","items":{"type":"object","properties":{"entity_id":{"type":"string"},"points":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"visibility":{"type":"number"},"win_rate":{"type":"number"},"avg_position":{"nullable":true,"type":"number"},"sov":{"type":"number"},"has_data":{"type":"boolean"}},"required":["date","visibility","win_rate","avg_position","sov","has_data"]}}},"required":["entity_id","points"]}}},"required":["entity_type","series"],"description":"Success"}}}}},"operationId":"postProductsTrend"}},"/products/performance":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Shopping Performance","description":"List ranked product or category shopping performance over a date range.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"category_ids":{"description":"Filter by shopping categories. Parent categories include descendants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"merchant_ids":{"description":"Filter to products sold through these merchants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"entity_type":{"type":"string","enum":["product","category"],"description":"Rank products (leaderboard) or categories."},"brand_ids":{"description":"For products, keep only products of these global brands.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"product_ids":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"category_id":{"description":"For categories, return only this category.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"chat_scope":{"description":"Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.","type":"string","enum":["all","shopping"]},"mode":{"default":"top","description":"top = highest now; trending = biggest gainers; losing = biggest losers.","type":"string","enum":["top","trending","losing"]},"order_by":{"default":"visibility","type":"string","enum":["visibility","win_rate","appearances"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]},"limit":{"default":50,"type":"integer","minimum":1,"maximum":1000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["entity_type"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"category_ids":{"description":"Filter by shopping categories. Parent categories include descendants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"merchant_ids":{"description":"Filter to products sold through these merchants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"entity_type":{"type":"string","enum":["product","category"],"description":"Rank products (leaderboard) or categories."},"brand_ids":{"description":"For products, keep only products of these global brands.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"product_ids":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"category_id":{"description":"For categories, return only this category.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"chat_scope":{"description":"Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.","type":"string","enum":["all","shopping"]},"mode":{"default":"top","description":"top = highest now; trending = biggest gainers; losing = biggest losers.","type":"string","enum":["top","trending","losing"]},"order_by":{"default":"visibility","type":"string","enum":["visibility","win_rate","appearances"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]},"limit":{"default":50,"type":"integer","minimum":1,"maximum":1000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["entity_type"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"category_ids":{"description":"Filter by shopping categories. Parent categories include descendants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"merchant_ids":{"description":"Filter to products sold through these merchants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"entity_type":{"type":"string","enum":["product","category"],"description":"Rank products (leaderboard) or categories."},"brand_ids":{"description":"For products, keep only products of these global brands.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"product_ids":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"category_id":{"description":"For categories, return only this category.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"chat_scope":{"description":"Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.","type":"string","enum":["all","shopping"]},"mode":{"default":"top","description":"top = highest now; trending = biggest gainers; losing = biggest losers.","type":"string","enum":["top","trending","losing"]},"order_by":{"default":"visibility","type":"string","enum":["visibility","win_rate","appearances"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]},"limit":{"default":50,"type":"integer","minimum":1,"maximum":1000},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["entity_type"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"entity_type":{"type":"string","enum":["product","category"]},"entity_id":{"type":"string"},"name":{"type":"string"},"visibility":{"type":"number"},"visibility_delta":{"nullable":true,"type":"number"},"win_rate":{"type":"number"},"win_rate_delta":{"nullable":true,"type":"number"},"avg_position":{"nullable":true,"type":"number"},"avg_position_delta":{"nullable":true,"type":"number"},"appearances":{"type":"number"},"appearances_delta":{"nullable":true,"type":"number"}},"required":["entity_type","entity_id","name","visibility","visibility_delta","win_rate","win_rate_delta","avg_position","avg_position_delta","appearances","appearances_delta"]}},"total_count":{"type":"number"}},"required":["data","total_count"],"description":"Success"}}}}},"operationId":"postProductsPerformance"}},"/products/demand":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Shopping Demand","description":"List top shopping queries, web-search fan-out queries, or query terms over a date range.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"category_ids":{"description":"Filter by shopping categories. Parent categories include descendants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"kind":{"type":"string","enum":["shopping_query","fanout_query","query_term"],"description":"shopping_query = product fan-out queries; fanout_query = web-search fan-out queries; query_term = n-grams across shopping queries."},"mode":{"default":"top","description":"top = highest now; trending = gainers; losing = losers; new = appeared this window only.","type":"string","enum":["top","trending","losing","new"]},"limit":{"default":50,"type":"integer","minimum":1,"maximum":1000},"n":{"default":2,"description":"n-gram width for kind=query_term (default 2 = bigrams).","type":"integer","minimum":1,"maximum":3}},"required":["kind"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"category_ids":{"description":"Filter by shopping categories. Parent categories include descendants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"kind":{"type":"string","enum":["shopping_query","fanout_query","query_term"],"description":"shopping_query = product fan-out queries; fanout_query = web-search fan-out queries; query_term = n-grams across shopping queries."},"mode":{"default":"top","description":"top = highest now; trending = gainers; losing = losers; new = appeared this window only.","type":"string","enum":["top","trending","losing","new"]},"limit":{"default":50,"type":"integer","minimum":1,"maximum":1000},"n":{"default":2,"description":"n-gram width for kind=query_term (default 2 = bigrams).","type":"integer","minimum":1,"maximum":3}},"required":["kind"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"category_ids":{"description":"Filter by shopping categories. Parent categories include descendants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"kind":{"type":"string","enum":["shopping_query","fanout_query","query_term"],"description":"shopping_query = product fan-out queries; fanout_query = web-search fan-out queries; query_term = n-grams across shopping queries."},"mode":{"default":"top","description":"top = highest now; trending = gainers; losing = losers; new = appeared this window only.","type":"string","enum":["top","trending","losing","new"]},"limit":{"default":50,"type":"integer","minimum":1,"maximum":1000},"n":{"default":2,"description":"n-gram width for kind=query_term (default 2 = bigrams).","type":"integer","minimum":1,"maximum":3}},"required":["kind"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["shopping_query","fanout_query","query_term"]},"text":{"type":"string"},"distinct_chat_count":{"type":"number"},"distinct_chat_count_previous":{"type":"number"},"delta":{"nullable":true,"type":"number"}},"required":["kind","text","distinct_chat_count","distinct_chat_count_previous","delta"]}},"total_count":{"type":"number"}},"required":["data","total_count"],"description":"Success"}}}}},"operationId":"postProductsDemand"}},"/products/merchants":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Merchants","description":"List the merchants (sellers) whose product offers surfaced in AI answers, ranked over a date range: mentions, share of voice against the other merchants, buy-box win rate, average position, and average star rating, each with a delta against the previous window. Scope the population with category_ids or product_ids to get per-category or per-product seller breakdowns.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"category_ids":{"description":"Filter by shopping categories. Parent categories include descendants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"merchant_ids":{"description":"Return only these merchants. Unlike category_ids/product_ids, this does not shrink the share_of_voice denominator.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"product_ids":{"description":"Narrow the population to these products — per-product seller breakdowns. share_of_voice is then the share among that product's sellers.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"order_by":{"default":"mention_count","type":"string","enum":["mention_count","win_rate","avg_rating","avg_position"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]},"limit":{"default":50,"type":"integer","minimum":1,"maximum":200},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"category_ids":{"description":"Filter by shopping categories. Parent categories include descendants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"merchant_ids":{"description":"Return only these merchants. Unlike category_ids/product_ids, this does not shrink the share_of_voice denominator.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"product_ids":{"description":"Narrow the population to these products — per-product seller breakdowns. share_of_voice is then the share among that product's sellers.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"order_by":{"default":"mention_count","type":"string","enum":["mention_count","win_rate","avg_rating","avg_position"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]},"limit":{"default":50,"type":"integer","minimum":1,"maximum":200},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"start_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"category_ids":{"description":"Filter by shopping categories. Parent categories include descendants.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"country_codes":{"type":"array","items":{"type":"string"}},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"topic_ids":{"type":"array","items":{"type":"string"}},"tag_ids":{"type":"array","items":{"type":"string"}},"tag_operator":{"type":"string","enum":["and","or"]},"previous_start_date":{"description":"Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"previous_end_date":{"description":"End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"merchant_ids":{"description":"Return only these merchants. Unlike category_ids/product_ids, this does not shrink the share_of_voice denominator.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"product_ids":{"description":"Narrow the population to these products — per-product seller breakdowns. share_of_voice is then the share among that product's sellers.","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"order_by":{"default":"mention_count","type":"string","enum":["mention_count","win_rate","avg_rating","avg_position"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]},"limit":{"default":50,"type":"integer","minimum":1,"maximum":200},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Merchants (sellers) ranked by their metrics over the date range, with deltas against the previous window. share_of_voice divides a merchant's mentions by all merchants' mentions in the filtered population, so category_ids/product_ids give per-category or per-product seller shares. win_rate is the buy-box rate (position-1 mentions over all mentions). Only merchants with current-window mentions are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"merchant_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"domain":{"type":"string"},"mention_count":{"type":"number"},"mention_count_delta":{"type":"number"},"share_of_voice":{"type":"number"},"share_of_voice_delta":{"nullable":true,"type":"number"},"win_rate":{"type":"number"},"win_rate_delta":{"nullable":true,"type":"number"},"avg_position":{"nullable":true,"type":"number"},"avg_position_delta":{"nullable":true,"type":"number"},"avg_rating":{"nullable":true,"type":"number"},"avg_rating_delta":{"nullable":true,"type":"number"}},"required":["merchant_id","name","domain","mention_count","mention_count_delta","share_of_voice","share_of_voice_delta","win_rate","win_rate_delta","avg_position","avg_position_delta","avg_rating","avg_rating_delta"]}},"total_count":{"type":"number"}},"required":["data","total_count"],"description":"Merchants (sellers) ranked by their metrics over the date range, with deltas against the previous window. share_of_voice divides a merchant's mentions by all merchants' mentions in the filtered population, so category_ids/product_ids give per-category or per-product seller shares. win_rate is the buy-box rate (position-1 mentions over all mentions). Only merchants with current-window mentions are returned."}}}}},"operationId":"postProductsMerchants"}},"/products/create":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Create Products","description":"Create products. Each item is independent: valid products are created and per-item failures are returned in `rejected`, so the batch never fails as a whole. Optional `category_ids` assigns the product to categories.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"products":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"global_brand_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":5000},"image_url":{"type":"string","format":"uri"},"price_override":{"type":"object","additionalProperties":{"type":"object","properties":{"min":{"type":"number","minimum":0,"maximum":10000000000000},"max":{"type":"number","minimum":0,"maximum":10000000000000}}}},"category_ids":{"maxItems":100,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["global_brand_id","name"]}}},"required":["products"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"products":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"global_brand_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":5000},"image_url":{"type":"string","format":"uri"},"price_override":{"type":"object","additionalProperties":{"type":"object","properties":{"min":{"type":"number","minimum":0,"maximum":10000000000000},"max":{"type":"number","minimum":0,"maximum":10000000000000}}}},"category_ids":{"maxItems":100,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["global_brand_id","name"]}}},"required":["products"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"products":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"global_brand_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":5000},"image_url":{"type":"string","format":"uri"},"price_override":{"type":"object","additionalProperties":{"type":"object","properties":{"min":{"type":"number","minimum":0,"maximum":10000000000000},"max":{"type":"number","minimum":0,"maximum":10000000000000}}}},"category_ids":{"maxItems":100,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["global_brand_id","name"]}}},"required":["products"]}}}},"responses":{"200":{"description":"Per-item create results","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string"},"name":{"type":"string"}},"required":["product_id","name"]}},"rejected":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"reason":{"type":"string","enum":["brand_not_found","name_conflict","category_not_found"]},"message":{"type":"string"}},"required":["name","reason","message"]}}},"required":["created","rejected"],"description":"Per-item create results"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postProductsCreate"}},"/products/update":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Update Products","description":"Update products (name, description, image, price overrides, categories). Each item is independent: items with nothing to apply (not found, no changes, duplicate id) are reported in `skipped`, and unsatisfiable changes (name conflict, unknown category) in `rejected`, so the batch never fails as a whole.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"products":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":5000},"image_url":{"type":"string","format":"uri"},"price_override":{"type":"object","additionalProperties":{"type":"object","properties":{"min":{"type":"number","minimum":0,"maximum":10000000000000},"max":{"type":"number","minimum":0,"maximum":10000000000000}}}},"category_ids":{"maxItems":100,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["product_id"]}}},"required":["products"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"products":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":5000},"image_url":{"type":"string","format":"uri"},"price_override":{"type":"object","additionalProperties":{"type":"object","properties":{"min":{"type":"number","minimum":0,"maximum":10000000000000},"max":{"type":"number","minimum":0,"maximum":10000000000000}}}},"category_ids":{"maxItems":100,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["product_id"]}}},"required":["products"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"products":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":5000},"image_url":{"type":"string","format":"uri"},"price_override":{"type":"object","additionalProperties":{"type":"object","properties":{"min":{"type":"number","minimum":0,"maximum":10000000000000},"max":{"type":"number","minimum":0,"maximum":10000000000000}}}},"category_ids":{"maxItems":100,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["product_id"]}}},"required":["products"]}}}},"responses":{"200":{"description":"Per-item update results","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string"}},"required":["product_id"]}},"skipped":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string"},"reason":{"type":"string","enum":["not_found","no_changes","duplicate_id"]}},"required":["product_id","reason"]}},"rejected":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string"},"reason":{"type":"string","enum":["conflict","category_not_found"]},"message":{"type":"string"}},"required":["product_id","reason","message"]}}},"required":["updated","skipped","rejected"],"description":"Per-item update results"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postProductsUpdate"}},"/products/delete":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Delete Products","description":"Delete products. Ids that don't exist in the project are returned in `skipped`.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"product_ids":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["product_ids"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"product_ids":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["product_ids"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"product_ids":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["product_ids"]}}}},"responses":{"200":{"description":"Per-item delete results","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string"}},"required":["product_id"]}},"skipped":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string"},"reason":{"type":"string","enum":["not_found"]}},"required":["product_id","reason"]}}},"required":["deleted","skipped"],"description":"Per-item delete results"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postProductsDelete"}},"/categories":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Categories","description":"List a project's product categories. Each row carries its full `path` and its `parent_id`, so the flat list reconstructs the category tree. Use the returned `id` as a `category_id` when creating, updating, or assigning products.","tags":["Products"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}}],"responses":{"200":{"description":"The project's categories as a flat tree","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","example":"0190f9a1-1d8c-7e3a-9c2b-1f0a2b3c4d5e"},"name":{"type":"string","example":"Running Shoes"},"path":{"type":"string","example":"Footwear > Shoes > Running Shoes"},"parent_id":{"nullable":true,"description":"The parent category id, or null at the top level.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id","name","path","parent_id"]}},"total_count":{"type":"number"}},"required":["data","total_count"],"description":"The project's categories as a flat tree"}}}}},"operationId":"getCategories"}},"/categories/create":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Create Categories","description":"Create product categories. Each item takes a `name` and an optional `parent_id` (omit or null for a top-level category). Items apply in order. Returns per-item results { created, rejected } — the batch never fails as a whole. Rejection reasons: parent_not_found, name_conflict (a sibling already has that name).","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"categories":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"parent_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["name"]}}},"required":["categories"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"categories":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"parent_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["name"]}}},"required":["categories"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"categories":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"parent_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["name"]}}},"required":["categories"]}}}},"responses":{"200":{"description":"Per-item create results","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"array","items":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"}},"required":["category_id","name"]}},"rejected":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"reason":{"type":"string","enum":["parent_not_found","name_conflict"]},"message":{"type":"string"}},"required":["name","reason","message"]}}},"required":["created","rejected"],"description":"Per-item create results"}}}}},"operationId":"postCategoriesCreate"}},"/categories/update":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Update Categories","description":"Rename and/or reparent categories by id. Each item sets `name` (rename), `parent_id` (move; null = promote to top level), or both — at least one is required. A combined edit is applied move-then-rename. Returns per-item results { updated, rejected } — the batch never fails as a whole. Rejection reasons: not_found, name_conflict, invalid_move (would nest a category inside itself).","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"categories":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":200},"parent_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["category_id"]}}},"required":["categories"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"categories":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":200},"parent_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["category_id"]}}},"required":["categories"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"categories":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":200},"parent_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["category_id"]}}},"required":["categories"]}}}},"responses":{"200":{"description":"Per-item update results","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"array","items":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["category_id"]}},"rejected":{"type":"array","items":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"reason":{"type":"string","enum":["not_found","name_conflict","invalid_move"]},"message":{"type":"string"}},"required":["category_id","reason","message"]}}},"required":["updated","rejected"],"description":"Per-item update results"}}}}},"operationId":"postCategoriesUpdate"}},"/categories/delete":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Delete Categories","description":"Delete categories by id. Each one's child categories and products move up to its parent, then it is removed. Returns per-item results { deleted, rejected } — the batch never fails as a whole. Rejection reasons: not_found, name_conflict (a child moving up would clash with an existing sibling name).","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"category_ids":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["category_ids"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"category_ids":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["category_ids"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"category_ids":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["category_ids"]}}}},"responses":{"200":{"description":"Per-item delete results","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"array","items":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["category_id"]}},"rejected":{"type":"array","items":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"reason":{"type":"string","enum":["not_found","name_conflict"]},"message":{"type":"string"}},"required":["category_id","reason","message"]}}},"required":["deleted","rejected"],"description":"Per-item delete results"}}}}},"operationId":"postCategoriesDelete"}},"/global-brands":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Global Brands","description":"Search Peec's global brand catalog — the shared registry of real-world brands that products attach to via `global_brand_id`. Use it to find the `global_brand_id` for a brand when creating products. This is separate from `GET /brands`, which lists the brands a project tracks for AI-visibility reporting; the two use different ids. Primarily used with `search`. Pass `ownership` (`own`, `competitor`, or `all`) instead to list the project's shopping brands ranked by mentions, for use as shopping brand filters.","tags":["Products"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"search","in":"query","required":false,"schema":{"example":"nike","description":"Search the catalog by brand name (matches names and aliases). The primary way to use this endpoint.","type":"string"}},{"name":"ownership","in":"query","required":false,"schema":{"description":"List the project's shopping brands instead of searching the catalog, ranked by all-time shopping mention count: `own` for the project's own brands, `competitor` for competitors appearing in shopping data, `all` for both.","type":"string","enum":["own","competitor","all"]}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","example":"019ecb6e-d030-7222-b531-b371fe9db583","description":"The global_brand_id — pass this as a product's brand when creating products, and as a shopping brand filter."},"name":{"type":"string","example":"Nike"},"domain":{"nullable":true,"example":"nike.com","type":"string"},"description":{"nullable":true,"example":"American athletic footwear and apparel company","description":"Short description that disambiguates same-named brands.","type":"string"},"mention_count":{"description":"All-time shopping mention count in this project. Present only when `ownership` is set.","type":"number"},"is_own":{"description":"Whether this is one of the project's own brands. Present only when `ownership` is set.","type":"boolean"}},"required":["id","name","domain","description"]}},"total_count":{"type":"number","example":42,"description":"Total number of matching brands, ignoring pagination"},"totalCount":{"type":"number","example":42,"description":"Total number of matching brands, ignoring pagination","deprecated":true}},"required":["data","total_count","totalCount"],"description":"Success"}}}}},"operationId":"getGlobal-brands"},"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Create Global Brand","description":"Create a brand and return its `id` — pass it as a product's `global_brand_id` when creating products. The returned `name` is the brand's canonical name and may differ slightly from the name you sent. This is separate from `POST /brands`, which creates a brand a project tracks for AI-visibility reporting.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"name":{"type":"string","minLength":1,"example":"Nike","description":"The brand name."}},"required":["name"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"name":{"type":"string","minLength":1,"example":"Nike","description":"The brand name."}},"required":["name"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"name":{"type":"string","minLength":1,"example":"Nike","description":"The brand name."}},"required":["name"]}}}},"responses":{"200":{"description":"The brand","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","example":"019ecb6e-d030-7222-b531-b371fe9db583","description":"The global_brand_id — pass this as a product's brand when creating products."},"name":{"type":"string","example":"Nike","description":"The brand's canonical name. May differ slightly from the name you sent, since an existing brand is reused where one is found."}},"required":["id","name"],"description":"The brand"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postGlobal-brands"}},"/brand-perception/brand-attributes":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Brand Perception Attributes","description":"How AI models describe the project's own brand: attribute clusters (e.g. \"Luxury\", \"Racing Heritage\") scored by average prominence per AI answer (0-100). The data is a snapshot of the latest brand-perception run — there is no date range. An empty result means the first run has not completed yet.","tags":["Brand Perception"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"model_channel_ids","in":"query","required":false,"schema":{"description":"Only include answers from these AI engine channels (repeat the parameter for multiple values). Omit to aggregate across all tracked channels.","type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Luxury","description":"The attribute's name."},"score":{"type":"number","example":67,"description":"Average prominence per AI answer, 0-100. Higher means the attribute is mentioned earlier and more often when AI describes the brand."},"members":{"type":"array","items":{"type":"string"},"example":["luxury","prestige","exclusivity"],"description":"The attribute's terms: the raw phrasings from AI answers grouped under it."}},"required":["name","score","members"]},"description":"Attributes sorted by score, most prominent first."},"total_count":{"type":"number","example":8,"description":"Total number of attributes, ignoring pagination"}},"required":["data","total_count"],"description":"Success"}}}}},"operationId":"getBrand-perceptionBrand-attributes"}},"/brand-perception/attribute-rankings":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Brand Perception Attribute Rankings","description":"How the project's own brand ranks against competitors for each brand-perception attribute. The ranking is the own brand's mean position across AI answers mentioning the attribute (lower is better). The data is aggregated across the brand-perception runs of one industry and one target market — there is no date range. Pass `industry` to pick the industry; omitted, it is the one with the most recent completed run. The target market is always the industry's most recently completed one and cannot be picked. Both are returned as `industry` and `target_market`.","tags":["Brand Perception"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"model_channel_ids","in":"query","required":false,"schema":{"description":"Only include answers from these AI engine channels (repeat the parameter for multiple values). Omit to aggregate across all tracked channels.","type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},{"name":"industry","in":"query","required":false,"schema":{"example":"Luxury Sports Cars","description":"Only read the runs dispatched for this industry, as returned by the brand-perception industries endpoint. Omit to read the industry marked `is_default` there — the one with the most recent completed run.","type":"string"}},{"name":"search","in":"query","required":false,"schema":{"example":"heritage","description":"Case-insensitive substring filter on the attribute name.","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Italian Heritage","description":"The attribute (cluster representative name)."},"ranking":{"nullable":true,"example":2,"description":"The project's own brand's position among every brand scored for this attribute, by average prominence across all AI answers about it; lower is better. Answers the brand never surfaced in count against it. Null when it never surfaced at all.","type":"number"},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Porsche"},"domain":{"nullable":true,"example":"porsche.com","description":"The competitor's domain; null when it has no resolvable domain.","type":"string"}},"required":["name","domain"]},"description":"Competing brands AI associates with this attribute, most relevant first."}},"required":["name","ranking","competitors"]},"description":"Attributes sorted by ranking, best-ranked first; attributes without a ranking last."},"total_count":{"type":"number","example":8,"description":"Total number of matching attributes, ignoring pagination"},"industry":{"nullable":true,"example":"Luxury Sports Cars","description":"The industry the data was read from; null when the project has no brand-perception runs yet.","type":"string"},"target_market":{"nullable":true,"example":"Germany","description":"The target market the read narrowed to within that industry — its most recently completed one. Runs dispatched for the industry's other markets are not included.","type":"string"},"industries":{"description":"Every industry the project has runs for, latest-started first — present only when there is more than one. Pass a name as `industry` to read that one instead.","type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Athleisure"},"has_completed_run":{"type":"boolean","description":"False while the industry's first run is still in flight, so its data is partial."}},"required":["name","has_completed_run"]}}},"required":["data","total_count","industry","target_market"],"description":"Success"}}}}},"operationId":"getBrand-perceptionAttribute-rankings"}},"/brand-perception/attribute-sources":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Brand Perception Attribute Sources","description":"The sources feeding one attribute's associations: the URLs AI answers cited when describing the brand with this attribute. Data is aggregated across all brand-perception runs (no date range), and unlike the attribute rankings it is not scoped to one industry. An unknown attribute returns an empty result.","tags":["Brand Perception"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"attribute","in":"query","required":true,"schema":{"type":"string","minLength":1,"example":"Italian Heritage","description":"The attribute name, exactly as returned by the brand-attributes or attribute-rankings endpoints."}},{"name":"model_channel_ids","in":"query","required":false,"schema":{"description":"Only include answers from these AI engine channels (repeat the parameter for multiple values). Omit to aggregate across all tracked channels.","type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},{"name":"order_by","in":"query","required":false,"schema":{"description":"Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied.","example":[{"field":"occurrences","direction":"desc"}],"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["occurrences","retrievals","citation_rate"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]}},"required":["field"]}}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","example":"https://www.ferrari.com/en-EN/history"},"title":{"nullable":true,"example":"Ferrari History","description":"Page title; null when not yet enriched.","type":"string"},"domain":{"type":"string","example":"ferrari.com"},"url_classification":{"type":"string","example":"OWNED","description":"Classification of the URL."},"domain_classification":{"type":"string","example":"OWNED","description":"Classification of the domain."},"occurrences":{"type":"number","example":12,"description":"How many AI answers about this attribute cited this source (all time)."},"retrievals":{"type":"number","example":34,"description":"Distinct chats the source was retrieved in."},"citation_rate":{"type":"number","example":1.4,"description":"Mean citations per chat the source was retrieved in. An average, not a percentage — can exceed 1."}},"required":["url","title","domain","url_classification","domain_classification","occurrences","retrievals","citation_rate"]}},"total_count":{"type":"number","example":42,"description":"Total number of sources, ignoring pagination"}},"required":["data","total_count"],"description":"Success"}}}}},"operationId":"getBrand-perceptionAttribute-sources"}},"/brand-perception/attribute-history":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Brand Perception Attribute History","description":"How one brand's prominence on each brand-perception attribute has moved over time: one series per attribute, each point a day and the brand's average prominence (0-100) across that day's AI answers about the attribute. These are the same scores as the competitive breakdown, split by day instead of aggregated. The brand defaults to the project's own brand. The data covers the brand-perception runs of one industry and one target market. Pass `industry` to pick the industry; omitted, it is the one with the most recent completed run. The target market is always the industry's most recently completed one and cannot be picked. Both are returned as `industry` and `target_market`. Pagination applies to attributes.","tags":["Brand Perception"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"brand","in":"query","required":false,"schema":{"example":"Porsche","description":"The brand whose history to read, spelled as the competitive-breakdown endpoint reports it. Omit to read the project's own brand.","type":"string","minLength":1}},{"name":"model_channel_ids","in":"query","required":false,"schema":{"description":"Only include answers from these AI engine channels (repeat the parameter for multiple values). Omit to aggregate across all tracked channels.","type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},{"name":"industry","in":"query","required":false,"schema":{"example":"Luxury Sports Cars","description":"Only read the runs dispatched for this industry, as returned by the brand-perception industries endpoint. Omit to read the industry marked `is_default` there — the one with the most recent completed run.","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"attribute":{"type":"string","example":"Racing Heritage","description":"The attribute (cluster representative name)."},"points":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","example":"2026-09-01","description":"The day the answers were collected."},"score":{"type":"number","example":29,"description":"The brand's average prominence for this attribute across that day's AI answers about it, 0-100. Answers the brand was absent from count as 0."}},"required":["date","score"]},"description":"One point per day with data, oldest first. Every attribute carries the same days, so the series line up."}},"required":["attribute","points"]},"description":"Attributes sorted by the brand's score on the latest day, strongest first."},"total_count":{"type":"number","example":8,"description":"Total number of attributes, ignoring pagination"},"brand":{"nullable":true,"example":"Ferrari","description":"The brand the series describe; null when no brand was passed and the project has no own brand.","type":"string"},"industry":{"nullable":true,"example":"Luxury Sports Cars","description":"The industry the data was read from; null when the project has no brand-perception runs yet.","type":"string"},"target_market":{"nullable":true,"example":"Germany","description":"The target market the read narrowed to within that industry — its most recently completed one. Runs dispatched for the industry's other markets are not included.","type":"string"},"industries":{"description":"Every industry the project has runs for, latest-started first — present only when there is more than one. Pass a name as `industry` to read that one instead.","type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Athleisure"},"has_completed_run":{"type":"boolean","description":"False while the industry's first run is still in flight, so its data is partial."}},"required":["name","has_completed_run"]}}},"required":["data","total_count","brand","industry","target_market"],"description":"Success"}}}}},"operationId":"getBrand-perceptionAttribute-history"}},"/brand-perception/competitive-breakdown":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Brand Perception Competitive Breakdown","description":"The full competitive breakdown matrix: for every brand-perception attribute, the average prominence (0-100) of each brand — the project's own brand and its competitors — across AI answers. A higher score means the brand tends to be mentioned earlier when AI talks about that attribute. The data is aggregated across the brand-perception runs of one industry and one target market — there is no date range. Pass `industry` to pick the industry; omitted, it is the one with the most recent completed run. The target market is always the industry's most recently completed one and cannot be picked. Both are returned as `industry` and `target_market`. Pagination applies to attributes.","tags":["Brand Perception"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"model_channel_ids","in":"query","required":false,"schema":{"description":"Only include answers from these AI engine channels (repeat the parameter for multiple values). Omit to aggregate across all tracked channels.","type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},{"name":"industry","in":"query","required":false,"schema":{"example":"Luxury Sports Cars","description":"Only read the runs dispatched for this industry, as returned by the brand-perception industries endpoint. Omit to read the industry marked `is_default` there — the one with the most recent completed run.","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"attribute":{"type":"string","example":"Racing Heritage","description":"The attribute (cluster representative name)."},"brands":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Ferrari"},"score":{"type":"number","example":29,"description":"Average prominence of the brand for this attribute across AI answers, 0-100. Higher means the brand tends to be mentioned earlier when AI talks about the attribute."},"is_own":{"type":"boolean","description":"True when this is one of the project's own brands."}},"required":["name","score","is_own"]},"description":"Brands sorted by score, most prominent first."}},"required":["attribute","brands"]},"description":"Attributes sorted by the own brand's score, strongest first."},"total_count":{"type":"number","example":8,"description":"Total number of attributes, ignoring pagination"},"industry":{"nullable":true,"example":"Luxury Sports Cars","description":"The industry the data was read from; null when the project has no brand-perception runs yet.","type":"string"},"target_market":{"nullable":true,"example":"Germany","description":"The target market the read narrowed to within that industry — its most recently completed one. Runs dispatched for the industry's other markets are not included.","type":"string"},"industries":{"description":"Every industry the project has runs for, latest-started first — present only when there is more than one. Pass a name as `industry` to read that one instead.","type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Athleisure"},"has_completed_run":{"type":"boolean","description":"False while the industry's first run is still in flight, so its data is partial."}},"required":["name","has_completed_run"]}}},"required":["data","total_count","industry","target_market"],"description":"Success"}}}}},"operationId":"getBrand-perceptionCompetitive-breakdown"}},"/brand-perception/objections":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Brand Perception Objections","description":"The recurring arguments AI models make against the project's brand when a buyer is deciding. Data is aggregated across all objection runs and has no date range.","tags":["Brand Perception"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"model_channel_ids","in":"query","required":false,"schema":{"description":"Only include answers from these AI engine channels. Omit to aggregate across all tracked channels.","type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Too expensive"},"score":{"type":"number","example":67,"description":"Average prominence per AI answer, from 0 to 100. Higher means the objection is raised earlier and more often."},"members":{"type":"array","items":{"type":"string"},"description":"Raw objection phrasings folded into this objection cluster."}},"required":["name","score","members"]}},"total_count":{"type":"number"}},"required":["data","total_count"]}}}}},"operationId":"getBrand-perceptionObjections"}},"/brand-perception/objection-sources":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Brand Perception Objection Sources","description":"The sources AI models retrieved when asked about one objection. Data is aggregated across all objection runs and has no date range. An unknown objection returns an empty result.","tags":["Brand Perception"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"objection","in":"query","required":true,"schema":{"type":"string","minLength":1,"example":"Too expensive","description":"The objection name exactly as returned by the objections endpoint."}},{"name":"model_channel_ids","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},{"name":"order_by","in":"query","required":false,"schema":{"description":"Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied.","example":[{"field":"occurrences","direction":"desc"}],"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["occurrences","retrievals","citation_rate"]},"direction":{"default":"desc","type":"string","enum":["asc","desc"]}},"required":["field"]}}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"nullable":true,"type":"string"},"domain":{"type":"string"},"url_classification":{"type":"string"},"domain_classification":{"type":"string"},"occurrences":{"type":"number"},"retrievals":{"type":"number"},"citation_rate":{"type":"number"}},"required":["url","title","domain","url_classification","domain_classification","occurrences","retrievals","citation_rate"]}},"total_count":{"type":"number"}},"required":["data","total_count"]}}}}},"operationId":"getBrand-perceptionObjection-sources"}},"/brand-perception/fact-checking-verdicts":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Brand Perception Fact-Checking Verdicts","description":"Claims AI models make about the project's brand, each judged against one of the project's facts as supported or contradicted. Data is aggregated across all fact-checked chats and has no date range. Newest claims first.","tags":["Brand Perception"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"fact_ids","in":"query","required":false,"schema":{"description":"Only include verdicts against these facts. Omit to include every active fact.","type":"array","items":{"type":"string"}}},{"name":"claim_ids","in":"query","required":false,"schema":{"description":"Only include these claims, returning every fact each one was judged against. Omit to include every claim.","type":"array","items":{"type":"string"}}},{"name":"verdicts","in":"query","required":false,"schema":{"description":"Only include these verdicts. Omit to include both supported and contradicted claims.","type":"array","items":{"type":"string","enum":["contradicted","supported"]}}},{"name":"model_channel_ids","in":"query","required":false,"schema":{"description":"Only include claims from answers on these AI engine channels. Omit to aggregate across all tracked channels.","type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"claim_id":{"type":"string","example":"clm_01j8x2k9v4"},"claim":{"type":"string","example":"Peec AI was founded in 2019.","description":"The statement an AI answer made about the brand."},"fact_id":{"type":"string","example":"fct_01j8x2k9v4"},"fact":{"type":"string","example":"Peec AI was founded in 2024.","description":"The fact wording the claim was judged against."},"verdict":{"type":"string","enum":["contradicted","supported"],"example":"contradicted","description":"Whether the fact supports or contradicts the claim. Claims no fact covers are not returned."},"chats":{"type":"number","example":12,"description":"Distinct AI answers that made the claim."},"prompts":{"type":"number","example":4,"description":"Distinct prompts whose AI answers made the claim."},"example_chat_id":{"type":"string","example":"ch_01j8x2k9v4","description":"The most recent AI answer that made the claim."},"model_channel_ids":{"type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]},"description":"AI engine channels whose answers made the claim."},"last_seen":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","example":"2026-09-18","description":"Most recent day an AI answer made the claim."}},"required":["claim_id","claim","fact_id","fact","verdict","chats","prompts","example_chat_id","model_channel_ids","last_seen"]}},"total_count":{"type":"number"}},"required":["data","total_count"]}}}}},"operationId":"getBrand-perceptionFact-checking-verdicts"}},"/brand-perception/claim-sources":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Brand Perception Claim Sources","description":"The pages behind one fact-checked claim, each with the strongest role it earned. Data is aggregated across every answer that made the claim and has no date range. Strongest tier first.","tags":["Brand Perception"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"claim_id","in":"query","required":true,"schema":{"type":"string","minLength":1,"example":"clm_01j8x2k9v4","description":"The claim to read, identified by the claim_id the fact-checking verdicts endpoint returned. An unknown id returns an empty result."}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","example":"https://listicle.example/best-crm","description":"The page behind the claim."},"title":{"nullable":true,"example":"Best CRM tools","description":"The page's title, when one is known.","type":"string"},"tier":{"type":"string","enum":["at_claim","elsewhere","retrieved"],"example":"at_claim","description":"at_claim for a page cited inside the passage the claim was mined from, elsewhere for a page cited elsewhere in the same answer, retrieved for a page the answer retrieved and never cited. A page that earned different roles in different answers keeps the strongest one."}},"required":["url","title","tier"]}},"total_count":{"type":"number"}},"required":["data","total_count"]}}}}},"operationId":"getBrand-perceptionClaim-sources"}},"/facts":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Facts","description":"List the facts a project uses to check claims found in AI answers. Manual facts were added by a person; website facts were extracted from the project's website. Inactive facts are listed but excluded from future fact-checking. Deleted facts are never returned. Use the returned `id` as a `fact_id` in Update Facts, Delete Facts, and the `fact_ids` filter of Get Brand Perception Fact-Checking Verdicts.","tags":["Brand Perception"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"origin","in":"query","required":false,"schema":{"description":"Only include facts added this way: manual or website.","type":"string","enum":["website","manual"]}},{"name":"is_active","in":"query","required":false,"schema":{"description":"Only include facts that are (true) or are not (false) used in future fact-checking.","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"The project's facts, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","example":"0198f000-0000-7000-8000-000000000001"},"text":{"type":"string","example":"Plans start at €99 per month.","description":"The statement Peec checks AI claims against."},"origin":{"type":"string","enum":["website","manual"],"example":"manual","description":"How the fact was added: `manual` by a person, `website` extracted from the project's website."},"is_active":{"type":"boolean","description":"Whether Peec uses the fact in future fact-checking. An inactive fact stays listed."},"edited_at":{"nullable":true,"example":"2026-09-18T10:00:00.000Z","description":"When the wording was last changed, or null if never edited.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","example":"2026-09-01T10:00:00.000Z"}},"required":["id","text","origin","is_active","edited_at","created_at"]}},"total_count":{"type":"number"},"fact_limit":{"nullable":true,"description":"How many active facts the project's plan allows, or null for unlimited.","type":"number"},"active_fact_count":{"type":"number","description":"How many active facts the project holds now. Creating or activating facts beyond `fact_limit` is rejected."}},"required":["data","total_count","fact_limit","active_fact_count"],"description":"The project's facts, newest first"}}}}},"operationId":"getFacts"}},"/facts/create":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Create Facts","description":"Add manual facts to a project. Each fact is a statement about the brand that Peec uses to check claims found in future AI answers. New facts are active. The batch is all or nothing: if the active facts would exceed the plan's `fact_limit` (see List Facts), nothing is created and the request fails with 402.","tags":["Brand Perception"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"facts":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1,"example":"Plans start at €99 per month.","description":"The statement Peec should check AI claims against."}},"required":["text"]}}},"required":["facts"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"facts":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1,"example":"Plans start at €99 per month.","description":"The statement Peec should check AI claims against."}},"required":["text"]}}},"required":["facts"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"facts":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1,"example":"Plans start at €99 per month.","description":"The statement Peec should check AI claims against."}},"required":["text"]}}},"required":["facts"]}}}},"responses":{"200":{"description":"Every created fact with its new id","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","example":"0198f000-0000-7000-8000-000000000001"},"text":{"type":"string","example":"Plans start at €99 per month.","description":"The statement Peec checks AI claims against."},"origin":{"type":"string","enum":["website","manual"],"example":"manual","description":"How the fact was added: `manual` by a person, `website` extracted from the project's website."},"is_active":{"type":"boolean","description":"Whether Peec uses the fact in future fact-checking. An inactive fact stays listed."},"edited_at":{"nullable":true,"example":"2026-09-18T10:00:00.000Z","description":"When the wording was last changed, or null if never edited.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","example":"2026-09-01T10:00:00.000Z"}},"required":["id","text","origin","is_active","edited_at","created_at"]}}},"required":["created"],"description":"Every created fact with its new id"}}}},"402":{"description":"The project's plan does not cover this many active facts. Nothing was created.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"description":"The project's plan does not cover this many active facts. Nothing was created."}}}}},"operationId":"postFactsCreate"}},"/facts/update":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Update Facts","description":"Change the wording and/or active state of facts by id. Each item sets `text`, `is_active`, or both. Changing the wording keeps the old wording for verdicts already judged against it. Setting `is_active` to false keeps the fact listed but excludes it from future fact-checking. Returns per-item results { updated, skipped, rejected }; the batch never fails as a whole. Skip reasons: not_found. Rejection reasons: duplicate_id (the same fact appears twice in the request), plan_limit (activating it would exceed the plan's `fact_limit`).","tags":["Brand Perception"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"facts":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"fact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The fact ID returned by List Facts."},"text":{"description":"Replacement wording. Earlier verdicts keep the wording they were judged against.","type":"string","minLength":1},"is_active":{"description":"Whether Peec should use the fact in future fact-checking.","type":"boolean"}},"required":["fact_id"]}}},"required":["facts"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"facts":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"fact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The fact ID returned by List Facts."},"text":{"description":"Replacement wording. Earlier verdicts keep the wording they were judged against.","type":"string","minLength":1},"is_active":{"description":"Whether Peec should use the fact in future fact-checking.","type":"boolean"}},"required":["fact_id"]}}},"required":["facts"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"facts":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"fact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The fact ID returned by List Facts."},"text":{"description":"Replacement wording. Earlier verdicts keep the wording they were judged against.","type":"string","minLength":1},"is_active":{"description":"Whether Peec should use the fact in future fact-checking.","type":"boolean"}},"required":["fact_id"]}}},"required":["facts"]}}}},"responses":{"200":{"description":"Per-item update results","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","example":"0198f000-0000-7000-8000-000000000001"},"text":{"type":"string","example":"Plans start at €99 per month.","description":"The statement Peec checks AI claims against."},"origin":{"type":"string","enum":["website","manual"],"example":"manual","description":"How the fact was added: `manual` by a person, `website` extracted from the project's website."},"is_active":{"type":"boolean","description":"Whether Peec uses the fact in future fact-checking. An inactive fact stays listed."},"edited_at":{"nullable":true,"example":"2026-09-18T10:00:00.000Z","description":"When the wording was last changed, or null if never edited.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","example":"2026-09-01T10:00:00.000Z"}},"required":["id","text","origin","is_active","edited_at","created_at"]}},"skipped":{"type":"array","items":{"type":"object","properties":{"fact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"reason":{"type":"string","enum":["not_found"]}},"required":["fact_id","reason"]}},"rejected":{"type":"array","items":{"type":"object","properties":{"fact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"reason":{"type":"string","enum":["duplicate_id","no_changes","plan_limit"]},"message":{"type":"string"}},"required":["fact_id","reason","message"]}}},"required":["updated","skipped","rejected"],"description":"Per-item update results"}}}}},"operationId":"postFactsUpdate"}},"/facts/delete":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Delete Facts","description":"Delete facts by id. Deleted facts disappear from List Facts and are excluded from future fact-checking; verdicts already judged against them keep their original wording. Deletion cannot be undone. Returns per-item results { deleted, skipped }; the batch never fails as a whole. Skip reasons: not_found, already_deleted.","tags":["Brand Perception"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"fact_ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["fact_ids"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"fact_ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["fact_ids"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"fact_ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["fact_ids"]}}}},"responses":{"200":{"description":"Per-item delete results","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"array","items":{"type":"object","properties":{"fact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["fact_id"]}},"skipped":{"type":"array","items":{"type":"object","properties":{"fact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"reason":{"type":"string","enum":["not_found","already_deleted"]}},"required":["fact_id","reason"]}}},"required":["deleted","skipped"],"description":"Per-item delete results"}}}}},"operationId":"postFactsDelete"}},"/brand-perception/industries":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Brand Perception Industries","description":"The industries the project has brand-perception runs for. Each run is dispatched for one industry, so a project that changed its industry has data for several — pass a `name` from here as the `industry` filter on the attribute-rankings and competitive-breakdown endpoints to read one of them. An empty result means no run has been dispatched yet.","tags":["Brand Perception"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Luxury Sports Cars","description":"Pass this value as the `industry` filter on the other brand-perception endpoints."},"is_default":{"type":"boolean","example":true,"description":"True for the industry the other endpoints read when no `industry` filter is passed: the one with the most recent completed run, or the most recent run of any status while none has completed."},"last_run_started_at":{"type":"string","example":"2025-09-22","description":"When the industry's most recent brand-perception run was dispatched."},"last_run_completed_at":{"nullable":true,"example":"2025-09-23","description":"When the industry's most recent completed run finished; null while no run has completed and the data is still partial.","type":"string"}},"required":["name","is_default","last_run_started_at","last_run_completed_at"]},"description":"Industries sorted most-recently-started first."},"total_count":{"type":"number","example":2,"description":"Total number of industries, ignoring pagination"}},"required":["data","total_count"],"description":"Success"}}}}},"operationId":"getBrand-perceptionIndustries"}},"/brand-perception/attribute-clusters":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Brand Perception Attribute Clusters","description":"The project's brand-perception attribute taxonomy: every attribute with its id, name and terms (the raw phrasings from AI answers grouped under it), plus the unassigned terms no attribute claims. Unlike the brand-attributes endpoint this is the editable grouping rather than the scored snapshot, so it also lists attributes that carry no score yet. Use it to resolve the `cluster_id` values the edit endpoint takes and the create endpoint returns.","tags":["Brand Perception"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"cluster_id":{"type":"string","example":"0199a4c1-9f3e-7c21-9f0f-2c0a5d3b1e42","description":"Stable id of the attribute. Pass it to the edit endpoint; it survives renames."},"name":{"type":"string","example":"Luxury","description":"The attribute's name, as the Market view and the brand-perception reads show it."},"is_custom":{"type":"boolean","example":false,"description":"True when a user added the attribute by hand rather than Peec extracting it from AI answers."},"members":{"type":"array","items":{"type":"string"},"example":["luxury","prestige","exclusivity"],"description":"The attribute's terms: raw phrasings from AI answers grouped under it, alphabetically sorted."}},"required":["cluster_id","name","is_custom","members"]},"description":"Attributes sorted by name."},"total_count":{"type":"number","example":12,"description":"Total number of attributes, ignoring pagination"},"unassigned":{"type":"array","items":{"type":"string"},"example":["hand-built"],"description":"Terms that belong to no attribute yet. Move one into an attribute to give it a home. Not paginated."}},"required":["data","total_count","unassigned"],"description":"Success"}}}}},"operationId":"getBrand-perceptionAttribute-clusters"}},"/brand-perception/attribute-clusters/edit":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Edit Brand Perception Attribute Clusters","description":"Rename and delete the project's brand-perception attributes, move terms between attributes and unassign terms from theirs — the same edits the Manage attributes screen makes. The whole call is one transaction: if any edit is rejected nothing is applied. Edits apply in the order reassign, rename, unassign_terms, delete_cluster_ids regardless of how they are listed. Neither deleting an attribute nor unassign_terms permanently removes a term — both unassign it, so it stays visible under `unassigned` and can be moved into an attribute later. Scores re-aggregate on the next read, so no new scraping run is needed. Naming one term or attribute twice in a call is rejected, since the two edits would race. To add an attribute, use the create endpoint. Errors: 400 when a target is repeated, 404 when an attribute or term does not exist, 409 when a new name collides with another attribute.","tags":["Brand Perception"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"renames":{"description":"Attributes to rename.","maxItems":50,"type":"array","items":{"type":"object","properties":{"cluster_id":{"type":"string","example":"0199a4c1-9f3e-7c21-9f0f-2c0a5d3b1e42","description":"Attribute to rename, from the attribute-clusters listing."},"name":{"type":"string","minLength":1,"maxLength":120,"example":"Racing Heritage","description":"New name. Must be unique within the project, case-insensitively."}},"required":["cluster_id","name"]}},"delete_cluster_ids":{"example":["0199a4c1-9f3e-7c21-9f0f-2c0a5d3b1e42"],"description":"Attributes to remove, even ones that still hold terms — their terms become unassigned rather than being deleted.","maxItems":50,"type":"array","items":{"type":"string"}},"unassign_terms":{"example":["hand-built"],"description":"Terms to unassign from their attribute, spelled exactly as the listing returns them (in `members`). A no-op for a term already in `unassigned`.","maxItems":200,"type":"array","items":{"type":"string"}},"reassignments":{"description":"Terms to move into a different attribute.","maxItems":200,"type":"array","items":{"type":"object","properties":{"attribute":{"type":"string","minLength":1,"example":"hand-built","description":"Term to move, spelled exactly as the listing returns it (in `members` or `unassigned`)."},"cluster_id":{"type":"string","example":"0199a4c1-9f3e-7c21-9f0f-2c0a5d3b1e42","description":"Attribute the term moves into."}},"required":["attribute","cluster_id"]}}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"renames":{"description":"Attributes to rename.","maxItems":50,"type":"array","items":{"type":"object","properties":{"cluster_id":{"type":"string","example":"0199a4c1-9f3e-7c21-9f0f-2c0a5d3b1e42","description":"Attribute to rename, from the attribute-clusters listing."},"name":{"type":"string","minLength":1,"maxLength":120,"example":"Racing Heritage","description":"New name. Must be unique within the project, case-insensitively."}},"required":["cluster_id","name"]}},"delete_cluster_ids":{"example":["0199a4c1-9f3e-7c21-9f0f-2c0a5d3b1e42"],"description":"Attributes to remove, even ones that still hold terms — their terms become unassigned rather than being deleted.","maxItems":50,"type":"array","items":{"type":"string"}},"unassign_terms":{"example":["hand-built"],"description":"Terms to unassign from their attribute, spelled exactly as the listing returns them (in `members`). A no-op for a term already in `unassigned`.","maxItems":200,"type":"array","items":{"type":"string"}},"reassignments":{"description":"Terms to move into a different attribute.","maxItems":200,"type":"array","items":{"type":"object","properties":{"attribute":{"type":"string","minLength":1,"example":"hand-built","description":"Term to move, spelled exactly as the listing returns it (in `members` or `unassigned`)."},"cluster_id":{"type":"string","example":"0199a4c1-9f3e-7c21-9f0f-2c0a5d3b1e42","description":"Attribute the term moves into."}},"required":["attribute","cluster_id"]}}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"renames":{"description":"Attributes to rename.","maxItems":50,"type":"array","items":{"type":"object","properties":{"cluster_id":{"type":"string","example":"0199a4c1-9f3e-7c21-9f0f-2c0a5d3b1e42","description":"Attribute to rename, from the attribute-clusters listing."},"name":{"type":"string","minLength":1,"maxLength":120,"example":"Racing Heritage","description":"New name. Must be unique within the project, case-insensitively."}},"required":["cluster_id","name"]}},"delete_cluster_ids":{"example":["0199a4c1-9f3e-7c21-9f0f-2c0a5d3b1e42"],"description":"Attributes to remove, even ones that still hold terms — their terms become unassigned rather than being deleted.","maxItems":50,"type":"array","items":{"type":"string"}},"unassign_terms":{"example":["hand-built"],"description":"Terms to unassign from their attribute, spelled exactly as the listing returns them (in `members`). A no-op for a term already in `unassigned`.","maxItems":200,"type":"array","items":{"type":"string"}},"reassignments":{"description":"Terms to move into a different attribute.","maxItems":200,"type":"array","items":{"type":"object","properties":{"attribute":{"type":"string","minLength":1,"example":"hand-built","description":"Term to move, spelled exactly as the listing returns it (in `members` or `unassigned`)."},"cluster_id":{"type":"string","example":"0199a4c1-9f3e-7c21-9f0f-2c0a5d3b1e42","description":"Attribute the term moves into."}},"required":["attribute","cluster_id"]}}}}}}},"responses":{"200":{"description":"Success — every edit in the call was applied. Counts echo what was requested.","content":{"application/json":{"schema":{"type":"object","properties":{"renamed_count":{"type":"number","example":1},"deleted_count":{"type":"number","example":1},"unassigned_terms_count":{"type":"number","example":1},"reassigned_count":{"type":"number","example":3}},"required":["renamed_count","deleted_count","unassigned_terms_count","reassigned_count"],"description":"Success — every edit in the call was applied. Counts echo what was requested."}}}}},"operationId":"postBrand-perceptionAttribute-clustersEdit"}},"/brand-perception/attribute-clusters/create":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Create Brand Perception Attribute Clusters","description":"Add custom attributes to the project's brand-perception market view, the same edit the Add attribute button makes. Each new attribute starts with no terms; a top-of-funnel run is queued for the batch so its market prominence scores populate within a few minutes. A project holds at most 10 custom attributes. Errors: 400 when a name is empty, 409 when the batch would exceed the custom-attribute limit; nothing is added in that case.","tags":["Brand Perception"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"names":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"example":["Sustainability","Customer support"],"description":"Attributes to add. Each must be unique within the project, case-insensitively; a name that already exists is skipped rather than rejected. A project holds at most 10 custom attributes."}},"required":["names"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"names":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"example":["Sustainability","Customer support"],"description":"Attributes to add. Each must be unique within the project, case-insensitively; a name that already exists is skipped rather than rejected. A project holds at most 10 custom attributes."}},"required":["names"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"names":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"example":["Sustainability","Customer support"],"description":"Attributes to add. Each must be unique within the project, case-insensitively; a name that already exists is skipped rather than rejected. A project holds at most 10 custom attributes."}},"required":["names"]}}}},"responses":{"200":{"description":"Success. Every name is either in `created` or in `skipped`.","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"array","items":{"type":"object","properties":{"cluster_id":{"type":"string","example":"0199a4c1-9f3e-7c21-9f0f-2c0a5d3b1e42","description":"Stable id of the new attribute. Pass it to the edit endpoint; it survives renames."},"name":{"type":"string","example":"Sustainability"}},"required":["cluster_id","name"]},"description":"The attributes added by this call."},"skipped":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Pricing"},"reason":{"type":"string","enum":["duplicate"],"description":"The name already exists in the project or repeats within the call."}},"required":["name","reason"]},"description":"Names that were not added, with the reason."}},"required":["created","skipped"],"description":"Success. Every name is either in `created` or in `skipped`."}}}},"400":{"description":"A name is empty.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"description":"A name is empty."}}}},"409":{"description":"The batch would exceed the 10 custom-attribute limit. Nothing was added.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"description":"The batch would exceed the 10 custom-attribute limit. Nothing was added."}}}}},"operationId":"postBrand-perceptionAttribute-clustersCreate"}},"/brands":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Brands","description":"List the brands of a project","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"kw_915e742b-396d-4a86-ad57-8bc84e8c2232"},"name":{"type":"string","example":"Peec AI"},"domains":{"type":"array","items":{"type":"string","example":"peec.ai"}},"aliases":{"type":"array","items":{"type":"string","example":"Peec"}},"regex":{"nullable":true,"type":"string"},"is_own":{"type":"boolean"},"color":{"type":"string","example":"#3b82f6","description":"Hex color of the brand"},"source":{"type":"string","enum":["manual","suggestion","onboarding"],"example":"manual","description":"How the brand was added: 'manual' for direct creation, 'suggestion' for accepted brand suggestions, 'onboarding' for autogenerated competitors seeded at project start. Absent for brands created before this field was tracked."}},"required":["id","name","is_own","color"]}},"total_count":{"type":"number","example":42,"description":"Total number of brands, ignoring pagination"},"totalCount":{"type":"number","example":42,"description":"Total number of brands, ignoring pagination","deprecated":true}},"required":["data","total_count","totalCount"],"description":"Success"}}}}},"operationId":"getBrands"},"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Create Brand","description":"Create a new brand within a project","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"domains":{"type":"array","items":{"type":"string"}},"regex":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"color":{"description":"Hex color like #1A2B3C","type":"string"}},"required":["name"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"domains":{"type":"array","items":{"type":"string"}},"regex":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"color":{"description":"Hex color like #1A2B3C","type":"string"}},"required":["name"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"domains":{"type":"array","items":{"type":"string"}},"regex":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"color":{"description":"Hex color like #1A2B3C","type":"string"}},"required":["name"]}}}},"responses":{"201":{"description":"Brand created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"kw_915e742b-396d-4a86-ad57-8bc84e8c2232"}},"required":["id"],"description":"Brand created successfully"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postBrands"}},"/brands/social-channels":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Brand Social Channels","description":"List the social channels configured for a project, optionally filtered to one brand.","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"brand_id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"brand_id":{"type":"string"},"platform":{"type":"string","enum":["reddit","youtube","instagram","tiktok","linkedin","medium"]},"channel_id":{"type":"string"},"channel_handle":{"type":"string"}},"required":["id","brand_id","platform","channel_id","channel_handle"]}}},"required":["data"]}}}}},"operationId":"getBrandsSocial-channels"}},"/brands/suggestions":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Brand Suggestions","description":"List the open brand suggestions of a project","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"kw_915e742b-396d-4a86-ad57-8bc84e8c2232"},"name":{"type":"string","example":"Peec AI"},"domains":{"type":"array","items":{"type":"string","example":"peec.ai"}},"chat_count":{"type":"number","example":5},"source":{"type":"string","enum":["chat","competitor"],"example":"competitor","description":"Origin of the suggestion. 'chat' = extracted from AI chat responses. 'competitor' = direct competitor from the project profile."}},"required":["id","name","chat_count","source"]}}},"required":["data"],"description":"Success"}}}}},"operationId":"getBrandsSuggestions"}},"/brands/suggestions/{brand_suggestion_id}/accept":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Accept Brand Suggestion","description":"Accept a brand suggestion by ID, converting it into a brand within the project","tags":["Project"],"parameters":[{"name":"brand_suggestion_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Brand suggestion accepted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"kw_915e742b-396d-4a86-ad57-8bc84e8c2232"}},"required":["id"],"description":"Brand suggestion accepted successfully"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postBrandsSuggestionsByBrand_suggestion_idAccept"}},"/brands/suggestions/{brand_suggestion_id}/reject":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Reject Brand Suggestion","description":"Reject a brand suggestion by ID, removing it from the project and preventing it from being re-suggested","tags":["Project"],"parameters":[{"name":"brand_suggestion_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Brand suggestion rejected successfully","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Brand suggestion rejected successfully"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postBrandsSuggestionsByBrand_suggestion_idReject"}},"/brands/{brand_id}":{"delete":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Delete Brand","description":"Delete a brand within a project.","tags":["Project"],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Brand deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Brand deleted successfully"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"The brand is the project's own brand","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"description":"The brand is the project's own brand"}}}}},"operationId":"deleteBrandsByBrand_id"},"patch":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Update Brand","description":"Update a brand within a project. Changes to name, regex, or aliases trigger a background recalculation of metrics. While recalculation is in progress, further updates to these fields are blocked (409 Conflict) until it completes.","tags":["Project"],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"Triggers metric recalculation when changed","type":"string","minLength":1},"regex":{"description":"Triggers metric recalculation when changed","nullable":true,"type":"string"},"aliases":{"description":"Triggers metric recalculation when changed","type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"}},"color":{"description":"Hex color like #1A2B3C","type":"string"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"name":{"description":"Triggers metric recalculation when changed","type":"string","minLength":1},"regex":{"description":"Triggers metric recalculation when changed","nullable":true,"type":"string"},"aliases":{"description":"Triggers metric recalculation when changed","type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"}},"color":{"description":"Hex color like #1A2B3C","type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"description":"Triggers metric recalculation when changed","type":"string","minLength":1},"regex":{"description":"Triggers metric recalculation when changed","nullable":true,"type":"string"},"aliases":{"description":"Triggers metric recalculation when changed","type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"}},"color":{"description":"Hex color like #1A2B3C","type":"string"}}}}}},"responses":{"200":{"description":"Brand updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Brand updated successfully"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"The brand name already exists, or the brand is currently being recomputed and cannot be updated until the recalculation completes","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"description":"The brand name already exists, or the brand is currently being recomputed and cannot be updated until the recalculation completes"}}}}},"operationId":"patchBrandsByBrand_id"}},"/brands/{brand_id}/social-channels":{"put":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Set Brand Social Channels","description":"Replace the complete list of social channels configured for a brand. Pass an empty list to remove them all.","tags":["Project"],"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channels":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["reddit","youtube","instagram","tiktok","linkedin","medium"]},"channel":{"type":"string","minLength":1,"maxLength":2048}},"required":["platform","channel"]}}},"required":["channels"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"channels":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["reddit","youtube","instagram","tiktok","linkedin","medium"]},"channel":{"type":"string","minLength":1,"maxLength":2048}},"required":["platform","channel"]}}},"required":["channels"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"channels":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["reddit","youtube","instagram","tiktok","linkedin","medium"]},"channel":{"type":"string","minLength":1,"maxLength":2048}},"required":["platform","channel"]}}},"required":["channels"]}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"brand_id":{"type":"string"},"platform":{"type":"string","enum":["reddit","youtube","instagram","tiktok","linkedin","medium"]},"channel_id":{"type":"string"},"channel_handle":{"type":"string"}},"required":["id","brand_id","platform","channel_id","channel_handle"]}}},"required":["data"]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"putBrandsByBrand_idSocial-channels"}},"/prompts":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Prompts","description":"List the prompts of a project","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"topic_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"tag_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"is_archived","in":"query","required":false,"schema":{"description":"Filter by archived status. Omit (or `false`) to return only active prompts; `true` to return only archived prompts.","type":"string"}},{"name":"start_date","in":"query","required":false,"schema":{"description":"Only return prompts created on or after this date (UTC).","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"end_date","in":"query","required":false,"schema":{"description":"Only return prompts created on or before this date (UTC).","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"search","in":"query","required":false,"schema":{"description":"Free-text search over prompt text. Fuzzy and word-order-insensitive; results are ordered by relevance (best match first).","type":"string","minLength":1,"maxLength":500}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d"},"messages":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string","example":"Example Prompt"}},"required":["content"]}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"tg_23abec5b-100a-4261-9ee7-1effe68f0149"}},"required":["id"]}},"topic":{"nullable":true,"type":"object","properties":{"id":{"type":"string","example":"to_e6b8cdd3-a51b-4d94-a866-28dbe6b830a6"}},"required":["id"]},"user_location":{"type":"object","properties":{"country":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}},"required":["country"]},"volume":{"type":"number"},"is_archived":{"type":"boolean","example":false,"description":"Whether the prompt is archived (no longer tracked daily). Only active prompts are returned unless `is_archived=true` is passed."},"created_at":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["id","messages","tags","topic","user_location","is_archived"]}},"total_count":{"type":"number","example":42,"description":"Total number of matching prompts, ignoring pagination"},"totalCount":{"type":"number","example":42,"description":"Total number of matching prompts, ignoring pagination","deprecated":true},"search_truncated":{"description":"Only present when `search` is used. True when the project has more prompts than the search scan limit (20000); only the most recent 20000 prompts were searched, so matches may be missing and total_count may undercount.","type":"boolean"}},"required":["data","total_count","totalCount"],"description":"Success"}}}}},"operationId":"getPrompts"},"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Create Prompt","description":"Create a new prompt within a project. Without a `country_code` the prompt takes the market of its topic, or the project's market when the topic has none.","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":2000},"country_code":{"description":"The market to track the prompt from, as an ISO 3166-1 alpha-2 code. Omit it to use the topic's market, or the project's market when the topic has none.","example":"US","type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]},"tag_ids":{"type":"array","items":{"type":"string"}},"topic_id":{"type":"string"}},"required":["text"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":2000},"country_code":{"description":"The market to track the prompt from, as an ISO 3166-1 alpha-2 code. Omit it to use the topic's market, or the project's market when the topic has none.","example":"US","type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]},"tag_ids":{"type":"array","items":{"type":"string"}},"topic_id":{"type":"string"}},"required":["text"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":2000},"country_code":{"description":"The market to track the prompt from, as an ISO 3166-1 alpha-2 code. Omit it to use the topic's market, or the project's market when the topic has none.","example":"US","type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]},"tag_ids":{"type":"array","items":{"type":"string"}},"topic_id":{"type":"string"}},"required":["text"]}}}},"responses":{"201":{"description":"Prompt created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d"},"warning":{"description":"Warning message regarding the created prompt","type":"string"}},"required":["id"],"description":"Prompt created successfully"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"402":{"description":"Response for status 402","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postPrompts"}},"/prompts/suggestions":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Prompt Suggestions","description":"List the prompt suggestions of a project","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"topic_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"legacy","in":"query","required":false,"schema":{"description":"Which suggestions to return. `true` (the default) returns the project's standard prompt suggestions. `false` returns Prompt discovery suggestions — the generated set awaiting review, which is accepted through the Prompt discovery rather than the accept/reject endpoints below, and whose ids are prefixed `pr_` rather than `ps_`.","type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"ps_93f790de-5b7a-45ee-b782-61103c81f20d"},"messages":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string","example":"What is the best SEO tool?"}},"required":["content"]}},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"tg_23abec5b-100a-4261-9ee7-1effe68f0149"}},"required":["id"]}},"topic":{"nullable":true,"type":"object","properties":{"id":{"type":"string","example":"to_e6b8cdd3-a51b-4d94-a866-28dbe6b830a6"}},"required":["id"]},"user_location":{"type":"object","properties":{"country":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}},"required":["country"]},"volume":{"type":"number"}},"required":["id","messages","tags","topic","user_location"]}}},"required":["data"],"description":"Success"}}}}},"operationId":"getPromptsSuggestions"}},"/prompts/suggestions/generate":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Generate Prompt Suggestions","description":"Generate Prompt Builder suggestions for a project, the same way the Prompt Builder does. Generation runs in the background: this returns its generation ID as soon as it is queued. Poll `GET /prompts/suggestions/generations/{generation_id}` until it succeeds or fails, then list successful results with `GET /prompts/suggestions?legacy=false`. `topic_id`, `prompt_suggestion_id` and `segment` each narrow the run and are mutually exclusive; with an empty body every topic awaiting review is generated for again, replacing its current suggestions. The project's branding/intent split has to be configured first, with `PUT /project-profile` — generation has nothing to run against without it. Markets are optional: without them the project's own country and language are used. A project gets one full run of suggestions a day, sized as every topic, market, branding and intent combination at 10 prompts each. Once the project has queued that many, the request returns 429 with the time to retry.","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"topic_id":{"description":"Generates for this topic alone instead of every topic awaiting review, replacing the suggestions it already has.","example":"to_e6b8cdd3-a51b-4d94-a866-28dbe6b830a6","type":"string","minLength":1},"prompt_suggestion_id":{"description":"Replaces this one Prompt Builder suggestion, keeping its id, topic and market.","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d","type":"string","minLength":1},"segment":{"description":"Adds suggestions for one slice of a topic, keeping the suggestions it already has. Any dimension left unset is filled from the project's target distribution and markets.","type":"object","properties":{"topic_id":{"type":"string","minLength":1},"branding":{"type":"string","enum":["branded","non-branded"]},"intent":{"type":"string","enum":["informational","commercial","transactional"]},"persona_tag_id":{"type":"string"},"country":{"description":"Must be one of the project's markets, or its own country when it has none.","type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]},"count":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991}},"required":["topic_id"]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"topic_id":{"description":"Generates for this topic alone instead of every topic awaiting review, replacing the suggestions it already has.","example":"to_e6b8cdd3-a51b-4d94-a866-28dbe6b830a6","type":"string","minLength":1},"prompt_suggestion_id":{"description":"Replaces this one Prompt Builder suggestion, keeping its id, topic and market.","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d","type":"string","minLength":1},"segment":{"description":"Adds suggestions for one slice of a topic, keeping the suggestions it already has. Any dimension left unset is filled from the project's target distribution and markets.","type":"object","properties":{"topic_id":{"type":"string","minLength":1},"branding":{"type":"string","enum":["branded","non-branded"]},"intent":{"type":"string","enum":["informational","commercial","transactional"]},"persona_tag_id":{"type":"string"},"country":{"description":"Must be one of the project's markets, or its own country when it has none.","type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]},"count":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991}},"required":["topic_id"]}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"topic_id":{"description":"Generates for this topic alone instead of every topic awaiting review, replacing the suggestions it already has.","example":"to_e6b8cdd3-a51b-4d94-a866-28dbe6b830a6","type":"string","minLength":1},"prompt_suggestion_id":{"description":"Replaces this one Prompt Builder suggestion, keeping its id, topic and market.","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d","type":"string","minLength":1},"segment":{"description":"Adds suggestions for one slice of a topic, keeping the suggestions it already has. Any dimension left unset is filled from the project's target distribution and markets.","type":"object","properties":{"topic_id":{"type":"string","minLength":1},"branding":{"type":"string","enum":["branded","non-branded"]},"intent":{"type":"string","enum":["informational","commercial","transactional"]},"persona_tag_id":{"type":"string"},"country":{"description":"Must be one of the project's markets, or its own country when it has none.","type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]},"count":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991}},"required":["topic_id"]}}}}}},"responses":{"200":{"description":"Generation queued","content":{"application/json":{"schema":{"type":"object","properties":{"generation_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The generation to poll with GET /prompts/suggestions/generations/{generation_id}."},"topic_id":{"description":"The topic being generated when the request scoped the run to one topic or suggestion.","type":"string"}},"required":["generation_id"],"description":"Generation queued"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postPromptsSuggestionsGenerate"}},"/prompts/suggestions/generations/{generation_id}":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Prompt Suggestion Generation","description":"Get the authoritative state of a Prompt Builder suggestion generation queued by this project.","tags":["Project"],"parameters":[{"name":"generation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"generation_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","enum":["QUEUED","RUNNING","SUCCEEDED","FAILED"]},"topic_id":{"nullable":true,"type":"string"},"generated_suggestion_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"error_code":{"nullable":true,"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"started_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"finished_at":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["generation_id","status","topic_id","generated_suggestion_count","error_code","created_at","started_at","finished_at","updated_at"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"getPromptsSuggestionsGenerationsByGeneration_id"}},"/prompts/suggestions/{prompt_suggestion_id}/accept":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Accept Prompt Suggestion","description":"Accept a prompt suggestion by ID, creating a new prompt from it. Accepts both standard suggestions (`ps_`) and Prompt discovery suggestions (`pr_`); accepting a Prompt discovery suggestion also promotes its pending topic into a project topic. Optionally pass a country_code to override the suggestion's country for the created prompt — it applies to standard suggestions only, since a Prompt discovery suggestion keeps the market it was generated for.","tags":["Project"],"parameters":[{"name":"prompt_suggestion_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"default":{},"type":"object","properties":{"country_code":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}}},"application/x-www-form-urlencoded":{"schema":{"default":{},"type":"object","properties":{"country_code":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}}},"multipart/form-data":{"schema":{"default":{},"type":"object","properties":{"country_code":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}}}}},"responses":{"200":{"description":"Prompt suggestion accepted and prompt created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d"},"warning":{"description":"Present when the project's daily new-prompt allowance was reached; the prompt is created but its first chats are deferred.","type":"string"}},"required":["id"],"description":"Prompt suggestion accepted and prompt created"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"402":{"description":"Response for status 402","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postPromptsSuggestionsByPrompt_suggestion_idAccept"}},"/prompts/suggestions/{prompt_suggestion_id}/reject":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Reject Prompt Suggestion","description":"Reject a prompt suggestion by ID, deleting it. Accepts both standard suggestions (`ps_`) and Prompt discovery suggestions (`pr_`).","tags":["Project"],"parameters":[{"name":"prompt_suggestion_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Prompt suggestion rejected successfully","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Prompt suggestion rejected successfully"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postPromptsSuggestionsByPrompt_suggestion_idReject"}},"/prompts/suggestions/update":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Update Prompt Suggestions","description":"Edit pending Prompt discovery suggestions (`pr_`) before accepting them: rewrite the text and/or replace the tag set per item. Editing keeps a suggestion pending — accept it to create the tracked prompt. Each item is independent: unknown ids are reported in `skipped`, and unsatisfiable items (a standard `ps_` suggestion, an unknown tag, a duplicate id, nothing to change) in `rejected`, so the batch never fails as a whole.","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"suggestions":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"prompt_suggestion_id":{"type":"string","description":"The suggestion to edit, from GET /prompts/suggestions.","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d"},"text":{"description":"New prompt text, replacing the suggestion's current text.","type":"string","minLength":1,"maxLength":2000},"tag_ids":{"description":"New tag set, replacing the suggestion's existing tags. Each id must be an existing tag in the project.","type":"array","items":{"type":"string"}}},"required":["prompt_suggestion_id"]}}},"required":["suggestions"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"suggestions":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"prompt_suggestion_id":{"type":"string","description":"The suggestion to edit, from GET /prompts/suggestions.","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d"},"text":{"description":"New prompt text, replacing the suggestion's current text.","type":"string","minLength":1,"maxLength":2000},"tag_ids":{"description":"New tag set, replacing the suggestion's existing tags. Each id must be an existing tag in the project.","type":"array","items":{"type":"string"}}},"required":["prompt_suggestion_id"]}}},"required":["suggestions"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"suggestions":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"prompt_suggestion_id":{"type":"string","description":"The suggestion to edit, from GET /prompts/suggestions.","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d"},"text":{"description":"New prompt text, replacing the suggestion's current text.","type":"string","minLength":1,"maxLength":2000},"tag_ids":{"description":"New tag set, replacing the suggestion's existing tags. Each id must be an existing tag in the project.","type":"array","items":{"type":"string"}}},"required":["prompt_suggestion_id"]}}},"required":["suggestions"]}}}},"responses":{"200":{"description":"Per-item update results","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"array","items":{"type":"object","properties":{"prompt_suggestion_id":{"type":"string"}},"required":["prompt_suggestion_id"]}},"skipped":{"type":"array","items":{"type":"object","properties":{"prompt_suggestion_id":{"type":"string"},"reason":{"type":"string","enum":["not_found"]}},"required":["prompt_suggestion_id","reason"]}},"rejected":{"type":"array","items":{"type":"object","properties":{"prompt_suggestion_id":{"type":"string"},"reason":{"type":"string","enum":["not_editable","invalid_tag","duplicate_id","no_changes"]},"message":{"type":"string"}},"required":["prompt_suggestion_id","reason","message"]}}},"required":["updated","skipped","rejected"],"description":"Per-item update results"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postPromptsSuggestionsUpdate"}},"/prompts/{prompt_id}":{"delete":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Delete Prompt","description":"Delete a prompt and cascade to related chats","tags":["Project"],"parameters":[{"name":"prompt_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Prompt deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Prompt deleted successfully"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"deletePromptsByPrompt_id"},"patch":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Update Prompt","description":"Update a prompt's topic and tags within a project","tags":["Project"],"parameters":[{"name":"prompt_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"topic_id":{"nullable":true,"type":"string"},"tag_ids":{"type":"array","items":{"type":"string"}}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"topic_id":{"nullable":true,"type":"string"},"tag_ids":{"type":"array","items":{"type":"string"}}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"topic_id":{"nullable":true,"type":"string"},"tag_ids":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Prompt updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Prompt updated successfully"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"patchPromptsByPrompt_id"}},"/prompts/{prompt_id}/archive":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Archive Prompt","description":"Archive a prompt (is_archived = true) so it stops running while keeping its chats and history","tags":["Project"],"parameters":[{"name":"prompt_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Prompt archived successfully","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Prompt archived successfully"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postPromptsByPrompt_idArchive"}},"/prompts/{prompt_id}/unarchive":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Unarchive Prompt","description":"Unarchive a prompt (is_archived = false), reactivating it. Subject to the project's active-prompt plan limit","tags":["Project"],"parameters":[{"name":"prompt_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Prompt unarchived successfully","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Prompt unarchived successfully"}}}},"402":{"description":"Response for status 402","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postPromptsByPrompt_idUnarchive"}},"/members/invite":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Invite Project Members","description":"Invite people to the project by email, as a viewer or an owner. Each person gets the same invitation email as an invite from the app. An email that already has a Peec account gets access right away; anyone else gets access once they sign up from the email. An email that already has access or an open invitation lands in `skipped`, and the request never fails as a whole because of one item. Returns 403 when the company has turned off email invitations.","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"members":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"Email address to send the invitation to.","example":"jane.doe@example.com"},"role":{"default":"VIEWER","description":"Role in the project. Defaults to `VIEWER`.","type":"string","enum":["OWNER","VIEWER"],"example":"VIEWER"}},"required":["email"]},"description":"Up to 50 people to invite."}},"required":["members"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"members":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"Email address to send the invitation to.","example":"jane.doe@example.com"},"role":{"default":"VIEWER","description":"Role in the project. Defaults to `VIEWER`.","type":"string","enum":["OWNER","VIEWER"],"example":"VIEWER"}},"required":["email"]},"description":"Up to 50 people to invite."}},"required":["members"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"members":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"Email address to send the invitation to.","example":"jane.doe@example.com"},"role":{"default":"VIEWER","description":"Role in the project. Defaults to `VIEWER`.","type":"string","enum":["OWNER","VIEWER"],"example":"VIEWER"}},"required":["email"]},"description":"Up to 50 people to invite."}},"required":["members"]}}}},"responses":{"200":{"description":"Per-item results, `index` naming the position in the request.","content":{"application/json":{"schema":{"type":"object","properties":{"invited":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number"},"email":{"type":"string"},"role":{"type":"string","enum":["OWNER","VIEWER"],"description":"`VIEWER` can see the project's data. `OWNER` can also change the project and manage its members.","example":"VIEWER"},"access":{"type":"string","enum":["granted","pending"],"description":"`granted` when the email already has a Peec account and can open the project now. `pending` until the invitee signs up from the invitation email."}},"required":["index","email","role","access"]}},"skipped":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number"},"email":{"type":"string"},"reason":{"type":"string","enum":["already_member","already_invited","duplicate"],"description":"`already_member` has access to the project, `already_invited` has an open invitation to it, and `duplicate` repeats an earlier email in the same request."}},"required":["index","email","reason"]}},"rejected":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number"},"email":{"type":"string"},"message":{"type":"string"}},"required":["index","email","message"]}}},"required":["invited","skipped","rejected"],"description":"Per-item results, `index` naming the position in the request."}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postMembersInvite"}},"/tags":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Tags","description":"List the tags of a project. Tags include user-created tags and Peec-managed system tags (is_system=true). Each tag carries a `group`: for system tags this is the mutually-exclusive dimension (branding or intentType); for user tags it is the user-defined group name (or null). Pass `group` to filter to a single user-defined group. System tags cannot be edited or deleted.","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"group","in":"query","required":false,"schema":{"example":"persona","description":"Filter to tags in this user-defined group (matches the `group` column exactly).","type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"tg_23abec5b-100a-4261-9ee7-1effe68f0149"},"name":{"type":"string","example":"SEO"},"is_system":{"example":false,"description":"Whether this is a system tag. System tags are maintained by Peec and auto-assigned to every prompt by its branding/intent classification; they cannot be created, edited, or deleted, but can be assigned to prompts.","type":"boolean"},"group":{"nullable":true,"example":"branding","description":"The group a tag belongs to, or null if ungrouped. For system tags this is the mutually-exclusive dimension \"branding\" (branded / non-branded) or \"intentType\" (informational / commercial / transactional) — every prompt carries exactly one tag per system group. For user tags it is the user-defined group name (e.g. \"persona\").","type":"string"}},"required":["id","name","group"]}},"total_count":{"type":"number","example":42,"description":"Total number of matching tags, ignoring pagination"},"totalCount":{"type":"number","example":42,"description":"Total number of matching tags, ignoring pagination","deprecated":true}},"required":["data","total_count","totalCount"],"description":"Success"}}}}},"operationId":"getTags"},"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Create Tag","description":"Create a new tag within a project","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"color":{"default":"gray","type":"string","enum":["gray","red","orange","yellow","lime","green","cyan","blue","purple","fuchsia","pink","emerald","amber","violet","indigo","teal","sky","rose","slate","zinc","neutral","stone"]},"group":{"example":"persona","description":"Optional tag group. Tags sharing a group are colored as a unit, so a grouped tag inherits the group's color and the `color` field is ignored.","nullable":true,"type":"string","minLength":1}},"required":["name"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"color":{"default":"gray","type":"string","enum":["gray","red","orange","yellow","lime","green","cyan","blue","purple","fuchsia","pink","emerald","amber","violet","indigo","teal","sky","rose","slate","zinc","neutral","stone"]},"group":{"example":"persona","description":"Optional tag group. Tags sharing a group are colored as a unit, so a grouped tag inherits the group's color and the `color` field is ignored.","nullable":true,"type":"string","minLength":1}},"required":["name"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"color":{"default":"gray","type":"string","enum":["gray","red","orange","yellow","lime","green","cyan","blue","purple","fuchsia","pink","emerald","amber","violet","indigo","teal","sky","rose","slate","zinc","neutral","stone"]},"group":{"example":"persona","description":"Optional tag group. Tags sharing a group are colored as a unit, so a grouped tag inherits the group's color and the `color` field is ignored.","nullable":true,"type":"string","minLength":1}},"required":["name"]}}}},"responses":{"201":{"description":"Tag created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"tg_23abec5b-100a-4261-9ee7-1effe68f0149"}},"required":["id"],"description":"Tag created successfully"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postTags"}},"/tags/{tag_id}":{"delete":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Delete Tag","description":"Delete a tag within a project","tags":["Project"],"parameters":[{"name":"tag_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Tag deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Tag deleted successfully"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"deleteTagsByTag_id"},"patch":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Update Tag","description":"Update a tag within a project","tags":["Project"],"parameters":[{"name":"tag_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"color":{"type":"string","enum":["gray","red","orange","yellow","lime","green","cyan","blue","purple","fuchsia","pink","emerald","amber","violet","indigo","teal","sky","rose","slate","zinc","neutral","stone"]},"group":{"example":"persona","description":"Set to move the tag into a group (it inherits the group's color, overriding `color`), or `null` to remove it from its group. Omit to leave the group unchanged.","nullable":true,"type":"string","minLength":1}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"color":{"type":"string","enum":["gray","red","orange","yellow","lime","green","cyan","blue","purple","fuchsia","pink","emerald","amber","violet","indigo","teal","sky","rose","slate","zinc","neutral","stone"]},"group":{"example":"persona","description":"Set to move the tag into a group (it inherits the group's color, overriding `color`), or `null` to remove it from its group. Omit to leave the group unchanged.","nullable":true,"type":"string","minLength":1}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"color":{"type":"string","enum":["gray","red","orange","yellow","lime","green","cyan","blue","purple","fuchsia","pink","emerald","amber","violet","indigo","teal","sky","rose","slate","zinc","neutral","stone"]},"group":{"example":"persona","description":"Set to move the tag into a group (it inherits the group's color, overriding `color`), or `null` to remove it from its group. Omit to leave the group unchanged.","nullable":true,"type":"string","minLength":1}}}}}},"responses":{"200":{"description":"Tag updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Tag updated successfully"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"patchTagsByTag_id"}},"/tag-groups":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Tag Groups","description":"List the user-defined tag groups of a project (distinct non-empty `group` values across the project's tags), each with its shared color and tag count. System groups (branding/intentType) are not included — see List Tags for those.","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"group":{"type":"string","example":"persona"},"color":{"nullable":true,"example":"blue","description":"Shared color of every tag in the group","type":"string"},"tag_count":{"type":"number","example":3,"description":"Number of tags in the group"}},"required":["group","color","tag_count"]}}},"required":["data"],"description":"Success"}}}}},"operationId":"getTag-groups"},"delete":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Delete Tag Group","description":"Delete a user-defined tag group. By default the tags are kept and simply ungrouped (their `group` becomes null); pass delete_tags=true to delete the tags themselves and detach them from every prompt. System groups (branding/intentType) cannot be deleted.","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"group":{"type":"string","example":"persona","description":"The group name to delete"},"delete_tags":{"default":false,"example":false,"description":"When true, the group's tags are deleted (and removed from all prompts) instead of just being ungrouped. Defaults to false.","type":"boolean"}},"required":["group"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"group":{"type":"string","example":"persona","description":"The group name to delete"},"delete_tags":{"default":false,"example":false,"description":"When true, the group's tags are deleted (and removed from all prompts) instead of just being ungrouped. Defaults to false.","type":"boolean"}},"required":["group"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"group":{"type":"string","example":"persona","description":"The group name to delete"},"delete_tags":{"default":false,"example":false,"description":"When true, the group's tags are deleted (and removed from all prompts) instead of just being ungrouped. Defaults to false.","type":"boolean"}},"required":["group"]}}}},"responses":{"200":{"description":"Group deleted successfully. By default its tags are kept and ungrouped; with delete_tags=true they are deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"tag_count":{"type":"number"}},"required":["tag_count"],"description":"Group deleted successfully. By default its tags are kept and ungrouped; with delete_tags=true they are deleted."}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"deleteTag-groups"}},"/tag-groups/{group}":{"patch":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Update Tag Group","description":"Rename and/or recolor a user-defined tag group. Applies to every tag in the group. System groups (branding/intentType) cannot be modified.","tags":["Project"],"parameters":[{"name":"group","in":"path","required":true,"schema":{"type":"string","example":"persona","description":"The current group name (URL-encoded)"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"audience","description":"New group name to rename the group to","type":"string","minLength":1},"color":{"example":"green","description":"New color applied to every tag in the group","type":"string","enum":["gray","red","orange","yellow","lime","green","cyan","blue","purple","fuchsia","pink","emerald","amber","violet","indigo","teal","sky","rose","slate","zinc","neutral","stone"]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"name":{"example":"audience","description":"New group name to rename the group to","type":"string","minLength":1},"color":{"example":"green","description":"New color applied to every tag in the group","type":"string","enum":["gray","red","orange","yellow","lime","green","cyan","blue","purple","fuchsia","pink","emerald","amber","violet","indigo","teal","sky","rose","slate","zinc","neutral","stone"]}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"example":"audience","description":"New group name to rename the group to","type":"string","minLength":1},"color":{"example":"green","description":"New color applied to every tag in the group","type":"string","enum":["gray","red","orange","yellow","lime","green","cyan","blue","purple","fuchsia","pink","emerald","amber","violet","indigo","teal","sky","rose","slate","zinc","neutral","stone"]}}}}}},"responses":{"200":{"description":"Group updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"tag_count":{"type":"number"}},"required":["tag_count"],"description":"Group updated successfully"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"patchTag-groupsByGroup"}},"/topics":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Topics","description":"List the topics of a project","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"to_5524d66a-df1e-47e4-9dbc-802af39235ad"},"name":{"type":"string","example":"SEO"}},"required":["id","name"]}},"total_count":{"type":"number","example":42,"description":"Total number of matching topics, ignoring pagination"},"totalCount":{"type":"number","example":42,"description":"Total number of matching topics, ignoring pagination","deprecated":true}},"required":["data","total_count","totalCount"],"description":"Success"}}}}},"operationId":"getTopics"},"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Create Topic","description":"Create a new topic within a project","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"country_code":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}},"required":["name"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"country_code":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}},"required":["name"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"country_code":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}},"required":["name"]}}}},"responses":{"201":{"description":"Topic created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"to_5524d66a-df1e-47e4-9dbc-802af39235ad"}},"required":["id"],"description":"Topic created successfully"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postTopics"}},"/topics/generate":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Generate Topics","description":"Compose candidate topics for the project from its brand profile. Nothing is saved — review the returned names and create the ones you want with `POST /topics`. Composition already accounts for the project's existing topics, so it proposes only what fills a gap and can return an empty list when the set is already well covered. Rate limited per project; the `x-ratelimit-*` response headers report the remaining budget.","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"default":{},"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"topic_count":{"description":"How many topics to compose. Defaults to the number the project's plan allows.","type":"integer","minimum":1,"maximum":50}}}},"application/x-www-form-urlencoded":{"schema":{"default":{},"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"topic_count":{"description":"How many topics to compose. Defaults to the number the project's plan allows.","type":"integer","minimum":1,"maximum":50}}}},"multipart/form-data":{"schema":{"default":{},"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"topic_count":{"description":"How many topics to compose. Defaults to the number the project's plan allows.","type":"integer","minimum":1,"maximum":50}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Running shoes"}},"required":["name"]}}},"required":["data"],"description":"Success"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postTopicsGenerate"}},"/topics/suggestions":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Topic Suggestions","description":"List the topic suggestions of a project","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"to_5524d66a-df1e-47e4-9dbc-802af39235ad"},"name":{"type":"string","example":"SEO"}},"required":["id","name"]}}},"required":["data"],"description":"Success"}}}}},"operationId":"getTopicsSuggestions"}},"/topics/suggestions/{topic_suggestion_id}/accept":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Accept Topic Suggestion","description":"Accept a topic suggestion by ID, converting it into a regular topic","tags":["Project"],"parameters":[{"name":"topic_suggestion_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Topic suggestion accepted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"to_93f790de-5b7a-45ee-b782-61103c81f20d"}},"required":["id"],"description":"Topic suggestion accepted successfully"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postTopicsSuggestionsByTopic_suggestion_idAccept"}},"/topics/suggestions/{topic_suggestion_id}/reject":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Reject Topic Suggestion","description":"Reject a topic suggestion by ID, deleting it and its associated prompt suggestions","tags":["Project"],"parameters":[{"name":"topic_suggestion_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Topic suggestion rejected successfully","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Topic suggestion rejected successfully"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postTopicsSuggestionsByTopic_suggestion_idReject"}},"/topics/{topic_id}":{"delete":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Delete Topic","description":"Delete a topic, detaching all associated prompts and deleting prompt suggestions","tags":["Project"],"parameters":[{"name":"topic_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Topic deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Topic deleted successfully"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"deleteTopicsByTopic_id"},"patch":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Update Topic","description":"Update a topic within a project","tags":["Project"],"parameters":[{"name":"topic_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64}}}}}},"responses":{"200":{"description":"Topic updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Topic updated successfully"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"patchTopicsByTopic_id"}},"/models":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Models","description":"Deprecated: use List Model Channels instead.","tags":["Project"],"deprecated":true,"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Human-readable display name for the model (e.g., \"ChatGPT\", \"Perplexity\")."},"is_active":{"type":"boolean","description":"Indicates if the model is active for the project."}},"required":["id","name","is_active"]}}},"required":["data"],"description":"Success","example":{"data":[{"id":"chatgpt-scraper","name":"ChatGPT","is_active":true},{"id":"gpt-4o-search","name":"GPT 5 Search","is_active":true},{"id":"perplexity-scraper","name":"Perplexity","is_active":true}]}}}}}},"operationId":"getModels"}},"/model-channels":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Model Channels","description":"List the model channels","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"openai-0"},"description":{"type":"string","description":"Human-readable description of the model channel.","example":"ChatGPT Website"},"current_model":{"type":"object","properties":{"id":{"type":"string","example":"perplexity-scraper"}},"required":["id"],"description":"The currently active model in this channel."},"is_active":{"type":"boolean","description":"Indicates if the model channel is active for the project."},"unsupported_country_codes":{"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]},"description":"Country codes that cannot be used with this channel. Chats requested for these countries are not created."}},"required":["id","description","current_model","is_active","unsupported_country_codes"]}}},"required":["data"],"description":"Success","example":{"data":[{"id":"openai-0","description":"ChatGPT","current_model":{"id":"chatgpt-scraper"},"is_active":true,"unsupported_country_codes":[]},{"id":"amazon-0","description":"Amazon Rufus UI","current_model":{"id":"amazon-rufus-scraper"},"is_active":true,"unsupported_country_codes":["AE","AR","AT"]}]}}}}}},"operationId":"getModel-channels"}},"/agent-analytics/bots":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Bots","description":"List all known AI agent bots from agent analytics.","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"GPTBot"},"provider":{"type":"string","example":"OpenAI"},"type":{"type":"string","example":"training"}},"required":["id","provider","type"]}}},"required":["data"],"description":"Success","example":{"data":[{"id":"GPTBot","provider":"OpenAI","type":"training"}]}}}}}},"operationId":"getAgent-analyticsBots"}},"/agent-analytics/logs":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Agent logs","description":"List Agent access logs from your log provider integration or access file upload, oldest first.","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"start_date","in":"query","required":false,"schema":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"end_date","in":"query","required":false,"schema":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"bot_ids","in":"query","required":false,"schema":{"description":"List of bot IDs to filter by. you will get it from /agent-analytics/bots","example":["AppleBot","GoogleBot"],"type":"array","items":{"type":"string","enum":["GPTBot","anthropic-ai","Google-Extended","Meta-ExternalAgent","Applebot-Extended","Amazonbot","Bytespider","CCBot","Ai2Bot","Ai2Bot-Dolma","cohere-ai","cohere-training-data-crawler","DeepSeekBot","PanguBot","Webzio-Extended","Diffbot","Brightbot","FacebookBot","omgili","Timpibot","GrokBot","OAI-SearchBot","Claude-SearchBot","PerplexityBot","Amzn-SearchBot","AzureAI-SearchBot","Google-CloudVertexBot","meta-webindexer","Applebot","Grok-DeepSearch","xAI-Grok","ChatGPT-User","Claude-User","Perplexity-User","Manus-User","GoogleAgent-Mariner","NovaAct","Gemini-Deep-Research","MistralAI-User","DuckAssistBot","quillbot.com","meta-externalfetcher","Claude-Code","MyCentralAIScraperBot","Google-Agent","omgilibot","ClaudeBot","Claude-Web","YouBot"]}}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"bot_id":{"type":"string","example":"AppleBot"},"timestamp":{"type":"string","description":"ISO 8601, UTC.","example":"2025-01-01T00:01:02.000Z"},"request_method":{"type":"string","example":"GET"},"request_host":{"type":"string","example":"example.com"},"request_path":{"type":"string","example":"/path"},"response_status":{"type":"number","example":200},"user_agent":{"type":"string","example":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Safari/605.1.15 (Applebot/0.1; +http://www.apple.com/go/applebot)"},"client_ip":{"type":"string","example":"127.0.0.1"},"referer":{"type":"string","example":"notexample.com"}},"required":["bot_id","timestamp","request_method","request_host","request_path","response_status","user_agent"]}},"total_count":{"type":"number","example":100,"description":"Total number of agent logs in storage"},"totalCount":{"type":"number","example":100,"description":"Total number of agent logs in storage","deprecated":true}},"required":["data","total_count","totalCount"]}}}}},"operationId":"getAgent-analyticsLogs"}},"/agent-analytics/visits":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Agent Visits","description":"Aggregate agent access log visits grouped by a chosen dimension (bot, response status, host, path).","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"start_date","in":"query","required":false,"schema":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"end_date","in":"query","required":false,"schema":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"group_by","in":"query","required":false,"schema":{"description":"Dimension(s) to group visit counts by.","example":["bot_id"],"type":"array","items":{"type":"string","enum":["bot_id","response_status","request_host","request_path"]}}},{"name":"bot_ids","in":"query","required":false,"schema":{"description":"Optional list of bot IDs to filter by.","example":["AppleBot","GoogleBot"],"type":"array","items":{"type":"string"}}},{"name":"verification_statuses","in":"query","required":false,"schema":{"description":"Verification statuses to include. Defaults to verified and unverifiable, excluding spoofed traffic. Include all three statuses to restore totals that contain spoofed traffic.","example":["verified","unverifiable"],"minItems":1,"type":"array","items":{"type":"string","enum":["verified","spoofed","unverifiable"]}}},{"name":"time_bucket","in":"query","required":false,"schema":{"description":"Optional time_bucket for grouping visits by time.","example":"day","type":"string","enum":["hour","day","week","month"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"bot_id":{"example":"GPTBot","type":"string"},"response_status":{"example":200,"type":"number"},"request_host":{"example":"example.com","type":"string"},"time_bucket":{"description":"Bucket start in ISO 8601 (UTC). Week and month buckets are plain dates.","example":"2026-03-01T00:00:00Z","type":"string"},"request_path":{"example":"/path","type":"string"},"visits":{"type":"number","example":1402}},"required":["visits"]}},"total_count":{"type":"number","description":"Total number of grouped rows.","example":10},"totalCount":{"type":"number","description":"Total number of grouped rows.","example":10,"deprecated":true}},"required":["data","total_count","totalCount"],"description":"Success","example":{"data":[{"bot_id":"GPTBot","visits":1402},{"bot_id":"AppleBot","visits":893}],"total_count":2,"totalCount":2}}}}}},"operationId":"getAgent-analyticsVisits"}},"/agent-analytics/readiness":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Agent Readiness","description":"How ready the project's own brand domains and its competitors' domains are for AI agents, from Peec's agent readiness audit. Each domain of each brand is its own entry in `own` or `competitors`.\n\nEach site gets a level from 0 to 5 (0 Turned away, 1 Reachable, 2 Findable, 3 Readable, 4 Operable, 5 Transactable), named in `level_name`. A level is reached when every gate check of that level and of every level below it passes, so `next_level.blocking_check_ids` lists what to fix next. Each check also reports its own outcome and what that outcome means in `reason_label`, including the optional checks that never block a level, how to fix it, and the pages it failed on.\n\nReading this endpoint never starts an audit; request one for the project's own domains with `POST /agent-analytics/readiness/audits`, then follow it through `latest_run` on the domain's `own` entry. A domain without an audit completed in the last 90 days returns `audit: null`.","tags":["Agent Analytics"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"own":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"object","properties":{"id":{"type":"string","example":"kw_3f1c9a2e-7b4d-4e8a-9c21-5d6b8e0f1a2b"},"name":{"type":"string","example":"Peec AI"}},"required":["id","name"]},"domain":{"type":"string","description":"One of the own brand's domains, exactly as the brand lists it; a brand with several domains appears once per domain.","example":"peec.ai"},"audit":{"nullable":true,"description":"The newest audit completed within the last 90 days, or null when the domain has none.","type":"object","properties":{"completed_at":{"type":"string","description":"When the audit finished, in ISO 8601 (UTC).","example":"2026-10-01T09:30:00.000Z"},"level":{"type":"integer","minimum":0,"maximum":5,"description":"The highest level whose gate checks all pass, climbing from level 1. 0 until every level 1 gate passes.","example":2},"level_name":{"type":"string","description":"The name of `level`: 0 Turned away, 1 Reachable, 2 Findable, 3 Readable, 4 Operable, 5 Transactable.","example":"Findable"},"level_question":{"type":"string","description":"The question `level` answers for agents.","example":"Can they find what's there?"},"ceiling":{"type":"integer","minimum":0,"maximum":5,"description":"The highest level this audit can award the site: the top level that has at least one applicable gate check.","example":4},"ceiling_name":{"type":"string","description":"The name of `ceiling`.","example":"Findable"},"ceiling_question":{"type":"string","description":"The question `ceiling` answers for agents.","example":"Can they find what's there?"},"next_level":{"nullable":true,"description":"What stands between the site and the next level. Null when the site is already at its ceiling.","type":"object","properties":{"level":{"type":"integer","minimum":0,"maximum":5,"example":3},"level_name":{"type":"string","description":"The name of the next level.","example":"Findable"},"level_question":{"type":"string","description":"The question the next level answers for agents.","example":"Can they find what's there?"},"passed_gates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Gate checks of the next level that already pass.","example":3},"total_gates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Applicable gate checks of the next level.","example":5},"blocking_check_ids":{"type":"array","items":{"type":"string","enum":["domain.robots_txt","domain.ai_agent_access","domain.sitemap","domain.link_headers","domain.llms_txt","domain.soft_404","domain.content_signals","domain.aipref_content_usage","domain.sitemap_lastmod","domain.llms_full_txt","domain.api_catalog","domain.mcp_server_card","domain.oauth_authorization_server","domain.oauth_protected_resource","domain.a2a_agent_card","domain.agent_skills_index","domain.auth_md","domain.web_bot_auth","domain.ard","domain.ucp","page.md_suffix","page.render_without_javascript","page.navigation_without_javascript","page.markdown_negotiation","page.bot_reachability","page.meta_robots","page.snippet_controls","page.soft_404","page.structured_data","page.organization_schema","page.semantic_landmarks","page.heading_structure","page.document_title","page.language","page.meta_description","page.canonical","page.open_graph","page.image_alt_text","page.descriptive_links","page.editorial_freshness","page.page_type_schema","page.entity_linking"]},"description":"The gate checks that keep the site from the next level. Fix these to level up.","example":["page.structured_data","page.organization_schema"]}},"required":["level","level_name","level_question","passed_gates","total_gates","blocking_check_ids"]},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["domain.robots_txt","domain.ai_agent_access","domain.sitemap","domain.link_headers","domain.llms_txt","domain.soft_404","domain.content_signals","domain.aipref_content_usage","domain.sitemap_lastmod","domain.llms_full_txt","domain.api_catalog","domain.mcp_server_card","domain.oauth_authorization_server","domain.oauth_protected_resource","domain.a2a_agent_card","domain.agent_skills_index","domain.auth_md","domain.web_bot_auth","domain.ard","domain.ucp","page.md_suffix","page.render_without_javascript","page.navigation_without_javascript","page.markdown_negotiation","page.bot_reachability","page.meta_robots","page.snippet_controls","page.soft_404","page.structured_data","page.organization_schema","page.semantic_landmarks","page.heading_structure","page.document_title","page.language","page.meta_description","page.canonical","page.open_graph","page.image_alt_text","page.descriptive_links","page.editorial_freshness","page.page_type_schema","page.entity_linking"],"example":"domain.llms_txt"},"title":{"type":"string","description":"The check's name, as the Peec app shows it.","example":"llms.txt"},"level":{"type":"integer","minimum":0,"maximum":5,"description":"The level this check counts toward.","example":2},"level_name":{"type":"string","description":"The name of the check's level.","example":"Findable"},"level_question":{"type":"string","description":"The question the check's level answers for agents.","example":"Can they find what's there?"},"tier":{"type":"string","enum":["gate","reported","emerging"],"description":"`gate` (Scored): Decides your level. Every scored check at a level has to pass to clear it. `reported` (Optional): Hygiene that doesn't change your level. `emerging` (Optional): A standard few agents use yet. It doesn't change your level.","example":"emerging"},"outcome":{"type":"string","enum":["confirmed","absent","invalid","blocked","inconclusive","not_applicable"],"description":"The check's result across every page it ran on, the most severe one winning. `absent`, `invalid`, and `blocked` need fixing.","example":"absent"},"reason_label":{"type":"string","description":"What the result that decided `outcome` means, in plain language, such as why a file counts as malformed.","example":"The server reported that this resource does not exist."},"why":{"type":"string","description":"Why the check matters to AI agents, written for the check's outcome, such as a missing file versus a malformed one.","example":"A curated index of the pages you'd want an LLM to read first."},"fix":{"type":"string","description":"How to make the check pass from its outcome.","example":"If you keep one, link canonical pages from valid Markdown."},"failing_pages":{"type":"array","items":{"type":"string"},"description":"Up to 5 URLs of pages the check failed on, sorted. Empty when it failed on none, and for checks of the whole domain, such as robots.txt.","example":["https://peec.ai/blog/ai-search"]}},"required":["id","title","level","level_name","level_question","tier","outcome","reason_label","why","fix","failing_pages"]},"description":"Every check the audit ran, in catalog order."}},"required":["completed_at","level","level_name","level_question","ceiling","ceiling_name","ceiling_question","next_level","checks"]},"latest_run":{"nullable":true,"description":"The domain's newest audit run, to follow one requested with `POST /agent-analytics/readiness/audits`. Null when no audit was ever run for the domain.","type":"object","properties":{"id":{"type":"string","description":"The run's id, as `POST /agent-analytics/readiness/audits` returns it in `run_id`.","example":"0199c3a4-5b6e-7f80-9a1b-2c3d4e5f6a7b"},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"],"description":"`queued` and `running` runs are in progress. Once a run is `completed`, `audit` holds its result.","example":"completed"},"created_at":{"type":"string","description":"When the run was requested, in ISO 8601 (UTC).","example":"2026-10-01T09:28:00.000Z"},"finished_at":{"nullable":true,"description":"When the run completed or failed, in ISO 8601 (UTC). Null while it is in progress.","example":"2026-10-01T09:30:00.000Z","type":"string"},"error":{"nullable":true,"description":"The error code of the run's last failed attempt, such as `execution_failed` or `execution_expired`, or null. A `failed` run always has one.","example":null,"type":"string"}},"required":["id","status","created_at","finished_at","error"]}},"required":["brand","domain","audit","latest_run"]},"description":"Every own brand domain of the project, audited or not. Empty when the project has no own domain."},"competitors":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"object","properties":{"id":{"type":"string","example":"kw_915e742b-396d-4a86-ad57-8bc84e8c2232"},"name":{"type":"string","example":"Acme"}},"required":["id","name"]},"domain":{"type":"string","description":"One of the competitor brand's domains; a brand with several domains appears once per domain.","example":"acme.com"},"audit":{"nullable":true,"description":"The newest audit completed within the last 90 days, or null when the domain has none.","type":"object","properties":{"completed_at":{"type":"string","description":"When the audit finished, in ISO 8601 (UTC).","example":"2026-10-01T09:30:00.000Z"},"level":{"type":"integer","minimum":0,"maximum":5,"description":"The highest level whose gate checks all pass, climbing from level 1. 0 until every level 1 gate passes.","example":2},"level_name":{"type":"string","description":"The name of `level`: 0 Turned away, 1 Reachable, 2 Findable, 3 Readable, 4 Operable, 5 Transactable.","example":"Findable"},"level_question":{"type":"string","description":"The question `level` answers for agents.","example":"Can they find what's there?"},"ceiling":{"type":"integer","minimum":0,"maximum":5,"description":"The highest level this audit can award the site: the top level that has at least one applicable gate check.","example":4},"ceiling_name":{"type":"string","description":"The name of `ceiling`.","example":"Findable"},"ceiling_question":{"type":"string","description":"The question `ceiling` answers for agents.","example":"Can they find what's there?"},"next_level":{"nullable":true,"description":"What stands between the site and the next level. Null when the site is already at its ceiling.","type":"object","properties":{"level":{"type":"integer","minimum":0,"maximum":5,"example":3},"level_name":{"type":"string","description":"The name of the next level.","example":"Findable"},"level_question":{"type":"string","description":"The question the next level answers for agents.","example":"Can they find what's there?"},"passed_gates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Gate checks of the next level that already pass.","example":3},"total_gates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Applicable gate checks of the next level.","example":5},"blocking_check_ids":{"type":"array","items":{"type":"string","enum":["domain.robots_txt","domain.ai_agent_access","domain.sitemap","domain.link_headers","domain.llms_txt","domain.soft_404","domain.content_signals","domain.aipref_content_usage","domain.sitemap_lastmod","domain.llms_full_txt","domain.api_catalog","domain.mcp_server_card","domain.oauth_authorization_server","domain.oauth_protected_resource","domain.a2a_agent_card","domain.agent_skills_index","domain.auth_md","domain.web_bot_auth","domain.ard","domain.ucp","page.md_suffix","page.render_without_javascript","page.navigation_without_javascript","page.markdown_negotiation","page.bot_reachability","page.meta_robots","page.snippet_controls","page.soft_404","page.structured_data","page.organization_schema","page.semantic_landmarks","page.heading_structure","page.document_title","page.language","page.meta_description","page.canonical","page.open_graph","page.image_alt_text","page.descriptive_links","page.editorial_freshness","page.page_type_schema","page.entity_linking"]},"description":"The gate checks that keep the site from the next level. Fix these to level up.","example":["page.structured_data","page.organization_schema"]}},"required":["level","level_name","level_question","passed_gates","total_gates","blocking_check_ids"]},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["domain.robots_txt","domain.ai_agent_access","domain.sitemap","domain.link_headers","domain.llms_txt","domain.soft_404","domain.content_signals","domain.aipref_content_usage","domain.sitemap_lastmod","domain.llms_full_txt","domain.api_catalog","domain.mcp_server_card","domain.oauth_authorization_server","domain.oauth_protected_resource","domain.a2a_agent_card","domain.agent_skills_index","domain.auth_md","domain.web_bot_auth","domain.ard","domain.ucp","page.md_suffix","page.render_without_javascript","page.navigation_without_javascript","page.markdown_negotiation","page.bot_reachability","page.meta_robots","page.snippet_controls","page.soft_404","page.structured_data","page.organization_schema","page.semantic_landmarks","page.heading_structure","page.document_title","page.language","page.meta_description","page.canonical","page.open_graph","page.image_alt_text","page.descriptive_links","page.editorial_freshness","page.page_type_schema","page.entity_linking"],"example":"domain.llms_txt"},"title":{"type":"string","description":"The check's name, as the Peec app shows it.","example":"llms.txt"},"level":{"type":"integer","minimum":0,"maximum":5,"description":"The level this check counts toward.","example":2},"level_name":{"type":"string","description":"The name of the check's level.","example":"Findable"},"level_question":{"type":"string","description":"The question the check's level answers for agents.","example":"Can they find what's there?"},"tier":{"type":"string","enum":["gate","reported","emerging"],"description":"`gate` (Scored): Decides your level. Every scored check at a level has to pass to clear it. `reported` (Optional): Hygiene that doesn't change your level. `emerging` (Optional): A standard few agents use yet. It doesn't change your level.","example":"emerging"},"outcome":{"type":"string","enum":["confirmed","absent","invalid","blocked","inconclusive","not_applicable"],"description":"The check's result across every page it ran on, the most severe one winning. `absent`, `invalid`, and `blocked` need fixing.","example":"absent"},"reason_label":{"type":"string","description":"What the result that decided `outcome` means, in plain language, such as why a file counts as malformed.","example":"The server reported that this resource does not exist."},"why":{"type":"string","description":"Why the check matters to AI agents, written for the check's outcome, such as a missing file versus a malformed one.","example":"A curated index of the pages you'd want an LLM to read first."},"fix":{"type":"string","description":"How to make the check pass from its outcome.","example":"If you keep one, link canonical pages from valid Markdown."},"failing_pages":{"type":"array","items":{"type":"string"},"description":"Up to 5 URLs of pages the check failed on, sorted. Empty when it failed on none, and for checks of the whole domain, such as robots.txt.","example":["https://peec.ai/blog/ai-search"]}},"required":["id","title","level","level_name","level_question","tier","outcome","reason_label","why","fix","failing_pages"]},"description":"Every check the audit ran, in catalog order."}},"required":["completed_at","level","level_name","level_question","ceiling","ceiling_name","ceiling_question","next_level","checks"]}},"required":["brand","domain","audit"]},"description":"Every competitor brand of the project that has a domain, audited or not."}},"required":["own","competitors"],"description":"Success"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"getAgent-analyticsReadiness"}},"/agent-analytics/readiness/audits":{"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Request Agent Readiness Audits","description":"Queue Peec's agent readiness audit for the project's own brand domains. Audits run only on domains of the project's own brands, matched exactly as the brand lists them; any other domain is returned in `rejected` and the rest of the request still goes through. A domain whose audit is already queued or running is returned in `skipped` with that run's id instead of queuing a second one.\n\nAudits run in the background. Follow each one with `GET /agent-analytics/readiness`, where the domain's `latest_run` carries the same id and its status, and read the result there once it is `completed`.","tags":["Agent Analytics"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"domains":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1},"description":"Up to 50 of the project's own brand domains, exactly as `GET /agent-analytics/readiness` lists them in `own`.","example":["peec.ai"]}},"required":["domains"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"domains":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1},"description":"Up to 50 of the project's own brand domains, exactly as `GET /agent-analytics/readiness` lists them in `own`.","example":["peec.ai"]}},"required":["domains"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"domains":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1},"description":"Up to 50 of the project's own brand domains, exactly as `GET /agent-analytics/readiness` lists them in `own`.","example":["peec.ai"]}},"required":["domains"]}}}},"responses":{"200":{"description":"Per-domain results","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","description":"One of the project's own brand domains.","example":"peec.ai"},"run_id":{"type":"string","description":"The id of the audit run serving this request.","example":"0199c3a4-5b6e-7f80-9a1b-2c3d4e5f6a7b"}},"required":["domain","run_id"]},"description":"Domains a new audit was queued for."},"skipped":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","description":"One of the project's own brand domains.","example":"peec.ai"},"run_id":{"type":"string","description":"The id of the audit run serving this request.","example":"0199c3a4-5b6e-7f80-9a1b-2c3d4e5f6a7b"},"reason":{"type":"string","enum":["in_progress"]}},"required":["domain","run_id","reason"]},"description":"Domains with an audit already queued or running. No new audit is queued; `run_id` is the one in progress."},"rejected":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","example":"acme.com"},"reason":{"type":"string","enum":["not_own_domain","duplicate"]},"message":{"type":"string"}},"required":["domain","reason","message"]},"description":"Domains not audited: `not_own_domain` for a domain that isn't one of the project's own brand domains, `duplicate` for a repeat within the request."}},"required":["created","skipped","rejected"],"description":"Per-domain results"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postAgent-analyticsReadinessAudits"}},"/agent-analytics/google-analytics/referrals":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get AI Referrals","description":"AI-referral traffic from the project's connected Google Analytics property, scoped to the hosts the project owns and to referrals from AI assistants. There is no way to ask this endpoint for non-AI traffic.\n\nTo list the values a dimension takes, pass it as the only `group_by` and read the rows — that is how you discover event names, countries, pages and the assistants that actually sent traffic. When populating a filter, do not filter by the dimension you are listing, or the options the user has not already picked disappear.\n\nMetric definitions, because the names are shorter than the meanings:\n- `events`: GA4 event count.\n- `session_starts`: GA4 `session_start` events, which is not GA4's `sessions` metric. Most are visits that entered on the site; the rest resumed there after idling past GA4's session timeout. It cannot be combined with `group_by=event_name`.\n- `conversions`: GA4 key events, so one visit can contribute several, and which events count follows whatever the property marked as a key event.\n- `revenue`: GA4 purchase revenue in the property's reporting currency, returned as `currency`.\n\nUnknown dimension values come back as `(not set)`. It is a real row, and the free-string filters (`sources`, `devices`, `event_names`, `mediums`) accept it back; `countries` does not, because it takes ISO codes only. Figures are a lower bound on AI referrals: only referrer-visible traffic reaches GA4, so native apps and no-referrer policies land as Direct, and Gemini is often folded into Organic Search.","tags":["Agent Analytics"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"start_date","in":"query","required":true,"schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"Inclusive bound, as full-date notation per RFC 3339 section 5.6. Required. A range spans at most 366 days.","example":"2026-09-22"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"Inclusive bound, as full-date notation per RFC 3339 section 5.6. Required. A range spans at most 366 days.","example":"2026-09-22"}},{"name":"group_by","in":"query","required":false,"schema":{"description":"Dimension(s) to break the numbers down by, at most 3. Omit for period totals only. Pass a single dimension to list the values it takes.","example":["assistant"],"type":"array","items":{"type":"string","enum":["assistant","platform","source","medium","country","device","event_name","landing_page","page_path","host"]}}},{"name":"metrics","in":"query","required":false,"schema":{"description":"Metrics to return. Defaults to all of them, minus session_starts when grouping by event_name. Unrequested metrics are left out of the query.","example":["session_starts","conversions"],"type":"array","items":{"type":"string","enum":["events","session_starts","conversions","revenue"]}}},{"name":"time_bucket","in":"query","required":false,"schema":{"description":"Adds a time_bucket column holding the bucket's start date. There is no hourly bucket: the source data is daily. Buckets at either end of the range cover only the days inside it.","example":"week","type":"string","enum":["day","week","month"]}},{"name":"assistants","in":"query","required":false,"schema":{"description":"Filter by assistant display name. An unrecognised name is rejected rather than ignored.","example":["ChatGPT"],"type":"array","items":{"type":"string"}}},{"name":"sources","in":"query","required":false,"schema":{"description":"Filter by raw GA4 sessionSource host.","example":["chatgpt.com"],"type":"array","items":{"type":"string"}}},{"name":"countries","in":"query","required":false,"schema":{"description":"Filter by ISO 3166-1 alpha-2 country code.","example":["DE"],"type":"array","items":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]}}},{"name":"mediums","in":"query","required":false,"schema":{"description":"Filter by GA4 session medium. Use `ai-assistant` to isolate traffic identified by medium rather than by a known referrer host.","example":["ai-assistant"],"type":"array","items":{"type":"string"}}},{"name":"devices","in":"query","required":false,"schema":{"description":"Filter by device category. Property-specific and case-sensitive: an unmatched value yields zeros rather than an error.","example":["mobile"],"type":"array","items":{"type":"string"}}},{"name":"event_names","in":"query","required":false,"schema":{"description":"Filter by GA4 event name. Property-specific: a name this property never sends yields zeros rather than an error, so discover them with `group_by=event_name` first.","example":["purchase"],"type":"array","items":{"type":"string"}}},{"name":"order_by","in":"query","required":false,"schema":{"description":"Field to sort by, which must be one of the requested metrics (or time_bucket when it is set). Defaults to the first requested metric.","example":"session_starts","type":"string","enum":["events","session_starts","conversions","revenue","time_bucket"]}},{"name":"order_direction","in":"query","required":false,"schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"include_total_count","in":"query","required":false,"schema":{"description":"Set false to skip total_count. Counting is a second pass over the same rows, so it doubles the cost of the call.","example":"false","default":"true","type":"string","enum":["true","false"]}},{"name":"limit","in":"query","required":false,"schema":{"default":100,"type":"integer","minimum":1,"maximum":1000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"assistant":{"example":"ChatGPT","type":"string"},"platform":{"example":"OpenAI","type":"string"},"source":{"example":"chatgpt.com","type":"string"},"medium":{"example":"referral","type":"string"},"country":{"example":"DE","type":"string"},"device":{"example":"mobile","type":"string"},"event_name":{"example":"page_view","type":"string"},"landing_page":{"description":"The session's entry page, repeated on every event in that session. Query string stripped.","example":"/pricing","type":"string"},"page_path":{"description":"The page the event fired on. Query string stripped and UUIDs collapsed to `*`, so it does not join to landing_page.","example":"/blog/*/overview","type":"string"},"host":{"example":"www.example.com","type":"string"},"time_bucket":{"description":"First day of the bucket this row covers, always a plain date. Present only when the `time_bucket` request parameter was set, which names the width rather than a date.","example":"2026-03-01","type":"string"},"events":{"example":4820,"type":"number"},"session_starts":{"example":1402,"type":"number"},"conversions":{"example":37,"type":"number"},"revenue":{"example":4210.5,"type":"number"}}}},"columns":{"type":"array","items":{"type":"string"},"description":"Column order for the rows, derived from the request so a zero-row answer still carries its shape.","example":["assistant","session_starts"]},"total_count":{"nullable":true,"description":"Number of grouped rows the filters match — not a sum of any metric. Null when include_total_count was false.","example":12,"type":"number"},"currency":{"nullable":true,"description":"Reporting currency of `revenue`, null when revenue was not requested. Values are not converted, so revenue is not comparable across projects.","example":"EUR","type":"string"}},"required":["data","columns","total_count","currency"],"description":"Success"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"getAgent-analyticsGoogle-analyticsReferrals"}},"/agent-analytics/google-analytics/list-referral-sources":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Referral Sources","description":"Every AI assistant Peec can attribute referral traffic to, whether or not this project has seen traffic from it — one row per referrer host, so an assistant reachable on several hosts appears once per host. Use `assistant` for the `assistants` filter on the referrals endpoint, and `source` to recognise a raw host in its results. The list is maintained by hand and reviewed quarterly, so a brand-new assistant may be missing.","tags":["Agent Analytics"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","description":"The GA4 sessionSource host, as it appears in results.","example":"chatgpt.com"},"assistant":{"type":"string","example":"ChatGPT"},"platform":{"type":"string","example":"OpenAI"}},"required":["source","assistant","platform"]}},"total_count":{"type":"number","example":78}},"required":["data","total_count"],"description":"Success"}}}}},"operationId":"getAgent-analyticsGoogle-analyticsList-referral-sources"}},"/chats":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Chats","description":"List the chats of a project","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"start_date","in":"query","required":false,"schema":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"end_date","in":"query","required":false,"schema":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"brand_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"prompt_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"model_id","in":"query","required":false,"schema":{"deprecated":true,"description":"Deprecated: use model_channel_id instead","type":"string","enum":["chatgpt-scraper","gpt-4o","gpt-4o-search","gpt-3.5-turbo","llama-sonar","perplexity-scraper","sonar","gemini-2.5-flash","gemini-3.1-flash-lite-search","gemini-scraper","google-ai-overview-scraper","google-ai-mode-scraper","llama-3.3-70b-instruct","deepseek-r1","deepseek-v4-pro","claude-3.5-haiku","claude-haiku-4.5","claude-sonnet-4","grok-scraper","microsoft-copilot-scraper","grok-4","grok-4.3","grok-4.6","qwen-3-6-plus","qwen-3-7-plus","amazon-rufus-scraper","mistral-small-4","mistral-medium-3-5","muse-spark-1.2","muse-spark-1.3","muse-wonder-1.0","gemini-4-argon","naver-ai-briefing-scraper","claude-opus-5","claude-fable-5.1","gpt-6-astra","gpt-5.6-sol","gpt-5.6-terra","ernie-scraper"]}},{"name":"model_channel_id","in":"query","required":false,"schema":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},{"name":"features","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["SHOPPING","PRODUCT_COMPARISON","AD","MAP","WEB_SEARCH","LINKS","CHART"]}}},{"name":"include_archived_prompts","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"default":"asc","description":"Sort order by chat creation time. Defaults to asc (oldest first); use desc to get the most recent chats first.","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"ch_61184892-36ad-4e1a-8178-3a83608f7711"},"prompt":{"type":"object","properties":{"id":{"type":"string","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d"}},"required":["id"]},"model":{"type":"object","properties":{"id":{"type":"string","example":"gpt-4o-search"}},"required":["id"],"deprecated":true,"description":"Deprecated: use model_channel instead"},"model_channel":{"type":"object","properties":{"id":{"type":"string","example":"openai-1"}},"required":["id"]},"date":{"type":"string","example":"2025-09-17"},"features":{"type":"array","items":{"type":"string","enum":["SHOPPING","PRODUCT_COMPARISON","AD","MAP","WEB_SEARCH","LINKS","CHART"]}}},"required":["id","prompt","model","model_channel","date"]}},"total_count":{"type":"number","example":42,"description":"Total number of matching chats, ignoring pagination"},"totalCount":{"type":"number","example":42,"description":"Total number of matching chats, ignoring pagination","deprecated":true}},"required":["data","total_count","totalCount"],"description":"Success"}}}}},"operationId":"getChats"}},"/chats/{chat_id}/content":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Chat","description":"Get a single chat","tags":["Project"],"parameters":[{"name":"chat_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"ch_61184892-36ad-4e1a-8178-3a83608f7711"},"prompt":{"type":"object","properties":{"id":{"type":"string","example":"pr_93f790de-5b7a-45ee-b782-61103c81f20d"}},"required":["id"]},"model":{"type":"object","properties":{"id":{"type":"string","example":"gpt-4o-search"}},"required":["id"],"deprecated":true,"description":"Deprecated: use model_channel instead"},"model_channel":{"type":"object","properties":{"id":{"type":"string","example":"openai-1"}},"required":["id"]},"sources":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","example":"https://peec.ai/blog#header"},"url_normalized":{"nullable":true,"example":"peec.ai/blog","type":"string"},"urlNormalized":{"nullable":true,"example":"peec.ai/blog","deprecated":true,"type":"string"},"domain":{"type":"string","example":"peec.ai"},"citation_count":{"type":"number"},"citationCount":{"type":"number","deprecated":true},"citation_position":{"type":"number"},"citationPosition":{"type":"number","deprecated":true}},"required":["url","url_normalized","urlNormalized","domain","citation_count","citationCount","citation_position","citationPosition"]}},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","example":"https://www.acme.com/"},"url_normalized":{"nullable":true,"example":"acme.com","type":"string"},"domain":{"type":"string","example":"acme.com"},"text":{"type":"string","description":"The words the answer linked, at the first link.","example":"Acme"},"link_count":{"type":"number","description":"How many times the answer linked this URL."},"link_position":{"type":"number","description":"1-based order of the URL's first link in the answer."}},"required":["url","url_normalized","domain","text","link_count","link_position"]},"description":"URLs the answer wrote into its own text, in order of first appearance. A link is never also one of `sources`."},"brands_mentioned":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"kw_915e742b-396d-4a86-ad57-8bc84e8c2232"},"name":{"type":"string","example":"Peec AI"},"position":{"type":"number"}},"required":["id","name","position"]}},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"}},"required":["role","content"]},"example":[{"role":"user","content":"Example Prompt"},{"role":"assistant","content":"Example Response"}]},"queries":{"type":"array","items":{"type":"string","example":"best AI search tools 2026"}},"products":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Peec AI Pro"},"queries":{"type":"array","items":{"type":"string","example":"buy Peec AI Pro online"}}},"required":["name","queries"]}},"features":{"type":"array","items":{"type":"string","enum":["SHOPPING","PRODUCT_COMPARISON","AD","MAP","WEB_SEARCH","LINKS","CHART"]}},"maps":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"J&F Drainage"},"url":{"example":"https://www.google.com/maps/dir/?api=1&destination=53.850994%2C-3.009608","type":"string"}},"required":["name"]}},"ads":{"type":"array","items":{"type":"object","properties":{"brand_name":{"type":"string","example":"Whoop"},"brandName":{"type":"string","example":"Whoop","deprecated":true},"url":{"type":"string","example":"https://www.whoop.com/"},"id":{"example":"697cd903185c819684793d8936700e6f","type":"string"},"ad_unit_type":{"example":"single_advertiser_ad_unit","type":"string"},"adUnitType":{"example":"single_advertiser_ad_unit","deprecated":true,"type":"string"},"ads_request_id":{"example":"069eb308-ae3b-7ae5-8000-641914dcb9b0","type":"string"},"adsRequestId":{"example":"069eb308-ae3b-7ae5-8000-641914dcb9b0","deprecated":true,"type":"string"},"cards":{"type":"array","items":{"type":"object","properties":{"title":{"example":"Win Your Routine","type":"string"},"body":{"example":"Daily guidance for your goals","type":"string"},"image_url":{"example":"https://bzrcdn.openai.com/<hash>.png","type":"string"},"imageUrl":{"example":"https://bzrcdn.openai.com/<hash>.png","deprecated":true,"type":"string"},"target_url":{"example":"https://join.whoop.com/chatgpt4/?utm_source=chatgpt&utm_medium=cpc","type":"string"},"targetUrl":{"deprecated":true,"example":"https://join.whoop.com/chatgpt4/?utm_source=chatgpt&utm_medium=cpc","type":"string"}}}}},"required":["brand_name","brandName","url","cards"]}}},"required":["id","prompt","model","model_channel","sources","links","brands_mentioned","messages","queries","products","features","maps","ads"],"description":"Success"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"getChatsByChat_idContent"}},"/project-profile":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Get Project Profile","description":"Read the project's brand profile (description, industry, brand identity, target markets, audience distribution, products & services). Returns `{ profile: null }` if the project hasn't been profiled yet.","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}}],"responses":{"200":{"description":"Project profile fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"nullable":true,"type":"object","properties":{"name":{"type":"string"},"occupation":{"type":"string","minLength":1},"industry":{"type":"string","minLength":1},"brand_presentation":{"minItems":1,"type":"array","items":{"type":"string","minLength":1}},"products_and_services":{"minItems":1,"type":"array","items":{"type":"string","minLength":1}},"target_markets":{"minItems":1,"type":"array","items":{"type":"object","properties":{"market_size":{"type":"string","enum":["Neighborhood","City","State/Province","National","Continental Bloc","Global"]},"location":{"type":"string","minLength":1},"osm_id":{"type":"string"}},"required":["market_size","location"]}},"audience_distribution":{"type":"object","properties":{"simple_recommendation_seeker":{"type":"integer","minimum":0,"maximum":9007199254740991},"informed_shopper":{"type":"integer","minimum":0,"maximum":9007199254740991},"evaluative_researcher":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["simple_recommendation_seeker","informed_shopper","evaluative_researcher"]},"personas":{"description":"The audience segments prompts are written from the perspective of.","type":"array","items":{"type":"string"}},"used_prepared_profile":{"type":"boolean"},"brandPresentation":{"minItems":1,"type":"array","items":{"type":"string","minLength":1},"deprecated":true},"productsAndServices":{"minItems":1,"type":"array","items":{"type":"string","minLength":1},"deprecated":true},"prompt_builder":{"type":"object","properties":{"markets":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]},"language":{"type":"string","enum":["ar","az","bg","bn","bs","cs","da","de","el","en","es","et","fi","fr","he","hi","hr","hu","hy","id","it","ja","ko","lt","lv","mk","mn","ms","no","nl","pl","pt","ro","ru","sk","sl","sq","sr","sv","th","tl","tr","uk","ur","vi","zh"]}},"required":["country","language"]}},"distribution":{"type":"object","properties":{"branding":{"type":"object","additionalProperties":{"type":"number"},"required":["branded","non-branded"]},"intent":{"type":"object","additionalProperties":{"type":"number"},"required":["informational","commercial","transactional"]},"additional_context":{"description":"Free-text steer on how the branding and intent split is applied. Scoped to this distribution.","type":"string"}},"required":["branding","intent"]},"additional_context":{"description":"Free-text context about the project, applied to every generated prompt whatever the distribution.","type":"string"}}},"targetMarkets":{"minItems":1,"type":"array","items":{"type":"object","properties":{"marketSize":{"type":"string","enum":["Neighborhood","City","State/Province","National","Continental Bloc","Global"]},"location":{"type":"string","minLength":1},"osmId":{"type":"string"}},"required":["marketSize","location"]},"deprecated":true},"audienceDistribution":{"type":"object","properties":{"simpleRecommendationSeeker":{"type":"integer","minimum":0,"maximum":9007199254740991},"informedShopper":{"type":"integer","minimum":0,"maximum":9007199254740991},"evaluativeResearcher":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["simpleRecommendationSeeker","informedShopper","evaluativeResearcher"],"deprecated":true},"usedPreparedProfile":{"deprecated":true,"type":"boolean"}},"required":["name","occupation","industry","brand_presentation","products_and_services","target_markets","audience_distribution","brandPresentation","productsAndServices","targetMarkets","audienceDistribution"]}},"required":["profile"],"description":"Project profile fetched successfully"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"getProject-profile"},"put":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Set Project Profile","description":"Replace the project's brand profile. All fields are required — the entire profile is overwritten. Triggers a background refresh of prompt suggestions. Audience distribution percentages must sum to 100. The project's display name is not part of the profile and cannot be changed via this endpoint. Returns 403 while the project is in onboarding.","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"occupation":{"type":"string","minLength":1,"description":"The role or perspective the profile speaks from, e.g. 'Founder'."},"industry":{"type":"string","minLength":1,"description":"The industry the brand operates in, e.g. 'SaaS'."},"brand_presentation":{"description":"Short statements describing how the brand presents itself, e.g. [\"Premium eco-friendly cleaning products\"].","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"brandPresentation":{"deprecated":true,"description":"Deprecated camelCase alias of brand_presentation, e.g. [\"Premium eco-friendly cleaning products\"].","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"products_and_services":{"description":"The products and services the brand offers, e.g. [\"CRM software\",\"Analytics dashboard\"].","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"productsAndServices":{"deprecated":true,"description":"Deprecated camelCase alias of products_and_services, e.g. [\"CRM software\",\"Analytics dashboard\"].","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"target_markets":{"description":"The geographic markets the brand targets, e.g. [{\"market_size\":\"National\",\"location\":\"United States\"}].","minItems":1,"type":"array","items":{"type":"object","properties":{"market_size":{"type":"string","enum":["Neighborhood","City","State/Province","National","Continental Bloc","Global"]},"marketSize":{"deprecated":true,"type":"string","enum":["Neighborhood","City","State/Province","National","Continental Bloc","Global"]},"location":{"type":"string","minLength":1},"osm_id":{"type":"string"},"osmId":{"deprecated":true,"type":"string"}},"required":["location"]}},"targetMarkets":{"deprecated":true,"description":"Deprecated camelCase alias of target_markets, e.g. [{\"marketSize\":\"National\",\"location\":\"United States\"}].","minItems":1,"type":"array","items":{"type":"object","properties":{"market_size":{"type":"string","enum":["Neighborhood","City","State/Province","National","Continental Bloc","Global"]},"marketSize":{"deprecated":true,"type":"string","enum":["Neighborhood","City","State/Province","National","Continental Bloc","Global"]},"location":{"type":"string","minLength":1},"osm_id":{"type":"string"},"osmId":{"deprecated":true,"type":"string"}},"required":["location"]}},"audience_distribution":{"description":"Percentage split of the audience across buyer types (must sum to 100), e.g. {\"simple_recommendation_seeker\":40,\"informed_shopper\":40,\"evaluative_researcher\":20}.","type":"object","properties":{"simple_recommendation_seeker":{"type":"integer","minimum":0,"maximum":9007199254740991},"simpleRecommendationSeeker":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991},"informed_shopper":{"type":"integer","minimum":0,"maximum":9007199254740991},"informedShopper":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991},"evaluative_researcher":{"type":"integer","minimum":0,"maximum":9007199254740991},"evaluativeResearcher":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991}}},"audienceDistribution":{"deprecated":true,"description":"Deprecated camelCase alias of audience_distribution (must sum to 100), e.g. {\"simpleRecommendationSeeker\":40,\"informedShopper\":40,\"evaluativeResearcher\":20}.","type":"object","properties":{"simple_recommendation_seeker":{"type":"integer","minimum":0,"maximum":9007199254740991},"simpleRecommendationSeeker":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991},"informed_shopper":{"type":"integer","minimum":0,"maximum":9007199254740991},"informedShopper":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991},"evaluative_researcher":{"type":"integer","minimum":0,"maximum":9007199254740991},"evaluativeResearcher":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991}}},"personas":{"description":"The audience segments prompts are written from the perspective of, e.g. [\"Marketing lead\",\"Procurement manager\"]. Omit to leave the project's existing personas untouched.","type":"array","items":{"type":"string","minLength":1}},"prompt_builder":{"type":"object","properties":{"markets":{"description":"Country and language pairs the prompt builder generates for, e.g. [{\"country\":\"US\",\"language\":\"en\"}].","minItems":1,"type":"array","items":{"type":"object","properties":{"country":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]},"language":{"type":"string","enum":["ar","az","bg","bn","bs","cs","da","de","el","en","es","et","fi","fr","he","hi","hr","hu","hy","id","it","ja","ko","lt","lv","mk","mn","ms","no","nl","pl","pt","ro","ru","sk","sl","sq","sr","sv","th","tl","tr","uk","ur","vi","zh"]}},"required":["country","language"]}},"distribution":{"description":"How the prompt builder splits generated prompts across branding and intent.","type":"object","properties":{"branding":{"type":"object","additionalProperties":{"type":"integer","minimum":0,"maximum":100},"required":["branded","non-branded"],"description":"Share of generated prompts that name the brand, e.g. {\"branded\":30,\"non-branded\":70}."},"intent":{"type":"object","additionalProperties":{"type":"integer","minimum":0,"maximum":100},"required":["informational","commercial","transactional"],"description":"Share of generated prompts per buyer intent, e.g. {\"informational\":50,\"commercial\":30,\"transactional\":20}."},"additional_context":{"description":"Free-text steer applied to the generated distribution.","type":"string","maxLength":200}},"required":["branding","intent"]},"additional_context":{"description":"Free-text context about the project that shapes prompt generation.","type":"string"}},"description":"Prompt generation settings."}},"required":["occupation","industry"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"occupation":{"type":"string","minLength":1,"description":"The role or perspective the profile speaks from, e.g. 'Founder'."},"industry":{"type":"string","minLength":1,"description":"The industry the brand operates in, e.g. 'SaaS'."},"brand_presentation":{"description":"Short statements describing how the brand presents itself, e.g. [\"Premium eco-friendly cleaning products\"].","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"brandPresentation":{"deprecated":true,"description":"Deprecated camelCase alias of brand_presentation, e.g. [\"Premium eco-friendly cleaning products\"].","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"products_and_services":{"description":"The products and services the brand offers, e.g. [\"CRM software\",\"Analytics dashboard\"].","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"productsAndServices":{"deprecated":true,"description":"Deprecated camelCase alias of products_and_services, e.g. [\"CRM software\",\"Analytics dashboard\"].","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"target_markets":{"description":"The geographic markets the brand targets, e.g. [{\"market_size\":\"National\",\"location\":\"United States\"}].","minItems":1,"type":"array","items":{"type":"object","properties":{"market_size":{"type":"string","enum":["Neighborhood","City","State/Province","National","Continental Bloc","Global"]},"marketSize":{"deprecated":true,"type":"string","enum":["Neighborhood","City","State/Province","National","Continental Bloc","Global"]},"location":{"type":"string","minLength":1},"osm_id":{"type":"string"},"osmId":{"deprecated":true,"type":"string"}},"required":["location"]}},"targetMarkets":{"deprecated":true,"description":"Deprecated camelCase alias of target_markets, e.g. [{\"marketSize\":\"National\",\"location\":\"United States\"}].","minItems":1,"type":"array","items":{"type":"object","properties":{"market_size":{"type":"string","enum":["Neighborhood","City","State/Province","National","Continental Bloc","Global"]},"marketSize":{"deprecated":true,"type":"string","enum":["Neighborhood","City","State/Province","National","Continental Bloc","Global"]},"location":{"type":"string","minLength":1},"osm_id":{"type":"string"},"osmId":{"deprecated":true,"type":"string"}},"required":["location"]}},"audience_distribution":{"description":"Percentage split of the audience across buyer types (must sum to 100), e.g. {\"simple_recommendation_seeker\":40,\"informed_shopper\":40,\"evaluative_researcher\":20}.","type":"object","properties":{"simple_recommendation_seeker":{"type":"integer","minimum":0,"maximum":9007199254740991},"simpleRecommendationSeeker":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991},"informed_shopper":{"type":"integer","minimum":0,"maximum":9007199254740991},"informedShopper":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991},"evaluative_researcher":{"type":"integer","minimum":0,"maximum":9007199254740991},"evaluativeResearcher":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991}}},"audienceDistribution":{"deprecated":true,"description":"Deprecated camelCase alias of audience_distribution (must sum to 100), e.g. {\"simpleRecommendationSeeker\":40,\"informedShopper\":40,\"evaluativeResearcher\":20}.","type":"object","properties":{"simple_recommendation_seeker":{"type":"integer","minimum":0,"maximum":9007199254740991},"simpleRecommendationSeeker":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991},"informed_shopper":{"type":"integer","minimum":0,"maximum":9007199254740991},"informedShopper":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991},"evaluative_researcher":{"type":"integer","minimum":0,"maximum":9007199254740991},"evaluativeResearcher":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991}}},"personas":{"description":"The audience segments prompts are written from the perspective of, e.g. [\"Marketing lead\",\"Procurement manager\"]. Omit to leave the project's existing personas untouched.","type":"array","items":{"type":"string","minLength":1}},"prompt_builder":{"type":"object","properties":{"markets":{"description":"Country and language pairs the prompt builder generates for, e.g. [{\"country\":\"US\",\"language\":\"en\"}].","minItems":1,"type":"array","items":{"type":"object","properties":{"country":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]},"language":{"type":"string","enum":["ar","az","bg","bn","bs","cs","da","de","el","en","es","et","fi","fr","he","hi","hr","hu","hy","id","it","ja","ko","lt","lv","mk","mn","ms","no","nl","pl","pt","ro","ru","sk","sl","sq","sr","sv","th","tl","tr","uk","ur","vi","zh"]}},"required":["country","language"]}},"distribution":{"description":"How the prompt builder splits generated prompts across branding and intent.","type":"object","properties":{"branding":{"type":"object","additionalProperties":{"type":"integer","minimum":0,"maximum":100},"required":["branded","non-branded"],"description":"Share of generated prompts that name the brand, e.g. {\"branded\":30,\"non-branded\":70}."},"intent":{"type":"object","additionalProperties":{"type":"integer","minimum":0,"maximum":100},"required":["informational","commercial","transactional"],"description":"Share of generated prompts per buyer intent, e.g. {\"informational\":50,\"commercial\":30,\"transactional\":20}."},"additional_context":{"description":"Free-text steer applied to the generated distribution.","type":"string","maxLength":200}},"required":["branding","intent"]},"additional_context":{"description":"Free-text context about the project that shapes prompt generation.","type":"string"}},"description":"Prompt generation settings."}},"required":["occupation","industry"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"occupation":{"type":"string","minLength":1,"description":"The role or perspective the profile speaks from, e.g. 'Founder'."},"industry":{"type":"string","minLength":1,"description":"The industry the brand operates in, e.g. 'SaaS'."},"brand_presentation":{"description":"Short statements describing how the brand presents itself, e.g. [\"Premium eco-friendly cleaning products\"].","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"brandPresentation":{"deprecated":true,"description":"Deprecated camelCase alias of brand_presentation, e.g. [\"Premium eco-friendly cleaning products\"].","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"products_and_services":{"description":"The products and services the brand offers, e.g. [\"CRM software\",\"Analytics dashboard\"].","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"productsAndServices":{"deprecated":true,"description":"Deprecated camelCase alias of products_and_services, e.g. [\"CRM software\",\"Analytics dashboard\"].","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"target_markets":{"description":"The geographic markets the brand targets, e.g. [{\"market_size\":\"National\",\"location\":\"United States\"}].","minItems":1,"type":"array","items":{"type":"object","properties":{"market_size":{"type":"string","enum":["Neighborhood","City","State/Province","National","Continental Bloc","Global"]},"marketSize":{"deprecated":true,"type":"string","enum":["Neighborhood","City","State/Province","National","Continental Bloc","Global"]},"location":{"type":"string","minLength":1},"osm_id":{"type":"string"},"osmId":{"deprecated":true,"type":"string"}},"required":["location"]}},"targetMarkets":{"deprecated":true,"description":"Deprecated camelCase alias of target_markets, e.g. [{\"marketSize\":\"National\",\"location\":\"United States\"}].","minItems":1,"type":"array","items":{"type":"object","properties":{"market_size":{"type":"string","enum":["Neighborhood","City","State/Province","National","Continental Bloc","Global"]},"marketSize":{"deprecated":true,"type":"string","enum":["Neighborhood","City","State/Province","National","Continental Bloc","Global"]},"location":{"type":"string","minLength":1},"osm_id":{"type":"string"},"osmId":{"deprecated":true,"type":"string"}},"required":["location"]}},"audience_distribution":{"description":"Percentage split of the audience across buyer types (must sum to 100), e.g. {\"simple_recommendation_seeker\":40,\"informed_shopper\":40,\"evaluative_researcher\":20}.","type":"object","properties":{"simple_recommendation_seeker":{"type":"integer","minimum":0,"maximum":9007199254740991},"simpleRecommendationSeeker":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991},"informed_shopper":{"type":"integer","minimum":0,"maximum":9007199254740991},"informedShopper":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991},"evaluative_researcher":{"type":"integer","minimum":0,"maximum":9007199254740991},"evaluativeResearcher":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991}}},"audienceDistribution":{"deprecated":true,"description":"Deprecated camelCase alias of audience_distribution (must sum to 100), e.g. {\"simpleRecommendationSeeker\":40,\"informedShopper\":40,\"evaluativeResearcher\":20}.","type":"object","properties":{"simple_recommendation_seeker":{"type":"integer","minimum":0,"maximum":9007199254740991},"simpleRecommendationSeeker":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991},"informed_shopper":{"type":"integer","minimum":0,"maximum":9007199254740991},"informedShopper":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991},"evaluative_researcher":{"type":"integer","minimum":0,"maximum":9007199254740991},"evaluativeResearcher":{"deprecated":true,"type":"integer","minimum":0,"maximum":9007199254740991}}},"personas":{"description":"The audience segments prompts are written from the perspective of, e.g. [\"Marketing lead\",\"Procurement manager\"]. Omit to leave the project's existing personas untouched.","type":"array","items":{"type":"string","minLength":1}},"prompt_builder":{"type":"object","properties":{"markets":{"description":"Country and language pairs the prompt builder generates for, e.g. [{\"country\":\"US\",\"language\":\"en\"}].","minItems":1,"type":"array","items":{"type":"object","properties":{"country":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]},"language":{"type":"string","enum":["ar","az","bg","bn","bs","cs","da","de","el","en","es","et","fi","fr","he","hi","hr","hu","hy","id","it","ja","ko","lt","lv","mk","mn","ms","no","nl","pl","pt","ro","ru","sk","sl","sq","sr","sv","th","tl","tr","uk","ur","vi","zh"]}},"required":["country","language"]}},"distribution":{"description":"How the prompt builder splits generated prompts across branding and intent.","type":"object","properties":{"branding":{"type":"object","additionalProperties":{"type":"integer","minimum":0,"maximum":100},"required":["branded","non-branded"],"description":"Share of generated prompts that name the brand, e.g. {\"branded\":30,\"non-branded\":70}."},"intent":{"type":"object","additionalProperties":{"type":"integer","minimum":0,"maximum":100},"required":["informational","commercial","transactional"],"description":"Share of generated prompts per buyer intent, e.g. {\"informational\":50,\"commercial\":30,\"transactional\":20}."},"additional_context":{"description":"Free-text steer applied to the generated distribution.","type":"string","maxLength":200}},"required":["branding","intent"]},"additional_context":{"description":"Free-text context about the project that shapes prompt generation.","type":"string"}},"description":"Prompt generation settings."}},"required":["occupation","industry"]}}}},"responses":{"200":{"description":"Project profile set successfully","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Project profile set successfully"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"putProject-profile"}},"/classifications/domains":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Custom Domain Classifications","description":"List the custom domain classifications defined for a project. These complement the built-in classifications and can be assigned to domains.","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Industry Blog"},"color":{"type":"string","example":"orange"}},"required":["name","color"]}},"total_count":{"type":"number","example":5,"description":"Total number of matching custom domain classifications, ignoring pagination"},"totalCount":{"type":"number","example":5,"description":"Total number of matching custom domain classifications, ignoring pagination","deprecated":true}},"required":["data","total_count","totalCount"],"description":"Success"}}}}},"operationId":"getClassificationsDomains"},"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Create Custom Domain Classification","description":"Define a new custom domain classification for a project. Once created, it can be assigned to domains via the assignment endpoint.","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"name":{"type":"string","minLength":1,"maxLength":60},"color":{"default":"orange","example":"orange","type":"string","enum":["orange","red","amber","yellow","lime","green","emerald","teal","cyan","sky","blue","indigo","violet","purple","fuchsia","pink","rose","gray"]}},"required":["name"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"name":{"type":"string","minLength":1,"maxLength":60},"color":{"default":"orange","example":"orange","type":"string","enum":["orange","red","amber","yellow","lime","green","emerald","teal","cyan","sky","blue","indigo","violet","purple","fuchsia","pink","rose","gray"]}},"required":["name"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"name":{"type":"string","minLength":1,"maxLength":60},"color":{"default":"orange","example":"orange","type":"string","enum":["orange","red","amber","yellow","lime","green","emerald","teal","cyan","sky","blue","indigo","violet","purple","fuchsia","pink","rose","gray"]}},"required":["name"]}}}},"responses":{"201":{"description":"Custom domain classification created","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"}},"required":["name","color"],"description":"Custom domain classification created"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postClassificationsDomains"},"delete":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Delete Custom Domain Classification","description":"Delete a custom domain classification. Cascades through the override table, so any domains currently assigned this classification fall back to their heuristic classification.","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"name":{"type":"string","minLength":1,"maxLength":60}},"required":["name"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"name":{"type":"string","minLength":1,"maxLength":60}},"required":["name"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"name":{"type":"string","minLength":1,"maxLength":60}},"required":["name"]}}}},"responses":{"200":{"description":"Custom domain classification deleted","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Custom domain classification deleted"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"deleteClassificationsDomains"}},"/classifications/domain-assignments":{"put":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Set Domain Classification","description":"Assign a built-in or custom classification to a domain (overriding any heuristic classification), or clear the assignment by passing null.","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"domain":{"type":"string","minLength":1,"description":"Domain to classify (any host or apex — the override applies at apex granularity)"},"classification":{"nullable":true,"description":"Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or the name of a custom domain classification. Pass null to clear the assignment.","type":"string","minLength":1,"maxLength":60}},"required":["domain","classification"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"domain":{"type":"string","minLength":1,"description":"Domain to classify (any host or apex — the override applies at apex granularity)"},"classification":{"nullable":true,"description":"Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or the name of a custom domain classification. Pass null to clear the assignment.","type":"string","minLength":1,"maxLength":60}},"required":["domain","classification"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"domain":{"type":"string","minLength":1,"description":"Domain to classify (any host or apex — the override applies at apex granularity)"},"classification":{"nullable":true,"description":"Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or the name of a custom domain classification. Pass null to clear the assignment.","type":"string","minLength":1,"maxLength":60}},"required":["domain","classification"]}}}},"responses":{"200":{"description":"Domain classification assignment updated","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Domain classification assignment updated"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"putClassificationsDomain-assignments"}},"/classifications/urls":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Custom URL Classifications","description":"List the custom URL classifications defined for a project. These complement the built-in classifications and can be assigned to URLs.","tags":["Project"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Tutorial"},"color":{"type":"string","example":"orange"}},"required":["name","color"]}},"total_count":{"type":"number","example":5,"description":"Total number of matching custom URL classifications, ignoring pagination"},"totalCount":{"type":"number","example":5,"description":"Total number of matching custom URL classifications, ignoring pagination","deprecated":true}},"required":["data","total_count","totalCount"],"description":"Success"}}}}},"operationId":"getClassificationsUrls"},"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Create Custom URL Classification","description":"Define a new custom URL classification for a project. Once created, it can be assigned to URLs via the assignment endpoint.","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"name":{"type":"string","minLength":1,"maxLength":60},"color":{"default":"orange","example":"orange","type":"string","enum":["orange","red","amber","yellow","lime","green","emerald","teal","cyan","sky","blue","indigo","violet","purple","fuchsia","pink","rose","gray"]}},"required":["name"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"name":{"type":"string","minLength":1,"maxLength":60},"color":{"default":"orange","example":"orange","type":"string","enum":["orange","red","amber","yellow","lime","green","emerald","teal","cyan","sky","blue","indigo","violet","purple","fuchsia","pink","rose","gray"]}},"required":["name"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"name":{"type":"string","minLength":1,"maxLength":60},"color":{"default":"orange","example":"orange","type":"string","enum":["orange","red","amber","yellow","lime","green","emerald","teal","cyan","sky","blue","indigo","violet","purple","fuchsia","pink","rose","gray"]}},"required":["name"]}}}},"responses":{"201":{"description":"Custom URL classification created","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"}},"required":["name","color"],"description":"Custom URL classification created"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postClassificationsUrls"},"delete":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Delete Custom URL Classification","description":"Delete a custom URL classification. Cascades through the override table, so any URLs currently assigned this classification fall back to their heuristic classification.","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"name":{"type":"string","minLength":1,"maxLength":60}},"required":["name"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"name":{"type":"string","minLength":1,"maxLength":60}},"required":["name"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"name":{"type":"string","minLength":1,"maxLength":60}},"required":["name"]}}}},"responses":{"200":{"description":"Custom URL classification deleted","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Custom URL classification deleted"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"deleteClassificationsUrls"}},"/classifications/url-assignments":{"put":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Set URL Classification","description":"Assign a built-in or custom classification to a URL (overriding any heuristic classification), or clear the assignment by passing null.","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"url":{"type":"string","minLength":1,"description":"URL to classify. The override applies to the normalized form, so it covers every source row that canonicalizes to the same URL."},"classification":{"nullable":true,"description":"Built-in classification (HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, REVIEW, OTHER) or the name of a custom URL classification. Pass null to clear the assignment.","type":"string","minLength":1,"maxLength":60}},"required":["url","classification"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"url":{"type":"string","minLength":1,"description":"URL to classify. The override applies to the normalized form, so it covers every source row that canonicalizes to the same URL."},"classification":{"nullable":true,"description":"Built-in classification (HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, REVIEW, OTHER) or the name of a custom URL classification. Pass null to clear the assignment.","type":"string","minLength":1,"maxLength":60}},"required":["url","classification"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"project_id":{"description":"Required if using a company api key","example":"or_f45b94ba-5e35-4982-93ed-285e72ee14eb","type":"string"},"url":{"type":"string","minLength":1,"description":"URL to classify. The override applies to the normalized form, so it covers every source row that canonicalizes to the same URL."},"classification":{"nullable":true,"description":"Built-in classification (HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, REVIEW, OTHER) or the name of a custom URL classification. Pass null to clear the assignment.","type":"string","minLength":1,"maxLength":60}},"required":["url","classification"]}}}},"responses":{"200":{"description":"URL classification assignment updated","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"URL classification assignment updated"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"putClassificationsUrl-assignments"}},"/source-tags":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Source Tags","description":"List the tags a project can put on URLs and domains. Source tags sit next to the URL and domain classification, and a URL or domain can carry any number of them. They are separate from prompt tags.","tags":["Project"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"stg_23abec5b-100a-4261-9ee7-1effe68f0149"},"name":{"type":"string","example":"Affiliate"},"color":{"type":"string","enum":["gray","red","orange","yellow","lime","green","cyan","blue","purple","fuchsia","pink","emerald","amber","violet","indigo","teal","sky","rose","slate","zinc","neutral","stone"],"example":"orange","description":"Badge color the tag is shown with."}},"required":["id","name","color"]}},"total_count":{"type":"number","example":12,"description":"Total number of source tags, ignoring pagination"}},"required":["data","total_count"],"description":"Success"}}}}},"operationId":"getSource-tags"},"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Create Source Tag","description":"Create a tag that can be put on URLs and domains.","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"example":"Affiliate","description":"Tag name, unique within the project regardless of letter case."},"color":{"default":"gray","type":"string","enum":["gray","red","orange","yellow","lime","green","cyan","blue","purple","fuchsia","pink","emerald","amber","violet","indigo","teal","sky","rose","slate","zinc","neutral","stone"],"example":"orange","description":"Badge color the tag is shown with."}},"required":["name"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"example":"Affiliate","description":"Tag name, unique within the project regardless of letter case."},"color":{"default":"gray","type":"string","enum":["gray","red","orange","yellow","lime","green","cyan","blue","purple","fuchsia","pink","emerald","amber","violet","indigo","teal","sky","rose","slate","zinc","neutral","stone"],"example":"orange","description":"Badge color the tag is shown with."}},"required":["name"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"example":"Affiliate","description":"Tag name, unique within the project regardless of letter case."},"color":{"default":"gray","type":"string","enum":["gray","red","orange","yellow","lime","green","cyan","blue","purple","fuchsia","pink","emerald","amber","violet","indigo","teal","sky","rose","slate","zinc","neutral","stone"],"example":"orange","description":"Badge color the tag is shown with."}},"required":["name"]}}}},"responses":{"201":{"description":"Source tag created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"stg_23abec5b-100a-4261-9ee7-1effe68f0149"}},"required":["id"],"description":"Source tag created"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postSource-tags"}},"/source-tags/{source_tag_id}":{"patch":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Update Source Tag","description":"Rename or recolor a source tag.","tags":["Project"],"parameters":[{"name":"source_tag_id","in":"path","required":true,"schema":{"type":"string","example":"stg_23abec5b-100a-4261-9ee7-1effe68f0149"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"example":"Affiliate","description":"Tag name, unique within the project regardless of letter case."},"color":{"type":"string","enum":["gray","red","orange","yellow","lime","green","cyan","blue","purple","fuchsia","pink","emerald","amber","violet","indigo","teal","sky","rose","slate","zinc","neutral","stone"],"example":"orange","description":"Badge color the tag is shown with."}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"example":"Affiliate","description":"Tag name, unique within the project regardless of letter case."},"color":{"type":"string","enum":["gray","red","orange","yellow","lime","green","cyan","blue","purple","fuchsia","pink","emerald","amber","violet","indigo","teal","sky","rose","slate","zinc","neutral","stone"],"example":"orange","description":"Badge color the tag is shown with."}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"example":"Affiliate","description":"Tag name, unique within the project regardless of letter case."},"color":{"type":"string","enum":["gray","red","orange","yellow","lime","green","cyan","blue","purple","fuchsia","pink","emerald","amber","violet","indigo","teal","sky","rose","slate","zinc","neutral","stone"],"example":"orange","description":"Badge color the tag is shown with."}}}}}},"responses":{"200":{"description":"Source tag updated","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Source tag updated"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"patchSource-tagsBySource_tag_id"},"delete":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Delete Source Tag","description":"Delete a source tag. It is removed from every URL and domain that carries it.","tags":["Project"],"parameters":[{"name":"source_tag_id","in":"path","required":true,"schema":{"type":"string","example":"stg_23abec5b-100a-4261-9ee7-1effe68f0149"}}],"responses":{"200":{"description":"Source tag deleted","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Source tag deleted"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"deleteSource-tagsBySource_tag_id"}},"/source-tags/url-assignments":{"put":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Update URL Source Tags","description":"Add and remove source tags on URLs. Removals apply before additions.","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"urls":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","minLength":1},"example":["https://example.com/best-crm-tools"],"description":"URLs to tag. A tag applies to the normalized form, so it covers every variant of the URL that normalizes to the same address."},"add_tag_ids":{"default":[],"example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"],"description":"Source tag ids to add. Adding a tag already present is a no-op.","maxItems":50,"type":"array","items":{"type":"string"}},"remove_tag_ids":{"default":[],"example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"],"description":"Source tag ids to remove.","maxItems":50,"type":"array","items":{"type":"string"}}},"required":["urls"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"urls":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","minLength":1},"example":["https://example.com/best-crm-tools"],"description":"URLs to tag. A tag applies to the normalized form, so it covers every variant of the URL that normalizes to the same address."},"add_tag_ids":{"default":[],"example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"],"description":"Source tag ids to add. Adding a tag already present is a no-op.","maxItems":50,"type":"array","items":{"type":"string"}},"remove_tag_ids":{"default":[],"example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"],"description":"Source tag ids to remove.","maxItems":50,"type":"array","items":{"type":"string"}}},"required":["urls"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"urls":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","minLength":1},"example":["https://example.com/best-crm-tools"],"description":"URLs to tag. A tag applies to the normalized form, so it covers every variant of the URL that normalizes to the same address."},"add_tag_ids":{"default":[],"example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"],"description":"Source tag ids to add. Adding a tag already present is a no-op.","maxItems":50,"type":"array","items":{"type":"string"}},"remove_tag_ids":{"default":[],"example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"],"description":"Source tag ids to remove.","maxItems":50,"type":"array","items":{"type":"string"}}},"required":["urls"]}}}},"responses":{"200":{"description":"URL tags updated","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"URL tags updated"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"putSource-tagsUrl-assignments"}},"/source-tags/domain-assignments":{"put":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Update Domain Source Tags","description":"Add and remove source tags on domains. Removals apply before additions.","tags":["Project"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","minLength":1},"example":["forbes.com"],"description":"Domains to tag. A tag applies to the registrable domain, so blog.example.com and example.com share tags."},"add_tag_ids":{"default":[],"example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"],"description":"Source tag ids to add. Adding a tag already present is a no-op.","maxItems":50,"type":"array","items":{"type":"string"}},"remove_tag_ids":{"default":[],"example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"],"description":"Source tag ids to remove.","maxItems":50,"type":"array","items":{"type":"string"}}},"required":["domains"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"domains":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","minLength":1},"example":["forbes.com"],"description":"Domains to tag. A tag applies to the registrable domain, so blog.example.com and example.com share tags."},"add_tag_ids":{"default":[],"example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"],"description":"Source tag ids to add. Adding a tag already present is a no-op.","maxItems":50,"type":"array","items":{"type":"string"}},"remove_tag_ids":{"default":[],"example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"],"description":"Source tag ids to remove.","maxItems":50,"type":"array","items":{"type":"string"}}},"required":["domains"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"domains":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","minLength":1},"example":["forbes.com"],"description":"Domains to tag. A tag applies to the registrable domain, so blog.example.com and example.com share tags."},"add_tag_ids":{"default":[],"example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"],"description":"Source tag ids to add. Adding a tag already present is a no-op.","maxItems":50,"type":"array","items":{"type":"string"}},"remove_tag_ids":{"default":[],"example":["stg_23abec5b-100a-4261-9ee7-1effe68f0149"],"description":"Source tag ids to remove.","maxItems":50,"type":"array","items":{"type":"string"}}},"required":["domains"]}}}},"responses":{"200":{"description":"Domain tags updated","content":{"application/json":{"schema":{"type":"object","properties":{},"description":"Domain tags updated"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"putSource-tagsDomain-assignments"}},"/projects":{"get":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"List Projects","description":"List the projects of a company","tags":["Company"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":1000,"type":"integer","minimum":1,"maximum":10000}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"external_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"or_915e742b-396d-4a86-ad57-8bc84e8c2232"},"name":{"type":"string","example":"Peec AI"},"status":{"type":"string","enum":["CUSTOMER","CUSTOMER_ENDED","PITCH","PITCH_ENDED","TRIAL","TRIAL_ENDED","ONBOARDING","DELETED","API_PARTNER","PAUSED"],"example":"PITCH"},"country_code":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"]},"language_code":{"description":"ISO 639-1 language code the project's prompts run in.","example":"en","type":"string","enum":["ar","az","bg","bn","bs","cs","da","de","el","en","es","et","fi","fr","he","hi","hr","hu","hy","id","it","ja","ko","lt","lv","mk","mn","ms","no","nl","pl","pt","ro","ru","sk","sl","sq","sr","sv","th","tl","tr","uk","ur","vi","zh"]},"external_id":{"type":"string"},"chat_interval_weekdays":{"description":"1 is monday, 7 is sunday. Not set means daily.","type":"array","items":{"type":"number"}},"chat_interval_month_days":{"description":"Days of the month (1-31) the project runs on, e.g. [1, 15]. Not set together with chat_interval_weekdays.","type":"array","items":{"type":"number"}},"created_at":{"default":"2026-01-01","description":"full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21","example":"2025-09-22","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["id","name","status","country_code"]}}},"required":["data"],"description":"Success"}}}}},"operationId":"getProjects"},"post":{"security":[{"APIKeyHeader":[]},{"APIKeyQuery":[]},{"BearerAuth":[]}],"summary":"Create Project","description":"Create a project in the company, under the same plan limits and credit pool as creating it in the app. Add brands and prompts to it afterwards.","tags":["Company"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"domain":{"type":"string","minLength":1,"example":"peec.ai"},"country_code":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"],"description":"The country the project's prompts run from.","example":"US"},"language_code":{"description":"ISO 639-1 language code the project's prompts run in.","example":"en","type":"string","enum":["ar","az","bg","bn","bs","cs","da","de","el","en","es","et","fi","fr","he","hi","hr","hu","hy","id","it","ja","ko","lt","lv","mk","mn","ms","no","nl","pl","pt","ro","ru","sk","sl","sq","sr","sv","th","tl","tr","uk","ur","vi","zh"]},"model_channel_ids":{"description":"Model channels to track. Defaults to the company's default channels. Not allowed on a pitch project, which uses the company's pitch models.","type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"allocated_credits":{"description":"Credits to allocate to the project from the company's pool. Required for every project except an onboarding one, the first project of a company that has no plan yet, and a pitch project, which takes none.","type":"number"},"is_pitch":{"description":"Create a pitch project, available to agency and partner companies. It runs under the company's pitch project and prompt limits and ends after the company's pitch period.","type":"boolean"},"is_instant_pitch":{"description":"Make the pitch project an instant pitch, which does not run on the daily schedule. Requires is_pitch.","type":"boolean"},"timezone":{"description":"IANA timezone. Defaults to the company's timezone.","example":"Europe/Berlin","type":"string"},"chat_interval_weekdays":{"description":"ISO 8601 weekdays: 1 is monday, 7 is sunday. Defaults to the company's schedule, and not set means daily.","type":"array","items":{"type":"number","minimum":1,"maximum":7}}},"required":["name","domain","country_code"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"domain":{"type":"string","minLength":1,"example":"peec.ai"},"country_code":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"],"description":"The country the project's prompts run from.","example":"US"},"language_code":{"description":"ISO 639-1 language code the project's prompts run in.","example":"en","type":"string","enum":["ar","az","bg","bn","bs","cs","da","de","el","en","es","et","fi","fr","he","hi","hr","hu","hy","id","it","ja","ko","lt","lv","mk","mn","ms","no","nl","pl","pt","ro","ru","sk","sl","sq","sr","sv","th","tl","tr","uk","ur","vi","zh"]},"model_channel_ids":{"description":"Model channels to track. Defaults to the company's default channels. Not allowed on a pitch project, which uses the company's pitch models.","type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"allocated_credits":{"description":"Credits to allocate to the project from the company's pool. Required for every project except an onboarding one, the first project of a company that has no plan yet, and a pitch project, which takes none.","type":"number"},"is_pitch":{"description":"Create a pitch project, available to agency and partner companies. It runs under the company's pitch project and prompt limits and ends after the company's pitch period.","type":"boolean"},"is_instant_pitch":{"description":"Make the pitch project an instant pitch, which does not run on the daily schedule. Requires is_pitch.","type":"boolean"},"timezone":{"description":"IANA timezone. Defaults to the company's timezone.","example":"Europe/Berlin","type":"string"},"chat_interval_weekdays":{"description":"ISO 8601 weekdays: 1 is monday, 7 is sunday. Defaults to the company's schedule, and not set means daily.","type":"array","items":{"type":"number","minimum":1,"maximum":7}}},"required":["name","domain","country_code"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"domain":{"type":"string","minLength":1,"example":"peec.ai"},"country_code":{"type":"string","enum":["AE","AL","AM","AR","AT","AU","BA","BE","BG","BH","BO","BR","BS","BY","CA","CH","CL","CN","CO","CR","CY","CZ","DE","DK","DO","EC","EE","EG","ES","FI","FR","GB","GE","GH","GR","GT","HK","HN","HR","HU","ID","IE","IL","IN","IQ","IS","IT","JO","JP","KR","KW","LB","LI","LT","LU","LV","MA","MD","ME","MK","MN","MT","MX","MY","NG","NI","NL","NO","NZ","OM","PK","PA","PE","PH","PL","PT","PY","PS","QA","RO","RS","SA","SE","SG","SI","SK","SV","TH","TN","TR","TW","UA","US","UY","VE","VN","ZA","AD","AF","AS","AZ","BB","BQ","CG","CI","CM","CW","DM","DZ","FO","GF","GP","JM","KG","KH","KI","KZ","LK","LR","LS","MW","NC","PG","TD","TF","UG","VU","ZW"],"description":"The country the project's prompts run from.","example":"US"},"language_code":{"description":"ISO 639-1 language code the project's prompts run in.","example":"en","type":"string","enum":["ar","az","bg","bn","bs","cs","da","de","el","en","es","et","fi","fr","he","hi","hr","hu","hy","id","it","ja","ko","lt","lv","mk","mn","ms","no","nl","pl","pt","ro","ru","sk","sl","sq","sr","sv","th","tl","tr","uk","ur","vi","zh"]},"model_channel_ids":{"description":"Model channels to track. Defaults to the company's default channels. Not allowed on a pitch project, which uses the company's pitch models.","type":"array","items":{"type":"string","enum":["openai-0","openai-1","qwen-0","openai-2","perplexity-0","perplexity-1","google-0","google-1","google-2","google-3","google-4","google-5","anthropic-0","anthropic-1","anthropic-2","anthropic-3","deepseek-0","meta-0","meta-1","meta-2","xai-0","xai-1","microsoft-0","amazon-0","mistral-0","mistral-1","naver-0","openai-3","openai-4","openai-5","baidu-0"]}},"allocated_credits":{"description":"Credits to allocate to the project from the company's pool. Required for every project except an onboarding one, the first project of a company that has no plan yet, and a pitch project, which takes none.","type":"number"},"is_pitch":{"description":"Create a pitch project, available to agency and partner companies. It runs under the company's pitch project and prompt limits and ends after the company's pitch period.","type":"boolean"},"is_instant_pitch":{"description":"Make the pitch project an instant pitch, which does not run on the daily schedule. Requires is_pitch.","type":"boolean"},"timezone":{"description":"IANA timezone. Defaults to the company's timezone.","example":"Europe/Berlin","type":"string"},"chat_interval_weekdays":{"description":"ISO 8601 weekdays: 1 is monday, 7 is sunday. Defaults to the company's schedule, and not set means daily.","type":"array","items":{"type":"number","minimum":1,"maximum":7}}},"required":["name","domain","country_code"]}}}},"responses":{"201":{"description":"Project created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"or_915e742b-396d-4a86-ad57-8bc84e8c2232"}},"required":["id"],"description":"Project created successfully"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"operationId":"postProjects"}}}}