{"openapi":"3.0.3","info":{"title":"Rankability Agent API","version":"1.23.0","description":"REST API for programmatic SEO and AI search visibility work in Rankability: content jobs, AI and organic rank tracking, keyword research, page and site audits, clients and their Knowledge sources, crawling, and usage.\n\nAuthenticate with an organization API key (`Authorization: Bearer rk_live_...`, created in Settings > API keys) or an OAuth 2.0 access token. Each operation lists the scopes it needs in `x-required-scopes` (all required) or `x-accepted-scopes` (any one is enough); an empty `x-required-scopes` with no `x-accepted-scopes` means any Agent API scope works.\n\nErrors use one shape: `{ \"error\": { \"code\", \"message\", \"details\" } }`. Every response carries `X-Request-Id`, `X-API-Version` and `X-RateLimit-*` headers. Call `GET /usage` before starting on-demand work.","contact":{"name":"Rankability support","url":"https://help.rankability.com"},"termsOfService":"https://www.rankability.com/terms/"},"servers":[{"url":"https://app.rankability.com","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":[]}],"tags":[{"name":"Backlink profile","description":"Saved backlink profile evidence for a client, and explicit refreshes."},{"name":"Campaigns","description":"Client campaign records: context, log entries, snapshots and attached documents."},{"name":"Clients","description":"Client workspaces: identity, settings, integrations and Search Console data."},{"name":"Copywriter","description":"SEO content jobs in auto, stepped or Autopilot mode, plus entity research."},{"name":"Crawler","description":"Scrape single pages, crawl sites within bounds and extract structured data."},{"name":"Jobs and exports","description":"One status contract for asynchronous jobs, artifact inventory and exports."},{"name":"Knowledge Base","description":"Rankability Help Center content for grounding agents."},{"name":"Knowledge sources","description":"A client's Knowledge sources used for content and Serena grounding."},{"name":"Optimize","description":"Durable page optimization runs scored against SERP competitors."},{"name":"Page Auditor","description":"Single-page and batch AEO/SEO page audits."},{"name":"Prospect scans","description":"AI visibility reports for prospects."},{"name":"Prospector","description":"Saved outreach lists and pipeline items."},{"name":"Reporter","description":"AI and organic rank tracking: projects, scans, results, trends and visibility."},{"name":"Researcher","description":"Keyword research jobs and saved Researcher projects."},{"name":"Routines and publishing","description":"Recurring Routine state and confirmed, draft-only CMS delivery."},{"name":"SEO Research","description":"SEO Research jobs and usage."},{"name":"Saved audit artifacts","description":"Saved GBP audits and Batch URL Analyzer runs."},{"name":"Search Intelligence","description":"Live queries across Google and AI platforms."},{"name":"Serena","description":"Read-only consultation with Serena, Rankability's AI SEO director."},{"name":"Site Auditor","description":"Full-site crawls with page-level issues."},{"name":"Usage","description":"The active metering contract, limits, usage events and estimates."}],"paths":{"/api/agent/v1/audit-manifest":{"get":{"operationId":"get_audit_manifest","summary":"Inventory client Tracker, audit, research, and content artifacts with lifecycle metadata","description":"Inventory client Tracker, audit, research, and content artifacts with lifecycle metadata\n\nRequired scope: one of `page_audit:read` or `site-auditor:read` or `reporter:read` or `researcher:read` or `copywriter:read`.","tags":["Jobs and exports"],"x-required-scopes":[],"x-accepted-scopes":["page_audit:read","site-auditor:read","reporter:read","researcher:read","copywriter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["page_audit:read"]},{"OAuth2":["site-auditor:read"]},{"OAuth2":["reporter:read"]},{"OAuth2":["researcher:read"]},{"OAuth2":["copywriter:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients":{"get":{"operationId":"get_clients","summary":"List all clients","description":"List all clients\n\nList all clients for your organization.\n\nRequired scope: one of `clients:read` or `copywriter:read` or `reporter:read`.","tags":["Clients"],"x-required-scopes":[],"x-accepted-scopes":["clients:read","copywriter:read","reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:read"]},{"OAuth2":["copywriter:read"]},{"OAuth2":["reporter:read"]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Max results (default 50, max 100)","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Pagination offset (default 0)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"clients":[{"id":"uuid","name":"Acme Corp","domain":"acme.com","icon":"A","color":"bg-blue-500","created_at":"2025-01-15T10:00:00.000Z","updated_at":"2025-01-15T10:00:00.000Z"}],"pagination":{"limit":50,"offset":0,"count":1,"total":1}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"post_clients","summary":"Create a new client","description":"Create a new client\n\nCreate a new client.\n\nRequired scope: `clients:write`.","tags":["Clients"],"x-required-scopes":["clients:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Client name"},"domain":{"type":"string","description":"Client website domain"},"icon":{"type":"string","description":"Icon character (default: `C`)"},"color":{"type":"string","description":"Color class (default: `bg-blue-500`)"},"knowledge_base":{"type":"object","additionalProperties":true,"description":"Knowledge base data (writing style, brand context, reference docs)"}},"required":["name"]},"example":{"name":"Acme Corp","domain":"acme.com"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"id":"uuid","name":"Acme Corp","domain":"acme.com","icon":"A","color":"bg-blue-500","created_at":"2025-01-15T10:00:00.000Z"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/backlinks/profile":{"get":{"operationId":"get_clients_by_client_id_backlinks_profile","summary":"Read one bounded saved backlink profile section with freshness","description":"Read one bounded saved backlink profile section with freshness\n\nEvery response reports `data_state`, `cached_at`, and `freshness`. `unavailable` means no matching saved snapshot exists; it is not a measured zero. Stale evidence remains visible and labeled rather than being refreshed implicitly. Raw provider payloads, individual live backlink lists, exports, and provider refresh are not exposed by this route.\n\nRequired scope: `backlinks:read`.","tags":["Backlink profile"],"x-required-scopes":["backlinks:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["backlinks:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/backlinks/profile/refresh":{"post":{"operationId":"post_clients_by_client_id_backlinks_profile_refresh","summary":"Confirm and idempotently create or refresh all four cache-backed profile sections","description":"Confirm and idempotently create or refresh all four cache-backed profile sections\n\nRequired scope: `backlinks:run`.","tags":["Backlink profile"],"x-required-scopes":["backlinks:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["backlinks:run"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/batch-url-runs":{"get":{"operationId":"get_clients_by_client_id_batch_url_runs","summary":"List saved Batch URL Analyzer runs","description":"List saved Batch URL Analyzer runs\n\nRequired scope: `batch-url:read`.","tags":["Saved audit artifacts"],"x-required-scopes":["batch-url:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["batch-url:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/batch-url-runs/{run_id}":{"get":{"operationId":"get_clients_by_client_id_batch_url_runs_by_run_id","summary":"Read one paginated saved Batch URL result","description":"Read one paginated saved Batch URL result\n\nRequired scope: `batch-url:read`.","tags":["Saved audit artifacts"],"x-required-scopes":["batch-url:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["batch-url:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/campaigns":{"get":{"operationId":"get_clients_by_client_id_campaigns","summary":"List client campaign records","description":"List client campaign records (archived hidden unless `include_archived=true`)\n\nRequired scope: `clients:read`.","tags":["Campaigns"],"x-required-scopes":["clients:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"post_clients_by_client_id_campaigns","summary":"Create a campaign","description":"Create a campaign; `Idempotency-Key` required. Prompt set is `{tracker_cluster_id}` or `{tracker_project_ids}`; nothing is created or scanned\n\nRequired scope: `clients:write`.","tags":["Campaigns"],"x-required-scopes":["clients:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:write"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/campaigns/{campaign_id}":{"get":{"operationId":"get_clients_by_client_id_campaigns_by_campaign_id","summary":"Get a campaign summary","description":"Compact summary; `log_limit` (0 to 50), `include_log_detail`. Report status needs `reporter:read`\n\nRequired scope: `clients:read`.","tags":["Campaigns"],"x-required-scopes":["clients:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"patch_clients_by_client_id_campaigns_by_campaign_id","summary":"Update a campaign","description":"Patch fields; context lists replace only the lists provided; `Idempotency-Key` required\n\nRequired scope: `clients:write`.","tags":["Campaigns"],"x-required-scopes":["clients:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:write"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/campaigns/{campaign_id}/documents":{"post":{"operationId":"post_clients_by_client_id_campaigns_by_campaign_id_documents","summary":"Attach an existing Knowledge source as `internal` or `client_facing`","description":"Attach an existing Knowledge source as `internal` or `client_facing`\n\nRequired scope: `clients:write`.","tags":["Campaigns"],"x-required-scopes":["clients:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:write"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/campaigns/{campaign_id}/log":{"get":{"operationId":"get_clients_by_client_id_campaigns_by_campaign_id_log","summary":"Page the campaign log","description":"Page the log (`limit`, `before`, `kind`) or append an entry; resolve with `resolves_entry_id`\n\nRequired scope: `clients:read`.","tags":["Campaigns"],"x-required-scopes":["clients:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"post_clients_by_client_id_campaigns_by_campaign_id_log","summary":"Append a campaign log entry","description":"Page the log (`limit`, `before`, `kind`) or append an entry; resolve with `resolves_entry_id`\n\nRequired scope: `clients:write`.","tags":["Campaigns"],"x-required-scopes":["clients:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:write"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/campaigns/{campaign_id}/snapshots":{"get":{"operationId":"get_clients_by_client_id_campaigns_by_campaign_id_snapshots","summary":"List campaign snapshots","description":"List snapshots with headline numbers, or save one (no scan, no sync, no usage). First-party totals match the SEO performance dashboard for `first_party_range`; each item reports `payload_version` and `first_party` (`basis`, `range`, `partial`, `caveats`). Version 1 snapshots used stored-row totals (`basis: \"stored_rows\"`) and are always partial\n\nRequired scope: `clients:read`.","tags":["Campaigns"],"x-required-scopes":["clients:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"post_clients_by_client_id_campaigns_by_campaign_id_snapshots","summary":"Save a campaign snapshot","description":"List snapshots with headline numbers, or save one (no scan, no sync, no usage). First-party totals match the SEO performance dashboard for `first_party_range`; each item reports `payload_version` and `first_party` (`basis`, `range`, `partial`, `caveats`). Version 1 snapshots used stored-row totals (`basis: \"stored_rows\"`) and are always partial\n\nRequired scope: `clients:write` and `reporter:read`.","tags":["Campaigns"],"x-required-scopes":["clients:write","reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:write","reporter:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/campaigns/{campaign_id}/snapshots/{snapshot_id}":{"get":{"operationId":"get_clients_by_client_id_campaigns_by_campaign_id_snapshots_by_snapshot_id","summary":"Get a full stored campaign snapshot","description":"Full stored snapshot payload\n\nRequired scope: `clients:read` and `reporter:read`.","tags":["Campaigns"],"x-required-scopes":["clients:read","reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:read","reporter:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"snapshot_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/campaigns/{campaign_id}/snapshots/compare":{"get":{"operationId":"get_clients_by_client_id_campaigns_by_campaign_id_snapshots_compare","summary":"Compare two snapshots","description":"Compare two snapshots (`before_id`, `after_id`; default baseline vs latest)\n\nRequired scope: `clients:read`.","tags":["Campaigns"],"x-required-scopes":["clients:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/gbp-audits":{"get":{"operationId":"get_clients_by_client_id_gbp_audits","summary":"List bounded saved GBP audits","description":"List bounded saved GBP audits\n\nRequired scope: `gbp-audit:read`.","tags":["Saved audit artifacts"],"x-required-scopes":["gbp-audit:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["gbp-audit:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/gbp-audits/{audit_id}":{"get":{"operationId":"get_clients_by_client_id_gbp_audits_by_audit_id","summary":"Read one saved summary or bounded full GBP audit","description":"Read one saved summary or bounded full GBP audit\n\nRequired scope: `gbp-audit:read`.","tags":["Saved audit artifacts"],"x-required-scopes":["gbp-audit:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["gbp-audit:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"audit_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/prospect-lists":{"get":{"operationId":"get_clients_by_client_id_prospect_lists","summary":"List bounded saved outreach lists and status counts","description":"List bounded saved outreach lists and status counts\n\nRequired scope: `prospector:read`.","tags":["Prospector"],"x-required-scopes":["prospector:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["prospector:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"post_clients_by_client_id_prospect_lists","summary":"Create one retry-safe saved list","description":"Create one retry-safe saved list\n\nRequired scope: `prospector:write`.","tags":["Prospector"],"x-required-scopes":["prospector:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["prospector:write"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/prospect-lists/{list_id}":{"delete":{"operationId":"delete_clients_by_client_id_prospect_lists_by_list_id","summary":"Delete one exact-name-confirmed list","description":"Delete one exact-name-confirmed list\n\nRequired scope: `prospector:write`.","tags":["Prospector"],"x-required-scopes":["prospector:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["prospector:write"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/prospect-lists/{list_id}/items":{"get":{"operationId":"get_clients_by_client_id_prospect_lists_by_list_id_items","summary":"List bounded pipeline items with optional status filtering","description":"List bounded pipeline items with optional status filtering\n\nRequired scope: `prospector:read`.","tags":["Prospector"],"x-required-scopes":["prospector:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["prospector:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"post_clients_by_client_id_prospect_lists_by_list_id_items","summary":"Save and canonical-URL-deduplicate one known prospect","description":"Save and canonical-URL-deduplicate one known prospect\n\nRequired scope: `prospector:write`.","tags":["Prospector"],"x-required-scopes":["prospector:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["prospector:write"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/prospect-lists/{list_id}/items/{item_id}":{"delete":{"operationId":"delete_clients_by_client_id_prospect_lists_by_list_id_items_by_item_id","summary":"Remove one exact-URL-confirmed list item","description":"Remove one exact-URL-confirmed list item\n\nRequired scope: `prospector:write`.","tags":["Prospector"],"x-required-scopes":["prospector:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["prospector:write"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"patch_clients_by_client_id_prospect_lists_by_list_id_items_by_item_id","summary":"Update saved status or notes","description":"Update saved status or notes\n\nRequired scope: `prospector:write`.","tags":["Prospector"],"x-required-scopes":["prospector:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["prospector:write"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/publishing/artifacts":{"post":{"operationId":"post_clients_by_client_id_publishing_artifacts","summary":"Create or reuse an immutable destination-specific snapshot without destination mutation","description":"Create or reuse an immutable destination-specific snapshot without destination mutation\n\nRequired scope: `publishing:write`.","tags":["Routines and publishing"],"x-required-scopes":["publishing:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["publishing:write"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/publishing/connections":{"get":{"operationId":"get_clients_by_client_id_publishing_connections","summary":"List credential-free destination state and safe target metadata","description":"List credential-free destination state and safe target metadata\n\nRequired scope: `publishing:read`.","tags":["Routines and publishing"],"x-required-scopes":["publishing:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["publishing:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/publishing/deliveries":{"get":{"operationId":"get_clients_by_client_id_publishing_deliveries","summary":"List bounded privacy-safe delivery receipts","description":"List bounded privacy-safe delivery receipts\n\nRequired scope: `publishing:read`.","tags":["Routines and publishing"],"x-required-scopes":["publishing:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["publishing:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"post_clients_by_client_id_publishing_deliveries","summary":"Request one confirmed, idempotent draft delivery","description":"Request one confirmed, idempotent draft delivery\n\nRequired scope: `publishing:write`.","tags":["Routines and publishing"],"x-required-scopes":["publishing:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["publishing:write"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/publishing/deliveries/{delivery_id}":{"get":{"operationId":"get_clients_by_client_id_publishing_deliveries_by_delivery_id","summary":"Read one delivery's preflight, remote, currency, and validation state","description":"Read one delivery's preflight, remote, currency, and validation state\n\nRequired scope: `publishing:read`.","tags":["Routines and publishing"],"x-required-scopes":["publishing:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["publishing:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"delivery_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/publishing/preflight":{"get":{"operationId":"get_clients_by_client_id_publishing_preflight","summary":"Validate one immutable article snapshot without mutation","description":"Validate one immutable article snapshot without mutation\n\nRequired scope: `publishing:read`.","tags":["Routines and publishing"],"x-required-scopes":["publishing:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["publishing:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/routines":{"get":{"operationId":"get_clients_by_client_id_routines","summary":"List bounded recurring content and Knowledge-monitor Routines","description":"List bounded recurring content and Knowledge-monitor Routines\n\nRequired scope: `routines:read`.","tags":["Routines and publishing"],"x-required-scopes":["routines:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["routines:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{client_id}/routines/{routine_id}":{"get":{"operationId":"get_clients_by_client_id_routines_by_routine_id","summary":"Read one Routine with bounded topics or source IDs","description":"Read one Routine with bounded topics or source IDs\n\nRequired scope: `routines:read`.","tags":["Routines and publishing"],"x-required-scopes":["routines:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["routines:read"]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"routine_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{id}":{"delete":{"operationId":"delete_clients_by_id","summary":"Delete a client and associated data","description":"Delete a client and associated data\n\nDelete a client and cascade-delete all associated data (rank tracker projects, results, runs, copywriter projects).\n\nRequired scope: `clients:write`.","tags":["Clients"],"x-required-scopes":["clients:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"id":"uuid","deleted":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"get_clients_by_id","summary":"Get client details","description":"Get client details\n\nGet lightweight identity, integration, settings, and content-grounding details for a specific client. `content_profile.brand_name` is the effective brand Copywriter uses; `brand_name_source` identifies whether it came from the knowledge base or fell back to the workspace name. `content_controls` exposes the configured `do_not_use`, `blocked_keywords`, and `excluded_topics` arrays. `tracker_identity.brand_aliases` contains the approved workspace aliases inherited by new Tracker projects. `tracker_identity.gbp_location_name` is the connected primary GBP name when available; update a report's explicit location identity through the Tracker project endpoint rather than editing the connection mirror.\n\nRequired scope: one of `clients:read` or `copywriter:read` or `reporter:read`.","tags":["Clients"],"x-required-scopes":[],"x-accepted-scopes":["clients:read","copywriter:read","reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:read"]},{"OAuth2":["copywriter:read"]},{"OAuth2":["reporter:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"id":"uuid","name":"Acme Corp","domain":"acme.com","icon":"A","color":"bg-blue-500","content_profile":{"brand_name":"Acme","brand_name_source":"knowledge_base","tagline":"Make operations simple","target_audience":"Operations leaders","industry":"Software","tone":"professional","voice_summary":"Direct and practical","unique_selling_propositions":[],"competitors":[]},"content_controls":{"do_not_use":["guaranteed"],"blocked_keywords":["coupon"],"excluded_topics":["politics"]},"tracker_identity":{"brand_aliases":["Acme Corporation","Acme Software"],"gbp_location_name":"Acme Downtown","gbp_location_name_source":"connected_gbp"},"created_at":"2025-01-15T10:00:00.000Z","updated_at":"2025-01-15T10:00:00.000Z"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"patch_clients_by_id","summary":"Update a client","description":"Update a client\n\nUpdate a client. Only provided fields are updated.\n\nRequired scope: `clients:write`.","tags":["Clients"],"x-required-scopes":["clients:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Client name"},"domain":{"type":"string","nullable":true,"description":"Client domain"},"icon":{"type":"string","description":"Icon character"},"color":{"type":"string","description":"Color class"},"knowledge_base":{"type":"object","additionalProperties":true,"description":"Knowledge base data"},"knowledge_base_patch":{"type":"object","additionalProperties":true,"description":"Merge selected Knowledge fields without clearing omitted sections"},"brand_aliases":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Approved workspace Tracker aliases; null clears the workspace default. This does not re-score stored history."}}},"example":{"name":"Acme Corp Updated","domain":"newdomain.com","brand_aliases":["Acme Corporation","Acme Software"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{id}/connect-link":{"post":{"operationId":"post_clients_by_id_connect_link","summary":"Create an integration connect link for a client","description":"Create a secure browser handoff for Google authorization and GSC/GA4 property selection. The link expires after seven days. Creating a new link revokes any older active connect link for the client.\n\nRequired scope: `clients:write`.","tags":["Clients"],"x-required-scopes":["clients:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"client":{"id":"uuid","name":"Acme Corp","domain":"acme.com"},"url":"https://app.rankability.com/connect/one-time-token","expires_at":"2025-01-22T10:00:00.000Z","previous_link_revoked":false,"next_action":"Open the URL in a browser to authorize Google and select the GSC and GA4 properties."}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{id}/gsc/search-performance":{"get":{"operationId":"get_clients_by_id_gsc_search_performance","summary":"Get bounded GSC query, page, or query-page performance with sync freshness","description":"Get bounded GSC query, page, or query-page performance with sync freshness\n\nRequired scope: `clients:read`.","tags":["Clients"],"x-required-scopes":["clients:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{id}/search-performance/catalog":{"get":{"operationId":"get_clients_by_id_search_performance_catalog","summary":"GET /clients/:id/search-performance/catalog","description":"Required scope: `clients:read`.","tags":["Clients"],"x-required-scopes":["clients:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{id}/search-performance/query":{"post":{"operationId":"post_clients_by_id_search_performance_query","summary":"POST /clients/:id/search-performance/query","description":"Required scope: `clients:read`.","tags":["Clients"],"x-required-scopes":["clients:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{id}/sources":{"get":{"operationId":"get_clients_by_id_sources","summary":"List compact Knowledge source metadata","description":"List compact Knowledge source metadata; use `view=full` only when source bodies are required\n\nRequired scope: one of `clients:read` or `copywriter:read`.","tags":["Knowledge sources"],"x-required-scopes":[],"x-accepted-scopes":["clients:read","copywriter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:read"]},{"OAuth2":["copywriter:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"post_clients_by_id_sources","summary":"Create a pasted source up to 250,000 characters","description":"Create a pasted source up to 250,000 characters; optional `role` and `usage`; `upsert_by_name=true` safely syncs one exact-name match\n\nWhen `upsert_by_name` is `true`, the endpoint updates one case-insensitive, whitespace-normalized exact-name match or creates a source when none exists. It returns `409 ambiguous_source_name` instead of guessing when duplicate names already exist. Omitting `role` preserves the role on an existing source; sending `null` clears it. `usage` accepts `generation` or `reference_only`; the latter remains readable through Knowledge tools but is excluded from automatic Copywriter prompt selection even when selected or priority. Existing sources default to `generation`, and omitting `usage` during an upsert preserves the current value.\n\nRequired scope: `clients:write`.","tags":["Knowledge sources"],"x-required-scopes":["clients:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"name":"September entity research","content":"# Research\n...","role":"strategy_notes","usage":"reference_only","upsert_by_name":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"articles":[{"id":"uuid","slug":"what-is-rankability","title":"What is Rankability?","summary":"Learn how Rankability organizes SEO and AI search work...","category":"Getting Started","canonical_url":"https://help.rankability.com/getting-started/what-is-rankability","content_html":"<p>Rankability is a search visibility platform...</p>","content_markdown":"Rankability is a search visibility platform...","sort_order":1,"created_at":"2026-08-03T12:00:00.000Z","updated_at":"2026-08-03T12:00:00.000Z"}],"faq_markdown":"# Frequently asked questions\n\n...","meta":{"article_count":89,"last_updated":"2026-08-03T12:00:00.000Z","has_faq":true,"source":"canonical_help_center","canonical_base_url":"https://help.rankability.com","manifest_version":1}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{id}/sources/{source_id}":{"delete":{"operationId":"delete_clients_by_id_sources_by_source_id","summary":"Delete one Knowledge source","description":"Delete one Knowledge source\n\nRequired scope: `clients:write`.","tags":["Knowledge sources"],"x-required-scopes":["clients:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"source_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"get_clients_by_id_sources_by_source_id","summary":"Get one Knowledge source in compact or full view","description":"Get one Knowledge source in compact or full view\n\nRequired scope: one of `clients:read` or `copywriter:read`.","tags":["Knowledge sources"],"x-required-scopes":[],"x-accepted-scopes":["clients:read","copywriter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:read"]},{"OAuth2":["copywriter:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"source_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"patch_clients_by_id_sources_by_source_id","summary":"Update source name, body, role, generation usage, selection, or priority","description":"Update source name, body, role, generation usage, selection, or priority\n\nRequired scope: `clients:write`.","tags":["Knowledge sources"],"x-required-scopes":["clients:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"source_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{id}/sources/{source_id}/contradictions":{"get":{"operationId":"get_clients_by_id_sources_by_source_id_contradictions","summary":"Read durable contradiction-check receipts and completed findings","description":"Read durable contradiction-check receipts and completed findings\n\nRequired scope: one of `clients:read` or `copywriter:read`.","tags":["Knowledge sources"],"x-required-scopes":[],"x-accepted-scopes":["clients:read","copywriter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:read"]},{"OAuth2":["copywriter:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"source_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/{id}/sources/{source_id}/sections":{"get":{"operationId":"get_clients_by_id_sources_by_source_id_sections","summary":"Read sections of one Knowledge source","description":"Required scope: `clients:read`.","tags":["Knowledge sources"],"x-required-scopes":["clients:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"source_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/clients/resolve":{"get":{"operationId":"get_clients_resolve","summary":"Resolve a client by name or domain","description":"Required scope: one of `clients:read` or `copywriter:read` or `reporter:read`.","tags":["Clients"],"x-required-scopes":[],"x-accepted-scopes":["clients:read","copywriter:read","reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["clients:read"]},{"OAuth2":["copywriter:read"]},{"OAuth2":["reporter:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/copywriter/autopilot":{"post":{"operationId":"post_copywriter_autopilot","summary":"Start an Autopilot run","description":"Start an Autopilot run (one-shot orchestrated pipeline)\n\nAutopilot is the fully-orchestrated, one-shot pipeline: research → auto-approved brief → draft → automatic optimize passes → fact-check → final review summary. It costs a flat 750 credits, charged once a usable draft exists. A run that fails before producing a draft is not charged. Images remain user-selected in the editor.\n\nRequired scope: `copywriter:run`.","tags":["Copywriter"],"x-required-scopes":["copywriter:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:run"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"topic":{"type":"string","description":"Topic/keyword to create content for"},"intent":{"type":"string","enum":["educate","discover","compete","convert"],"description":"`educate`, `discover`, `compete`, or `convert`","default":"educate"},"page_contract":{"type":"string","enum":["article","commercial_service"],"description":"`article` or `commercial_service`. The explicit choice is persisted before the flat credit reservation."},"client_id":{"type":"string","format":"uuid","description":"Client workspace to scope the run to (must belong to your org). Required so drafts inherit the client's brand voice, knowledge base sources, and excluded topics. Find valid ids with `GET /api/agent/v1/clients`. Omitting it returns `400 invalid_input`."},"context":{"type":"string","description":"Free-form steering context (max 2,000 chars) threaded into the brief and draft"},"language":{"type":"string","description":"Content language code","default":"en"},"location":{"type":"string","description":"Target location for geo-specific content. A conflict with saved workspace service-area knowledge returns `409` before credits or allowance are reserved."},"allow_location_conflict":{"type":"boolean","description":"Set to `true` only after reviewing a `location_conflict` response and confirming the different market is intentional.","default":false},"research_platforms":{"type":"array","items":{"type":"string"},"description":"Same values and fixed-price semantics as `/copywriter/jobs`"}},"required":["topic","page_contract","client_id"]}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"job_id":"uuid","status":"queued","stage":"researching","flat_credits":750,"created_at":"2026-07-07T12:00:00.000Z"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/copywriter/autopilot/{id}":{"get":{"operationId":"get_copywriter_autopilot_by_id","summary":"Get Autopilot run status + review summary","description":"Get Autopilot run status + review summary\n\nReturns the live orchestration state. New runs progress through `queued`, `researching`, `briefing`, `drafting`, `optimizing`, `fact_checking`, `finalizing`, then `complete` or `failed`. Older persisted runs can still report an `image` stage. Poll until `stage` is `complete` or `failed`, then fetch the finished draft with `GET /copywriter/jobs/:id/artifacts` (the Autopilot `job_id` is a regular copywriter job id).\n\nRequired scope: `copywriter:read`.","tags":["Copywriter"],"x-required-scopes":["copywriter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"job_id":"uuid","status":"complete","stage":"complete","started_at":"2026-07-07T12:00:00.000Z","updated_at":"2026-07-07T12:14:05.000Z","completed_at":"2026-07-07T12:14:05.000Z","optimize_passes":2,"optimize_pass_cap":3,"charged":true,"released":false,"error":null,"review":{"verdict":"ready","summary":"...","flags":[]},"publish":{"status":"idle","heldReason":null,"error":null,"pushedAt":null}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/copywriter/jobs":{"get":{"operationId":"get_copywriter_jobs","summary":"List all content jobs","description":"List all content jobs\n\nList all copywriter jobs for your organization, with optional filtering.\n\nRequired scope: `copywriter:read`.","tags":["Copywriter"],"x-required-scopes":["copywriter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:read"]}],"parameters":[{"name":"client_id","in":"query","required":false,"description":"Filter by client","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"description":"Filter by status (e.g., `completed`, `researching`, `brief_ready`, `failed`). Raw internal statuses (`complete`, `analyzing`, `error`, …) are accepted for back-compat.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max results (default 50, max 100)","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Pagination offset (default 0)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"jobs":[{"job_id":"uuid","topic":"Best SEO tools 2025","status":"completed","marked_complete":false,"marked_complete_at":null,"content_type":null,"client_id":"uuid","created_at":"2025-01-15T10:00:00.000Z","updated_at":"2025-01-15T10:30:00.000Z"}],"pagination":{"limit":50,"offset":0,"count":1,"total":1}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"post_copywriter_jobs","summary":"Create a content job","description":"Create a content job\n\nReturns immediately with `\"status\": \"completed\"` and `\"job_id\"`. Calling `GET /copywriter/jobs/:id/artifacts` returns the uploaded body under `draft.content`.\n\nRequired scope: one of `copywriter:run` or `seo_research:run`.","tags":["Copywriter"],"x-required-scopes":[],"x-accepted-scopes":["copywriter:run","seo_research:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:run"]},{"OAuth2":["seo_research:run"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"topic":{"type":"string","description":"Primary keyword/topic"},"client_id":{"type":"string","format":"uuid","description":"Client workspace to scope the project to (must belong to your org). Required so drafts inherit the client's brand voice, knowledge base sources, and excluded topics. Find valid ids with `GET /api/agent/v1/clients`. Omitting it returns `400 invalid_input`."},"intent":{"type":"string","enum":["educate","discover","compete","convert"],"description":"Search intent: `educate`, `discover`, `compete`, `convert`","default":"educate"},"page_contract":{"type":"string","enum":["article","commercial_service"],"description":"Explicit page shape: `article` or `commercial_service`. Required before research/generation so an ambiguous topic cannot silently fall back to an article. `commercial_service` covers local services and broader offers such as training, courses, and consulting. Optional only when `draft_body` is supplied because that path performs no generation."},"mode":{"type":"string","enum":["auto","stepped"],"description":"Execution mode: `auto` or `stepped`","default":"auto"},"location":{"type":"string","description":"Target location (e.g., \"St. Louis, MO\")"},"language":{"type":"string","description":"Content language code. Controls SERP language, brief language, draft language, and entity extraction language. See Supported languages for all codes.","default":"en"},"tone":{"type":"string","enum":["clear_practical","expert_detailed","friendly_simple","technical_precise","persuasive_direct"],"description":"Writing tone: `clear_practical`, `expert_detailed`, `friendly_simple`, `technical_precise`, `persuasive_direct`"},"custom_instructions":{"type":"string","description":"Additional guidance for AI generation"},"word_count_target":{"type":"integer","description":"Target word count (100–10,000)"},"project_mode":{"type":"string","enum":["new","optimize"],"description":"`new` (create from scratch) or `optimize` (optimize existing page)","default":"new"},"source_url":{"type":"string","format":"uri","description":"Page URL to optimize (required when `project_mode` is `optimize`)"},"draft_body":{"type":"string","description":"Pre-written draft content. When supplied, Rankability skips the research/brief/draft pipeline, no AI generation runs for the draft, no credits are charged, and the project is created in `completed` state with this body as the finished draft. Max length: 500,000 characters. Cannot be combined with `project_mode: \"optimize\"` or `source_url`."},"draft_format":{"type":"string","enum":["draft_body","markdown","html"],"description":"Format of `draft_body`: `markdown` or `html`. The exact body and format you send are preserved and returned unchanged by `GET /jobs/:id/artifacts` and the matching `/export/markdown` or `/export/html` route. Ignored when `draft_body` is not supplied.","default":"markdown"},"research_platforms":{"type":"array","items":{"type":"string"},"description":"Which research platforms to run. Changes evidence coverage, not the fixed completed-deliverable price. Allowed values: `organic`, `ai_overview`, `ai_mode`, `perplexity`, `chatgpt`, `grok`, `gemini`, `brave`, `claude`. `organic` is always required and force-enabled. Hidden `google_video_pack` and `youtube_search` compatibility keys are also added to the resolved selection. When omitted, no AI source is selected. Unknown keys are ignored. The resolved list is echoed as `research_platforms`."}},"required":["topic","client_id"]},"example":{"client_id":"uuid","topic":"emergency plumber st louis","intent":"convert","page_contract":"commercial_service","mode":"auto","location":"St. Louis, MO","language":"en","tone":"clear_practical","custom_instructions":"Mention 24/7 availability and licensed technicians","word_count_target":1200,"project_mode":"new","source_url":"https://example.com/existing-page","research_platforms":["organic","ai_overview","perplexity"]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"job_id":"uuid","status":"queued","content_type":"alternatives","created_at":"2026-02-25T15:30:00.000Z","research_platforms":["organic","google_video_pack","youtube_search"],"credits_estimated":750}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/copywriter/jobs/{id}":{"delete":{"operationId":"delete_copywriter_jobs_by_id","summary":"Delete a content job","description":"Delete a content job\n\nPermanently delete a copywriter job/project.\n\nRequired scope: `copywriter:run`.","tags":["Copywriter"],"x-required-scopes":["copywriter:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:run"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"job_id":"uuid","deleted":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"get_copywriter_jobs_by_id","summary":"Get job status","description":"Get job status\n\n`status` describes generation, not the Projects Complete tab. The independent `marked_complete` flag reflects the editor's Mark as done action. `marked_complete_at` is its UTC ISO timestamp, or `null` when not marked Done or when a legacy Done project's original date is unknown. Do not substitute `updated_at`.\n\nRequired scope: `copywriter:read`.","tags":["Copywriter"],"x-required-scopes":["copywriter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"job_id":"uuid","status":"researching","marked_complete":false,"marked_complete_at":null,"content_type":"alternatives","progress":{"stage":"fetching_serp","percent":0.25},"error":null,"created_at":"2026-02-25T15:30:00.000Z","updated_at":"2026-02-25T15:31:00.000Z"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"patch_copywriter_jobs_by_id","summary":"Mark/unmark the project as Done","description":"Mark/unmark the project as Done\n\n`marked_complete` field. Use `false` to undo Done.\n\nRequired scope: `copywriter:run`.","tags":["Copywriter"],"x-required-scopes":["copywriter:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:run"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"job_id":"uuid","status":"completed","marked_complete":true,"marked_complete_at":"2026-10-03T12:30:00.000Z","updated_at":"2026-10-03T12:30:00.000Z"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/copywriter/jobs/{id}/approve":{"post":{"operationId":"post_copywriter_jobs_by_id_approve","summary":"Approve brief","description":"Approve brief (stepped mode)\n\nApproves the brief and triggers draft generation. Only valid for stepped-mode jobs in `brief_ready` status.\n\nRequired scope: `copywriter:run`.","tags":["Copywriter"],"x-required-scopes":["copywriter:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:run"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"job_id":"uuid","status":"generating_draft","brief_approved":true,"approved_at":"2026-02-25T15:35:00.000Z"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/copywriter/jobs/{id}/artifacts":{"get":{"operationId":"get_copywriter_jobs_by_id_artifacts","summary":"Get completed content artifacts","description":"Get completed content artifacts\n\nReturns 409 if job is not yet completed. In stepped mode at `brief_ready`, returns partial artifacts (outline, SEO, entities, FAQs) with `draft` and `score` as `null`.\n\nRequired scope: `copywriter:read`.","tags":["Copywriter"],"x-required-scopes":["copywriter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"content_type":"alternatives","outline":[{"heading":"What Is Emergency Plumbing?","level":"h2","subheadings":[{"heading":"Signs You Need Emergency Service","level":"h3"}]}],"draft":{"format":"markdown","content":"# Emergency Plumber St. Louis\n\nWhen a pipe bursts...","word_count":1247},"seo":{"title_tag":"Emergency Plumber St. Louis | 24/7 Licensed Service","meta_description":"Need an emergency plumber in St. Louis? ...","h1":"Emergency Plumber St. Louis"},"entities":[{"name":"St. Louis","type":"location","relevance":0.95}],"faqs":[{"question":"How much does an emergency plumber cost in St. Louis?","answer":"Emergency plumbing in St. Louis typically costs..."}],"faq_schema_json_ld":"{\"@context\":\"https://schema.org\",\"@type\":\"FAQPage\",...}","score":{"overall":82,"overall_max":100,"calculated_at":"2026-09-22T17:36:39.879Z","scored_revision":"sha256:abc123...","draft_revision":"sha256:abc123...","freshness_state":"current","score_source":"editor","categories":{"copywriting":17,"readability":8,"seo":13},"category_details":{"copywriting":{"score":17,"max_score":20,"percent":85},"readability":{"score":8,"max_score":10,"percent":80},"seo":{"score":13,"max_score":15,"percent":86.7}}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/copywriter/jobs/{id}/brief":{"patch":{"operationId":"patch_copywriter_jobs_by_id_brief","summary":"Edit the brief of a stepped-mode content job before approval","description":"Required scope: `copywriter:run`.","tags":["Copywriter"],"x-required-scopes":["copywriter:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:run"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/copywriter/jobs/{id}/draft":{"put":{"operationId":"put_copywriter_jobs_by_id_draft","summary":"Replace the draft body on an existing project","description":"Replace the draft body on an existing project\n\nReplaces `generated_draft` on an existing copywriter project with a pre-written body. Useful when you've iterated on a draft outside Rankability (in a CMS, a writer's doc, or another tool) and want to push the new copy back without deleting and recreating the project — project metadata (topic, client, tone, brief, exclusions, share token, …) is preserved.\n\nRequired scope: `copywriter:run`.","tags":["Copywriter"],"x-required-scopes":["copywriter:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:run"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"draft_body":{"type":"string","description":"Replacement draft content. Max length: 500,000 characters. Cannot be empty or whitespace-only."},"draft_format":{"type":"string","enum":["draft_body","markdown","html"],"description":"Format of `draft_body`: `markdown` or `html`. The exact body and format you send are preserved and returned unchanged by `GET /jobs/:id/artifacts` and the matching `/export/markdown` or `/export/html` route.","default":"markdown"}},"required":["draft_body"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"job_id":"uuid","status":"completed","draft":{"format":"markdown","word_count":1342},"replaced_at":"2026-05-08T15:30:00.000Z"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/copywriter/jobs/{id}/export/{format}":{"get":{"operationId":"get_copywriter_jobs_by_id_export_by_format","summary":"Export content as markdown or HTML","description":"Export content as markdown or HTML\n\nExport a completed job's draft content in the specified format.\n\nRequired scope: `copywriter:read`.","tags":["Copywriter"],"x-required-scopes":["copywriter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/copywriter/queue/status":{"get":{"operationId":"get_copywriter_queue_status","summary":"Get queue depth, estimated wait, and service alerts","description":"Get queue depth, estimated wait, and service alerts\n\nReturns the current health of the research and draft queues — including global queue depth, number of active workers, your organization's queued job count and estimated position, and any active service alerts. Use this endpoint to monitor queue congestion without polling individual job statuses.\n\nRequired scope: `copywriter:read`.","tags":["Copywriter"],"x-required-scopes":["copywriter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"research":{"queue_depth":4,"active":1,"org_queued_count":2,"org_position":3,"estimated_wait_minutes":9},"draft":{"queue_depth":1,"active":1,"org_queued_count":0,"org_position":null,"estimated_wait_minutes":null},"service_alerts":[],"retrieved_at":"2026-04-30T12:00:00.000Z"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/crawl":{"post":{"operationId":"post_crawl","summary":"Start a bounded multi-page crawl","description":"Required scope: `crawl:run`.","tags":["Crawler"],"x-required-scopes":["crawl:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["crawl:run"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/crawl/{jobId}":{"get":{"operationId":"get_crawl_by_jobId","summary":"Get a crawl job and its pages","description":"Required scope: `crawl:run`.","tags":["Crawler"],"x-required-scopes":["crawl:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["crawl:run"]}],"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/crawler/usage":{"get":{"operationId":"get_crawler_usage","summary":"Get the daily page quota for scrape and crawl","description":"Required scope: one of `scrape:run` or `crawl:run` or `extract:run`.","tags":["Crawler"],"x-required-scopes":[],"x-accepted-scopes":["scrape:run","crawl:run","extract:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["scrape:run"]},{"OAuth2":["crawl:run"]},{"OAuth2":["extract:run"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/credits/balance":{"get":{"operationId":"get_credits_balance","summary":"Get the credit balance","description":"Required scope: one of `copywriter:read` or `reporter:read`.","tags":["Usage"],"x-required-scopes":[],"x-accepted-scopes":["copywriter:read","reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:read"]},{"OAuth2":["reporter:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/entities/jobs":{"post":{"operationId":"post_entities_jobs","summary":"Start an entity-only research job","description":"Required scope: `copywriter:run`.","tags":["Copywriter"],"x-required-scopes":["copywriter:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:run"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/entities/jobs/{job_id}":{"get":{"operationId":"get_entities_jobs_by_job_id","summary":"Get an entity-only research job","description":"Required scope: `copywriter:read`.","tags":["Copywriter"],"x-required-scopes":["copywriter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:read"]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/exports":{"get":{"operationId":"get_exports","summary":"Retrieve a structured browser-free artifact or paginated result handoff","description":"Retrieve a structured browser-free artifact or paginated result handoff\n\nRequired scope: one of `page_audit:read` or `site-auditor:read` or `reporter:read` or `researcher:read` or `copywriter:read`.","tags":["Jobs and exports"],"x-required-scopes":[],"x-accepted-scopes":["page_audit:read","site-auditor:read","reporter:read","researcher:read","copywriter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["page_audit:read"]},{"OAuth2":["site-auditor:read"]},{"OAuth2":["reporter:read"]},{"OAuth2":["researcher:read"]},{"OAuth2":["copywriter:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/extract":{"post":{"operationId":"post_extract","summary":"Extract structured data from a page","description":"Required scope: `extract:run`.","tags":["Crawler"],"x-required-scopes":["extract:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["extract:run"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/jobs/{job_id}":{"get":{"operationId":"get_jobs_by_job_id","summary":"Reconcile supported asynchronous job families through one status contract","description":"Reconcile supported asynchronous job families through one status contract\n\nAny Agent API scope.","tags":["Jobs and exports"],"x-required-scopes":[],"security":[{"ApiKeyAuth":[]},{"OAuth2":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/jobs/status":{"post":{"operationId":"post_jobs_status","summary":"Reconcile one to 50 job IDs in one read-only batch","description":"Reconcile one to 50 job IDs in one read-only batch\n\nAny Agent API scope.","tags":["Jobs and exports"],"x-required-scopes":[],"security":[{"ApiKeyAuth":[]},{"OAuth2":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/kb/articles":{"get":{"operationId":"get_kb_articles","summary":"Get all published KB articles and FAQ content","description":"Get all published KB articles and FAQ content\n\nReturns the canonical Help Center snapshot generated from the same Markdown source that publishes to `help.rankability.com`. The endpoint does not query legacy in-app KB records or scrape GitBook at request time. It supports two response formats via the `Accept` header.\n\nRequired scope: `kb:read`.","tags":["Knowledge Base"],"x-required-scopes":["kb:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["kb:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"articles":[{"id":"uuid","slug":"what-is-rankability","title":"What is Rankability?","summary":"Learn how Rankability organizes SEO and AI search work...","category":"Getting Started","canonical_url":"https://help.rankability.com/getting-started/what-is-rankability","content_html":"<p>Rankability is a search visibility platform...</p>","content_markdown":"Rankability is a search visibility platform...","sort_order":1,"created_at":"2026-08-03T12:00:00.000Z","updated_at":"2026-08-03T12:00:00.000Z"}],"faq_markdown":"# Frequently asked questions\n\n...","meta":{"article_count":89,"last_updated":"2026-08-03T12:00:00.000Z","has_faq":true,"source":"canonical_help_center","canonical_base_url":"https://help.rankability.com","manifest_version":1}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/notifications":{"get":{"operationId":"get_notifications","summary":"List recent notifications for the organization","description":"Required scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/optimizations":{"get":{"operationId":"get_optimizations","summary":"List compact saved optimization history","description":"List compact saved optimization history\n\nRequired scope: `optimize:run`.","tags":["Optimize"],"x-required-scopes":["optimize:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["optimize:run"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/optimizations/{id}":{"get":{"operationId":"get_optimizations_by_id","summary":"Poll a run or read its saved summary/full result","description":"Poll a run or read its saved summary/full result\n\nRequired scope: `optimize:run`.","tags":["Optimize"],"x-required-scopes":["optimize:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["optimize:run"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/optimize":{"post":{"operationId":"post_optimize","summary":"Start one durable, retry-safe page optimization run","description":"Start one durable, retry-safe page optimization run\n\nRequired scope: `optimize:run`.","tags":["Optimize"],"x-required-scopes":["optimize:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["optimize:run"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string","format":"uri","description":"The public URL to analyze and score. Must use `http` or `https` protocol."},"keyword":{"type":"string","description":"The target keyword to evaluate the page against"},"language":{"type":"string","description":"Language code for SERP data (e.g., `en-US`, `es`, `de`, `ja`). Max 10 characters.","default":"en-US"},"client_id":{"type":"string","format":"uuid","description":"Organization-owned client used for run attribution and history filtering."}},"required":["url","keyword"]},"example":{"url":"https://example.com/your-page","keyword":"target keyword","language":"en-US","client_id":"4746d28b-0a38-43f9-a1ca-5e8402ef73d4"}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"optimization_id":"opt-0123456789abcdef","status":"queued","url":"https://example.com/your-page","keyword":"target keyword"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/page-auditor/audits":{"get":{"operationId":"get_page_auditor_audits","summary":"List audits","description":"List audits\n\nList recent audits, most recent first.\n\nRequired scope: `page_audit:read`.","tags":["Page Auditor"],"x-required-scopes":["page_audit:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["page_audit:read"]}],"parameters":[{"name":"client_id","in":"query","required":false,"description":"Filter by client","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"description":"Filter by `pending`, `crawling`, `researching`, `scoring`, `complete`, or `error`","schema":{"type":"string","enum":["pending","crawling","researching","scoring","complete","error"]}},{"name":"limit","in":"query","required":false,"description":"Max 100","schema":{"type":"number","default":50}},{"name":"offset","in":"query","required":false,"description":"For pagination","schema":{"type":"number","default":0}},{"name":"view","in":"query","required":false,"description":"`compact` or `full`","schema":{"type":"string","enum":["compact","full"]}},{"name":"fields","in":"query","required":false,"description":"Explicit top-level field selection; overrides the view field set","schema":{}},{"name":"naming","in":"query","required":false,"description":"Use `legacy` only for mixed-casing backward compatibility","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"audits":[{"audit_id":"8c2a...uuid","status":"complete","keyword":"best running shoes 2026","url":"https://example.com/best-running-shoes","overall_score":78,"created_at":"2026-04-29T15:00:00.000Z","completed_at":"2026-04-29T15:01:42.000Z"}],"pagination":{"limit":50,"offset":0,"count":1,"total":1,"has_more":false},"view":"compact"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"post_page_auditor_audits","summary":"Start one durable retry-safe page audit","description":"Start one durable retry-safe page audit (150 credits on legacy Full accounts)\n\nReserve 150 credits and start a new audit. Returns immediately with `status: \"pending\"`. `Idempotency-Key` is required and derives the durable audit ID, so a retry returns the same audit across process restarts and concurrent delivery. Reusing a key for different inputs returns `409 idempotency_conflict`.\n\nRequired scope: `page_audit:write`.","tags":["Page Auditor"],"x-required-scopes":["page_audit:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["page_audit:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"keyword":{"type":"string","description":"Target keyword the page should rank for. Max 500 chars."},"url":{"type":"string","format":"uri","description":"Public URL to audit. Must use `http` or `https`. Private/loopback hosts are rejected."},"location":{"type":"string","description":"Optional location for SERP context (e.g. `\"United States\"`). Max 200 chars."},"intent":{"type":"string","enum":["informational","commercial","transactional","navigational"],"description":"One of `informational`, `commercial`, `transactional`, `navigational`. If omitted, Rankability infers it from the keyword, URL, and location (for example, a service keyword with a city, state, or \"near me\" is treated as `transactional`, which uses the local-service rubric). The response reports it as `detected_intent` with `intent_source` (`provided` or `inferred`). Pass `intent` to override."},"client_id":{"type":"string","format":"uuid","description":"Optional client to associate the audit with. Must belong to your organization."}},"required":["keyword","url"]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"audit_id":"8c2a...uuid","status":"pending","credits_reserved":150,"keyword":"best running shoes 2026","url":"https://example.com/best-running-shoes","intent":"commercial","detected_intent":"commercial","intent_source":"provided","client_id":null,"created_at":"2026-04-29T15:00:00.000Z"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/page-auditor/audits/{audit_id}":{"delete":{"operationId":"delete_page_auditor_audits_by_audit_id","summary":"Permanently delete a finished audit","description":"Permanently delete a finished audit (409 if it is still in progress — wait for it to finish)\n\nPermanently delete a finished audit and free up clutter from old runs. This lets assistants prune stale audits the same way they prune finished Site Auditor projects.\n\nRequired scope: `page_audit:write`.","tags":["Page Auditor"],"x-required-scopes":["page_audit:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["page_audit:write"]}],"parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"audit_id":"8c2a...uuid"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"get_page_auditor_audits_by_audit_id","summary":"Get an audit by ID","description":"Get an audit by ID\n\nFetch a single audit. Poll with `?view=status` until `status` is `complete` or `error`, then request `view=full` (the default) for the analysis. Nested audit objects use canonical `snake_case` by default; `naming=legacy` preserves the earlier mixed-casing representation.\n\nRequired scope: `page_audit:read`.","tags":["Page Auditor"],"x-required-scopes":["page_audit:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["page_audit:read"]}],"parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/page-auditor/audits/batch":{"put":{"operationId":"put_page_auditor_audits_batch","summary":"Dry-run or start/resume a durable batch of up to 25 audits","description":"Dry-run or start/resume a durable batch of up to 25 audits\n\nThe batch validates tenant ownership, public URLs, duplicates, total capacity, and all legacy credit availability before launching work. Setup failures release newly created reservations and remove newly created audit rows. A retry resumes the same batch rather than creating another set of audits.\n\nRequired scope: `page_audit:write`.","tags":["Page Auditor"],"x-required-scopes":["page_audit:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["page_audit:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/prospect-scans":{"get":{"operationId":"get_prospect_scans","summary":"List prospect AI visibility reports","description":"Required scope: `prospect_scan:read`.","tags":["Prospect scans"],"x-required-scopes":["prospect_scan:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["prospect_scan:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"post_prospect_scans","summary":"Start a prospect AI visibility report","description":"Required scope: `prospect_scan:run`.","tags":["Prospect scans"],"x-required-scopes":["prospect_scan:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["prospect_scan:run"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/prospect-scans/{publicId}":{"get":{"operationId":"get_prospect_scans_by_publicId","summary":"Get one prospect AI visibility report","description":"Required scope: `prospect_scan:read`.","tags":["Prospect scans"],"x-required-scopes":["prospect_scan:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["prospect_scan:read"]}],"parameters":[{"name":"publicId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/brand-summary":{"get":{"operationId":"get_reporter_brand_summary","summary":"Get a client-scoped latest-per-platform brand summary","description":"Get a client-scoped latest-per-platform brand summary\n\nRequired scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/capabilities":{"get":{"operationId":"get_reporter_capabilities","summary":"Preflight platform entitlements, report capacity, and client identity/location dependencies","description":"Preflight platform entitlements, report capacity, and client identity/location dependencies\n\nRequired scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/matrix":{"get":{"operationId":"get_reporter_matrix","summary":"Get the prompt by platform visibility matrix for a client","description":"Required scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/projects":{"get":{"operationId":"get_reporter_projects","summary":"List rank tracking projects","description":"List rank tracking projects\n\nRequired scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"post_reporter_projects","summary":"Create a rank tracking project","description":"Create a rank tracking project\n\nCreate a new rank tracking project with keyword(s), domain, and platform configuration.\n\nRequired scope: `reporter:write`.","tags":["Reporter"],"x-required-scopes":["reporter:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Project name"},"keywords":{"type":"array","items":{},"description":"Exactly one keyword string or `{keyword, targetDomain}` object"},"client_id":{"type":"string","format":"uuid","description":"Associate with a client"},"target_domain":{"type":"string","description":"Domain to track"},"brand_name":{"type":"string","description":"Brand name for mention tracking"},"gbp_location_name":{"type":"string","description":"Google Business Profile location name"},"platforms":{"type":"array","items":{"type":"string"},"description":"Platforms to track (default: google_organic, bing, chatgpt, perplexity, gemini)"},"location":{"type":"string","description":"Geographic location"},"location_lat":{"type":"number","description":"Latitude for local grid tracking"},"location_lng":{"type":"number","description":"Longitude for local grid tracking"},"grid_size":{"type":"string","description":"Grid size: `3x3`, `5x5`, or `7x7` (default: `3x3`)"},"language":{"type":"string","description":"Language code (default: `en`)"},"frequency":{"type":"string","description":"Scan frequency: `daily`, `weekly`, or `monthly` (default: `daily`)"},"platform_frequencies":{"type":"object","additionalProperties":true,"description":"Per-platform frequency overrides, e.g., `{\"chatgpt\": \"weekly\"}`"},"auto_track_enabled":{"type":"boolean","description":"Enable automatic scanning (default: `true`)"},"youtube_channel_url":{"type":"string","nullable":true,"description":"Required when enabling YouTube Search or Google Video Pack unless the client has a connected YouTube identity"},"youtube_channel_name":{"type":"string","nullable":true,"description":"Display name for the tracked YouTube channel"},"tiktok_profile_url":{"type":"string","nullable":true,"description":"Required when enabling TikTok Search unless the client has a saved TikTok profile"},"channel_queries":{"type":"object","additionalProperties":true,"description":"Optional AI, traditional, local, and video channel-specific query overrides"}},"required":["name","keywords"]},"example":{"name":"My SEO Project","keywords":["best seo tools"],"target_domain":"example.com","brand_name":"Example Co","platforms":["google_organic","bing","chatgpt","perplexity","gemini"],"location":"United States","language":"en","frequency":"daily","auto_track_enabled":true}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"id":"uuid","keyword":"best seo tools","domain":"example.com","brand_name":"Example Co","location":"United States","language":"en","platforms":["google_organic","bing","chatgpt","perplexity","gemini"],"frequency":"daily","auto_track_enabled":true,"created_at":"2025-01-15T10:00:00.000Z"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/projects/{id}":{"delete":{"operationId":"delete_reporter_projects_by_id","summary":"Delete a rank tracking project","description":"Delete a rank tracking project\n\nDelete a rank tracking project and all associated data (runs, results, history).\n\nRequired scope: `reporter:write`.","tags":["Reporter"],"x-required-scopes":["reporter:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"id":"uuid","deleted":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"get_reporter_projects_by_id","summary":"Get project detail with latest results","description":"Get project detail with latest results\n\nRequired scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"patch_reporter_projects_by_id","summary":"Update a rank tracking project","description":"Update a rank tracking project\n\nUpdate an existing rank tracking project. Only provided fields are updated.\n\nRequired scope: `reporter:write`.","tags":["Reporter"],"x-required-scopes":["reporter:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Project name"},"target_domain":{"type":"string","description":"Domain to track"},"brand_name":{"type":"string","nullable":true,"description":"Brand name"},"gbp_location_name":{"type":"string","nullable":true,"description":"GBP location name"},"platforms":{"type":"array","items":{"type":"string"},"description":"Platforms to track"},"location":{"type":"string","nullable":true,"description":"Geographic location"},"frequency":{"type":"string","description":"Scan frequency: `daily`, `weekly`, `monthly`"},"platform_frequencies":{"type":"object","additionalProperties":true,"description":"Per-platform frequency overrides"},"auto_track_enabled":{"type":"boolean","description":"Enable/disable automatic scanning"},"youtube_channel_url":{"type":"string","nullable":true,"description":"YouTube channel identity for YouTube Search and Google Video Pack"},"youtube_channel_name":{"type":"string","nullable":true,"description":"YouTube display name"},"tiktok_profile_url":{"type":"string","nullable":true,"description":"TikTok profile identity for TikTok Search"},"channel_queries":{"type":"object","additionalProperties":true,"description":"Channel-specific query overrides"}}},"example":{"brand_name":"New Brand Name","frequency":"weekly","auto_track_enabled":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/projects/{id}/citation-analysis":{"get":{"operationId":"get_reporter_projects_by_id_citation_analysis","summary":"Get citation analysis for a rank tracking project","description":"Required scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/projects/{id}/competitors":{"get":{"operationId":"get_reporter_projects_by_id_competitors","summary":"Get competitors seen in a rank tracking project","description":"Required scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/projects/{id}/results":{"get":{"operationId":"get_reporter_projects_by_id_results","summary":"Get full latest-per-platform results, or select one run","description":"Get full latest-per-platform results, or select one run\n\nRequired scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/projects/{id}/scan":{"post":{"operationId":"post_reporter_projects_by_id_scan","summary":"Trigger a scan of a rank tracking project","description":"Required scope: `reporter:run`.","tags":["Reporter"],"x-required-scopes":["reporter:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:run"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/projects/{id}/scan-estimate":{"get":{"operationId":"get_reporter_projects_by_id_scan_estimate","summary":"Estimate the usage of scanning a rank tracking project","description":"Required scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/projects/{id}/sources":{"get":{"operationId":"get_reporter_projects_by_id_sources","summary":"Get the sources cited in a project's AI answers","description":"Required scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/projects/{id}/trends":{"get":{"operationId":"get_reporter_projects_by_id_trends","summary":"Get SPI trend data","description":"Get SPI trend data\n\nRequired scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/projects/upsert":{"put":{"operationId":"put_reporter_projects_upsert","summary":"Declaratively create or update one client/topic report in place","description":"Declaratively create or update one client/topic report in place; supports `dry_run`\n\nIf more than one legacy report matches the normalized client/topic identity, the API returns `409 ambiguous_tracker_identity` with candidate IDs; retry with `project_id`. Video platforms accept `youtube_channel_url`, `youtube_channel_name`, and `tiktok_profile_url`, with linked client identities used as safe defaults. Dependency and entitlement failures are returned before a write or scan consumes usage.\n\nRequired scope: `reporter:write`.","tags":["Reporter"],"x-required-scopes":["reporter:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"client_id":"uuid","topic":"Mexico residency assistance","platform_policy":{"all_supported":true,"exclude":["local_pack","tiktok_search"]},"frequency":"weekly","auto_track_enabled":true,"dry_run":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/scan-status":{"get":{"operationId":"get_reporter_scan_status","summary":"Get the scan state of every rank tracking project for a client","description":"Required scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/seo-performance":{"get":{"operationId":"get_reporter_seo_performance","summary":"Get GSC and GA4 organic performance from the client's connected Google integrations","description":"Get GSC and GA4 organic performance from the client's connected Google integrations\n\nRequired scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/summary":{"get":{"operationId":"get_reporter_summary","summary":"Get org-wide Reporter summary","description":"Get org-wide Reporter summary\n\nRequired scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/visibility-comparison":{"get":{"operationId":"get_reporter_visibility_comparison","summary":"Compare client visibility between two dates like for like","description":"Compare client visibility between two dates like for like; optional `after_as_of`, or stored campaign snapshots via `before_snapshot_id` / `after_snapshot_id`, `project_ids`, `view=compact|full`\n\nRequired scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/visibility-gaps":{"get":{"operationId":"get_reporter_visibility_gaps","summary":"Find where a client is missing from search and AI answers","description":"Where the client is missing: deduplicated, classified, geo-matched, prioritized pages without the client, AI answers without the client, and organic or Local Pack gaps. `ready` and `source_check_progress` distinguish finished evidence from pages still being checked; repeat the same request after `retry_after_seconds` while false. Same default scope as the summary; cached up to 5 minutes per client, scope, and latest scan (`X-Rankability-Result-Cache: hit|miss`). Optional `project_ids` or `campaign_id` (include exactly those reports), `page_types`, `client_status`, `include_excluded`, `limit`, `offset`, `view`\n\nRequired scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/reporter/visibility-summary":{"get":{"operationId":"get_reporter_visibility_summary","summary":"Get an alias-aware client visibility summary","description":"Get an alias-aware client visibility summary (AI rates, organic and local pack positions, competitors, cited domains). Default scope: scheduled reports only (the rule Serena uses), or every active report when the client has none; `scope.mode` and `scope.excluded_unscheduled` report it. Optional `project_ids` (any report), `subset_project_ids`, `as_of`, `view=compact|full`\n\nRequired scope: `reporter:read`.","tags":["Reporter"],"x-required-scopes":["reporter:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reporter:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/researcher/jobs":{"get":{"operationId":"get_researcher_jobs","summary":"List recent research jobs","description":"List recent research jobs\n\nRequired scope: `researcher:read`.","tags":["Researcher"],"x-required-scopes":["researcher:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["researcher:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"jobs":[{"job_id":"uuid","status":"completed","client_id":null,"mode":"discover","topics":["emergency plumber st louis"],"country":"us","total_keywords":320,"cluster_count":12,"created_at":"2026-04-24T15:30:00.000Z","completed_at":"2026-04-24T15:32:11.000Z"}],"pagination":{"limit":50,"offset":0,"count":1}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"post_researcher_jobs","summary":"Start a keyword research job","description":"Start a keyword research job\n\nStart a keyword research job. If a recent cache entry exists for the same input fingerprint, returns the completed job synchronously.\n\nRequired scope: `researcher:run`.","tags":["Researcher"],"x-required-scopes":["researcher:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["researcher:run"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"topics":{"type":"array","items":{"type":"string"},"description":"1–20 seed topics"},"country":{"type":"string","description":"Two-letter country code (default `us`)"},"location":{"type":"string","description":"City/region for SERP geo-targeting"},"client_id":{"type":"string","format":"uuid","description":"Associate with a Client (must belong to your org)"},"business_description":{"type":"string","description":"Free-text business description"},"competitor_domains":{"type":"array","items":{"type":"string"},"description":"Domains to mine for competitor keywords"},"target_audience":{"type":"string","description":"Audience description"},"content_goals":{"type":"string","description":"Goals (educate, convert, etc.)"},"include_gsc":{"type":"boolean","description":"Pull in Google Search Console data when available"},"use_knowledge_base":{"type":"boolean","description":"Pull brand context from the Client's Knowledge Base. Defaults to `true` when `client_id` is provided and the field is omitted — explicit `false` overrides this."},"mode":{"type":"string","description":"`discover` (default), `trending`, `reddit`, `youtube`, `ecommerce`"},"refresh":{"type":"boolean","description":"Skip cache and re-run from scratch"}},"required":["topics"]},"example":{"topics":["emergency plumber st louis","24 hour plumber"],"country":"us","location":"St. Louis, MO","client_id":"uuid","business_description":"24/7 plumbing services in the St. Louis metro area","competitor_domains":["competitor1.com","competitor2.com"],"target_audience":"Homeowners with urgent plumbing issues","content_goals":"Drive emergency service bookings","include_gsc":false,"use_knowledge_base":false,"mode":"discover","refresh":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"job_id":"uuid","status":"completed","cached":true,"cached_at":"2026-04-23T18:12:00.000Z","credits_charged":0,"mode":"discover","created_at":"2026-04-24T15:30:00.000Z"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"job_id":"uuid","status":"pending","cached":false,"credits_charged":500,"mode":"discover","created_at":"2026-04-24T15:30:00.000Z"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/researcher/jobs/{job_id}":{"get":{"operationId":"get_researcher_jobs_by_job_id","summary":"Poll job status / fetch results","description":"Poll job status / fetch results\n\nRequired scope: `researcher:read`.","tags":["Researcher"],"x-required-scopes":["researcher:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["researcher:read"]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"job_id":"uuid","status":"completed","progress":{"stage":"complete","detail":"Found 320 keywords in 12 clusters"},"client_id":null,"mode":"discover","topics":["emergency plumber st louis"],"country":"us","results":{"totalKeywords":320,"clusters":[{"name":"emergency plumber","keywords":[{"keyword":"emergency plumber st louis","volume":1900,"kd":42,"cpc":"8.50","intent":"transactional","opportunityScore":78,"trend":[10,12,15,14,16],"source":"dataforseo"}]}]},"error":null,"credits_refunded":0,"created_at":"2026-04-24T15:30:00.000Z","completed_at":"2026-04-24T15:32:11.000Z"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/researcher/projects":{"get":{"operationId":"get_researcher_projects","summary":"List saved Researcher projects","description":"List saved Researcher projects\n\nReturns saved Researcher projects (manually-curated keyword lists), most recently updated first.\n\nRequired scope: `researcher:read`.","tags":["Researcher"],"x-required-scopes":["researcher:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["researcher:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"projects":[{"id":"uuid","name":"St. Louis plumber keywords","description":"Manually-curated emergency service terms","client_id":null,"country":"us","keyword_count":42,"created_at":"2026-04-10T00:00:00.000Z","updated_at":"2026-04-24T12:00:00.000Z"}],"pagination":{"limit":50,"offset":0,"count":1}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/researcher/projects/{id}":{"get":{"operationId":"get_researcher_projects_by_id","summary":"Get a project with its saved keywords","description":"Get a project with its saved keywords\n\nReturns the project plus all saved keywords, ordered by most-recently added.\n\nRequired scope: `researcher:read`.","tags":["Researcher"],"x-required-scopes":["researcher:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["researcher:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"id":"uuid","name":"St. Louis plumber keywords","description":"Manually-curated emergency service terms","client_id":null,"country":"us","keyword_count":2,"created_at":"2026-04-10T00:00:00.000Z","updated_at":"2026-04-24T12:00:00.000Z","keywords":[{"id":"uuid","keyword":"emergency plumber st louis","volume":1900,"kd":42,"cpc":"8.50","intent":"transactional","opportunity_score":78,"cluster":"emergency plumber","trend":[10,12,15,14,16],"source":"dataforseo","source_favicon":null,"experimental":false,"position":null,"ranking_url":null,"impressions":null,"clicks":null,"ctr":null,"status":"not_started","priority":"not_set","next_action":"no_action","added_at":"2026-04-10T00:00:00.000Z"}]}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/scrape":{"post":{"operationId":"post_scrape","summary":"Scrape one page with SEO and AEO extraction","description":"Required scope: `scrape:run`.","tags":["Crawler"],"x-required-scopes":["scrape:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["scrape:run"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/search-intelligence/query":{"post":{"operationId":"post_search_intelligence_query","summary":"Run a search intelligence query across Google and AI platforms","description":"Required scope: `search_intelligence:query`.","tags":["Search Intelligence"],"x-required-scopes":["search_intelligence:query"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["search_intelligence:query"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/search-intelligence/query/{runId}":{"get":{"operationId":"get_search_intelligence_query_by_runId","summary":"Get a search intelligence query run","description":"Required scope: `search_intelligence:query`.","tags":["Search Intelligence"],"x-required-scopes":["search_intelligence:query"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["search_intelligence:query"]}],"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/seo-research/connection":{"get":{"operationId":"get_seo_research_connection","summary":"Check the SEO Research connection","description":"Required scope: one of `seo_research:read` or `seo_research:run`.","tags":["SEO Research"],"x-required-scopes":[],"x-accepted-scopes":["seo_research:read","seo_research:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["seo_research:read"]},{"OAuth2":["seo_research:run"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/seo-research/jobs":{"get":{"operationId":"get_seo_research_jobs","summary":"List SEO Research jobs","description":"Required scope: `seo_research:read`.","tags":["SEO Research"],"x-required-scopes":["seo_research:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["seo_research:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"post_seo_research_jobs","summary":"Start an SEO Research job","description":"Required scope: `seo_research:run`.","tags":["SEO Research"],"x-required-scopes":["seo_research:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["seo_research:run"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/seo-research/jobs/{id}":{"get":{"operationId":"get_seo_research_jobs_by_id","summary":"Get an SEO Research job","description":"Required scope: `seo_research:read`.","tags":["SEO Research"],"x-required-scopes":["seo_research:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["seo_research:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/seo-research/jobs/{id}/result":{"get":{"operationId":"get_seo_research_jobs_by_id_result","summary":"Get the result of an SEO Research job","description":"Required scope: `seo_research:read`.","tags":["SEO Research"],"x-required-scopes":["seo_research:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["seo_research:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/seo-research/usage":{"get":{"operationId":"get_seo_research_usage","summary":"Get SEO Research usage","description":"Required scope: one of `seo_research:read` or `seo_research:run`.","tags":["SEO Research"],"x-required-scopes":[],"x-accepted-scopes":["seo_research:read","seo_research:run"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["seo_research:read"]},{"OAuth2":["seo_research:run"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/serena/consult":{"post":{"operationId":"post_serena_consult","summary":"Ask Serena one client-scoped question","description":"Required scope: `serena:ask`.","tags":["Serena"],"x-required-scopes":["serena:ask"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["serena:ask"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/serena/document-reviews":{"post":{"operationId":"post_serena_document_reviews","summary":"Ask Serena to review a Knowledge document","description":"Required scope: `serena:ask`.","tags":["Serena"],"x-required-scopes":["serena:ask"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["serena:ask"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/serena/document-reviews/{review_id}":{"get":{"operationId":"get_serena_document_reviews_by_review_id","summary":"Get a Serena document review","description":"Required scope: `serena:ask`.","tags":["Serena"],"x-required-scopes":["serena:ask"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["serena:ask"]}],"parameters":[{"name":"review_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/site-auditor/credit-estimate":{"get":{"operationId":"get_site_auditor_credit_estimate","summary":"Estimate crawl cost for N pages","description":"Estimate crawl cost for N pages\n\nEstimate the credit cost of a crawl. Read-only, charges nothing.\n\nRequired scope: `site-auditor:read`.","tags":["Site Auditor"],"x-required-scopes":["site-auditor:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["site-auditor:read"]}],"parameters":[{"name":"max_pages","in":"query","required":false,"description":"Pages to estimate for (1 credit / 5 pages)","schema":{"type":"number","default":500}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"max_pages":500,"estimated_credits":100}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/site-auditor/projects":{"get":{"operationId":"get_site_auditor_projects","summary":"List projects","description":"List projects\n\nList projects for your organization, most recent first.\n\nRequired scope: `site-auditor:read`.","tags":["Site Auditor"],"x-required-scopes":["site-auditor:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["site-auditor:read"]}],"parameters":[{"name":"client_id","in":"query","required":false,"description":"Filter by client","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"description":"Filter by `pending`, `crawling`, `analyzing`, `completed`, `error`, or `cancelled`","schema":{"type":"string","enum":["pending","crawling","analyzing","completed","error","cancelled"]}},{"name":"limit","in":"query","required":false,"description":"Max 100","schema":{"type":"number","default":50}},{"name":"offset","in":"query","required":false,"description":"For pagination","schema":{"type":"number","default":0}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"projects":[{"project_id":"8c2a...uuid","domain":"example.com","status":"completed","pages_crawled":312,"issues_found":47,"created_at":"2026-06-14T15:00:00.000Z","completed_at":"2026-06-14T15:04:22.000Z"}],"pagination":{"limit":50,"offset":0,"count":1,"total":1,"has_more":false}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"post_site_auditor_projects","summary":"Create a project and start a full-site crawl","description":"Create a project and start a full-site crawl (1 credit / 5 pages, charged on success)\n\nCreate a Site Auditor project and immediately start the first full-site crawl. Returns with `status: \"crawling\"`.\n\nRequired scope: `site-auditor:write`.","tags":["Site Auditor"],"x-required-scopes":["site-auditor:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["site-auditor:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"domain":{"type":"string","description":"Domain or root URL to crawl (e.g. `\"example.com\"`). A leading `http(s)://` and trailing slash are stripped. Max 2000 chars."},"name":{"type":"string","description":"Human-readable project name. Max 255 chars."},"client_id":{"type":"string","format":"uuid","description":"Optional client to associate the project with. Must belong to your organization."},"max_pages":{"type":"number","description":"Max pages to crawl (default 500, 1–1000). Values outside the shared Site Auditor limit are rejected before work starts. Drives the credit cost."},"max_depth":{"type":"number","description":"Max crawl depth from the root (default 10, 1–50)."},"check_external_links":{"type":"boolean","description":"Whether to validate external links (default false)."}},"required":["domain"]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"project_id":"8c2a...uuid","client_id":null,"name":"Example full-site audit","domain":"example.com","status":"crawling","max_pages":500,"max_depth":10,"check_external_links":false,"total_pages_found":0,"pages_crawled":0,"pages_analyzed":0,"issues_found":0,"created_at":"2026-06-14T15:00:00.000Z","estimated_credits":100}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/site-auditor/projects/{project_id}":{"delete":{"operationId":"delete_site_auditor_projects_by_project_id","summary":"Permanently delete a finished/cancelled/errored project and its pages + issues","description":"Permanently delete a finished/cancelled/errored project and its pages + issues (409 if a crawl is in progress — cancel first)\n\nRequired scope: `site-auditor:write`.","tags":["Site Auditor"],"x-required-scopes":["site-auditor:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["site-auditor:write"]}],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"get_site_auditor_projects_by_project_id","summary":"Get a project with pages + issues","description":"Get a project with pages + issues\n\nFetch a project without forcing its complete inventory into every call. Poll with `?view=status` until terminal. The default `view=summary` returns project, findings totals, and verification totals. Use `view=full` for paginated page and issue records.\n\nRequired scope: `site-auditor:read`.","tags":["Site Auditor"],"x-required-scopes":["site-auditor:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["site-auditor:read"]}],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/site-auditor/projects/{project_id}/cancel":{"post":{"operationId":"post_site_auditor_projects_by_project_id_cancel","summary":"Cancel an in-progress crawl","description":"Cancel an in-progress crawl\n\nAbort an in-progress crawl and flip the project `status` to `cancelled`. Only valid while the crawl is running (`status` is `crawling` or `analyzing`). No credits are charged for a cancelled run. Returns the updated project. If the crawl finished between your status check and the cancel call, the request fails with `409 conflict` rather than clobbering the completed project.\n\nRequired scope: `site-auditor:write`.","tags":["Site Auditor"],"x-required-scopes":["site-auditor:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["site-auditor:write"]}],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/site-auditor/projects/{project_id}/crawl":{"post":{"operationId":"post_site_auditor_projects_by_project_id_crawl","summary":"Re-crawl an existing project","description":"Re-crawl an existing project\n\nStart a fresh crawl on an existing project (reuses the project's stored crawl configuration). Prior crawl data is cleared; user-set page triage is carried over by URL.\n\nRequired scope: `site-auditor:write`.","tags":["Site Auditor"],"x-required-scopes":["site-auditor:write"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["site-auditor:write"]}],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. A stable key for this logical request so retries never repeat or double-charge the work.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/site-auditor/projects/{project_id}/pages/{page_id}":{"get":{"operationId":"get_site_auditor_projects_by_project_id_pages_by_page_id","summary":"Get one crawled page with its issues","description":"Required scope: `site-auditor:read`.","tags":["Site Auditor"],"x-required-scopes":["site-auditor:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["site-auditor:read"]}],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/usage":{"get":{"operationId":"get_usage","summary":"Read the active metering contract and limits","description":"Read the active metering contract and limits\n\nAny Agent API scope.","tags":["Usage"],"x-required-scopes":[],"security":[{"ApiKeyAuth":[]},{"OAuth2":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/usage/estimate":{"get":{"operationId":"get_usage_estimate","summary":"Estimate the usage impact of an operation before running it","description":"Required scope: one of `copywriter:read` or `copywriter:run` or `optimize:run` or `page_audit:read` or `page_audit:write` or `researcher:read` or `researcher:run` or `scrape:run` or `crawl:run` or `extract:run` or `search_intelligence:query` or `site-auditor:read` or `site-auditor:write` or `reporter:read` or `reporter:run` or `prospect_scan:run` or `prospect_scan:read`.","tags":["Usage"],"x-required-scopes":[],"x-accepted-scopes":["copywriter:read","copywriter:run","optimize:run","page_audit:read","page_audit:write","researcher:read","researcher:run","scrape:run","crawl:run","extract:run","search_intelligence:query","site-auditor:read","site-auditor:write","reporter:read","reporter:run","prospect_scan:run","prospect_scan:read"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["copywriter:read"]},{"OAuth2":["copywriter:run"]},{"OAuth2":["optimize:run"]},{"OAuth2":["page_audit:read"]},{"OAuth2":["page_audit:write"]},{"OAuth2":["researcher:read"]},{"OAuth2":["researcher:run"]},{"OAuth2":["scrape:run"]},{"OAuth2":["crawl:run"]},{"OAuth2":["extract:run"]},{"OAuth2":["search_intelligence:query"]},{"OAuth2":["site-auditor:read"]},{"OAuth2":["site-auditor:write"]},{"OAuth2":["reporter:read"]},{"OAuth2":["reporter:run"]},{"OAuth2":["prospect_scan:run"]},{"OAuth2":["prospect_scan:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/agent/v1/usage/events":{"get":{"operationId":"get_usage_events","summary":"List completed usage outcomes with bounded pagination","description":"List completed usage outcomes with bounded pagination\n\nAny Agent API scope.","tags":["Usage"],"x-required-scopes":[],"security":[{"ApiKeyAuth":[]},{"OAuth2":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-API-Version":{"$ref":"#/components/headers/X-API-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"rk_live_ API key","description":"Organization API key sent as `Authorization: Bearer rk_live_...`. Create keys in Settings > API keys; each key carries its own scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authorization code flow with PKCE (S256), used by MCP clients and integrations. Dynamic client registration is available at /oauth/register; metadata at /.well-known/oauth-authorization-server. Send the access token as `Authorization: Bearer <token>`.","flows":{"authorizationCode":{"authorizationUrl":"https://app.rankability.com/oauth/authorize","tokenUrl":"https://app.rankability.com/oauth/token","refreshUrl":"https://app.rankability.com/oauth/token","scopes":{"copywriter:run":"Create content","copywriter:read":"Read content","reporter:read":"Read reporter data","reporter:run":"Trigger scans","reporter:write":"Manage reporter projects","prospect_scan:run":"Run prospect visibility reports","prospect_scan:read":"Read prospect visibility reports","researcher:run":"Run keyword research","researcher:read":"Read research jobs & projects","seo_research:run":"Run SEO research","seo_research:read":"Read SEO research","clients:read":"Read workspaces","clients:write":"Create, update & delete workspaces","kb:read":"Read knowledge base","optimize:run":"Run page optimization","page_audit:read":"Read page audits","page_audit:write":"Run page audits","site-auditor:read":"Read site audits","site-auditor:write":"Run site audits","search_intelligence:query":"Query search intelligence (Google + AI platforms)","scrape:run":"Scrape a page (SEO + AEO extraction)","crawl:run":"Crawl a site (bounded multi-page)","extract:run":"Extract structured data from a page","prospector:read":"Read Prospector lists & outreach items","prospector:write":"Manage Prospector lists & outreach items","backlinks:read":"Read saved backlink profile evidence","backlinks:run":"Refresh backlink profile evidence","gbp-audit:read":"Read saved GBP audit evidence","batch-url:read":"Read saved Batch URL Analyzer runs","routines:read":"Read recurring Routine state","publishing:read":"Read publishing connections & receipts","publishing:write":"Create publishing drafts","serena:ask":"Consult Serena (read-only)"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_input"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}},"headers":{"X-Request-Id":{"description":"Unique request id for tracing and support.","schema":{"type":"string"}},"X-API-Version":{"description":"Agent API contract version.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum requests in the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}}},"responses":{"BadRequest":{"description":"Invalid input (`invalid_input`) or an operation not valid in the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing, invalid, expired or revoked credentials (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The credential lacks a required scope (`forbidden`), or the organization's plan does not include this (`plan_required`, `plan_limit_exceeded`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found or not owned by your organization (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests (`rate_limit_exceeded`) or on-demand usage paused (`usage_limit_reached`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error":{"description":"Error. See `error.code`; common codes include `insufficient_credits` (402), `conflict` (409) and `service_unavailable` (503).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}