{"openapi":"3.1.0","info":{"title":"SEOmator API","version":"0.1.0"},"servers":[{"url":"https://api.seomator.com"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key"},"cookie":{"type":"apiKey","in":"cookie","name":"better-auth.session_token"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request","unauthorized","insufficient_credits","plan_limit","forbidden","not_found","conflict","rate_limit_exceeded","internal_server_error","service_unavailable"]},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Connection":{"type":"object","properties":{"id":{"type":"string"},"client":{"type":"string"},"domain":{"type":["string","null"]},"organization":{"type":["string","null"]},"scopes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"},"lastUsedAt":{"type":"string"}},"required":["id","client","domain","organization","scopes","createdAt","lastUsedAt"]}},"parameters":{}},"paths":{"/health":{"get":{"tags":["system"],"responses":{"200":{"description":"Service is up and reaches its database","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"env":{"type":"string"}},"required":["ok","env"]}}}}}}},"/v1/quick-look":{"post":{"tags":["quick look"],"summary":"Look up how AI assistants answer a domain’s buyers","description":"Public, no account. Checks the Turnstile token, then returns a cached look for the domain (7 days) or starts one. Each visitor can start 3 new domains a day, and a daily spend ceiling applies; past either, the answer is 429. Poll GET /v1/quick-look/{id}.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":3,"maxLength":253},"turnstileToken":{"type":"string","minLength":1,"maxLength":4096}},"required":["domain","turnstileToken"]}}}},"responses":{"202":{"description":"Started or cached","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"cached":{"type":"boolean"}},"required":["id","cached"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/quick-look/{id}":{"get":{"tags":["quick look"],"summary":"Read a quick look","description":"History lands within seconds; each AI answer fills in when it arrives. One answer per assistant is a sample, never a rate.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Quick look","content":{"application/json":{"schema":{"type":"object","properties":{"quickLook":{"type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string","enum":["running","done","failed"]},"error":{"type":["string","null"]},"brand":{"type":["string","null"]},"category":{"type":["string","null"]},"businessType":{"type":["string","null"]},"question":{"type":["string","null"]},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"}},"required":["name","domain"],"additionalProperties":{}}},"history":{"type":["object","null"],"properties":{"traffic":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"value":{"type":["number","null"]}},"required":["date","value"]}},"rating":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"value":{"type":["number","null"]}},"required":["date","value"]}},"authority":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"rating":{"type":["number","null"]},"authority":{"type":["number","null"]},"authorityHistory":{"type":"array","items":{"type":"number"}}},"required":["domain","rating","authority","authorityHistory"]}}},"required":["traffic","rating","authority"]},"answers":{"type":"array","items":{"type":"object","properties":{"assistant":{"type":"string","enum":["chatgpt","ai_mode","gemini"]},"status":{"type":"string","enum":["asking","done","failed"]},"error":{"type":["string","null"]},"text":{"type":["string","null"]},"brands":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"place":{"type":["number","null"]},"retrieved":{"type":"boolean"},"cited":{"type":"boolean"},"linked":{"type":"boolean"},"tracked":{"type":"boolean"}},"required":["name","place","retrieved","cited","linked","tracked"],"additionalProperties":{}}}},"required":["assistant","status","error","text","brands"],"additionalProperties":{}}},"expiresAt":{"type":"string"}},"required":["id","domain","status","error","brand","category","businessType","question","competitors","history","answers","expiresAt"],"additionalProperties":{}}},"required":["quickLook"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/unsubscribe":{"post":{"tags":["account"],"summary":"Stop the weekly digest from an email link","description":"Public. The token comes from the email: the one-click List-Unsubscribe header posts here, and the dashboard page posts here after the person confirms. Only turns the weekly digest off.","parameters":[{"schema":{"type":"string","minLength":16,"maxLength":128},"required":true,"name":"token","in":"query"}],"responses":{"204":{"description":"Unsubscribed"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me/email-preferences":{"get":{"tags":["account"],"summary":"Read the signed-in person’s email preferences","security":[{"apiKey":[]},{"cookie":[]}],"responses":{"200":{"description":"Preferences","content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","properties":{"weeklyDigest":{"type":"boolean"}},"required":["weeklyDigest"],"additionalProperties":{}}},"required":["preferences"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["account"],"summary":"Change the signed-in person’s email preferences","security":[{"apiKey":[]},{"cookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"weeklyDigest":{"type":"boolean"}},"required":["weeklyDigest"]}}}},"responses":{"200":{"description":"Preferences","content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","properties":{"weeklyDigest":{"type":"boolean"}},"required":["weeklyDigest"],"additionalProperties":{}}},"required":["preferences"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me/connections":{"get":{"tags":["account"],"summary":"List the apps connected to the signed-in person over MCP","security":[{"apiKey":[]},{"cookie":[]}],"responses":{"200":{"description":"Connected apps, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"connections":{"type":"array","items":{"$ref":"#/components/schemas/Connection"}}},"required":["connections"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me/connections/{id}":{"delete":{"tags":["account"],"summary":"Disconnect an app: revoke its grant and tokens","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Disconnected"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orgs":{"get":{"tags":["orgs"],"summary":"Organizations the caller can access","security":[{"apiKey":[]},{"cookie":[]}],"responses":{"200":{"description":"Organizations","content":{"application/json":{"schema":{"type":"object","properties":{"organizations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"}},"required":["id","name","slug"],"additionalProperties":{}}}},"required":["organizations"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orgs/{id}":{"delete":{"tags":["orgs"],"summary":"Delete an organization","description":"Owners only, and only without a live subscription. The organization disappears at once: its members, invitations and API keys are removed and its projects are deleted. Its data is erased in the background after one day.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects":{"get":{"tags":["projects"],"summary":"List projects, newest first","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["summary"],"description":"summary adds each project’s tracking state and its visibility over the last 7 days."},"required":false,"description":"summary adds each project’s tracking state and its visibility over the last 7 days.","name":"include","in":"query"}],"responses":{"200":{"description":"A page of projects","content":{"application/json":{"schema":{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"country":{"type":"string"},"language":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":["string","null"]},"businessType":{"type":["string","null"],"enum":["b2b_saas","consumer_software","ecommerce","marketplace","agency_services","local_business","publisher_media","other",null]},"products":{"type":"array","items":{"type":"string"}},"personas":{"type":"array","items":{"type":"string"}},"topicTerms":{"type":"object","properties":{"product":{"type":"array","items":{"type":"string"}},"adjacent":{"type":"array","items":{"type":"string"}},"exclude":{"type":"array","items":{"type":"string"}}},"required":["product","adjacent","exclude"],"additionalProperties":{}},"createdAt":{"type":"string"},"summary":{"type":["object","null"],"properties":{"tracking":{"type":"object","properties":{"status":{"type":"string","enum":["off","active","paused"]},"country":{"type":"string"},"language":{"type":"string"},"runAt":{"type":["string","null"]},"lastRunAt":{"type":["string","null"]}},"required":["status","country","language","runAt","lastRunAt"],"additionalProperties":{}},"visibility":{"type":"object","properties":{"named":{"type":"number"},"answers":{"type":"number"}},"required":["named","answers"],"additionalProperties":{}},"comparison":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["comparable","incomplete","scope_changed","no_previous","no_data"]},"current":{"type":"object","properties":{"named":{"type":"number"},"answers":{"type":"number"}},"required":["named","answers"],"additionalProperties":{}},"previous":{"type":"object","properties":{"named":{"type":"number"},"answers":{"type":"number"}},"required":["named","answers"],"additionalProperties":{}},"excludedAssistants":{"type":"array","items":{"type":"string"},"default":[]}},"required":["status","current","previous"],"additionalProperties":{}}},"required":["tracking","visibility","comparison"],"additionalProperties":{}}},"required":["id","organizationId","name","domain","country","language","description","category","businessType","products","personas","topicTerms","createdAt","summary"],"additionalProperties":{}}},"nextCursor":{"type":["string","null"]}},"required":["projects","nextCursor"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["projects"],"summary":"Create a project","security":[{"apiKey":[]},{"cookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"domain":{"type":"string"},"quickLookId":{"type":"string","maxLength":40}},"required":["name","domain"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"country":{"type":"string"},"language":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":["string","null"]},"businessType":{"type":["string","null"],"enum":["b2b_saas","consumer_software","ecommerce","marketplace","agency_services","local_business","publisher_media","other",null]},"products":{"type":"array","items":{"type":"string"}},"personas":{"type":"array","items":{"type":"string"}},"topicTerms":{"type":"object","properties":{"product":{"type":"array","items":{"type":"string"}},"adjacent":{"type":"array","items":{"type":"string"}},"exclude":{"type":"array","items":{"type":"string"}}},"required":["product","adjacent","exclude"],"additionalProperties":{}},"createdAt":{"type":"string"}},"required":["id","organizationId","name","domain","country","language","description","category","businessType","products","personas","topicTerms","createdAt"],"additionalProperties":{}}},"required":["project"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}":{"get":{"tags":["projects"],"summary":"Get a project","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"responses":{"200":{"description":"Project","content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"country":{"type":"string"},"language":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":["string","null"]},"businessType":{"type":["string","null"],"enum":["b2b_saas","consumer_software","ecommerce","marketplace","agency_services","local_business","publisher_media","other",null]},"products":{"type":"array","items":{"type":"string"}},"personas":{"type":"array","items":{"type":"string"}},"topicTerms":{"type":"object","properties":{"product":{"type":"array","items":{"type":"string"}},"adjacent":{"type":"array","items":{"type":"string"}},"exclude":{"type":"array","items":{"type":"string"}}},"required":["product","adjacent","exclude"],"additionalProperties":{}},"createdAt":{"type":"string"}},"required":["id","organizationId","name","domain","country","language","description","category","businessType","products","personas","topicTerms","createdAt"],"additionalProperties":{}}},"required":["project"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["projects"],"summary":"Change a project’s name or profile","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":["string","null"],"minLength":1,"maxLength":500},"category":{"type":["string","null"],"minLength":1,"maxLength":100},"businessType":{"type":["string","null"],"enum":["b2b_saas","consumer_software","ecommerce","marketplace","agency_services","local_business","publisher_media","other",null]},"products":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":20},"personas":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":20},"topicTerms":{"type":"object","properties":{"product":{"type":"array","items":{"type":"string","minLength":2,"maxLength":60},"minItems":1,"maxItems":8},"adjacent":{"type":"array","items":{"type":"string","minLength":2,"maxLength":60},"maxItems":12},"exclude":{"type":"array","items":{"type":"string","minLength":2,"maxLength":60},"maxItems":20}},"required":["product","adjacent","exclude"]}}}}}},"responses":{"200":{"description":"Updated project","content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"country":{"type":"string"},"language":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":["string","null"]},"businessType":{"type":["string","null"],"enum":["b2b_saas","consumer_software","ecommerce","marketplace","agency_services","local_business","publisher_media","other",null]},"products":{"type":"array","items":{"type":"string"}},"personas":{"type":"array","items":{"type":"string"}},"topicTerms":{"type":"object","properties":{"product":{"type":"array","items":{"type":"string"}},"adjacent":{"type":"array","items":{"type":"string"}},"exclude":{"type":"array","items":{"type":"string"}}},"required":["product","adjacent","exclude"],"additionalProperties":{}},"createdAt":{"type":"string"}},"required":["id","organizationId","name","domain","country","language","description","category","businessType","products","personas","topicTerms","createdAt"],"additionalProperties":{}}},"required":["project"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["projects"],"summary":"Delete a project (soft delete)","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/brands":{"get":{"tags":["ai visibility"],"summary":"List the project’s own brand and tracked competitors","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"responses":{"200":{"description":"Brands","content":{"application/json":{"schema":{"type":"object","properties":{"brands":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["own","competitor"]},"aliases":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":100},"caseSensitive":{"type":"boolean"},"accentInsensitive":{"type":"boolean"},"ambiguous":{"type":"boolean"},"generated":{"type":"boolean"}},"required":["text","caseSensitive","accentInsensitive","ambiguous","generated"],"additionalProperties":{}}},"domains":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["profile","labs","llm_mentions","answers","user"]},"reason":{"type":["string","null"]},"sharedKeywords":{"type":["integer","null"]},"createdAt":{"type":"string"}},"required":["id","projectId","name","role","aliases","domains","source","reason","sharedKeywords","createdAt"],"additionalProperties":{}}}},"required":["brands"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["ai visibility"],"summary":"Track a brand","description":"Saved answers are scanned again in the background, so the brand’s history appears without new collection.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"role":{"type":"string","enum":["own","competitor"],"default":"competitor"},"aliases":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":100},"caseSensitive":{"type":"boolean"},"accentInsensitive":{"type":"boolean"},"ambiguous":{"type":"boolean"},"generated":{"type":"boolean"}},"required":["text"]},"maxItems":20},"domains":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":10,"description":"Its sites, at least one: citations count through them"}},"required":["name","domains"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["own","competitor"]},"aliases":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":100},"caseSensitive":{"type":"boolean"},"accentInsensitive":{"type":"boolean"},"ambiguous":{"type":"boolean"},"generated":{"type":"boolean"}},"required":["text","caseSensitive","accentInsensitive","ambiguous","generated"],"additionalProperties":{}}},"domains":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["profile","labs","llm_mentions","answers","user"]},"reason":{"type":["string","null"]},"sharedKeywords":{"type":["integer","null"]},"createdAt":{"type":"string"}},"required":["id","projectId","name","role","aliases","domains","source","reason","sharedKeywords","createdAt"],"additionalProperties":{}}},"required":["brand"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/brands/{brandId}":{"patch":{"tags":["ai visibility"],"summary":"Change a brand’s name, aliases or domains","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Brand id (brd_…)."},"required":true,"description":"Brand id (brd_…).","name":"brandId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"aliases":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":100},"caseSensitive":{"type":"boolean"},"accentInsensitive":{"type":"boolean"},"ambiguous":{"type":"boolean"},"generated":{"type":"boolean"}},"required":["text"]},"maxItems":20},"domains":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":10,"description":"Its sites, at least one: citations count through them"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["own","competitor"]},"aliases":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":100},"caseSensitive":{"type":"boolean"},"accentInsensitive":{"type":"boolean"},"ambiguous":{"type":"boolean"},"generated":{"type":"boolean"}},"required":["text","caseSensitive","accentInsensitive","ambiguous","generated"],"additionalProperties":{}}},"domains":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["profile","labs","llm_mentions","answers","user"]},"reason":{"type":["string","null"]},"sharedKeywords":{"type":["integer","null"]},"createdAt":{"type":"string"}},"required":["id","projectId","name","role","aliases","domains","source","reason","sharedKeywords","createdAt"],"additionalProperties":{}}},"required":["brand"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["ai visibility"],"summary":"Stop tracking a competitor and remove its counts","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Brand id (brd_…)."},"required":true,"description":"Brand id (brd_…).","name":"brandId","in":"path"}],"responses":{"204":{"description":"Deleted"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/brand-suggestions":{"get":{"tags":["ai visibility"],"summary":"List brands the answers name that the project does not track","description":"Open suggestions, most answers first. Each name was found by a model and its quote checked against the answer.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"responses":{"200":{"description":"Suggestions","content":{"application/json":{"schema":{"type":"object","properties":{"suggestions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"answers":{"type":"integer"},"quote":{"type":"string"},"domain":{"type":"string","description":"The brand's site, from the answer's sources"},"createdAt":{"type":"string"}},"required":["id","name","answers","quote","domain","createdAt"],"additionalProperties":{}}}},"required":["suggestions"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/brand-suggestions/{suggestionId}/accept":{"post":{"tags":["ai visibility"],"summary":"Track a suggested brand as a competitor","description":"Creates the competitor and scans the saved answers again, so its history appears at once.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Suggestion id (bsug_…)."},"required":true,"description":"Suggestion id (bsug_…).","name":"suggestionId","in":"path"}],"responses":{"201":{"description":"Tracked","content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["own","competitor"]},"aliases":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":100},"caseSensitive":{"type":"boolean"},"accentInsensitive":{"type":"boolean"},"ambiguous":{"type":"boolean"},"generated":{"type":"boolean"}},"required":["text","caseSensitive","accentInsensitive","ambiguous","generated"],"additionalProperties":{}}},"domains":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["profile","labs","llm_mentions","answers","user"]},"reason":{"type":["string","null"]},"sharedKeywords":{"type":["integer","null"]},"createdAt":{"type":"string"}},"required":["id","projectId","name","role","aliases","domains","source","reason","sharedKeywords","createdAt"],"additionalProperties":{}}},"required":["brand"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/brand-suggestions/{suggestionId}/dismiss":{"post":{"tags":["ai visibility"],"summary":"Hide a suggested brand","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Suggestion id (bsug_…)."},"required":true,"description":"Suggestion id (bsug_…).","name":"suggestionId","in":"path"}],"responses":{"204":{"description":"Dismissed"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/gsc":{"get":{"tags":["ai visibility"],"summary":"Read the Search Console connection","description":"status is none before a connection and error when Google no longer grants access. Read from our database only; list the properties with GET /gsc/properties.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"responses":{"200":{"description":"Connection","content":{"application/json":{"schema":{"type":"object","properties":{"gsc":{"type":"object","properties":{"status":{"type":"string","enum":["none","active","error"]},"property":{"type":["string","null"]}},"required":["status","property"],"additionalProperties":{}}},"required":["gsc"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["ai visibility"],"summary":"Pick the Search Console property","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"property":{"type":"string","minLength":1,"maxLength":500}},"required":["property"]}}}},"responses":{"200":{"description":"Connection","content":{"application/json":{"schema":{"type":"object","properties":{"gsc":{"type":"object","properties":{"status":{"type":"string","enum":["none","active","error"]},"property":{"type":["string","null"]}},"required":["status","property"],"additionalProperties":{}}},"required":["gsc"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["ai visibility"],"summary":"Disconnect Search Console and revoke its token","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"responses":{"204":{"description":"Disconnected"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/gsc/properties":{"get":{"tags":["ai visibility"],"summary":"List the Search Console properties of the project domain and its subdomains that the connection can read","description":"Asks Google, so it needs the right to change the project. 503 when Google does not answer.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"responses":{"200":{"description":"Properties","content":{"application/json":{"schema":{"type":"object","properties":{"properties":{"type":"array","items":{"type":"string"}}},"required":["properties"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/gsc/authorize":{"post":{"tags":["ai visibility"],"summary":"Start connecting Search Console","description":"Returns the Google consent URL. Google sends the person back to the dashboard, which returns them to returnTo.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"returnTo":{"type":"string","maxLength":500}},"required":["returnTo"]}}}},"responses":{"200":{"description":"Consent URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/gsc/query":{"post":{"tags":["search console"],"summary":"Query Search Console clicks, impressions, CTR and position","description":"Groups by `dimensions` (query, page, country, device, searchAppearance, date) over `startDate`–`endDate` (default: the last 28 final days, ending 3 days ago). `totals` cover every row; page with `limit` and `nextCursor`.\n\nReads only the project country unless `country` is `all`. 409 when Search Console is not connected or access was lost; 503 when Google does not answer. Answers are cached a day (an hour with `fresh` and for inspections).","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dimensions":{"type":"array","items":{"type":"string","enum":["query","page","country","device","searchAppearance","date"]},"maxItems":4,"default":["query"],"description":"Group rows by these; an empty list gives the totals only."},"startDate":{"type":"string","format":"date","description":"First day (YYYY-MM-DD, Pacific time). Defaults to 28 days before endDate."},"endDate":{"type":"string","format":"date","description":"Last day (YYYY-MM-DD). Defaults to 3 days ago, the last final day."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country, e.g. tr. Defaults to the project country; all reads every country."},"filters":{"type":"array","items":{"type":"object","properties":{"dimension":{"type":"string","enum":["query","page","country","device","searchAppearance"]},"operator":{"type":"string","enum":["equals","notEquals","contains","notContains","includingRegex","excludingRegex"],"default":"contains"},"expression":{"type":"string","minLength":1,"maxLength":4096,"description":"Text to match; a country is an alpha-2 code, a device DESKTOP, MOBILE or TABLET, a regex uses RE2 syntax."}},"required":["dimension","expression"]},"maxItems":10,"default":[]},"type":{"type":"string","enum":["web","image","video","news","discover","googleNews"],"default":"web"},"fresh":{"type":"boolean","default":false,"description":"Include the last 2–3 days, which Google is still counting."},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":100,"description":"Rows per page, most clicks first, as Google orders them."},"cursor":{"type":"string"}}}}}},"responses":{"200":{"description":"Rows","content":{"application/json":{"schema":{"type":"object","properties":{"property":{"type":"string"},"country":{"type":["string","null"]},"type":{"type":"string","enum":["web","image","video","news","discover","googleNews"]},"period":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":{}},"totals":{"type":"object","properties":{"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number"},"position":{"type":"number"}},"required":["clicks","impressions","ctr","position"],"additionalProperties":{}},"rows":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"page":{"type":"string"},"country":{"type":"string"},"device":{"type":"string"},"searchAppearance":{"type":"string"},"date":{"type":"string"},"clicks":{"type":"number"},"impressions":{"type":"number"},"ctr":{"type":"number"},"position":{"type":"number"}},"required":["clicks","impressions","ctr","position"],"additionalProperties":{}}},"nextCursor":{"type":["string","null"]}},"required":["property","country","type","period","totals","rows","nextCursor"],"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/gsc/inspect":{"post":{"tags":["search console"],"summary":"Inspect one URL with Search Console URL Inspection","description":"Index status, last crawl, canonical, mobile usability and rich results for a URL on the project domain.\n\nReads only the project country unless `country` is `all`. 409 when Search Console is not connected or access was lost; 503 when Google does not answer. Answers are cached a day (an hour with `fresh` and for inspections).","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"A full URL on the project domain."}},"required":["url"]}}}},"responses":{"200":{"description":"Inspection","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"property":{"type":"string"},"link":{"type":["string","null"]},"index":{"type":["object","null"],"properties":{},"additionalProperties":{}},"mobileUsability":{"type":["object","null"],"properties":{},"additionalProperties":{}},"richResults":{"type":["object","null"],"properties":{},"additionalProperties":{}}},"required":["url","property","link","index","mobileUsability","richResults"],"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/gsc/sitemaps":{"get":{"tags":["search console"],"summary":"List the sitemaps submitted in Search Console","description":"Each sitemap with when Google last read it, how many URLs it lists and its warning and error counts.\n\nReads only the project country unless `country` is `all`. 409 when Search Console is not connected or access was lost; 503 when Google does not answer. Answers are cached a day (an hour with `fresh` and for inspections).","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"responses":{"200":{"description":"Sitemaps","content":{"application/json":{"schema":{"type":"object","properties":{"property":{"type":"string"},"sitemaps":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"lastSubmitted":{"type":["string","null"]},"lastDownloaded":{"type":["string","null"]},"pending":{"type":"boolean"},"index":{"type":"boolean"},"warnings":{"type":"number"},"errors":{"type":"number"},"submitted":{"type":"number"}},"required":["path","lastSubmitted","lastDownloaded","pending","index","warnings","errors","submitted"],"additionalProperties":{}}}},"required":["property","sitemaps"],"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/keywords":{"get":{"tags":["ai visibility"],"summary":"List the project’s keywords","description":"Most clicks first, then most searched. position comes only from Search Console; without it the position is null, because DataForSEO Labs positions lag and count removed pages.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"responses":{"200":{"description":"Keywords","content":{"application/json":{"schema":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"source":{"type":"string","enum":["gsc","labs_ranked","labs_gap","labs_ideas","user"]},"volume":{"type":["integer","null"]},"position":{"type":["integer","null"]},"url":{"type":["string","null"]},"clicks":{"type":["integer","null"]},"topic":{"type":"string","enum":["product","adjacent","off"]},"status":{"type":"string","enum":["active","archived"]},"archivedAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","text","source","volume","position","url","clicks","topic","status","archivedAt","createdAt"],"additionalProperties":{}}}},"required":["keywords"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["ai visibility"],"summary":"Add a keyword","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":200}},"required":["text"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"keyword":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"source":{"type":"string","enum":["gsc","labs_ranked","labs_gap","labs_ideas","user"]},"volume":{"type":["integer","null"]},"position":{"type":["integer","null"]},"url":{"type":["string","null"]},"clicks":{"type":["integer","null"]},"topic":{"type":"string","enum":["product","adjacent","off"]},"status":{"type":"string","enum":["active","archived"]},"archivedAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","text","source","volume","position","url","clicks","topic","status","archivedAt","createdAt"],"additionalProperties":{}}},"required":["keyword"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/keywords/{keywordId}":{"delete":{"tags":["ai visibility"],"summary":"Remove a keyword","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Keyword id (kw_…)."},"required":true,"description":"Keyword id (kw_…).","name":"keywordId","in":"path"}],"responses":{"204":{"description":"Deleted"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/keywords/{keywordId}/reactivate":{"post":{"tags":["ai visibility"],"summary":"Bring back a keyword archived when the plan dropped to Free","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Keyword id (kw_…)."},"required":true,"description":"Keyword id (kw_…).","name":"keywordId","in":"path"}],"responses":{"200":{"description":"Keyword","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"source":{"type":"string","enum":["gsc","labs_ranked","labs_gap","labs_ideas","user"]},"volume":{"type":["integer","null"]},"position":{"type":["integer","null"]},"url":{"type":["string","null"]},"clicks":{"type":["integer","null"]},"topic":{"type":"string","enum":["product","adjacent","off"]},"status":{"type":"string","enum":["active","archived"]},"archivedAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","text","source","volume","position","url","clicks","topic","status","archivedAt","createdAt"],"additionalProperties":{}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/chats":{"get":{"tags":["agent"],"summary":"List your agent chats in this project, latest first","description":"Chats belong to the signed-in person; an API key gets 403. Deleted chats are left out.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"A page of chats","content":{"application/json":{"schema":{"type":"object","properties":{"chats":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","createdAt","updatedAt"],"additionalProperties":{}}},"nextCursor":{"type":["string","null"]}},"required":["chats","nextCursor"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/chats/{chatId}":{"get":{"tags":["agent"],"summary":"Read a chat with its messages","description":"Messages come back as AI SDK UI messages: each saved tool call as a dynamic-tool part, then the text. metadata.status is streaming, complete, aborted or failed; a reply still streaming after 15 minutes reads as aborted.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Chat id (chat_…)."},"required":true,"description":"Chat id (chat_…).","name":"chatId","in":"path"}],"responses":{"200":{"description":"The chat","content":{"application/json":{"schema":{"type":"object","properties":{"chat":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","createdAt","updatedAt"],"additionalProperties":{}},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["user","assistant"]},"metadata":{"type":"object","properties":{"status":{"type":"string","enum":["streaming","complete","aborted","failed"]}},"required":["status"],"additionalProperties":{}},"parts":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"}},"required":["type"],"additionalProperties":{}}}},"required":["id","role","metadata","parts"],"additionalProperties":{}}}},"required":["chat","messages"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["agent"],"summary":"Rename a chat","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Chat id (chat_…)."},"required":true,"description":"Chat id (chat_…).","name":"chatId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200}},"required":["title"]}}}},"responses":{"200":{"description":"Renamed","content":{"application/json":{"schema":{"type":"object","properties":{"chat":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","createdAt","updatedAt"],"additionalProperties":{}}},"required":["chat"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["agent"],"summary":"Delete a chat","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Chat id (chat_…)."},"required":true,"description":"Chat id (chat_…).","name":"chatId","in":"path"}],"responses":{"204":{"description":"Deleted"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/topics":{"get":{"tags":["ai visibility"],"summary":"List prompt topics","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"responses":{"200":{"description":"Topics","content":{"application/json":{"schema":{"type":"object","properties":{"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"name":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","projectId","name","createdAt"],"additionalProperties":{}}}},"required":["topics"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["ai visibility"],"summary":"Create a topic","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"topic":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"name":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","projectId","name","createdAt"],"additionalProperties":{}}},"required":["topic"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/topics/{topicId}":{"patch":{"tags":["ai visibility"],"summary":"Rename a topic; its history follows","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Topic id (top_…)."},"required":true,"description":"Topic id (top_…).","name":"topicId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80}},"required":["name"]}}}},"responses":{"200":{"description":"Renamed","content":{"application/json":{"schema":{"type":"object","properties":{"topic":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"name":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","projectId","name","createdAt"],"additionalProperties":{}}},"required":["topic"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["ai visibility"],"summary":"Delete a topic; its prompts keep running without one","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Topic id (top_…)."},"required":true,"description":"Topic id (top_…).","name":"topicId","in":"path"}],"responses":{"204":{"description":"Deleted"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/prompts":{"get":{"tags":["ai visibility"],"summary":"List prompts, newest first","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["active","archived"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"topicId","in":"query"}],"responses":{"200":{"description":"A page of prompts","content":{"application/json":{"schema":{"type":"object","properties":{"prompts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"topicId":{"type":["string","null"]},"text":{"type":"string"},"intent":{"type":"string","enum":["informational","commercial","transactional"]},"branded":{"type":"boolean"},"source":{"type":"string","enum":["suggested","ai_search_data","gsc","user","quick_look"]},"status":{"type":"string","enum":["active","archived"]},"replacesPromptId":{"type":["string","null"]},"createdAt":{"type":"string"},"archivedAt":{"type":["string","null"]}},"required":["id","projectId","topicId","text","intent","branded","source","status","replacesPromptId","createdAt","archivedAt"],"additionalProperties":{}}},"nextCursor":{"type":["string","null"]}},"required":["prompts","nextCursor"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["ai visibility"],"summary":"Add an active prompt","description":"Active prompts past the plan’s prompt allowance are answered on credits.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":3,"maxLength":1000},"topicId":{"type":["string","null"],"default":null},"intent":{"type":"string","enum":["informational","commercial","transactional"]}},"required":["text","intent"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"topicId":{"type":["string","null"]},"text":{"type":"string"},"intent":{"type":"string","enum":["informational","commercial","transactional"]},"branded":{"type":"boolean"},"source":{"type":"string","enum":["suggested","ai_search_data","gsc","user","quick_look"]},"status":{"type":"string","enum":["active","archived"]},"replacesPromptId":{"type":["string","null"]},"createdAt":{"type":"string"},"archivedAt":{"type":["string","null"]}},"required":["id","projectId","topicId","text","intent","branded","source","status","replacesPromptId","createdAt","archivedAt"],"additionalProperties":{}}},"required":["prompt"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/prompts/suggestions":{"post":{"tags":["ai visibility"],"summary":"Suggest prompts","description":"Writes new prompt texts for one topic, intent and branding with AI, without saving them. Branding is checked against the own brand, and texts that repeat a prompt of the project are left out, so fewer than `count` can come back. Costs no credits.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"intent":{"type":"string","enum":["informational","commercial","transactional"]},"branded":{"type":"boolean","default":false,"description":"Whether every suggestion names the own brand"},"topicId":{"type":["string","null"],"description":"Topic to write for; omitted means the project as a whole"},"count":{"type":"integer","minimum":1,"maximum":10,"default":5}},"required":["intent"]}}}},"responses":{"200":{"description":"Suggestions","content":{"application/json":{"schema":{"type":"object","properties":{"suggestions":{"type":"array","items":{"type":"string"},"description":"New prompt texts, not yet saved; none repeats a prompt"}},"required":["suggestions"],"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/prompts/{promptId}":{"patch":{"tags":["ai visibility"],"summary":"Change a prompt","description":"Changing the text archives this prompt with its history and returns the new prompt that replaces it.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Prompt id (prm_…)."},"required":true,"description":"Prompt id (prm_…).","name":"promptId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":3,"maxLength":1000},"topicId":{"type":["string","null"],"default":null},"intent":{"type":"string","enum":["informational","commercial","transactional"]}}}}}},"responses":{"200":{"description":"The prompt, or its replacement","content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"topicId":{"type":["string","null"]},"text":{"type":"string"},"intent":{"type":"string","enum":["informational","commercial","transactional"]},"branded":{"type":"boolean"},"source":{"type":"string","enum":["suggested","ai_search_data","gsc","user","quick_look"]},"status":{"type":"string","enum":["active","archived"]},"replacesPromptId":{"type":["string","null"]},"createdAt":{"type":"string"},"archivedAt":{"type":["string","null"]}},"required":["id","projectId","topicId","text","intent","branded","source","status","replacesPromptId","createdAt","archivedAt"],"additionalProperties":{}}},"required":["prompt"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["ai visibility"],"summary":"One prompt, active or archived","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Prompt id (prm_…)."},"required":true,"description":"Prompt id (prm_…).","name":"promptId","in":"path"}],"responses":{"200":{"description":"Prompt","content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"topicId":{"type":["string","null"]},"text":{"type":"string"},"intent":{"type":"string","enum":["informational","commercial","transactional"]},"branded":{"type":"boolean"},"source":{"type":"string","enum":["suggested","ai_search_data","gsc","user","quick_look"]},"status":{"type":"string","enum":["active","archived"]},"replacesPromptId":{"type":["string","null"]},"createdAt":{"type":"string"},"archivedAt":{"type":["string","null"]}},"required":["id","projectId","topicId","text","intent","branded","source","status","replacesPromptId","createdAt","archivedAt"],"additionalProperties":{}}},"required":["prompt"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["ai visibility"],"summary":"Delete a prompt and all its answers: an archived one, or any while tracking has not started","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Prompt id (prm_…)."},"required":true,"description":"Prompt id (prm_…).","name":"promptId","in":"path"}],"responses":{"204":{"description":"Deleted"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/prompts/{promptId}/archive":{"post":{"tags":["ai visibility"],"summary":"Stop running a prompt and keep its history","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Prompt id (prm_…)."},"required":true,"description":"Prompt id (prm_…).","name":"promptId","in":"path"}],"responses":{"200":{"description":"Archived","content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"topicId":{"type":["string","null"]},"text":{"type":"string"},"intent":{"type":"string","enum":["informational","commercial","transactional"]},"branded":{"type":"boolean"},"source":{"type":"string","enum":["suggested","ai_search_data","gsc","user","quick_look"]},"status":{"type":"string","enum":["active","archived"]},"replacesPromptId":{"type":["string","null"]},"createdAt":{"type":"string"},"archivedAt":{"type":["string","null"]}},"required":["id","projectId","topicId","text","intent","branded","source","status","replacesPromptId","createdAt","archivedAt"],"additionalProperties":{}}},"required":["prompt"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/prompts/{promptId}/reactivate":{"post":{"tags":["ai visibility"],"summary":"Run an archived prompt again","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Prompt id (prm_…)."},"required":true,"description":"Prompt id (prm_…).","name":"promptId","in":"path"}],"responses":{"200":{"description":"Active","content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"topicId":{"type":["string","null"]},"text":{"type":"string"},"intent":{"type":"string","enum":["informational","commercial","transactional"]},"branded":{"type":"boolean"},"source":{"type":"string","enum":["suggested","ai_search_data","gsc","user","quick_look"]},"status":{"type":"string","enum":["active","archived"]},"replacesPromptId":{"type":["string","null"]},"createdAt":{"type":"string"},"archivedAt":{"type":["string","null"]}},"required":["id","projectId","topicId","text","intent","branded","source","status","replacesPromptId","createdAt","archivedAt"],"additionalProperties":{}}},"required":["prompt"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/runs/latest":{"get":{"tags":["ai visibility"],"summary":"Progress of the latest daily run","description":"Counts of the answers planned for the latest run date: collected (returned by the assistant), analyzed (counted in the reports), failed (failed or of unknown outcome) and open (still being collected), in total and per assistant. `run` is null before the first run. `status` is `running` while any answer is open.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"responses":{"200":{"description":"Latest run","content":{"application/json":{"schema":{"type":"object","properties":{"run":{"type":["object","null"],"properties":{"runDate":{"type":"string"},"firstRun":{"type":"boolean","description":"True when this is the project's first day of answers"},"status":{"type":"string","enum":["running","done"],"description":"done once no answer is still being collected or waiting for analysis"},"planned":{"type":"number"},"collected":{"type":"number","description":"Answers the assistant returned"},"analyzed":{"type":"number","description":"Answers read and counted in the reports"},"failed":{"type":"number","description":"Answers that will not arrive: failed or of unknown outcome"},"open":{"type":"number","description":"Answers still being collected"},"analyzing":{"type":"number","description":"Answers collected and still waiting for analysis"},"assistants":{"type":"array","items":{"type":"object","properties":{"assistant":{"type":"string","enum":["chatgpt","ai_mode","gemini"]},"planned":{"type":"number"},"collected":{"type":"number","description":"Answers the assistant returned"},"analyzed":{"type":"number","description":"Answers read and counted in the reports"},"failed":{"type":"number","description":"Answers that will not arrive: failed or of unknown outcome"},"open":{"type":"number","description":"Answers still being collected"},"analyzing":{"type":"number","description":"Answers collected and still waiting for analysis"}},"required":["assistant","planned","collected","analyzed","failed","open","analyzing"],"additionalProperties":{}}}},"required":["runDate","firstRun","status","planned","collected","analyzed","failed","open","analyzing","assistants"],"additionalProperties":{}}},"required":["run"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/tracking":{"get":{"tags":["ai visibility"],"summary":"Daily tracking settings","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"object","properties":{"status":{"type":"string","enum":["off","active","paused"]},"country":{"type":"string"},"language":{"type":"string"},"runAt":{"type":["string","null"]},"lastRunAt":{"type":["string","null"]}},"required":["status","country","language","runAt","lastRunAt"],"additionalProperties":{}}},"required":["tracking"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["ai visibility"],"summary":"Start, pause or change daily tracking","description":"Setting `status` to `active` collects answers at once and sets `runAt` to now; later days run at the same UTC time.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["off","active","paused"]},"country":{"type":"string"},"language":{"type":"string"}}}}}},"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"object","properties":{"status":{"type":"string","enum":["off","active","paused"]},"country":{"type":"string"},"language":{"type":"string"},"runAt":{"type":["string","null"]},"lastRunAt":{"type":["string","null"]}},"required":["status","country","language","runAt","lastRunAt"],"additionalProperties":{}}},"required":["tracking"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/onboarding":{"get":{"tags":["ai visibility"],"summary":"The latest job of each onboarding step","description":"Each step is null until it first runs. A `queued` or `running` job is the step in progress: poll it with `GET /v1/jobs/{id}`, for example after a page reload. `research` is null until the latest keyword research is done; then it counts the competitors it confirmed (a profile competitor got a research reason) and added (from DataForSEO Labs or recorded AI answers) that are still on the list.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"responses":{"200":{"description":"Latest jobs","content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"type":["object","null"],"properties":{"id":{"type":"string"},"projectId":{"type":"string"},"type":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","failed"]},"error":{"type":["string","null"]},"chunksTotal":{"type":"number"},"chunksDone":{"type":"number"},"createdAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]}},"required":["id","projectId","type","status","error","chunksTotal","chunksDone","createdAt","startedAt","finishedAt"],"additionalProperties":{}},"keywords":{"type":["object","null"],"properties":{"id":{"type":"string"},"projectId":{"type":"string"},"type":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","failed"]},"error":{"type":["string","null"]},"chunksTotal":{"type":"number"},"chunksDone":{"type":"number"},"createdAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]}},"required":["id","projectId","type","status","error","chunksTotal","chunksDone","createdAt","startedAt","finishedAt"],"additionalProperties":{}},"prompts":{"type":["object","null"],"properties":{"id":{"type":"string"},"projectId":{"type":"string"},"type":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","failed"]},"error":{"type":["string","null"]},"chunksTotal":{"type":"number"},"chunksDone":{"type":"number"},"createdAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]}},"required":["id","projectId","type","status","error","chunksTotal","chunksDone","createdAt","startedAt","finishedAt"],"additionalProperties":{}},"research":{"type":["object","null"],"properties":{"confirmed":{"type":"integer"},"added":{"type":"integer"}},"required":["confirmed","added"]}},"required":["profile","keywords","prompts","research"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/onboarding/profile":{"post":{"tags":["ai visibility"],"summary":"Propose the profile and competitors from the site","description":"Reads the site, then writes the profile (description, category, business type, products, personas, country, language), the own brand and the competitors. Running it again replaces them. When the site cannot be read the job fails with `site_unreadable`: set `description` on the project and run it again. One step runs at a time per project, and only before tracking starts. Follow the job with `GET /v1/jobs/{id}`.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"responses":{"202":{"description":"The step is queued","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"type":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","failed"]},"error":{"type":["string","null"]},"chunksTotal":{"type":"number"},"chunksDone":{"type":"number"},"createdAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]}},"required":["id","projectId","type","status","error","chunksTotal","chunksDone","createdAt","startedAt","finishedAt"],"additionalProperties":{}}},"required":["job"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/onboarding/keywords":{"post":{"tags":["ai visibility"],"summary":"Find keywords and more competitors","description":"Reads Search Console when it is connected, otherwise DataForSEO Labs, and writes up to 50 keywords with their volume and position. Adds competitors that rank for the same keywords or are named next to the brand in recorded AI answers, each with its reason. Running it again replaces what it wrote; keywords and competitors you added stay. One step runs at a time per project, and only before tracking starts. Follow the job with `GET /v1/jobs/{id}`.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"responses":{"202":{"description":"The step is queued","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"type":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","failed"]},"error":{"type":["string","null"]},"chunksTotal":{"type":"number"},"chunksDone":{"type":"number"},"createdAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]}},"required":["id","projectId","type","status","error","chunksTotal","chunksDone","createdAt","startedAt","finishedAt"],"additionalProperties":{}}},"required":["job"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/onboarding/prompts":{"post":{"tags":["ai visibility"],"summary":"Propose topics and prompts from the profile","description":"Writes 25 prompts across 3 to 6 topics from the profile, the own brand, the competitors and the keywords. Questions seen in recorded AI answers keep their wording and the source `ai_search_data`. Running it again replaces every topic and prompt. One step runs at a time per project, and only before tracking starts. Follow the job with `GET /v1/jobs/{id}`.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"responses":{"202":{"description":"The step is queued","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"type":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","failed"]},"error":{"type":["string","null"]},"chunksTotal":{"type":"number"},"chunksDone":{"type":"number"},"createdAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]}},"required":["id","projectId","type","status","error","chunksTotal","chunksDone","createdAt","startedAt","finishedAt"],"additionalProperties":{}}},"required":["job"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/trend-markers":{"get":{"tags":["ai visibility"],"summary":"Days the measurement changed","description":"Marks for trend charts. One kind is the day an assistant’s main model changed: the model of more than half of its answers that day moved from one known model to another. A day without such a model is skipped, and so are unknown models. The other kind is the days prompts were added or archived after tracking started. With `promptId`, only the model changes in that prompt’s answers are returned.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","format":"date","description":"First day (UTC)"},"required":true,"description":"First day (UTC)","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date","description":"Last day (UTC)"},"required":true,"description":"Last day (UTC)","name":"endDate","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Only model changes in the answers to this prompt"},"required":false,"description":"Only model changes in the answers to this prompt","name":"promptId","in":"query"}],"responses":{"200":{"description":"Markers","content":{"application/json":{"schema":{"type":"object","properties":{"markers":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"date":{"type":"string","format":"date"},"kind":{"type":"string","enum":["model"]},"assistant":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"}},"required":["date","kind","assistant","from","to"]},{"type":"object","properties":{"date":{"type":"string","format":"date"},"kind":{"type":"string","enum":["prompts"]},"added":{"type":"integer"},"archived":{"type":"integer"}},"required":["date","kind","added","archived"]}]},"description":"Days the measurement itself changed: the main model of an assistant (the model of more than half of its answers that day) moved from one known model to another, or prompts were added or archived. Sorted by date."}},"required":["markers"],"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/reports/brands":{"post":{"tags":["ai visibility"],"summary":"Brand visibility in AI answers, with counts and the previous period","description":"Every row returns numerators and their denominator (`answers`), so you can re-aggregate.\n\nVisibility = named / answers. Named first = first / answers. Average position = positionSum / positionCount. Retrieved = retrieved / answers. Cited = cited / citable. Linked = linked / answers. Share of voice = mentions / the sum of mentions of every tracked brand in the same group (same period and dimensions); `mentions` counts every time the brand is named.\n\n`answers` is per brand: an answer whose mention of that brand is `pending` (an ambiguous name waiting for verification) or `unverified` (verification failed) is not counted for that brand, in `answers` or `named`, so brands can have different denominators. `recounting` counts answers not yet re-scanned after a brand change; they are not in `answers` either.\n\nRetrieved: one of the brand’s pages is in the assistant’s source list (it read the page). Cited: the answer cites one of the brand’s pages inline. Linked: the answer text links to one of the brand’s pages. One answer can count in all three.\n\nGemini shows no inline citations, so `cited` never counts a Gemini answer and its denominator is `citable`: the answers from assistants that show inline citations (ChatGPT, Google AI Mode).\n\nDates are UTC days, inclusive. The default is the last 7 complete UTC days, ending yesterday; pass `endDate` for today, which is still being collected (see `coverage`). Non-branded prompts only, unless `filters.branded` says otherwise.\n\n`comparison` compares only prompt × assistant pairs answered in both periods. Show a change only when its status is `comparable`.\n\nBreaking down by `prompt` together with `date` or `week` needs `filters.promptIds` with 1 to 20 prompts.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"filters":{"type":"object","properties":{"assistants":{"type":"array","items":{"type":"string","enum":["chatgpt","ai_mode","gemini"]}},"topicIds":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":50},"promptIds":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":200},"intents":{"type":"array","items":{"type":"string","enum":["informational","commercial","transactional"]}},"branded":{"type":"string","enum":["non_branded","branded","all"],"default":"non_branded"}},"default":{"branded":"non_branded"}},"dimensions":{"type":"array","items":{"type":"string","enum":["date","week","assistant","topic","prompt"]},"maxItems":3,"default":[]},"compare":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Report","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":{}},"previous":{"type":["object","null"],"properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":{}},"coverage":{"type":"object","properties":{"current":{"type":"object","properties":{"planned":{"type":["number","null"]},"collected":{"type":["number","null"]},"analyzed":{"type":["number","null"]}},"required":["planned","collected","analyzed"],"additionalProperties":{}},"previous":{"type":["object","null"],"properties":{"planned":{"type":["number","null"]},"collected":{"type":["number","null"]},"analyzed":{"type":["number","null"]}},"required":["planned","collected","analyzed"],"additionalProperties":{}}},"required":["current","previous"],"additionalProperties":{}},"rows":{"type":"array","items":{"type":"object","properties":{"answers":{"type":["number","null"]},"named":{"type":["number","null"]},"first":{"type":["number","null"]},"mentions":{"type":["number","null"]},"positionSum":{"type":["number","null"]},"positionCount":{"type":["number","null"]},"retrieved":{"type":["number","null"]},"cited":{"type":["number","null"]},"linked":{"type":["number","null"]},"citable":{"type":["number","null"]},"pending":{"type":["number","null"]},"unverified":{"type":["number","null"]},"recounting":{"type":["number","null"]},"period":{"type":"string","enum":["current","previous"]},"brandId":{"type":"string"},"brandName":{"type":"string"},"brandRole":{"type":"string","enum":["own","competitor"]},"date":{"type":["string","null"]},"week":{"type":["string","null"]},"assistant":{"type":["string","null"]},"topicId":{"type":["string","null"]},"promptId":{"type":["string","null"]}},"required":["answers","named","first","mentions","positionSum","positionCount","retrieved","cited","linked","citable","pending","unverified","recounting","period","brandId","brandName","brandRole","date","week","assistant","topicId","promptId"],"additionalProperties":{}}},"comparison":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["comparable","incomplete","scope_changed","no_previous","no_data"]},"matchedPairs":{"type":"number"},"excludedAssistants":{"type":"array","items":{"type":"string"},"description":"Assistants left out of the comparison because under 90% of their planned answers were analyzed in one of the periods"},"brands":{"type":"array","items":{"type":"object","properties":{"brandId":{"type":"string"},"current":{"type":"object","properties":{"answers":{"type":["number","null"]},"named":{"type":["number","null"]},"first":{"type":["number","null"]},"mentions":{"type":["number","null"]},"positionSum":{"type":["number","null"]},"positionCount":{"type":["number","null"]},"retrieved":{"type":["number","null"]},"cited":{"type":["number","null"]},"linked":{"type":["number","null"]},"citable":{"type":["number","null"]},"pending":{"type":["number","null"]},"unverified":{"type":["number","null"]},"recounting":{"type":["number","null"]}},"required":["answers","named","first","mentions","positionSum","positionCount","retrieved","cited","linked","citable","pending","unverified","recounting"],"additionalProperties":{}},"previous":{"type":"object","properties":{"answers":{"type":["number","null"]},"named":{"type":["number","null"]},"first":{"type":["number","null"]},"mentions":{"type":["number","null"]},"positionSum":{"type":["number","null"]},"positionCount":{"type":["number","null"]},"retrieved":{"type":["number","null"]},"cited":{"type":["number","null"]},"linked":{"type":["number","null"]},"citable":{"type":["number","null"]},"pending":{"type":["number","null"]},"unverified":{"type":["number","null"]},"recounting":{"type":["number","null"]}},"required":["answers","named","first","mentions","positionSum","positionCount","retrieved","cited","linked","citable","pending","unverified","recounting"],"additionalProperties":{}}},"required":["brandId","current","previous"],"additionalProperties":{}}}},"required":["status","matchedPairs","excludedAssistants","brands"],"additionalProperties":{}}},"required":["period","previous","coverage","rows","comparison"],"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/reports/sources":{"post":{"tags":["ai visibility"],"summary":"Domains and pages the AI answers cite","description":"A source is a page the assistant retrieved (in its source list) or cited inline; a page only linked in the answer text is not a source. `appearances` counts each page once per answer. `answers` counts answers with the domain or page among their sources. `retrieved` counts answers that read it (divide by `answerTotal`); `cited` counts answers that cite it inline (divide by `citableTotal`: Gemini shows no inline citations). Citation position = `citationRankSum / citationRankCount`, 1 being cited first.\n\nPass `brandId` to list only that brand’s own pages (your pages or a competitor’s).","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"filters":{"type":"object","properties":{"assistants":{"type":"array","items":{"type":"string","enum":["chatgpt","ai_mode","gemini"]}},"topicIds":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":50},"promptIds":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":200},"intents":{"type":"array","items":{"type":"string","enum":["informational","commercial","transactional"]}},"branded":{"type":"string","enum":["non_branded","branded","all"],"default":"non_branded"}},"default":{"branded":"non_branded"}},"groupBy":{"type":"string","enum":["domain","url","domainType","pageType"],"default":"domain","description":"`domain` or `url` rows, or one row per type: `domainType` (own, competitor, corporate, editorial, institutional, ugc, reference, other, unclassified) or `pageType` (homepage, category, product, listicle, comparison, profile, alternative, discussion, how_to, article, review, other, unclassified). Types are labelled automatically when a source is first seen; own and competitor come from the tracked brands’ domains"},"domainTypes":{"type":"array","items":{"type":"string","enum":["own","competitor","corporate","editorial","institutional","ugc","reference","other","unclassified"]},"description":"Only sources whose domain has one of these types"},"pageTypes":{"type":"array","items":{"type":"string","enum":["homepage","category","product","listicle","comparison","profile","alternative","discussion","how_to","article","review","other","unclassified"]},"description":"Only pages with one of these types"},"role":{"type":"string","enum":["sources","links"],"description":"`sources` (default): pages in the source list, retrieved or cited. `links`: pages linked in the answer text"},"brandId":{"type":"string","maxLength":64},"domains":{"type":"array","items":{"type":"string","maxLength":2048},"maxItems":10,"description":"Only pages of these domains (example.com). The answer totals keep counting every answer in scope"},"urls":{"type":"array","items":{"type":"string","maxLength":2048},"maxItems":10,"description":"Only these pages"},"dimension":{"type":"string","enum":["date","week","assistant","topic","prompt"],"description":"Break each row down by date, week, assistant, topic or prompt. Needs `domains` or `urls`; every row is returned, without paging"},"compare":{"type":"boolean","description":"Add each row’s counts in the previous period of the same length (`previous`)"},"order":{"type":"string","enum":["top","new","trending","losing"],"description":"`top` (default): most answers first, paged with `cursor`. `new`: absent from the previous period. `trending` / `losing`: largest rise / fall of the share of answers against the previous period. Orders other than `top` return one page and include `previous`"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25},"cursor":{"type":"string","description":"nextCursor from the previous page, to read the next sources"}}}}}},"responses":{"200":{"description":"Report","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":{}},"previousPeriod":{"type":["object","null"],"properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":{}},"answerTotal":{"type":"number"},"citableTotal":{"type":"number","description":"Answers from assistants that show inline citations (ChatGPT, Google AI Mode): the denominator of cited"},"previousAnswerTotal":{"type":["number","null"]},"previousCitableTotal":{"type":["number","null"]},"rowTotal":{"type":"number"},"nextCursor":{"type":["string","null"]},"rows":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"domain":{"type":"string"},"title":{"type":["string","null"],"description":"Page title (`groupBy: url`)"},"publishedAt":{"type":["string","null"],"description":"When the page was published, as reported (`groupBy: url`)"},"appearances":{"type":"number"},"answers":{"type":"number","description":"Answers whose sources include it (retrieved or cited); with role `links`, answers that link it"},"retrieved":{"type":"number"},"cited":{"type":"number"},"linked":{"type":"number","description":"Answers that link it in their text"},"citationRankSum":{"type":"number"},"citationRankCount":{"type":"number"},"ownerBrandId":{"type":["string","null"]},"ownerRole":{"type":["string","null"],"enum":["own","competitor",null]},"domainType":{"type":["string","null"],"enum":["own","competitor","corporate","editorial","institutional","ugc","reference","other","unclassified",null],"description":"Type of the domain (`groupBy: domain` or `url`)"},"pageType":{"type":["string","null"],"enum":["homepage","category","product","listicle","comparison","profile","alternative","discussion","how_to","article","review","other","unclassified",null],"description":"Type of the page (`groupBy: url`)"},"date":{"type":["string","null"]},"week":{"type":["string","null"]},"assistant":{"type":["string","null"]},"topicId":{"type":["string","null"]},"promptId":{"type":["string","null"]},"previous":{"type":["object","null"],"properties":{"answers":{"type":"number","description":"Answers whose sources include it (retrieved or cited); with role `links`, answers that link it"},"retrieved":{"type":"number"},"cited":{"type":"number"},"linked":{"type":"number","description":"Answers that link it in their text"}},"required":["answers","retrieved","cited","linked"],"additionalProperties":{},"description":"The same counts in the previous period, with `compare` or an order other than `top`"},"mentionedBrands":{"type":"array","items":{"type":"object","properties":{"brandId":{"type":"string"},"answers":{"type":"number"}},"required":["brandId","answers"],"additionalProperties":{}},"description":"Tracked brands named in the answers that use this source, most answers first (rows without `dimension`)"}},"required":["key","domain","title","publishedAt","appearances","answers","retrieved","cited","linked","citationRankSum","citationRankCount","ownerBrandId","ownerRole","domainType","pageType","date","week","assistant","topicId","promptId","previous","mentionedBrands"],"additionalProperties":{}}}},"required":["period","previousPeriod","answerTotal","citableTotal","previousAnswerTotal","previousCitableTotal","rowTotal","nextCursor","rows"],"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/reports/fanout":{"post":{"tags":["ai visibility"],"summary":"The web searches ChatGPT ran behind its answers (query fan-out)","description":"Only ChatGPT reports the searches it runs, so `answers` counts analyzed ChatGPT answers in scope. `totalQueries` counts every search, `distinctQueries` the different ones (case and spacing ignored).\n\n`queries` lists the 100 most frequent searches; `occurrences` counts searches, `answers` the answers that ran them. `terms` counts the searches that contain each two-word term. `brands` counts the distinct searches naming each tracked brand (ambiguous names left out). `topics` gives every topic its distinct searches and occurrences over all searches.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"filters":{"type":"object","properties":{"assistants":{"type":"array","items":{"type":"string","enum":["chatgpt","ai_mode","gemini"]}},"topicIds":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":50},"promptIds":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":200},"intents":{"type":"array","items":{"type":"string","enum":["informational","commercial","transactional"]}},"branded":{"type":"string","enum":["non_branded","branded","all"],"default":"non_branded"}},"default":{"branded":"non_branded"}}}}}}},"responses":{"200":{"description":"Report","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":{}},"answers":{"type":"number","description":"Analyzed ChatGPT answers in scope: the only assistant whose searches are captured"},"answersWithSearches":{"type":"number"},"totalQueries":{"type":"number"},"distinctQueries":{"type":"number"},"queries":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"occurrences":{"type":"number"},"answers":{"type":"number"},"promptIds":{"type":"array","items":{"type":"string"}},"topicIds":{"type":"array","items":{"type":["string","null"]},"description":"Topics of the prompts that ran it; null = no topic"},"lastSeen":{"type":"string"}},"required":["query","occurrences","answers","promptIds","topicIds","lastSeen"],"additionalProperties":{}}},"topics":{"type":"array","items":{"type":"object","properties":{"topicId":{"type":["string","null"]},"queries":{"type":"number"},"occurrences":{"type":"number"}},"required":["topicId","queries","occurrences"],"additionalProperties":{}}},"terms":{"type":"array","items":{"type":"object","properties":{"term":{"type":"string"},"occurrences":{"type":"number"}},"required":["term","occurrences"],"additionalProperties":{}}},"brands":{"type":"array","items":{"type":"object","properties":{"brandId":{"type":"string"},"queries":{"type":"number"}},"required":["brandId","queries"],"additionalProperties":{}}}},"required":["period","answers","answersWithSearches","totalQueries","distinctQueries","queries","topics","terms","brands"],"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/reports/features":{"post":{"tags":["ai visibility"],"summary":"How often the AI answers show shopping cards, ads and maps","description":"`shopping` counts answers with at least one product card; divide by `shoppingAnswers` (ChatGPT and Google AI Mode answers, the assistants that report them). `ads` and `map` count ChatGPT answers that showed ads or a map; divide by `adsAnswers` (only ChatGPT reports them).\n\nBreak rows down by `prompt`, `assistant` or `date` with `dimensions`.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"filters":{"type":"object","properties":{"assistants":{"type":"array","items":{"type":"string","enum":["chatgpt","ai_mode","gemini"]}},"topicIds":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":50},"promptIds":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":200},"intents":{"type":"array","items":{"type":"string","enum":["informational","commercial","transactional"]}},"branded":{"type":"string","enum":["non_branded","branded","all"],"default":"non_branded"}},"default":{"branded":"non_branded"}},"dimensions":{"type":"array","items":{"type":"string","enum":["prompt","assistant","date"]},"maxItems":2,"default":[]}}}}}},"responses":{"200":{"description":"Report","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":{}},"rows":{"type":"array","items":{"type":"object","properties":{"answers":{"type":"number"},"shoppingAnswers":{"type":"number","description":"Answers from assistants that report shopping cards (ChatGPT, Google AI Mode): the denominator of shopping"},"adsAnswers":{"type":"number","description":"Answers from assistants that report ads and maps (ChatGPT): the denominator of ads and map"},"shopping":{"type":"number"},"ads":{"type":"number"},"map":{"type":"number"},"promptId":{"type":["string","null"]},"assistant":{"type":["string","null"]},"date":{"type":["string","null"]}},"required":["answers","shoppingAnswers","adsAnswers","shopping","ads","map","promptId","assistant","date"],"additionalProperties":{}}}},"required":["period","rows"],"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/reports/answers":{"post":{"tags":["ai visibility"],"summary":"Totals of the answers read in a period and the one before it","description":"`answers` counts the answers that were read; `named` those that name your brand; `searched` those with at least one page in the source list; `citations` the inline citations across them (divide by `answers` for the average).\n\n`current` covers `period`, `previous` the same number of days right before it (`previousPeriod`). `brandId` and `domain` narrow both to the answers that name that brand or read, cite or link that domain, as the answers list does.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"filters":{"type":"object","properties":{"assistants":{"type":"array","items":{"type":"string","enum":["chatgpt","ai_mode","gemini"]}},"topicIds":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":50},"promptIds":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":200},"intents":{"type":"array","items":{"type":"string","enum":["informational","commercial","transactional"]}},"branded":{"type":"string","enum":["non_branded","branded","all"],"default":"non_branded"}},"default":{"branded":"non_branded"}},"brandId":{"type":"string","maxLength":64,"description":"Only answers that name this brand (brd_…)"},"domain":{"type":"string","maxLength":2048,"description":"Only answers that read, cite or link a page of this domain (example.com)"},"url":{"type":"string","maxLength":2048,"description":"Only answers that read, cite or link this page (its full URL)"}}}}}},"responses":{"200":{"description":"Report","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":{}},"previousPeriod":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":{}},"current":{"type":"object","properties":{"answers":{"type":"number","description":"Answers read in the period"},"named":{"type":"number","description":"Answers that name your brand (verified mentions only)"},"searched":{"type":"number","description":"Answers with at least one page in the source list"},"citations":{"type":"number","description":"Inline citations across these answers"}},"required":["answers","named","searched","citations"],"additionalProperties":{}},"previous":{"type":"object","properties":{"answers":{"type":"number","description":"Answers read in the period"},"named":{"type":"number","description":"Answers that name your brand (verified mentions only)"},"searched":{"type":"number","description":"Answers with at least one page in the source list"},"citations":{"type":"number","description":"Inline citations across these answers"}},"required":["answers","named","searched","citations"],"additionalProperties":{}}},"required":["period","previousPeriod","current","previous"],"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/answers":{"get":{"tags":["ai visibility"],"summary":"List collected answers, newest first","description":"One row per prompt × assistant × day, including failed ones (`status`), so coverage can be shown.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","maxLength":64},"required":false,"name":"promptId","in":"query"},{"schema":{"type":"string","enum":["chatgpt","ai_mode","gemini"]},"required":false,"name":"assistant","in":"query"},{"schema":{"type":"string","description":"Comma-separated assistants, for example chatgpt,gemini"},"required":false,"description":"Comma-separated assistants, for example chatgpt,gemini","name":"assistants","in":"query"},{"schema":{"type":"string","maxLength":64},"required":false,"name":"topicId","in":"query"},{"schema":{"type":"string","enum":["informational","commercial","transactional"]},"required":false,"name":"intent","in":"query"},{"schema":{"type":"string","enum":["non_branded","branded","all"],"default":"all","description":"Prompts that name your brand, the others, or all (default)"},"required":false,"description":"Prompts that name your brand, the others, or all (default)","name":"branded","in":"query"},{"schema":{"type":"string","enum":["pending","analyzed","unparsed"],"description":"`analyzed` lists only the answers that were read"},"required":false,"description":"`analyzed` lists only the answers that were read","name":"analysisStatus","in":"query"},{"schema":{"type":"string","enum":["text","no_ai_mode","non_text"],"description":"`text` lists only answers with text; with `analysisStatus: analyzed` these are the answers the reports count"},"required":false,"description":"`text` lists only answers with text; with `analysisStatus: analyzed` these are the answers the reports count","name":"outcome","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Only answers that name this brand (brd_…)"},"required":false,"description":"Only answers that name this brand (brd_…)","name":"brandId","in":"query"},{"schema":{"type":"string","maxLength":2048,"description":"Only answers that read, cite or link a page of this domain (example.com)"},"required":false,"description":"Only answers that read, cite or link a page of this domain (example.com)","name":"domain","in":"query"},{"schema":{"type":"string","maxLength":2048,"description":"Only answers that read, cite or link this page (its full URL)"},"required":false,"description":"Only answers that read, cite or link this page (its full URL)","name":"url","in":"query"},{"schema":{"type":"string","format":"date"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","format":"date"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"A page of answers","content":{"application/json":{"schema":{"type":"object","properties":{"answers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"promptId":{"type":"string"},"assistant":{"type":"string","enum":["chatgpt","ai_mode","gemini"]},"runDate":{"type":"string"},"status":{"type":"string"},"outcome":{"type":["string","null"]},"analysisStatus":{"type":"string","enum":["pending","analyzed","unparsed"]},"model":{"type":["string","null"]},"capturedAt":{"type":["string","null"]},"failCode":{"type":["string","null"],"enum":["no_result","provider_error","gave_up",null]},"named":{"type":"array","items":{"type":"string"}},"sourceCount":{"type":"number","description":"Pages the assistant retrieved or cited; links in the text are not sources"},"citationCount":{"type":"number"},"excerpt":{"type":["string","null"],"description":"The first 300 characters of the answer text, Markdown"},"sourceDomains":{"type":"array","items":{"type":"string"},"description":"Domains the assistant retrieved or cited, in source-list order, each once"},"linkDomains":{"type":"array","items":{"type":"string"},"description":"Domains linked in the answer text, in order, each once"}},"required":["id","promptId","assistant","runDate","status","outcome","analysisStatus","model","capturedAt","failCode","named","sourceCount","citationCount","excerpt","sourceDomains","linkDomains"],"additionalProperties":{}}},"nextCursor":{"type":["string","null"]}},"required":["answers","nextCursor"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/answers/{answerId}":{"get":{"tags":["ai visibility"],"summary":"One answer with its brand mentions and sources","description":"`text` is GFM Markdown. Mention `spans` are `[start, end)` UTF-16 offsets into `text`; render it without raw HTML and highlight from the spans.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"},{"schema":{"type":"string","description":"Answer id (ans_…)."},"required":true,"description":"Answer id (ans_…).","name":"answerId","in":"path"}],"responses":{"200":{"description":"Answer","content":{"application/json":{"schema":{"type":"object","properties":{"answer":{"type":"object","properties":{"id":{"type":"string"},"promptId":{"type":"string"},"assistant":{"type":"string","enum":["chatgpt","ai_mode","gemini"]},"runDate":{"type":"string"},"status":{"type":"string"},"outcome":{"type":["string","null"]},"analysisStatus":{"type":"string","enum":["pending","analyzed","unparsed"]},"model":{"type":["string","null"]},"capturedAt":{"type":["string","null"]},"failCode":{"type":["string","null"],"enum":["no_result","provider_error","gave_up",null]},"prompt":{"type":"string"},"text":{"type":["string","null"]},"mentions":{"type":"array","items":{"type":"object","properties":{"brandId":{"type":"string"},"rank":{"type":["number","null"]},"firstOffset":{"type":["number","null"]},"spans":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"retrieved":{"type":"boolean","description":"One of the brand's pages is in the assistant's source list"},"cited":{"type":"boolean","description":"The answer cites one of the brand's pages inline (never for Gemini, which shows no inline citations)"},"linked":{"type":"boolean","description":"The answer text links to one of the brand's pages"},"verification":{"type":"string","enum":["not_needed","pending","confirmed","rejected","unverified"]},"nearbyCitations":{"type":"array","items":{"type":"number"}}},"required":["brandId","rank","firstOffset","spans","retrieved","cited","linked","verification","nearbyCitations"],"additionalProperties":{}}},"citations":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number"},"offset":{"type":["number","null"]},"label":{"type":"string"},"url":{"type":["string","null"]},"domain":{"type":["string","null"]}},"required":["position","offset","label","url","domain"],"additionalProperties":{}}},"sources":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":["string","null"]},"host":{"type":"string"},"domain":{"type":"string"},"position":{"type":"number"},"publishedAt":{"type":["string","null"],"description":"When the page was published, as the assistant reported it"},"retrieved":{"type":"boolean","description":"In the assistant's source list: it read the page"},"linked":{"type":"boolean","description":"Linked in the answer text"},"citationRank":{"type":["number","null"],"description":"Order of its first inline citation, 1 = cited first; null when not cited"}},"required":["url","title","host","domain","position","publishedAt","retrieved","linked","citationRank"],"additionalProperties":{}}},"searchQueries":{"type":"array","items":{"type":"string"},"description":"The web searches the assistant ran for this answer (ChatGPT)"},"products":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":["string","null"]},"price":{"type":["string","null"]},"merchant":{"type":["string","null"]}},"required":["title","url","price","merchant"],"additionalProperties":{}}},"hasAds":{"type":"boolean"},"hasMap":{"type":"boolean"}},"required":["id","promptId","assistant","runDate","status","outcome","analysisStatus","model","capturedAt","failCode","prompt","text","mentions","citations","sources","searchQueries","products","hasAds","hasMap"],"additionalProperties":{}}},"required":["answer"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{id}/answers/reanalyze":{"post":{"tags":["ai visibility"],"summary":"Read unparsed answers again","description":"Sends the answers of the given run dates that could not be read (`analysisStatus: unparsed`) back for analysis from their stored raw response, after a parser fix. It never asks the assistants again and costs no credits. Calling it twice is safe: only unparsed answers are picked.","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string","description":"Project id (proj_…) or slug (the domain with dots as dashes)."},"required":true,"description":"Project id (proj_…) or slug (the domain with dots as dashes).","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","format":"date","description":"First run date to re-read (UTC day)"},"to":{"type":"string","format":"date","description":"Last run date to re-read (UTC day)"}},"required":["from","to"]}}}},"responses":{"200":{"description":"Answers sent back","content":{"application/json":{"schema":{"type":"object","properties":{"queued":{"type":"number","description":"Unparsed answers sent back for analysis"}},"required":["queued"],"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/gsc/callback":{"get":{"tags":["ai visibility"],"summary":"Google returns here after Search Console consent","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"code","in":"query"},{"schema":{"type":"string"},"required":true,"name":"state","in":"query"},{"schema":{"type":"string"},"required":false,"name":"error","in":"query"}],"responses":{"302":{"description":"Back to the dashboard"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jobs/{id}":{"get":{"tags":["jobs"],"summary":"Get a job","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Job","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"type":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","failed"]},"error":{"type":["string","null"]},"chunksTotal":{"type":"number"},"chunksDone":{"type":"number"},"createdAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]}},"required":["id","projectId","type","status","error","chunksTotal","chunksDone","createdAt","startedAt","finishedAt"],"additionalProperties":{}}},"required":["job"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/markets":{"get":{"tags":["ai visibility"],"summary":"Countries and languages a project can track","description":"`countries` are lowercase ISO 3166-1 alpha-2 codes, `languages` lowercase ISO 639-1 codes. A project’s `country` and `language` must be one of them.\n\nThe response carries an `ETag`. Send it back in `If-None-Match` to get `304` when the lists did not change.","security":[{"apiKey":[]},{"cookie":[]}],"responses":{"200":{"description":"Markets","content":{"application/json":{"schema":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}}},"required":["countries","languages"]}}}},"304":{"description":"Nothing changed since the version sent in `If-None-Match`."}}}},"/v1/api-keys":{"get":{"tags":["api-keys"],"summary":"List the organization's API keys","security":[{"cookie":[]}],"responses":{"200":{"description":"API keys (secret part never returned)","content":{"application/json":{"schema":{"type":"object","properties":{"apiKeys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"start":{"type":["string","null"]},"scopes":{"type":"array","items":{"type":"string","enum":["read","write"]}},"createdAt":{"type":"string"},"lastRequest":{"type":["string","null"]}},"required":["id","name","start","scopes","createdAt","lastRequest"],"additionalProperties":{}}}},"required":["apiKeys"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["api-keys"],"summary":"Create an organization API key","description":"`read` keys can call read endpoints and read tools. `write` keys can also create and delete. The full key is returned once.","security":[{"cookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"scope":{"type":"string","enum":["read","write"],"default":"read"}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"apiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"start":{"type":["string","null"]},"scopes":{"type":"array","items":{"type":"string","enum":["read","write"]}},"createdAt":{"type":"string"},"lastRequest":{"type":["string","null"]}},"required":["id","name","start","scopes","createdAt","lastRequest"],"additionalProperties":{}},"key":{"type":"string"}},"required":["apiKey","key"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/api-keys/{id}":{"delete":{"tags":["api-keys"],"summary":"Revoke an API key","security":[{"cookie":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Revoked"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing":{"get":{"tags":["billing"],"summary":"The organization's plan and credit balance","security":[{"apiKey":[]},{"cookie":[]}],"responses":{"200":{"description":"Billing","content":{"application/json":{"schema":{"type":"object","properties":{"subscription":{"type":["object","null"],"properties":{"status":{"type":"string"},"priceId":{"type":"string"},"plan":{"type":"string"},"interval":{"type":"string","enum":["month","year"]},"monthlyCredits":{"type":"number"},"perks":{"type":"array","items":{"type":"string"}},"currentPeriodEnd":{"type":"string"},"cancelAtPeriodEnd":{"type":"boolean"},"scheduledPriceId":{"type":["string","null"]}},"required":["status","priceId","plan","interval","monthlyCredits","perks","currentPeriodEnd","cancelAtPeriodEnd","scheduledPriceId"]},"credits":{"type":"object","properties":{"included":{"type":"number"},"purchased":{"type":"number"},"total":{"type":"number"},"spentThisMonth":{"type":"number"}},"required":["included","purchased","total","spentThisMonth"]},"plan":{"type":"object","properties":{"prompts":{"type":"number"},"keywords":{"type":"number"},"includedProjects":{"type":"number"},"monthlyCredits":{"type":"number"},"maxProjects":{"type":["number","null"]},"historyDays":{"type":["number","null"]},"perks":{"type":"array","items":{"type":"string"}},"key":{"type":"string"},"name":{"type":"string"},"source":{"type":"string","enum":["subscription","trial","free"]},"trialEndsAt":{"type":["string","null"]},"trialUsed":{"type":"boolean"},"planChosen":{"type":"boolean"}},"required":["prompts","keywords","includedProjects","monthlyCredits","maxProjects","historyDays","perks","key","name","source","trialEndsAt","trialUsed","planChosen"]},"trial":{"type":"object","properties":{"days":{"type":"number"},"credits":{"type":"number"}},"required":["days","credits"]},"usage":{"type":"object","properties":{"prompts":{"type":"number"},"keywords":{"type":"number"},"projects":{"type":"number"},"extraPrompts":{"type":"number"},"extraDailyCredits":{"type":"number"}},"required":["prompts","keywords","projects","extraPrompts","extraDailyCredits"]},"costs":{"type":"object","properties":{"answer":{"type":"object","properties":{"chatgpt":{"type":"number"},"ai_mode":{"type":"number"},"gemini":{"type":"number"}}},"extraPromptRun":{"type":"number"},"keywordCheck":{"type":"number"},"setup":{"type":"object","properties":{"gsc":{"type":"number"},"noGsc":{"type":"number"}},"required":["gsc","noGsc"]},"diagnosis":{"type":"object","properties":{"gsc":{"type":"number"},"noGsc":{"type":"number"}},"required":["gsc","noGsc"]},"includedDiagnosisNoGsc":{"type":"number"},"trafficDrop":{"type":"number"},"chatAnswer":{"type":"number"}},"required":["answer","extraPromptRun","keywordCheck","setup","diagnosis","includedDiagnosisNoGsc","trafficDrop","chatAnswer"]},"historyStart":{"type":["string","null"]},"plans":{"type":"array","items":{"type":"object","properties":{"prompts":{"type":"number"},"keywords":{"type":"number"},"includedProjects":{"type":"number"},"monthlyCredits":{"type":"number"},"maxProjects":{"type":["number","null"]},"historyDays":{"type":["number","null"]},"perks":{"type":"array","items":{"type":"string"}},"key":{"type":"string"},"name":{"type":"string"},"prices":{"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string"},"interval":{"type":"string","enum":["month","year"]},"amount":{"type":"number"},"currency":{"type":"string"}},"required":["priceId","interval","amount","currency"]}}},"required":["prompts","keywords","includedProjects","monthlyCredits","maxProjects","historyDays","perks","key","name","prices"]}},"packs":{"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"credits":{"type":"number"},"bonus":{"type":"number"}},"required":["priceId","amount","currency","credits","bonus"]}}},"required":["subscription","credits","plan","trial","usage","costs","historyStart","plans","packs"],"additionalProperties":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/checkout":{"post":{"tags":["billing"],"summary":"Start a Stripe Checkout for a plan or a credit pack","security":[{"cookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"priceId":{"type":"string"}},"required":["priceId"]}}}},"responses":{"200":{"description":"Checkout URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/change":{"post":{"tags":["billing"],"summary":"Change the plan: a bigger plan or yearly billing now, a smaller one at period end. The current plan cancels a scheduled change.","security":[{"cookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"priceId":{"type":"string"}},"required":["priceId"]}}}},"responses":{"200":{"description":"Changed, scheduled or canceled","content":{"application/json":{"schema":{"type":"object","properties":{"change":{"type":"string","enum":["now","scheduled","canceled"]}},"required":["change"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/trial":{"post":{"tags":["billing"],"summary":"Start the 14-day trial of a paid plan, once per organization","security":[{"cookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","minLength":1}},"required":["plan"]}}}},"responses":{"200":{"description":"Trial started","content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string"},"endsAt":{"type":"string"}},"required":["plan","endsAt"]}}}},"402":{"description":"Not enough credits, or over the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/free":{"post":{"tags":["billing"],"summary":"Continue on the Free plan","security":[{"cookie":[]}],"responses":{"200":{"description":"Free chosen","content":{"application/json":{"schema":{"type":"object","properties":{"chosen":{"type":"boolean"}},"required":["chosen"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/portal":{"post":{"tags":["billing"],"summary":"Open the Stripe billing portal","security":[{"cookie":[]}],"responses":{"200":{"description":"Portal URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/credits/usage":{"get":{"tags":["billing"],"summary":"Credit spending, newest first","security":[{"apiKey":[]},{"cookie":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["extra_prompt_answer","project_setup","diagnosis","diagnosis_traffic_drop","agent_answer"]},"required":false,"name":"reason","in":"query"}],"responses":{"200":{"description":"A page of credit usage","content":{"application/json":{"schema":{"type":"object","properties":{"usage":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number"},"reason":{"type":"string","enum":["extra_prompt_answer","project_setup","diagnosis","diagnosis_traffic_drop","agent_answer"]},"reference":{"type":["string","null"]},"assistant":{"type":["string","null"],"enum":["chatgpt","ai_mode","gemini",null]},"subject":{"type":["string","null"]},"project":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","amount","reason","reference","assistant","subject","project","createdAt"],"additionalProperties":{}}},"nextCursor":{"type":["string","null"]}},"required":["usage","nextCursor"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/credits":{"get":{"tags":["billing"],"summary":"Live credit batches with their expiry, credits expiring within 30 days, and the next grant","security":[{"apiKey":[]},{"cookie":[]}],"responses":{"200":{"description":"Credit batches","content":{"application/json":{"schema":{"type":"object","properties":{"grants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["plan","trial","free","pack","bonus","adjustment"]},"plan":{"type":["string","null"]},"upgrade":{"type":"boolean"},"amount":{"type":"number"},"remaining":{"type":"number"},"createdAt":{"type":"string"},"availableAt":{"type":"string"},"expiresAt":{"type":["string","null"]}},"required":["id","kind","plan","upgrade","amount","remaining","createdAt","availableAt","expiresAt"]}},"expiringSoon":{"type":"object","properties":{"credits":{"type":"number"},"before":{"type":"string"}},"required":["credits","before"]},"next":{"type":["object","null"],"properties":{"at":{"type":"string"},"credits":{"type":"number"},"plan":{"type":["string","null"]}},"required":["at","credits","plan"]}},"required":["grants","expiringSoon","next"],"additionalProperties":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/credits/summary":{"get":{"tags":["billing"],"summary":"Credits spent this UTC month and last, by reason","security":[{"apiKey":[]},{"cookie":[]}],"responses":{"200":{"description":"Spending","content":{"application/json":{"schema":{"type":"object","properties":{"months":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"total":{"type":"number"},"byReason":{"type":"object","properties":{"extra_prompt_answer":{"type":"number"},"project_setup":{"type":"number"},"diagnosis":{"type":"number"},"diagnosis_traffic_drop":{"type":"number"},"agent_answer":{"type":"number"}}}},"required":["month","total","byReason"]}}},"required":["months"],"additionalProperties":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/projects":{"get":{"tags":["billing"],"summary":"Projects with whether the plan includes them and whether this month’s free diagnosis is left","security":[{"apiKey":[]},{"cookie":[]}],"responses":{"200":{"description":"Plan coverage","content":{"application/json":{"schema":{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"included":{"type":"boolean"},"trackingStatus":{"type":"string","enum":["off","active","paused"]},"pausedReason":{"type":["string","null"],"enum":["plan","inactive",null]},"freeDiagnosisLeft":{"type":"boolean"}},"required":["id","name","domain","included","trackingStatus","pausedReason","freeDiagnosisLeft"]}}},"required":["projects"],"additionalProperties":{}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}