{"openapi":"3.1.0","info":{"title":"Verte API","version":"1","description":"How AI answer engines (ChatGPT, Gemini, Google AI Overviews and AI Mode) mention your clients. Send an API key from Settings → API and MCP as `Authorization: Bearer vrt_live_…`. Keys can read, or read and write. Each key gets 60 reads and 10 writes a minute. Lists take `cursor` and `limit` (1–100); dates are YYYY-MM-DD in UTC."},"servers":[{"url":"https://api.useverte.com/v1"}],"tags":[{"name":"Usage","description":"Your plan and this period’s usage."},{"name":"Clients","description":"The client brands you track."},{"name":"Metrics","description":"Visibility, share of voice and sentiment over a date range."},{"name":"Prompts","description":"The questions checked daily, and what AI answered."},{"name":"Subcategories","description":"Each client’s ordered groups of prompts, such as “Pricing and value”."},{"name":"Super prompts","description":"Prompts tracked in 5 wordings, rotated through the day (Pro and up; 5 prompt slots each), and what the wording and the time of day changed."},{"name":"Competitors","description":"The competitors tracked for each client."},{"name":"Citations","description":"The sites AI answers cite, and citation gaps."},{"name":"Audits","description":"AI-readiness audits of client websites (uses audit pages)."},{"name":"Reports","description":"White-labelled share links and PDFs."},{"name":"Pitch projects","description":"Show a prospect their AI visibility before they sign (uses pitch prompts)."},{"name":"Proposals","description":"Changes proposed through MCP or the Verte Engine, which wait for a confirmation. REST writes are direct, so here you only read them."}],"paths":{"/usage":{"get":{"operationId":"getUsage","summary":"Get usage","description":"Your plan’s limits and what this billing period has used: clients, prompts, pitches and audit pages.","tags":["Usage"],"x-scope":"read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"}},"required":["key","name"],"additionalProperties":false},"status":{"type":["string","null"]},"period":{"type":"object","properties":{"start":{"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":{"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":"Exclusive: usage resets that day."}},"required":["start","end"],"additionalProperties":false},"limits":{"type":"object","properties":{"clients":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"shared_prompts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pitch_projects":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"audit_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"engines":{"type":"array","items":{"type":"string","enum":["chatgpt","gemini","google_aio","google_ai_mode"]}}},"required":["clients","shared_prompts","pitch_projects","audit_pages","engines"],"additionalProperties":false},"usage":{"type":"object","properties":{"clients":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"shared_prompts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pitch_projects":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"audit_pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["clients","shared_prompts","pitch_projects","audit_pages"],"additionalProperties":false}},"required":["plan","status","period","limits","usage"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/clients":{"get":{"operationId":"listClients","summary":"List clients","description":"The client brands your agency tracks, with their ids. Use a client id with the other client endpoints.","tags":["Clients"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"include_archived","in":"query","required":false,"schema":{"description":"Include archived clients (default false).","anyOf":[{"type":"boolean"},{"type":"string","enum":["0","1","true","false"]}]},"description":"Include archived clients (default false)."},{"name":"cursor","in":"query","required":false,"schema":{"description":"From the previous page’s next_cursor.","type":"string","maxLength":500},"description":"From the previous page’s next_cursor."},{"name":"limit","in":"query","required":false,"schema":{"default":50,"description":"Items per page, 1–100 (default 50).","type":"integer","minimum":1,"maximum":100},"description":"Items per page, 1–100 (default 50)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"brand_aliases":{"type":"array","items":{"type":"string"}},"location_code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"DataForSEO location code (2840 = United States)."},"language_code":{"type":"string"},"archived":{"type":"boolean"},"prompts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Active prompts."},"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))$"}},"required":["id","name","domain","brand_aliases","location_code","language_code","archived","prompts","created_at"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createClient","summary":"Create a client","description":"Adds a client brand to track. Counts against your plan’s clients. Add prompts to it next.\n\nNeeds an API key with write access.","tags":["Clients"],"x-scope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The brand’s name, as AI answers would write it."},"domain":{"type":"string","description":"The brand’s website, e.g. example.com."},"brand_aliases":{"description":"Other names for the brand (up to 20).","type":"array","items":{"type":"string"}},"location_code":{"description":"Default 2840 (United States).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"language_code":{"description":"Default en.","type":"string"}},"required":["name","domain"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"brand_aliases":{"type":"array","items":{"type":"string"}},"location_code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"DataForSEO location code (2840 = United States)."},"language_code":{"type":"string"},"archived":{"type":"boolean"},"prompts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Active prompts."},"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))$"}},"required":["id","name","domain","brand_aliases","location_code","language_code","archived","prompts","created_at"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/clients/{client_id}/visibility":{"get":{"operationId":"getVisibility","summary":"Get visibility","description":"How often AI answers mention the client: visibility % with \"X of Y checks\", over a date range, with a point per day or week. Filter by engine.","tags":["Metrics"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"},"description":"The client's id."},{"name":"engine","in":"query","required":false,"schema":{"description":"all (default), chatgpt, gemini, google_aio or google_ai_mode.","type":"string","enum":["all","chatgpt","gemini","google_aio","google_ai_mode"]},"description":"all (default), chatgpt, gemini, google_aio or google_ai_mode."},{"name":"from","in":"query","required":false,"schema":{"description":"First day, YYYY-MM-DD (default: 29 days before to).","type":"string"},"description":"First day, YYYY-MM-DD (default: 29 days before to)."},{"name":"to","in":"query","required":false,"schema":{"description":"Last day, YYYY-MM-DD (default: today, UTC).","type":"string"},"description":"Last day, YYYY-MM-DD (default: today, UTC)."},{"name":"group_by","in":"query","required":false,"schema":{"description":"day or week (default day up to 90 days, else week).","type":"string"},"description":"day or week (default day up to 90 days, else week)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string"},"engine":{"type":"string","enum":["all","chatgpt","gemini","google_aio","google_ai_mode"]},"from":{"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])))$"},"to":{"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])))$"},"group_by":{"type":"string","enum":["day","week"]},"visibility_pct":{"description":"Brand mentions ÷ checks (absent AI Overviews excluded), or null.","type":["number","null"]},"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"points":{"type":"array","items":{"type":"object","properties":{"start":{"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":"The day, or the Monday of the week."},"visibility_pct":{"type":["number","null"]},"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["start","visibility_pct","mentions","checks"],"additionalProperties":false}}},"required":["client_id","engine","from","to","group_by","visibility_pct","mentions","checks","points"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/clients/{client_id}/share-of-voice":{"get":{"operationId":"getShareOfVoice","summary":"Get share of voice","description":"The brand’s share of mentions against its tracked competitors over a date range: brand mentions ÷ (brand + competitor mentions).","tags":["Metrics"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"},"description":"The client's id."},{"name":"engine","in":"query","required":false,"schema":{"description":"all (default), chatgpt, gemini, google_aio or google_ai_mode.","type":"string","enum":["all","chatgpt","gemini","google_aio","google_ai_mode"]},"description":"all (default), chatgpt, gemini, google_aio or google_ai_mode."},{"name":"from","in":"query","required":false,"schema":{"description":"First day, YYYY-MM-DD (default: 29 days before to).","type":"string"},"description":"First day, YYYY-MM-DD (default: 29 days before to)."},{"name":"to","in":"query","required":false,"schema":{"description":"Last day, YYYY-MM-DD (default: today, UTC).","type":"string"},"description":"Last day, YYYY-MM-DD (default: today, UTC)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string"},"engine":{"type":"string","enum":["all","chatgpt","gemini","google_aio","google_ai_mode"]},"from":{"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])))$"},"to":{"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])))$"},"brand":{"type":"object","properties":{"name":{"type":"string"},"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"share_pct":{"type":["number","null"]}},"required":["name","mentions","share_pct"],"additionalProperties":false},"competitors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"share_pct":{"type":["number","null"]}},"required":["id","name","mentions","share_pct"],"additionalProperties":false}}},"required":["client_id","engine","from","to","brand","competitors"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/clients/{client_id}/sentiment":{"get":{"operationId":"getSentiment","summary":"Get sentiment","description":"Positive, neutral and negative mentions of the brand over a date range.","tags":["Metrics"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"},"description":"The client's id."},{"name":"engine","in":"query","required":false,"schema":{"description":"all (default), chatgpt, gemini, google_aio or google_ai_mode.","type":"string","enum":["all","chatgpt","gemini","google_aio","google_ai_mode"]},"description":"all (default), chatgpt, gemini, google_aio or google_ai_mode."},{"name":"from","in":"query","required":false,"schema":{"description":"First day, YYYY-MM-DD (default: 29 days before to).","type":"string"},"description":"First day, YYYY-MM-DD (default: 29 days before to)."},{"name":"to","in":"query","required":false,"schema":{"description":"Last day, YYYY-MM-DD (default: today, UTC).","type":"string"},"description":"Last day, YYYY-MM-DD (default: today, UTC)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string"},"engine":{"type":"string","enum":["all","chatgpt","gemini","google_aio","google_ai_mode"]},"from":{"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])))$"},"to":{"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])))$"},"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Brand mentions; the labels are counted over them."},"positive":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"neutral":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"negative":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"positive_pct":{"type":["number","null"]},"neutral_pct":{"type":["number","null"]},"negative_pct":{"type":["number","null"]}},"required":["client_id","engine","from","to","mentions","positive","neutral","negative","positive_pct","neutral_pct","negative_pct"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/clients/{client_id}/prompts":{"get":{"operationId":"listPrompts","summary":"List prompts","description":"The questions tracked for a client, oldest first, with how often each mentioned the brand in its last 7 daily checks, per engine.","tags":["Prompts"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"},"description":"The client's id."},{"name":"include_inactive","in":"query","required":false,"schema":{"description":"Include deactivated prompts (default false).","anyOf":[{"type":"boolean"},{"type":"string","enum":["0","1","true","false"]}]},"description":"Include deactivated prompts (default false)."},{"name":"cursor","in":"query","required":false,"schema":{"description":"From the previous page’s next_cursor.","type":"string","maxLength":500},"description":"From the previous page’s next_cursor."},{"name":"limit","in":"query","required":false,"schema":{"default":50,"description":"Items per page, 1–100 (default 50).","type":"integer","minimum":1,"maximum":100},"description":"Items per page, 1–100 (default 50)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"text":{"type":"string"},"subcategory_id":{"description":"Its subcategory; null for “Other prompts”.","type":["string","null"]},"subcategory":{"description":"The subcategory’s name.","type":["string","null"]},"active":{"type":"boolean"},"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))$"},"kind":{"type":"string","enum":["regular","super"],"description":"A Super prompt is tracked in 5 wordings (see list_super_prompts) and uses 5 slots."},"slots":{"anyOf":[{"type":"number","const":1},{"type":"number","const":5}],"description":"The prompt slots it uses."},"last_7_days":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Checks with an answer; absent AI Overviews are left out."},"visibility_pct":{"type":["number","null"]}},"required":["mentions","checks","visibility_pct"],"additionalProperties":false},"engines":{"type":"object","propertyNames":{"type":"string","enum":["chatgpt","gemini","google_aio","google_ai_mode"]},"additionalProperties":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["mentions","checks"],"additionalProperties":false},"description":"The last 7 days per engine."}},"required":["id","client_id","text","subcategory_id","subcategory","active","created_at","kind","slots","last_7_days","engines"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addPrompts","summary":"Add prompts","description":"Adds questions to check daily for a client (up to 500 at a time). Each uses one place in your plan’s prompt pool; wording the client already tracks is skipped. Or give generate to have Verte write up to 20: one AI call, needing an active subscription (402) and sharing the org’s 10 AI setup steps a minute (429). A direct call checks first that that many fit in the pool, and a new subcategory named among the client’s 25 (402 before the AI call).\n\nNeeds an API key with write access.","tags":["Prompts"],"x-scope":"write","security":[{"bearerAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"},"description":"The client's id."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"prompts":{"description":"The questions, as a buyer would ask them. Give these or generate.","minItems":1,"maxItems":500,"type":"array","items":{"type":"string"}},"generate":{"description":"Or have Verte write them, for the subcategory given (none of them one the client tracks).","type":"object","properties":{"about":{"type":"string","minLength":1,"maxLength":200,"description":"What they should ask about, e.g. vegan options."},"count":{"type":"integer","minimum":1,"maximum":20,"description":"How many to write, 1–20."}},"required":["about","count"]},"subcategory_id":{"description":"One of the client’s subcategories for all of them (see list_subcategories).","type":"string"},"subcategory":{"description":"Or a subcategory by name, e.g. Pricing: created when the client has none by that name (up to 25 a client).","type":"string"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"added":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"text":{"type":"string"},"subcategory_id":{"description":"Its subcategory; null for “Other prompts”.","type":["string","null"]},"subcategory":{"description":"The subcategory’s name.","type":["string","null"]},"active":{"type":"boolean"},"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))$"},"kind":{"type":"string","enum":["regular","super"],"description":"A Super prompt is tracked in 5 wordings (see list_super_prompts) and uses 5 slots."},"slots":{"anyOf":[{"type":"number","const":1},{"type":"number","const":5}],"description":"The prompt slots it uses."},"last_7_days":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Checks with an answer; absent AI Overviews are left out."},"visibility_pct":{"type":["number","null"]}},"required":["mentions","checks","visibility_pct"],"additionalProperties":false},"engines":{"type":"object","propertyNames":{"type":"string","enum":["chatgpt","gemini","google_aio","google_ai_mode"]},"additionalProperties":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["mentions","checks"],"additionalProperties":false},"description":"The last 7 days per engine."}},"required":["id","client_id","text","subcategory_id","subcategory","active","created_at","kind","slots","last_7_days","engines"],"additionalProperties":false}},"skipped":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"reason":{"type":"string","enum":["duplicate","blank"]}},"required":["text","reason"],"additionalProperties":false}}},"required":["added","skipped"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/prompts/{prompt_id}":{"patch":{"operationId":"updatePrompt","summary":"Edit a prompt","description":"Changes a prompt’s wording, moves it to another of its client’s subcategories (null: “Other prompts”), or deactivates or reactivates it (within the pool). New wording for a Super prompt writes its other wordings again: it needs an active subscription and a plan with Super prompts (402), and takes one of the org’s 50 Super prompt wordings a minute (429).\n\nNeeds an API key with write access.","tags":["Prompts"],"x-scope":"write","security":[{"bearerAuth":[]}],"parameters":[{"name":"prompt_id","in":"path","required":true,"schema":{"type":"string"},"description":"The prompt's id."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"description":"New wording (up to 500 characters).","type":"string"},"subcategory_id":{"description":"A subcategory of the same client.","type":["string","null"]},"is_active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"text":{"type":"string"},"subcategory_id":{"description":"Its subcategory; null for “Other prompts”.","type":["string","null"]},"subcategory":{"description":"The subcategory’s name.","type":["string","null"]},"active":{"type":"boolean"},"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))$"},"kind":{"type":"string","enum":["regular","super"],"description":"A Super prompt is tracked in 5 wordings (see list_super_prompts) and uses 5 slots."},"slots":{"anyOf":[{"type":"number","const":1},{"type":"number","const":5}],"description":"The prompt slots it uses."},"last_7_days":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Checks with an answer; absent AI Overviews are left out."},"visibility_pct":{"type":["number","null"]}},"required":["mentions","checks","visibility_pct"],"additionalProperties":false},"engines":{"type":"object","propertyNames":{"type":"string","enum":["chatgpt","gemini","google_aio","google_ai_mode"]},"additionalProperties":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["mentions","checks"],"additionalProperties":false},"description":"The last 7 days per engine."}},"required":["id","client_id","text","subcategory_id","subcategory","active","created_at","kind","slots","last_7_days","engines"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deactivatePrompt","summary":"Deactivate a prompt","description":"Stops checking a prompt and frees its place in the pool. Its history is kept.\n\nNeeds an API key with write access.","tags":["Prompts"],"x-scope":"write","security":[{"bearerAuth":[]}],"parameters":[{"name":"prompt_id","in":"path","required":true,"schema":{"type":"string"},"description":"The prompt's id."}],"responses":{"204":{"description":"Done; no content."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/prompts/deactivate":{"post":{"operationId":"deactivatePrompts","summary":"Deactivate prompts","description":"Stops checking up to 50 prompts at once, freeing their places in the pool (a Super prompt frees 5). Their history is kept; ones already stopped are left as they are. If any id isn't one of your prompts, nothing changes (404).\n\nNeeds an API key with write access.","tags":["Prompts"],"x-scope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt_ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string"},"description":"Prompt ids from list_prompts, 1–50."}},"required":["prompt_ids"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"changed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"text":{"type":"string"},"subcategory_id":{"description":"Its subcategory; null for “Other prompts”.","type":["string","null"]},"subcategory":{"description":"The subcategory’s name.","type":["string","null"]},"active":{"type":"boolean"},"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))$"},"kind":{"type":"string","enum":["regular","super"],"description":"A Super prompt is tracked in 5 wordings (see list_super_prompts) and uses 5 slots."},"slots":{"anyOf":[{"type":"number","const":1},{"type":"number","const":5}],"description":"The prompt slots it uses."},"last_7_days":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Checks with an answer; absent AI Overviews are left out."},"visibility_pct":{"type":["number","null"]}},"required":["mentions","checks","visibility_pct"],"additionalProperties":false},"engines":{"type":"object","propertyNames":{"type":"string","enum":["chatgpt","gemini","google_aio","google_ai_mode"]},"additionalProperties":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["mentions","checks"],"additionalProperties":false},"description":"The last 7 days per engine."}},"required":["id","client_id","text","subcategory_id","subcategory","active","created_at","kind","slots","last_7_days","engines"],"additionalProperties":false},"description":"The prompts it changed, in the order given."},"unchanged":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"reason":{"type":"string","enum":["already_inactive","already_active"],"description":"Already stopped (deactivate) or already checked (reactivate)."}},"required":["id","reason"],"additionalProperties":false},"description":"The prompts that were already so, left as they are."}},"required":["changed","unchanged"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/prompts/reactivate":{"post":{"operationId":"reactivatePrompts","summary":"Reactivate prompts","description":"Starts checking up to 50 stopped prompts again, all or none: each needs a place in the pool, a Super prompt 5 and a plan with Super prompts (402), and comes back with its latest wordings. Ones already checked are left as they are; an archived client's prompts are refused (409). If any id isn't one of your prompts, nothing changes (404).\n\nNeeds an API key with write access.","tags":["Prompts"],"x-scope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt_ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string"},"description":"Prompt ids from list_prompts, 1–50."}},"required":["prompt_ids"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"changed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"text":{"type":"string"},"subcategory_id":{"description":"Its subcategory; null for “Other prompts”.","type":["string","null"]},"subcategory":{"description":"The subcategory’s name.","type":["string","null"]},"active":{"type":"boolean"},"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))$"},"kind":{"type":"string","enum":["regular","super"],"description":"A Super prompt is tracked in 5 wordings (see list_super_prompts) and uses 5 slots."},"slots":{"anyOf":[{"type":"number","const":1},{"type":"number","const":5}],"description":"The prompt slots it uses."},"last_7_days":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Checks with an answer; absent AI Overviews are left out."},"visibility_pct":{"type":["number","null"]}},"required":["mentions","checks","visibility_pct"],"additionalProperties":false},"engines":{"type":"object","propertyNames":{"type":"string","enum":["chatgpt","gemini","google_aio","google_ai_mode"]},"additionalProperties":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["mentions","checks"],"additionalProperties":false},"description":"The last 7 days per engine."}},"required":["id","client_id","text","subcategory_id","subcategory","active","created_at","kind","slots","last_7_days","engines"],"additionalProperties":false},"description":"The prompts it changed, in the order given."},"unchanged":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"reason":{"type":"string","enum":["already_inactive","already_active"],"description":"Already stopped (deactivate) or already checked (reactivate)."}},"required":["id","reason"],"additionalProperties":false},"description":"The prompts that were already so, left as they are."}},"required":["changed","unchanged"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/clients/{client_id}/subcategories":{"get":{"operationId":"listSubcategories","summary":"List subcategories","description":"A client’s subcategories (groups of prompts such as “Pricing and value”), in order, with how many prompts each holds. Prompts in none are “Other prompts”.","tags":["Subcategories"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"},"description":"The client's id."},{"name":"cursor","in":"query","required":false,"schema":{"description":"From the previous page’s next_cursor.","type":"string","maxLength":500},"description":"From the previous page’s next_cursor."},{"name":"limit","in":"query","required":false,"schema":{"default":50,"description":"Items per page, 1–100 (default 50).","type":"integer","minimum":1,"maximum":100},"description":"Items per page, 1–100 (default 50)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"0 is first."},"prompts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"active_prompts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Its prompts checked daily."},"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))$"}},"required":["id","client_id","name","description","position","prompts","active_prompts","created_at"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createSubcategory","summary":"Add a subcategory","description":"Adds a subcategory at the end of a client’s list (up to 25 a client), with the prompts given, or with generate_prompts written by Verte: one AI call, needing an active subscription (402) and sharing the org’s 10 AI setup steps a minute (429). Its prompts use places in the prompt pool, all or none (402); a direct call checks the 25 and the pool before the AI call.\n\nNeeds an API key with write access.","tags":["Subcategories"],"x-scope":"write","security":[{"bearerAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"},"description":"The client's id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"1 to 60 characters, unique per client (ignoring case)."},"description":{"description":"Up to 200 characters.","type":["string","null"]},"generate_prompts":{"default":0,"description":"Prompts for Verte to write for it, 0–20 (default 0).","type":"integer","minimum":0,"maximum":20},"prompts":{"description":"Or its prompts, up to 20, as a buyer would ask them.","maxItems":20,"type":"array","items":{"type":"string"}}},"required":["name"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"0 is first."},"prompts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"active_prompts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Its prompts checked daily."},"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))$"}},"required":["id","client_id","name","description","position","prompts","active_prompts","created_at"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/subcategories/{subcategory_id}":{"patch":{"operationId":"updateSubcategory","summary":"Rename a subcategory","description":"Renames or redescribes a subcategory; its prompts and their history stay with it.\n\nNeeds an API key with write access.","tags":["Subcategories"],"x-scope":"write","security":[{"bearerAuth":[]}],"parameters":[{"name":"subcategory_id","in":"path","required":true,"schema":{"type":"string"},"description":"The subcategory's id."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"1 to 60 characters, unique per client (ignoring case)."},"description":{"description":"Up to 200 characters.","type":["string","null"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"0 is first."},"prompts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"active_prompts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Its prompts checked daily."},"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))$"}},"required":["id","client_id","name","description","position","prompts","active_prompts","created_at"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteSubcategory","summary":"Delete a subcategory","description":"Removes a subcategory. Its prompts stop being checked (freeing places in the pool) and move to “Other prompts”, keeping their history.\n\nNeeds an API key with write access.","tags":["Subcategories"],"x-scope":"write","security":[{"bearerAuth":[]}],"parameters":[{"name":"subcategory_id","in":"path","required":true,"schema":{"type":"string"},"description":"The subcategory's id."}],"responses":{"204":{"description":"Done; no content."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/clients/{client_id}/super-prompts":{"get":{"operationId":"listSuperPrompts","summary":"List Super prompts with their findings","description":"A client’s Super prompts (each tracked in 5 wordings, rotated through the day) with what the wording and the time of day changed: each wording’s checks, visibility and position per engine; the spread between the best and worst wording (clear when significant with ≥ 20 checks each); visibility in five bands of the local day; the day of week from 28 days. Clearest differences first.","tags":["Super prompts"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"},"description":"The client's id."},{"name":"days","in":"query","required":false,"schema":{"description":"The last 7, 30 (default) or 90 days.","type":"string","enum":["7","30","90"]},"description":"The last 7, 30 (default) or 90 days."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["clearest","spread","visibility","checks"]}},{"name":"cursor","in":"query","required":false,"schema":{"description":"From the previous page’s next_cursor.","type":"string","maxLength":500},"description":"From the previous page’s next_cursor."},{"name":"limit","in":"query","required":false,"schema":{"default":50,"description":"Items per page, 1–100 (default 50).","type":"integer","minimum":1,"maximum":100},"description":"Items per page, 1–100 (default 50)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"window":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"additionalProperties":false},"summary":{"type":"object","properties":{"super_prompts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"wording_clear":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"time_clear":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"line":{"type":"string"}},"required":["super_prompts","wording_clear","time_clear","line"],"additionalProperties":false},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The Super prompt (its wording 0, the prompt in list_prompts)."},"text":{"type":"string"},"subcategory_id":{"type":["string","null"]},"overall":{"type":"object","properties":{"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"visibility_pct":{"type":["number","null"]},"avg_position":{"type":["number","null"]}},"required":["checks","mentions","visibility_pct","avg_position"],"additionalProperties":false},"wordings":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"0 is the prompt’s own text; 1–4 its other wordings."},"text":{"type":"string"},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"visibility_pct":{"type":["number","null"]},"avg_position":{"type":["number","null"]},"engines":{"type":"object","propertyNames":{"type":"string","enum":["chatgpt","gemini","google_aio","google_ai_mode"]},"additionalProperties":{"type":"object","properties":{"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"visibility_pct":{"type":["number","null"]}},"required":["checks","mentions","visibility_pct"],"additionalProperties":false}}},"required":["index","text","checks","mentions","visibility_pct","avg_position","engines"],"additionalProperties":false}},"wording_effect":{"type":"object","properties":{"status":{"type":"string","enum":["clear","no_difference","collecting"]},"spread_pts":{"description":"Best minus worst visibility, in points.","type":["number","null"]},"best":{"type":["string","null"]},"worst":{"type":["string","null"]},"label":{"type":"string"}},"required":["status","spread_pts","best","worst","label"],"additionalProperties":false},"time_bands":{"type":"array","items":{"type":"object","properties":{"band":{"type":"string"},"label":{"type":"string"},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"visibility_pct":{"type":["number","null"]}},"required":["band","label","checks","mentions","visibility_pct"],"additionalProperties":false}},"time_effect":{"type":"object","properties":{"status":{"type":"string","enum":["clear","no_difference","collecting"]},"spread_pts":{"description":"Best minus worst visibility, in points.","type":["number","null"]},"best":{"type":["string","null"]},"worst":{"type":["string","null"]},"label":{"type":"string"}},"required":["status","spread_pts","best","worst","label"],"additionalProperties":false},"day_of_week":{"anyOf":[{"type":"object","properties":{"days":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"visibility_pct":{"type":["number","null"]}},"required":["day","checks","mentions","visibility_pct"],"additionalProperties":false}},"effect":{"type":"object","properties":{"status":{"type":"string","enum":["clear","no_difference","collecting"]},"spread_pts":{"description":"Best minus worst visibility, in points.","type":["number","null"]},"best":{"type":["string","null"]},"worst":{"type":["string","null"]},"label":{"type":"string"}},"required":["status","spread_pts","best","worst","label"],"additionalProperties":false}},"required":["days","effect"],"additionalProperties":false},{"type":"null"}],"description":"From 28 days with checks."},"days_with_checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","text","subcategory_id","overall","wordings","wording_effect","time_bands","time_effect","day_of_week","days_with_checks"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["window","summary","data","next_cursor"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/prompts/{prompt_id}/super":{"post":{"operationId":"addSuperPrompt","summary":"Make a prompt a Super prompt","description":"Tracks a prompt in 5 wordings, rotated through the day (Pro and up). It uses 5 prompt slots instead of 1, so it needs 4 free: a shortage is refused with how many to free (deactivate prompts first). It needs an active subscription (402) and takes one of the org’s 50 Super prompt wordings a minute (429).\n\nNeeds an API key with write access.","tags":["Super prompts"],"x-scope":"write","security":[{"bearerAuth":[]}],"parameters":[{"name":"prompt_id","in":"path","required":true,"schema":{"type":"string"},"description":"The prompt's id."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"text":{"type":"string"},"subcategory_id":{"description":"Its subcategory; null for “Other prompts”.","type":["string","null"]},"subcategory":{"description":"The subcategory’s name.","type":["string","null"]},"active":{"type":"boolean"},"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))$"},"kind":{"type":"string","enum":["regular","super"],"description":"A Super prompt is tracked in 5 wordings (see list_super_prompts) and uses 5 slots."},"slots":{"anyOf":[{"type":"number","const":1},{"type":"number","const":5}],"description":"The prompt slots it uses."},"last_7_days":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Checks with an answer; absent AI Overviews are left out."},"visibility_pct":{"type":["number","null"]}},"required":["mentions","checks","visibility_pct"],"additionalProperties":false},"engines":{"type":"object","propertyNames":{"type":"string","enum":["chatgpt","gemini","google_aio","google_ai_mode"]},"additionalProperties":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["mentions","checks"],"additionalProperties":false},"description":"The last 7 days per engine."}},"required":["id","client_id","text","subcategory_id","subcategory","active","created_at","kind","slots","last_7_days","engines"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"removeSuperPrompt","summary":"Make a Super prompt normal","description":"It goes back to one wording and 1 prompt slot (4 freed); the other wordings’ history is kept.\n\nNeeds an API key with write access.","tags":["Super prompts"],"x-scope":"write","security":[{"bearerAuth":[]}],"parameters":[{"name":"prompt_id","in":"path","required":true,"schema":{"type":"string"},"description":"The prompt's id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"text":{"type":"string"},"subcategory_id":{"description":"Its subcategory; null for “Other prompts”.","type":["string","null"]},"subcategory":{"description":"The subcategory’s name.","type":["string","null"]},"active":{"type":"boolean"},"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))$"},"kind":{"type":"string","enum":["regular","super"],"description":"A Super prompt is tracked in 5 wordings (see list_super_prompts) and uses 5 slots."},"slots":{"anyOf":[{"type":"number","const":1},{"type":"number","const":5}],"description":"The prompt slots it uses."},"last_7_days":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Checks with an answer; absent AI Overviews are left out."},"visibility_pct":{"type":["number","null"]}},"required":["mentions","checks","visibility_pct"],"additionalProperties":false},"engines":{"type":"object","propertyNames":{"type":"string","enum":["chatgpt","gemini","google_aio","google_ai_mode"]},"additionalProperties":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["mentions","checks"],"additionalProperties":false},"description":"The last 7 days per engine."}},"required":["id","client_id","text","subcategory_id","subcategory","active","created_at","kind","slots","last_7_days","engines"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/prompts/{prompt_id}/answers":{"get":{"operationId":"getPromptAnswers","summary":"Get prompt answers","description":"What the AI engines answered to one prompt, newest first: whether and where the brand was mentioned, sentiment, competitors, other brands named, the answer text (kept 90 days) and the cited sources.","tags":["Prompts"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"prompt_id","in":"path","required":true,"schema":{"type":"string"},"description":"The prompt's id."},{"name":"engine","in":"query","required":false,"schema":{"description":"all (default), chatgpt, gemini, google_aio or google_ai_mode.","type":"string","enum":["all","chatgpt","gemini","google_aio","google_ai_mode"]},"description":"all (default), chatgpt, gemini, google_aio or google_ai_mode."},{"name":"from","in":"query","required":false,"schema":{"description":"First day, YYYY-MM-DD (default: 29 days before to).","type":"string"},"description":"First day, YYYY-MM-DD (default: 29 days before to)."},{"name":"to","in":"query","required":false,"schema":{"description":"Last day, YYYY-MM-DD (default: today, UTC).","type":"string"},"description":"Last day, YYYY-MM-DD (default: today, UTC)."},{"name":"cursor","in":"query","required":false,"schema":{"description":"From the previous page’s next_cursor.","type":"string","maxLength":500},"description":"From the previous page’s next_cursor."},{"name":"limit","in":"query","required":false,"schema":{"default":50,"description":"Items per page, 1–100 (default 50).","type":"integer","minimum":1,"maximum":100},"description":"Items per page, 1–100 (default 50)."},{"name":"answer_chars","in":"query","required":false,"schema":{"description":"Cut each answer text to this many characters (default: whole answers).","type":"integer","minimum":100,"maximum":20000},"description":"Cut each answer text to this many characters (default: whole answers)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"text":{"type":"string"},"subcategory_id":{"type":["string","null"]},"subcategory":{"type":["string","null"]}},"required":["id","client_id","text","subcategory_id","subcategory"],"additionalProperties":false},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The check (result) id."},"engine":{"type":"string","enum":["chatgpt","gemini","google_aio","google_ai_mode"]},"source":{"type":"string","enum":["scheduled","live"],"description":"scheduled = the daily check; live = a one-off check."},"run_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])))$"},"fetched_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))$"},"ai_overview_shown":{"type":"boolean","description":"False when Google showed no AI Overview."},"brand":{"type":"object","properties":{"mentioned":{"type":"boolean"},"position":{"type":"string","enum":["primary","supporting","absent"]},"rank":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its place in a numbered list, if any."},"sentiment":{"anyOf":[{"type":"string","enum":["positive","neutral","negative"]},{"type":"null"}]}},"required":["mentioned","position","rank","sentiment"],"additionalProperties":false},"competitors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mentioned":{"type":"boolean"},"rank":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["id","name","mentioned","rank"],"additionalProperties":false}},"other_brands":{"type":"array","items":{"type":"string"}},"answer_text":{"description":"Kept for 90 days; null after that.","type":["string","null"]},"answer_truncated":{"type":"boolean","description":"True when answer_chars cut the text."},"citations":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"url":{"type":"string"},"domain":{"type":"string"},"title":{"type":["string","null"]},"owner":{"type":"string","enum":["brand","competitor","other"]},"competitor_id":{"type":["string","null"]}},"required":["position","url","domain","title","owner","competitor_id"],"additionalProperties":false}}},"required":["id","engine","source","run_date","fetched_at","ai_overview_shown","brand","competitors","other_brands","answer_text","answer_truncated","citations"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["prompt","data","next_cursor"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/clients/{client_id}/competitors":{"get":{"operationId":"listCompetitors","summary":"List competitors","description":"The competitors tracked for a client, by name.","tags":["Competitors"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"},"description":"The client's id."},{"name":"cursor","in":"query","required":false,"schema":{"description":"From the previous page’s next_cursor.","type":"string","maxLength":500},"description":"From the previous page’s next_cursor."},{"name":"limit","in":"query","required":false,"schema":{"default":50,"description":"Items per page, 1–100 (default 50).","type":"integer","minimum":1,"maximum":100},"description":"Items per page, 1–100 (default 50)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"name":{"type":"string"},"domain":{"type":["string","null"]},"aliases":{"type":"array","items":{"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))$"}},"required":["id","client_id","name","domain","aliases","created_at"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addCompetitor","summary":"Add a competitor","description":"Tracks a competitor for a client (up to 25 per client; 402 past them).\n\nNeeds an API key with write access.","tags":["Competitors"],"x-scope":"write","security":[{"bearerAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"},"description":"The client's id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The competitor’s name, as AI answers would write it."},"domain":{"description":"Its website, e.g. rival.com.","type":"string"},"aliases":{"description":"Other names for it (up to 20).","type":"array","items":{"type":"string"}}},"required":["name"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"name":{"type":"string"},"domain":{"type":["string","null"]},"aliases":{"type":"array","items":{"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))$"}},"required":["id","client_id","name","domain","aliases","created_at"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/clients/{client_id}/competitors/{competitor_id}":{"delete":{"operationId":"deleteCompetitor","summary":"Delete a competitor","description":"Stops tracking a competitor and deletes its mention history.\n\nNeeds an API key with write access.","tags":["Competitors"],"x-scope":"write","security":[{"bearerAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"},"description":"The client's id."},{"name":"competitor_id","in":"path","required":true,"schema":{"type":"string"},"description":"The competitor's id."}],"responses":{"204":{"description":"Done; no content."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/clients/{client_id}/citations":{"get":{"operationId":"getCitations","summary":"Get citations","description":"The sites AI answers cited for a client over a date range, most cited first, with who owns each one. gap=true keeps the citation gaps: third-party sites cited for competitors but not for the brand.","tags":["Citations"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"},"description":"The client's id."},{"name":"engine","in":"query","required":false,"schema":{"description":"all (default), chatgpt, gemini, google_aio or google_ai_mode.","type":"string","enum":["all","chatgpt","gemini","google_aio","google_ai_mode"]},"description":"all (default), chatgpt, gemini, google_aio or google_ai_mode."},{"name":"from","in":"query","required":false,"schema":{"description":"First day, YYYY-MM-DD (default: 29 days before to).","type":"string"},"description":"First day, YYYY-MM-DD (default: 29 days before to)."},{"name":"to","in":"query","required":false,"schema":{"description":"Last day, YYYY-MM-DD (default: today, UTC).","type":"string"},"description":"Last day, YYYY-MM-DD (default: today, UTC)."},{"name":"gap","in":"query","required":false,"schema":{"description":"Only citation gaps (default false).","anyOf":[{"type":"boolean"},{"type":"string","enum":["0","1","true","false"]}]},"description":"Only citation gaps (default false)."},{"name":"cursor","in":"query","required":false,"schema":{"description":"From the previous page’s next_cursor.","type":"string","maxLength":500},"description":"From the previous page’s next_cursor."},{"name":"limit","in":"query","required":false,"schema":{"default":50,"description":"Items per page, 1–100 (default 50).","type":"integer","minimum":1,"maximum":100},"description":"Items per page, 1–100 (default 50)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"citations":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Checks whose answer cited the domain."},"brand_citations":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"…whose answer also mentioned the brand."},"gap_citations":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"…mentioning a tracked competitor but not the brand."},"owner":{"type":"string","enum":["brand","competitor","other"]},"competitor_id":{"type":["string","null"]},"competitors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"gap":{"type":"boolean","description":"A third-party site cited for competitors, not for the brand."}},"required":["domain","citations","brand_citations","gap_citations","owner","competitor_id","competitors","gap"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/pitch-projects":{"post":{"operationId":"createPitchProject","summary":"Create a pitch project","description":"Shows a prospect their AI visibility before they sign. Give the prospect's name and website (and, if you like, up to 5 competitors and 2–4 subcategories); Verte researches it and writes 25 prompts a person would ask (they stay hidden), then checks each on every engine in your plan, twice, an hour apart. Uses one pitch of your monthly allowance now; if the pitch can't be prepared it's refunded. Answers 202 with the pitch preparing: read it with GET /pitch-projects/{id}. The project and its share link expire after 30 days.\n\nNeeds an API key with write access.","tags":["Pitch projects"],"x-scope":"write","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prospect_name":{"type":"string","description":"The prospect’s brand name."},"domain":{"type":"string","description":"The prospect’s website, like prospect.com."},"location_code":{"description":"DataForSEO location (default 2840, US).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"language_code":{"description":"Language (default en).","type":"string"},"competitors":{"description":"Up to 5 competitors; research finds them otherwise.","maxItems":5,"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"}},"required":["name"]}},"subcategories":{"description":"2–4 subcategories for the prompts; proposed by research otherwise.","minItems":2,"maxItems":4,"type":"array","items":{"type":"string"}}},"required":["prospect_name","domain"]}}}},"responses":{"202":{"description":"Accepted: started in the background.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"prospect_name":{"type":"string"},"domain":{"type":"string"},"summary":{"description":"What research found the prospect does.","type":["string","null"]},"industry":{"type":["string","null"]},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":["string","null"]}},"required":["name","domain"],"additionalProperties":false}},"status":{"type":"string","enum":["preparing","running","complete","expired"],"description":"preparing: the 25 prompts are being written; running: its rounds are checked."},"checks_done":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rounds finished, 0–2 (each prompt is checked twice)."},"check_in_flight":{"type":"boolean","description":"A round is being checked right now."},"next_check_at":{"anyOf":[{"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))$"},{"type":"null"}],"description":"When the next round may start."},"prompts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Hidden prompts the pitch checks (25); never listed."},"engines":{"type":"array","items":{"type":"string","enum":["chatgpt","gemini","google_aio","google_ai_mode"]}},"visibility":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pct":{"description":"mentions ÷ checks as a percentage; null before any check.","type":["number","null"]}},"required":["mentions","checks","pct"],"additionalProperties":false,"description":"The prospect: answers that mention it, of answered checks."},"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))$"},"expires_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))$"},"converted_client_id":{"type":["string","null"]},"error":{"description":"Why it stopped, e.g. “We couldn’t prepare this pitch”.","type":["string","null"]}},"required":["id","prospect_name","domain","summary","industry","competitors","status","checks_done","check_in_flight","next_check_at","prompts","engines","visibility","created_at","expires_at","converted_client_id","error"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"get":{"operationId":"listPitchProjects","summary":"List pitch projects","description":"Your pitch projects, newest first, with the prospect’s visibility so far.","tags":["Pitch projects"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"description":"From the previous page’s next_cursor.","type":"string","maxLength":500},"description":"From the previous page’s next_cursor."},{"name":"limit","in":"query","required":false,"schema":{"default":50,"description":"Items per page, 1–100 (default 50).","type":"integer","minimum":1,"maximum":100},"description":"Items per page, 1–100 (default 50)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"prospect_name":{"type":"string"},"domain":{"type":"string"},"summary":{"description":"What research found the prospect does.","type":["string","null"]},"industry":{"type":["string","null"]},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":["string","null"]}},"required":["name","domain"],"additionalProperties":false}},"status":{"type":"string","enum":["preparing","running","complete","expired"],"description":"preparing: the 25 prompts are being written; running: its rounds are checked."},"checks_done":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rounds finished, 0–2 (each prompt is checked twice)."},"check_in_flight":{"type":"boolean","description":"A round is being checked right now."},"next_check_at":{"anyOf":[{"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))$"},{"type":"null"}],"description":"When the next round may start."},"prompts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Hidden prompts the pitch checks (25); never listed."},"engines":{"type":"array","items":{"type":"string","enum":["chatgpt","gemini","google_aio","google_ai_mode"]}},"visibility":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pct":{"description":"mentions ÷ checks as a percentage; null before any check.","type":["number","null"]}},"required":["mentions","checks","pct"],"additionalProperties":false,"description":"The prospect: answers that mention it, of answered checks."},"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))$"},"expires_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))$"},"converted_client_id":{"type":["string","null"]},"error":{"description":"Why it stopped, e.g. “We couldn’t prepare this pitch”.","type":["string","null"]}},"required":["id","prospect_name","domain","summary","industry","competitors","status","checks_done","check_in_flight","next_check_at","prompts","engines","visibility","created_at","expires_at","converted_client_id","error"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/pitch-projects/{project_id}":{"get":{"operationId":"getPitchProject","summary":"Get a pitch project","description":"A pitch project’s report: how often answers mention the prospect and each competitor, per engine and per subcategory, the biggest gaps (with at most 4 example prompts; the 25 prompts stay hidden), site readiness, what to do, and the share link.","tags":["Pitch projects"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string"},"description":"The pitch project's id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"prospect_name":{"type":"string"},"domain":{"type":"string"},"summary":{"description":"What research found the prospect does.","type":["string","null"]},"industry":{"type":["string","null"]},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":["string","null"]}},"required":["name","domain"],"additionalProperties":false}},"status":{"type":"string","enum":["preparing","running","complete","expired"],"description":"preparing: the 25 prompts are being written; running: its rounds are checked."},"checks_done":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rounds finished, 0–2 (each prompt is checked twice)."},"check_in_flight":{"type":"boolean","description":"A round is being checked right now."},"next_check_at":{"anyOf":[{"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))$"},{"type":"null"}],"description":"When the next round may start."},"prompts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Hidden prompts the pitch checks (25); never listed."},"engines":{"type":"array","items":{"type":"string","enum":["chatgpt","gemini","google_aio","google_ai_mode"]}},"visibility":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pct":{"description":"mentions ÷ checks as a percentage; null before any check.","type":["number","null"]}},"required":["mentions","checks","pct"],"additionalProperties":false,"description":"The prospect: answers that mention it, of answered checks."},"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))$"},"expires_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))$"},"converted_client_id":{"type":["string","null"]},"error":{"description":"Why it stopped, e.g. “We couldn’t prepare this pitch”.","type":["string","null"]},"preliminary":{"type":"boolean","description":"Rounds still running: the figures will move."},"headline":{"type":"string","description":"“AI mentions <prospect> in 18% of answers (36 of 200 checks)…”"},"brands":{"type":"array","items":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pct":{"description":"mentions ÷ checks as a percentage; null before any check.","type":["number","null"]},"name":{"type":"string"},"is_prospect":{"type":"boolean"},"share":{"description":"Share of voice among the tracked brands.","type":["number","null"]}},"required":["mentions","checks","pct","name","is_prospect","share"],"additionalProperties":false}},"by_engine":{"type":"array","items":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pct":{"description":"mentions ÷ checks as a percentage; null before any check.","type":["number","null"]},"engine":{"type":"string","enum":["chatgpt","gemini","google_aio","google_ai_mode"]}},"required":["mentions","checks","pct","engine"],"additionalProperties":false}},"subcategories":{"type":"array","items":{"type":"object","properties":{"mentions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pct":{"description":"mentions ÷ checks as a percentage; null before any check.","type":["number","null"]},"name":{"type":"string"},"prompts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Hidden prompts in it (a count)."},"label":{"type":"string","enum":["strong","steady","weak","too_few"]},"top_competitor":{"type":["string","null"]}},"required":["mentions","checks","pct","name","prompts","label","top_competitor"],"additionalProperties":false}},"gaps":{"type":"array","items":{"type":"object","properties":{"subcategory":{"type":"string"},"answers":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Answers naming competitors and not the prospect."},"competitors":{"type":"array","items":{"type":"string"}},"examples":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"competitors":{"type":"array","items":{"type":"string"}}},"required":["text","competitors"],"additionalProperties":false}}},"required":["subcategory","answers","competitors","examples"],"additionalProperties":false},"description":"At most 2 example prompts a gap and 4 in all: the pitch’s prompts stay hidden."},"citation_gaps":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"answers":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["domain","answers"],"additionalProperties":false}},"site":{"anyOf":[{"type":"object","properties":{"bots":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"allowed":{"type":"boolean"}},"required":["name","allowed"],"additionalProperties":false}},{"type":"null"}]},"llms_txt":{"type":"boolean"}},"required":["bots","llms_txt"],"additionalProperties":false},{"type":"null"}],"description":"The prospect's robots.txt and llms.txt, once the first round read them."},"strategies":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"why":{"type":"string"},"action":{"type":"string"},"priority":{"type":"string","enum":["high","medium","low"]},"area":{"type":"string","enum":["content","citations","competitors","technical","reputation"]},"subcategories":{"type":"array","items":{"type":"string"}}},"required":["title","why","action","priority","area","subcategories"],"additionalProperties":false}},"failed_checks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"share_url":{"description":"The white-labelled report link (expires with it).","type":["string","null"]}},"required":["id","prospect_name","domain","summary","industry","competitors","status","checks_done","check_in_flight","next_check_at","prompts","engines","visibility","created_at","expires_at","converted_client_id","error","preliminary","headline","brands","by_engine","subcategories","gaps","citation_gaps","site","strategies","failed_checks","share_url"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/clients/{client_id}/audits":{"post":{"operationId":"startAudit","summary":"Start an audit","description":"Starts an AI-readiness audit of the client’s website: robots.txt for AI crawlers, llms.txt, and per-page checks. Each page checked uses one audit page of your monthly quota; unchanged pages are free.\n\nNeeds an API key with write access.","tags":["Audits"],"x-scope":"write","security":[{"bearerAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"},"description":"The client's id."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_pages":{"description":"1–500 pages (default 50), within your quota.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}}}}},"responses":{"202":{"description":"Accepted: started in the background.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"status":{"type":"string","description":"queued, running, done or failed."},"pages_requested":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pages_done":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pages_checked":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Pages checked this time (each used one audit page)."},"score":{"description":"0–100, or null until there is a scored page.","type":["number","null"]},"error":{"type":["string","null"]},"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":{"anyOf":[{"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))$"},{"type":"null"}]},"finished_at":{"anyOf":[{"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))$"},{"type":"null"}]},"site":{"type":"object","properties":{"source":{"anyOf":[{"type":"string","enum":["sitemap","links"]},{"type":"null"}]},"discovered":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"skipped_by_robots":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ai_crawlers":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"allowed":{"type":"boolean"}},"required":["name","allowed"],"additionalProperties":false}},{"type":"null"}]},"llms_txt":{"type":["boolean","null"]}},"required":["source","discovered","skipped_by_robots","ai_crawlers","llms_txt"],"additionalProperties":false},"issues":{"type":"array","items":{"type":"object","properties":{"check":{"type":"string"},"severity":{"type":"string","enum":["critical","high","medium","low"]},"title":{"type":"string"},"fix_hint":{"type":"string"},"site":{"type":"boolean","description":"A site-wide finding (robots.txt, llms.txt)."},"pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Findings of this check."},"findings":{"type":"array","items":{"type":"object","properties":{"url":{"type":["string","null"]},"message":{"type":"string"},"fix_hint":{"type":["string","null"]}},"required":["url","message","fix_hint"],"additionalProperties":false}}},"required":["check","severity","title","fix_hint","site","pages","findings"],"additionalProperties":false}},"pages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"state":{"type":"string"},"status_code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"score":{"type":["number","null"]},"renders_without_js":{"type":["boolean","null"]},"issues":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["url","state","status_code","score","renders_without_js","issues"],"additionalProperties":false}}},"required":["id","client_id","status","pages_requested","pages_done","pages_checked","score","error","created_at","started_at","finished_at","site","issues","pages"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"get":{"operationId":"listAudits","summary":"List audits","description":"A client’s audits, newest first.","tags":["Audits"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"},"description":"The client's id."},{"name":"cursor","in":"query","required":false,"schema":{"description":"From the previous page’s next_cursor.","type":"string","maxLength":500},"description":"From the previous page’s next_cursor."},{"name":"limit","in":"query","required":false,"schema":{"default":50,"description":"Items per page, 1–100 (default 50).","type":"integer","minimum":1,"maximum":100},"description":"Items per page, 1–100 (default 50)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"status":{"type":"string","description":"queued, running, done or failed."},"pages_requested":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pages_done":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pages_checked":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Pages checked this time (each used one audit page)."},"score":{"description":"0–100, or null until there is a scored page.","type":["number","null"]},"error":{"type":["string","null"]},"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":{"anyOf":[{"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))$"},{"type":"null"}]},"finished_at":{"anyOf":[{"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))$"},{"type":"null"}]}},"required":["id","client_id","status","pages_requested","pages_done","pages_checked","score","error","created_at","started_at","finished_at"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/audits/{audit_id}":{"get":{"operationId":"getAudit","summary":"Get an audit","description":"An audit’s status, score, site findings (AI crawlers, llms.txt), issues with fix hints, and pages. Pass audit_id, or client_id for the client’s latest audit.","tags":["Audits"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string"},"description":"The audit’s id."},{"name":"client_id","in":"query","required":false,"schema":{"description":"A client id: its latest audit.","type":"string"},"description":"A client id: its latest audit."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"status":{"type":"string","description":"queued, running, done or failed."},"pages_requested":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pages_done":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pages_checked":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Pages checked this time (each used one audit page)."},"score":{"description":"0–100, or null until there is a scored page.","type":["number","null"]},"error":{"type":["string","null"]},"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":{"anyOf":[{"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))$"},{"type":"null"}]},"finished_at":{"anyOf":[{"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))$"},{"type":"null"}]},"site":{"type":"object","properties":{"source":{"anyOf":[{"type":"string","enum":["sitemap","links"]},{"type":"null"}]},"discovered":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"skipped_by_robots":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ai_crawlers":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"allowed":{"type":"boolean"}},"required":["name","allowed"],"additionalProperties":false}},{"type":"null"}]},"llms_txt":{"type":["boolean","null"]}},"required":["source","discovered","skipped_by_robots","ai_crawlers","llms_txt"],"additionalProperties":false},"issues":{"type":"array","items":{"type":"object","properties":{"check":{"type":"string"},"severity":{"type":"string","enum":["critical","high","medium","low"]},"title":{"type":"string"},"fix_hint":{"type":"string"},"site":{"type":"boolean","description":"A site-wide finding (robots.txt, llms.txt)."},"pages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Findings of this check."},"findings":{"type":"array","items":{"type":"object","properties":{"url":{"type":["string","null"]},"message":{"type":"string"},"fix_hint":{"type":["string","null"]}},"required":["url","message","fix_hint"],"additionalProperties":false}}},"required":["check","severity","title","fix_hint","site","pages","findings"],"additionalProperties":false}},"pages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"state":{"type":"string"},"status_code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"score":{"type":["number","null"]},"renders_without_js":{"type":["boolean","null"]},"issues":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["url","state","status_code","score","renders_without_js","issues"],"additionalProperties":false}}},"required":["id","client_id","status","pages_requested","pages_done","pages_checked","score","error","created_at","started_at","finished_at","site","issues","pages"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/clients/{client_id}/reports":{"post":{"operationId":"createReport","summary":"Create a report","description":"A white-labelled client report: a share link to its live report over a trailing period (kind link, the default), or a PDF rendered in the background (kind pdf; read its status with GET /report-exports/{id}).\n\nNeeds an API key with write access.","tags":["Reports"],"x-scope":"write","security":[{"bearerAuth":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"},"description":"The client's id."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"description":"link (default) or pdf.","type":"string","enum":["link","pdf"]},"period":{"description":"7d, 30d (default), 90d or 12m.","type":"string","enum":["7d","30d","90d","12m"]},"expires_in_days":{"description":"link: stop working after 7, 30 or 90 days (default: never).","anyOf":[{"type":"number","const":7},{"type":"number","const":30},{"type":"number","const":90}]}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["link","pdf"]},"id":{"type":"string"},"period":{"type":"string","enum":["7d","30d","90d","12m"]},"url":{"description":"link: the share link (anyone with it sees the report).","type":["string","null"]},"expires_at":{"anyOf":[{"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))$"},{"type":"null"}],"description":"link: when it stops working, or null."},"status":{"description":"pdf: queued, rendering, ready or failed.","type":["string","null"]},"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))$"}},"required":["kind","id","period","url","expires_at","status","created_at"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/report-exports/{export_id}":{"get":{"operationId":"getReportExport","summary":"Get a PDF report","description":"A PDF report’s status, and its download URL once it is ready.","tags":["Reports"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"export_id","in":"path","required":true,"schema":{"type":"string"},"description":"The report export's id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"type":"string"},"status":{"type":"string","enum":["queued","rendering","ready","failed"]},"period":{"type":"string","enum":["7d","30d","90d","12m"]},"bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"error":{"type":["string","null"]},"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))$"},"finished_at":{"anyOf":[{"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))$"},{"type":"null"}]},"download_url":{"description":"Once ready: GET it with your API key.","type":["string","null"]}},"required":["id","client_id","status","period","bytes","error","created_at","finished_at","download_url"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/proposals/{proposal_id}":{"get":{"operationId":"getProposal","summary":"Get a proposal","description":"A change proposed through MCP or the Verte Engine: what it does, whether it is waiting, applied, cancelled, expired or failed, who proposed and decided it, and its result once applied.","tags":["Proposals"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"proposal_id","in":"path","required":true,"schema":{"type":"string"},"description":"The proposal's id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"client_id":{"description":"The client it changes; null for an org-wide change.","type":["string","null"]},"operation":{"type":"string","description":"The operation it runs when confirmed, e.g. addPrompts."},"channel":{"type":"string","enum":["engine","mcp","app"],"description":"Where it was proposed: engine, mcp or app."},"status":{"type":"string","enum":["pending","applying","applied","cancelled","expired","failed"],"description":"pending until confirmed or cancelled; expired after 24 hours waiting."},"summary":{"type":"string","description":"What confirming does, in one sentence."},"details":{"type":"object","properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The items it changes (at most 50)."},"effects":{"type":"array","items":{"type":"string"},"description":"What follows from it."},"warnings":{"type":"array","items":{"type":"string"},"description":"What to mind before confirming."}},"required":["lines","effects","warnings"],"additionalProperties":false},"proposed_by":{"type":"object","properties":{"kind":{"type":"string","enum":["user","api_key"]},"id":{"description":"null once that user or key is deleted.","type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},"decided_by":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["user","api_key"]},"id":{"description":"null once that user or key is deleted.","type":["string","null"]}},"required":["kind","id"],"additionalProperties":false},{"type":"null"}],"description":"Who confirmed or cancelled it; null while pending, or when Verte cancelled it (an Engine message that didn’t finish)."},"conversation_id":{"description":"The Verte Engine conversation it came from: null unless you are the conversation’s user (conversations are private), so always null for an API key.","type":["string","null"]},"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))$"},"expires_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))$"},"decided_at":{"anyOf":[{"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))$"},{"type":"null"}]},"result":{"description":"Once applied, the operation’s output (as its own endpoint returns it); else null."},"error":{"description":"Why it failed, or why Verte cancelled it (an Engine message that didn’t finish).","type":["string","null"]}},"required":["id","client_id","operation","channel","status","summary","details","proposed_by","decided_by","conversation_id","created_at","expires_at","decided_at","result","error"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/report-exports/{export_id}/pdf":{"get":{"operationId":"downloadReportPdf","summary":"Download a PDF report","description":"The finished PDF, once GET /report-exports/{export_id} says it is ready.","tags":["Reports"],"x-scope":"read","security":[{"bearerAuth":[]}],"parameters":[{"name":"export_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The PDF.","content":{"application/pdf":{"schema":{"type":"string","contentMediaType":"application/pdf"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key from Settings → API and MCP: vrt_live_…"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","examples":["quota_exceeded"]},"message":{"type":"string","description":"Plain language, safe to show people."}}}}}},"responses":{"BadRequest":{"description":"The input is invalid (validation_failed).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"No API key, or the key is invalid or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"QuotaExceeded":{"description":"A plan limit or this period’s quota is used up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The key can only read, or keys can’t do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Not found in your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Not possible right now (the PDF isn’t ready), or it clashes (a subcategory name the client has, a prompt it already tracks).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PayloadTooLarge":{"description":"The JSON body is over 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Over the rate limit (rate_limited).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before trying again.","schema":{"type":"integer"}}}}}}}