{"openapi": "3.0.3", "info": {"title": "seofetch API", "version": "v1"}, "servers": [{"url": "https://api.seofetch.com"}], "paths": {"/v1/search": {"post": {"summary": "Run one search query and get the parsed SERP back \u2014 ranked items, not raw HTML.", "operationId": "search", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string", "maxLength": 700, "description": "Search query text. Required, max 700 chars."}, "engine": {"type": "string", "enum": ["bing", "google", "google-images", "google-maps", "google-news", "google-shopping", "yandex", "youtube"], "default": "google", "description": "Search engine. Optional, default \"google\". One of: google, google-maps, google-news, google-images, google-shopping, bing, yandex, youtube."}, "location": {"default": 2840, "description": "Google Ads geotarget ID. Optional, default 2840 (United States). Look one up with /v1/locations."}, "language": {"type": "string", "default": "en", "description": "ISO language code. Optional, default \"en\"."}, "device": {"type": "string", "enum": ["desktop", "mobile"], "default": "desktop", "description": "One of: desktop, mobile. Optional, default \"desktop\"."}, "depth": {"type": "integer", "enum": [10, 100], "default": 10, "description": "10 results \u2014 1 credit (default); 100 results \u2014 10 credits."}}, "required": ["query"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/keywords/volume": {"post": {"summary": "Historical Google keyword search volume and competition metrics.", "operationId": "keyword_volume", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"keywords": {"type": "array", "items": {"type": "string"}, "minItems": 1, "maxItems": 500, "description": "Keywords to fetch search volume for. Required, non-empty."}, "location": {"description": "Google Ads geotarget ID, or a location name (e.g. a country/state/city name). Required. Look one up with /v1/locations."}, "language": {"type": "string", "description": "ISO language code. Required."}, "search_partners": {"type": "boolean", "default": false, "description": "Include Google Search Network partner sites in the volume figures. Optional, default false."}, "tag": {"type": "string", "description": "Optional client-defined label forwarded to the upstream job for your own bookkeeping; not echoed back in the response."}}, "required": ["keywords", "location", "language"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/keywords/difficulty": {"post": {"summary": "Keyword difficulty (0-100) per keyword; unscored keywords return pending and are scored for a later call.", "operationId": "keyword_difficulty", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"keywords": {"type": "array", "items": {"type": "string"}, "minItems": 1, "maxItems": 500, "description": "Keywords to score difficulty for. Required, non-empty."}, "location": {"description": "Google Ads geotarget ID, or a location name (e.g. a country/state/city name). Required. Look one up with /v1/locations."}, "language": {"type": "string", "description": "ISO language code. Required."}, "tag": {"type": "string", "description": "Optional client-defined label forwarded to the upstream task for your own bookkeeping; not echoed back in the response."}}, "required": ["keywords", "location", "language"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/backlinks/summary": {"post": {"summary": "Backlink profile summary metrics for a domain or URL.", "operationId": "backlink_summary", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"target": {"type": "string", "description": "Domain or URL to analyze backlinks for. Required."}}, "required": ["target"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/backlinks/list": {"post": {"summary": "Individual backlinks pointing at a domain or URL.", "operationId": "backlink_list", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"target": {"type": "string", "description": "Domain or URL to analyze backlinks for. Required."}, "limit": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "Page size. Optional, default 100."}, "offset": {"type": "integer", "minimum": 0, "maximum": 10000, "default": 0, "description": "Pagination offset. Optional, default 0."}}, "required": ["target"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/backlinks/domains": {"post": {"summary": "Domains that link to a target, with per-domain metrics.", "operationId": "referring_domains", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"target": {"type": "string", "description": "Domain or URL to analyze backlinks for. Required."}, "limit": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "Page size. Optional, default 100."}, "offset": {"type": "integer", "minimum": 0, "maximum": 10000, "default": 0, "description": "Pagination offset. Optional, default 0."}}, "required": ["target"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/backlinks/anchors": {"post": {"summary": "Anchor-text distribution of backlinks to a target.", "operationId": "backlink_anchors", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"target": {"type": "string", "description": "Domain or URL to analyze backlinks for. Required."}, "limit": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "Page size. Optional, default 100."}, "offset": {"type": "integer", "minimum": 0, "maximum": 10000, "default": 0, "description": "Pagination offset. Optional, default 0."}}, "required": ["target"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/domains/overview": {"post": {"summary": "Return a domain's organic and paid search overview for one market.", "operationId": "domain_overview", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"domain": {"type": "string", "maxLength": 253, "description": "Domain to look up (bare hostname, e.g. example.com). Required, max 253 chars."}, "location": {"type": "integer", "default": 2840, "description": "Google Ads geotarget ID. Optional, default 2840 (United States). Look one up with /v1/locations."}, "language": {"type": "string", "default": "en", "description": "ISO language code. Optional, default \"en\"."}}, "required": ["domain"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/page/lighthouse": {"post": {"summary": "Lighthouse scores and core web vitals for a single page.", "operationId": "lighthouse", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"url": {"type": "string", "description": "Absolute http(s) page URL to audit. Required, max 2048 chars."}, "device": {"type": "string", "enum": ["mobile", "desktop"], "default": "mobile", "description": "One of: mobile, desktop. Optional, default \"mobile\"."}}, "required": ["url"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/page/crawl": {"post": {"summary": "Render a single page and return a slim page-SEO snapshot.", "operationId": "crawl", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"url": {"type": "string", "format": "uri", "maxLength": 2048, "description": "Absolute http(s) page URL to render and analyze. Required, max 2048 chars."}}, "required": ["url"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/page/accessibility": {"post": {"summary": "Axe accessibility scan of a single page \u2014 violations, keyboard-navigation checks, honest scan status.", "operationId": "accessibility", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"url": {"type": "string", "format": "uri", "maxLength": 2048, "description": "Absolute http(s) page URL to scan. Required, max 2048 chars."}}, "required": ["url"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/site/audit": {"post": {"summary": "Crawl and audit a whole site; billed per delivered page (sum of enabled checks x pages delivered).", "operationId": "site_audit", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"domain": {"type": "string", "description": "Domain or URL to crawl -- the hostname is extracted from either form. Required, max 253 chars."}, "max_pages": {"type": "integer", "minimum": 1, "maximum": 500, "description": "Maximum number of pages to crawl before stopping."}, "checks": {"type": "array", "items": {"type": "string", "enum": ["crawl", "lighthouse", "accessibility"]}, "minItems": 1, "default": ["crawl"], "description": "Which checks to run per crawled page. Optional, default [\"crawl\"]. Duplicates removed, order preserved."}, "device": {"type": "string", "enum": ["mobile", "desktop"], "default": "mobile", "description": "One of: mobile, desktop. Optional, default \"mobile\"."}}, "required": ["domain", "max_pages"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/serp/history": {"post": {"summary": "Position history for a (domain, keyword) pair from our SERP archive.", "operationId": "serp_history", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"domain": {"type": "string", "description": "Domain to check ranking history for (bare hostname, lowercased). Required, max 255 chars, no spaces."}, "keyword": {"type": "string", "maxLength": 700, "description": "Keyword to check ranking history for. Required, max 700 chars."}, "engine": {"type": "string", "enum": ["bing", "google", "google-images", "google-maps", "google-news", "google-shopping", "yandex", "youtube"], "default": "google", "description": "Optional, default \"google\". Same enum as /v1/search."}, "location": {"default": 2840, "description": "Google Ads geotarget ID. Optional, default 2840 (United States). Look one up with /v1/locations."}, "language": {"type": "string", "default": "en", "description": "ISO language code. Optional, default \"en\"."}, "device": {"type": "string", "enum": ["desktop", "mobile"], "default": "desktop", "description": "One of: desktop, mobile. Optional, default \"desktop\"."}, "date_from": {"type": "string", "description": "ISO YYYY-MM-DD, inclusive. Optional, default 730 days ago -- the rankings archive's TTL floor. An empty result is still a chargeable answer: coverage.observations counts the distinct days we archived this exact SERP in the window, so it can mean either \"we observed you on N days and you never ranked\" (observations > 0) or \"we never looked\" (observations: 0)."}, "date_to": {"type": "string", "description": "ISO YYYY-MM-DD, inclusive. Optional, default today."}}, "required": ["domain", "keyword"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/domains/card": {"post": {"summary": "Company card \u2014 identity, contacts, socials, technology from our crawl.", "operationId": "domain_card", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"domain": {"type": "string", "description": "Domain to look up (bare hostname, lowercased). Required, max 255 chars, no spaces."}}, "required": ["domain"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/keywords/questions": {"post": {"summary": "People-Also-Ask questions observed for a topic, deduplicated.", "operationId": "keyword_questions", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"keyword": {"type": "string", "description": "Topic keyword to fetch People-Also-Ask questions for. Required, max 700 chars."}, "location": {"default": 2840, "description": "Google Ads geotarget ID. Optional, default 2840 (United States). Look one up with /v1/locations."}, "language": {"type": "string", "default": "en", "description": "ISO language code. Optional, default \"en\"."}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Optional, default 50."}}, "required": ["keyword"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/ai/visibility": {"post": {"summary": "How often AI assistants mention a domain, per provider, over time.", "operationId": "ai_visibility", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"domain": {"type": "string", "description": "Domain to check AI-assistant mentions for (bare hostname, lowercased). Required, max 255 chars, no spaces."}, "providers": {"type": "array", "items": {"type": "string", "enum": ["chatgpt", "perplexity", "gemini", "copilot", "lechat"]}, "minItems": 1, "default": ["chatgpt", "perplexity", "gemini", "copilot", "lechat"], "description": "Optional, default all five (order preserved). Must be non-empty when present; unknown or internal-only lanes are rejected, never exposed."}, "granularity": {"type": "string", "enum": ["day", "week"], "default": "week", "description": "One of: day, week. Optional, default \"week\"."}, "date_from": {"type": "string", "description": "ISO YYYY-MM-DD, inclusive. Optional, default 90 days ago."}, "date_to": {"type": "string", "description": "ISO YYYY-MM-DD, inclusive. Optional, default today."}}, "required": ["domain"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/locations": {"get": {"summary": "Look up Google Ads geotarget IDs by name \u2014 country, state/region, city, or neighborhood.", "operationId": "location_list", "security": [{"bearerAuth": []}], "parameters": [{"name": "q", "in": "query", "required": true, "schema": {"type": "string", "description": "Name to search for. Required, min 2 chars. Common names match many places worldwide -- narrow multi-match names with a region or country word, e.g. \"austin texas\" instead of just \"austin\"."}}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Optional, default 10."}}], "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "405": {"description": "Wrong HTTP method.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/v1/domains/competitors": {"post": {"summary": "Competitor discovery from the SERP archive: domains that rank for the same keywords, ranked by overlap.", "operationId": "domain_competitors", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"domain": {"type": "string", "description": "Domain to find competitors for (bare hostname, lowercased). Required, max 255 chars, no spaces."}, "engine": {"type": "string", "enum": ["bing", "google", "google-images", "google-maps", "google-news", "google-shopping", "yandex", "youtube"], "default": "google", "description": "Optional, default \"google\". Same enum as /v1/search."}, "location": {"type": "integer", "default": 2840, "description": "Google Ads geotarget ID. Optional, default 2840 (United States). Look one up with /v1/locations."}, "language": {"type": "string", "default": "en", "description": "ISO language code. Optional, default \"en\"."}, "device": {"type": "string", "enum": ["desktop", "mobile"], "default": "desktop", "description": "One of: desktop, mobile. Optional, default \"desktop\"."}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of competitors to return. Optional, default 25."}, "date_from": {"type": "string", "description": "ISO YYYY-MM-DD, inclusive. Optional, default 730 days ago -- sets how far back in the archive the comparison reaches."}}, "required": ["domain"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}, "/v1/domains/gap": {"post": {"summary": "Keyword gap between two domains: opportunity, shared, or unique rankings, volume-enriched.", "operationId": "domain_gap", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"domains": {"type": "array", "items": {"type": "string"}, "minItems": 2, "maxItems": 2, "description": "Put your own domain first -- every mode is defined relative to domains[0]."}, "mode": {"type": "string", "enum": ["gap", "shared", "unique"], "default": "gap", "description": "gap: keywords domains[1] ranks for that domains[0] does not. shared: both rank. unique: only domains[0] ranks. Optional, default \"gap\"."}, "engine": {"type": "string", "enum": ["bing", "google", "google-images", "google-maps", "google-news", "google-shopping", "yandex", "youtube"], "default": "google", "description": "Optional, default \"google\". Same enum as /v1/search."}, "location": {"type": "integer", "default": 2840, "description": "Google Ads geotarget ID. Optional, default 2840 (United States). Look one up with /v1/locations."}, "language": {"type": "string", "default": "en", "description": "ISO language code. Optional, default \"en\"."}, "device": {"type": "string", "enum": ["desktop", "mobile"], "default": "desktop", "description": "One of: desktop, mobile. Optional, default \"desktop\"."}, "date_from": {"type": "string", "description": "ISO YYYY-MM-DD, inclusive. Optional, default 730 days ago -- sets how far back in the archive the comparison reaches."}, "limit": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "Optional, default 100."}, "offset": {"type": "integer", "minimum": 0, "maximum": 10000, "default": 0, "description": "Optional, default 0."}}, "required": ["domains"]}}}}, "responses": {"200": {"description": "Success.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["id", "request_id", "object", "created_at", "elapsed_ms", "cache", "credits", "data"], "properties": {"id": {"type": "string"}, "request_id": {"type": "string", "description": "This request's replay token. Send it back as Idempotency-Key (or use your own key up front) and a retry -- keyed or keyless, mid-flight or later -- is never charged twice. Format: req_<26 lowercase base32 chars>. See The Contract for the exact rules.", "example": "req_tmo6wtj3pvf23g65fmgxwpolnu"}, "object": {"type": "string"}, "created_at": {"type": "string"}, "elapsed_ms": {"type": "integer"}, "cache": {"type": "string"}, "credits": {"type": "object"}, "data": {"type": "object"}}}}}}, "400": {"description": "Invalid request.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Authentication failed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "IP not allowed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Insufficient credits, or account suspended.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency key valid, but its stored result is no longer retained.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "502": {"description": "Upstream error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Upstream timeout, or the result has not returned on this connection.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/ConnectionTimeoutError"}]}}}}}, "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional. Retry the same request safely -- a retry with the same key is never charged twice. If you send none, the response's request_id serves the same purpose.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{8,255}$"}}]}}}, "components": {"schemas": {"Error": {"type": "object", "required": ["error"], "additionalProperties": false, "properties": {"error": {"type": "object", "required": ["type", "code", "message"], "additionalProperties": false, "properties": {"type": {"type": "string", "enum": ["account_suspended", "authentication_error", "insufficient_credits", "invalid_request_error", "ip_not_allowed", "rate_limit_error", "upstream_error", "upstream_timeout"]}, "code": {"type": "string", "enum": ["account_suspended", "connection_timeout", "forbidden_key", "idempotency_key_invalid", "idempotency_key_result_expired", "idempotency_key_reused", "insufficient_credits", "invalid", "invalid_checks", "invalid_date", "invalid_depth", "invalid_device", "invalid_domain", "invalid_engine", "invalid_granularity", "invalid_keyword", "invalid_keywords", "invalid_language", "invalid_location", "invalid_max_pages", "invalid_mode", "invalid_prompt", "invalid_provider", "invalid_query", "invalid_target", "invalid_type", "invalid_url", "ip_not_allowed", "key_invalid", "key_revoked", "limit_out_of_range", "method_not_allowed", "offset_out_of_range", "rate_limited", "upstream_blocked", "upstream_error", "upstream_timeout"]}, "message": {"type": "string"}, "param": {"type": "string"}}}}}, "ConnectionTimeoutError": {"type": "object", "required": ["error", "request_id"], "additionalProperties": false, "properties": {"error": {"type": "object", "required": ["type", "code", "message"], "additionalProperties": false, "properties": {"type": {"type": "string", "enum": ["account_suspended", "authentication_error", "insufficient_credits", "invalid_request_error", "ip_not_allowed", "rate_limit_error", "upstream_error", "upstream_timeout"]}, "code": {"type": "string", "enum": ["account_suspended", "connection_timeout", "forbidden_key", "idempotency_key_invalid", "idempotency_key_result_expired", "idempotency_key_reused", "insufficient_credits", "invalid", "invalid_checks", "invalid_date", "invalid_depth", "invalid_device", "invalid_domain", "invalid_engine", "invalid_granularity", "invalid_keyword", "invalid_keywords", "invalid_language", "invalid_location", "invalid_max_pages", "invalid_mode", "invalid_prompt", "invalid_provider", "invalid_query", "invalid_target", "invalid_type", "invalid_url", "ip_not_allowed", "key_invalid", "key_revoked", "limit_out_of_range", "method_not_allowed", "offset_out_of_range", "rate_limited", "upstream_blocked", "upstream_error", "upstream_timeout"]}, "message": {"type": "string"}, "param": {"type": "string"}}}, "request_id": {"type": "string"}}}}, "securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer"}}}}