{ "openapi": "3.1.0", "info": { "title": "Context.dev API", "description": "API for retrieving context data from any website", "version": "1.0.0" }, "servers": [ { "url": "https://api.context.dev/v1" } ], "tags": [ { "name": "Webhooks", "description": "Inspect and retry webhook deliveries. These endpoints cost no credits." }, { "name": "Logs", "description": "Read your organization's API request logs to debug failed calls. These endpoints cost no credits and use a separate rate limit." }, { "name": "Batch", "description": "Scrape many pages or crawl a site asynchronously." }, { "name": "Monitors", "description": "Monitor pages, sitemaps, and extracted website data for exact or semantic changes. Webhook payloads are documented by the MonitorsChangeDetectedWebhookPayload and MonitorsRunCompletedWebhookPayload schemas." }, { "name": "News", "description": "Search live first-party RSS and free historical news data by company identity." } ], "paths": { "/logs": { "get": { "operationId": "listLogs", "summary": "List request logs", "tags": [ "Logs" ], "description": "List your organization's API requests, newest first. Defaults to the last 24 hours.", "parameters": [ { "schema": { "type": "string", "format": "date-time", "description": "Only include requests at or after this ISO 8601 timestamp. Defaults to 24 hours before `to`.", "example": "2026-09-10T00:00:00Z" }, "required": false, "description": "Only include requests at or after this ISO 8601 timestamp. Defaults to 24 hours before `to`.", "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Only include requests at or before this ISO 8601 timestamp. Defaults to now.", "example": "2026-09-11T00:00:00Z" }, "required": false, "description": "Only include requests at or before this ISO 8601 timestamp. Defaults to now.", "name": "to", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^\\/", "description": "Filter by endpoint path, with or without the /v1 prefix.", "example": "/brand/retrieve" }, "required": false, "description": "Filter by endpoint path, with or without the /v1 prefix.", "name": "path", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Filter by the API key that made the request." }, "required": false, "description": "Filter by the API key that made the request.", "name": "key_id", "in": "query" }, { "schema": { "type": "integer", "minimum": 100, "maximum": 599, "description": "Filter by exact HTTP status code.", "example": 500 }, "required": false, "description": "Filter by exact HTTP status code.", "name": "status_code", "in": "query" }, { "schema": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{1,63}$", "description": "Filter by the `error_code` returned in the response.", "example": "WEBSITE_ACCESS_ERROR" }, "required": false, "description": "Filter by the `error_code` returned in the response.", "name": "error_code", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "Only include requests that returned a 4xx or 5xx status." }, "required": false, "description": "Only include requests that returned a 4xx or 5xx status.", "name": "errors_only", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated request tags. Matches requests carrying any of them. Up to 20 tags, each 1-50 characters.", "example": "nightly-import,team-alpha" }, "required": false, "description": "Comma-separated request tags. Matches requests carrying any of them. Up to 20 tags, each 1-50 characters.", "name": "tags", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-insensitive substring match against the request query and body, e.g. a domain.", "example": "acme.com" }, "required": false, "description": "Case-insensitive substring match against the request query and body, e.g. a domain.", "name": "search", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1, "description": "Page number, starting at 1." }, "required": false, "description": "Page number, starting at 1.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Number of log entries per page." }, "required": false, "description": "Number of log entries per page.", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "A page of log entries", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListLogsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "description": "Rate limit exceeded (60 requests per minute per organization).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Log storage is temporarily unavailable.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/logs/{request_id}": { "get": { "operationId": "getLog", "summary": "Get a request log", "tags": [ "Logs" ], "description": "Get one logged API call, including its request input and response body.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "The request ID of the logged API call." }, "required": true, "description": "The request ID of the logged API call.", "name": "request_id", "in": "path" } ], "responses": { "200": { "description": "Log entry", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLogResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Rate limit exceeded (60 requests per minute per organization).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Log storage is temporarily unavailable.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/deliveries": { "post": { "operationId": "listWebhookDeliveries", "summary": "List webhook deliveries", "tags": [ "Webhooks" ], "description": "List your batch or monitor webhook deliveries, newest first.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "batch" ], "description": "Delivery source." }, "batch_id": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\w-]+$", "description": "Filter by batch ID." }, "status": { "type": "string", "enum": [ "pending", "delivering", "retrying", "delivered", "failed", "cancelled" ], "description": "Filter by delivery status." }, "created_after": { "type": "string", "format": "date-time", "description": "Only include events created after this ISO 8601 timestamp.", "example": "2026-09-01T00:00:00Z" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of deliveries to return." }, "cursor": { "type": "string", "pattern": "^whd_[a-f0-9]{32}$", "description": "The next_cursor from the previous response." }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "type" ], "additionalProperties": false, "title": "By Batch" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "monitor" ], "description": "Delivery source." }, "monitor_id": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\w-]+$", "description": "Filter by monitor ID." }, "run_id": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\w-]+$", "description": "Filter by monitor run ID." }, "status": { "type": "string", "enum": [ "pending", "delivering", "retrying", "delivered", "failed", "cancelled" ], "description": "Filter by delivery status." }, "created_after": { "type": "string", "format": "date-time", "description": "Only include events created after this ISO 8601 timestamp.", "example": "2026-09-01T00:00:00Z" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of deliveries to return." }, "cursor": { "type": "string", "pattern": "^whd_[a-f0-9]{32}$", "description": "The next_cursor from the previous response." }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "type" ], "additionalProperties": false, "title": "By Monitor" } ], "discriminator": { "propertyName": "type" } }, "examples": { "batch": { "summary": "List failed batch deliveries", "value": { "type": "batch", "status": "failed", "limit": 25 } }, "monitor": { "summary": "List deliveries for a monitor run", "value": { "type": "monitor", "monitor_id": "mon_123", "run_id": "run_123" } }, "recent_monitor_failures": { "summary": "List recent monitor delivery failures", "value": { "type": "monitor", "status": "failed", "created_after": "2026-09-01T00:00:00Z", "limit": 100 } } } } } }, "responses": { "200": { "description": "A page of webhook deliveries", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhookDeliveriesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Rate limit exceeded (600 requests per minute per organization).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Webhook service is temporarily unavailable.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/deliveries/{delivery_id}": { "get": { "operationId": "getWebhookDelivery", "summary": "Get a webhook delivery", "tags": [ "Webhooks" ], "description": "Get a webhook delivery, including its status and latest attempt.", "parameters": [ { "schema": { "type": "string", "pattern": "^whd_[a-f0-9]{32}$", "description": "Delivery ID." }, "required": true, "description": "Delivery ID.", "name": "delivery_id", "in": "path" }, { "$ref": "#/components/parameters/RequestTags" } ], "responses": { "200": { "description": "Webhook delivery", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDelivery" }, { "type": "object", "properties": { "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Rate limit exceeded (600 requests per minute per organization).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Webhook service is temporarily unavailable.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/deliveries/{delivery_id}/attempts": { "get": { "operationId": "listWebhookDeliveryAttempts", "summary": "List webhook delivery attempts", "tags": [ "Webhooks" ], "description": "List delivery attempts, newest first.", "parameters": [ { "schema": { "type": "string", "pattern": "^whd_[a-f0-9]{32}$", "description": "Delivery ID." }, "required": true, "description": "Delivery ID.", "name": "delivery_id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of attempts to return." }, "required": false, "description": "Number of attempts to return.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^wha_[a-f0-9]{32}$", "description": "The next_cursor from the previous response." }, "required": false, "description": "The next_cursor from the previous response.", "name": "cursor", "in": "query" }, { "$ref": "#/components/parameters/RequestTags" } ], "responses": { "200": { "description": "A page of delivery attempts", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhookAttemptsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Rate limit exceeded (600 requests per minute per organization).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Webhook service is temporarily unavailable.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/deliveries/{delivery_id}/retry": { "post": { "operationId": "retryWebhookDelivery", "summary": "Retry a webhook delivery", "tags": [ "Webhooks" ], "description": "Retry a webhook delivery within seven days of creation.", "parameters": [ { "schema": { "type": "string", "pattern": "^whd_[a-f0-9]{32}$", "description": "Delivery ID." }, "required": true, "description": "Delivery ID.", "name": "delivery_id", "in": "path" }, { "schema": { "type": "string", "maxLength": 200, "description": "Unique key to prevent duplicate retry requests." }, "required": false, "description": "Unique key to prevent duplicate retry requests.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "force": { "type": "boolean", "description": "Resend a delivery that already succeeded." }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "additionalProperties": false }, "example": {} } } }, "responses": { "202": { "description": "Retry accepted.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Location": { "description": "Delivery status URL.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryWebhookDeliveryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Delivery cannot be retried or the idempotency key conflicts.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The seven-day retry window has expired.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded (600 requests per minute per organization).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Webhook service is temporarily unavailable.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/news/search": { "post": { "summary": "Search company news", "description": "Searches live and historical company news for one company, identified in searchBy by name, domain, ticker (optionally disambiguated by exchange), or ISIN. Results can be filtered by publisher domain, publisher country, article language, article type, and published-at date, and include stable story IDs, source metadata, verified entity relevance, and cursor pagination.", "tags": [ "News" ], "x-mint": { "content": "1 Credit Per 10 Results" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "searchBy": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "entity" ], "description": "How to search. Only entity search is supported." }, "entity": { "oneOf": [ { "$ref": "#/components/schemas/NewsSearchEntityByName" }, { "$ref": "#/components/schemas/NewsSearchEntityByDomain" }, { "$ref": "#/components/schemas/NewsSearchEntityByTicker" }, { "$ref": "#/components/schemas/NewsSearchEntityByIsin" } ], "discriminator": { "propertyName": "type", "mapping": { "name": "#/components/schemas/NewsSearchEntityByName", "domain": "#/components/schemas/NewsSearchEntityByDomain", "ticker": "#/components/schemas/NewsSearchEntityByTicker", "isin": "#/components/schemas/NewsSearchEntityByIsin" } }, "description": "The company to search news for, identified by name, domain, ticker, or ISIN." } }, "required": [ "type", "entity" ], "additionalProperties": false, "description": "What to search for." }, "filterBy": { "type": "object", "properties": { "sourceDomain": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 }, "minItems": 1, "maxItems": 3, "description": "Publisher domains to include. Up to 3." }, "sourceCountry": { "type": "array", "items": { "type": "string", "enum": [ "ae", "ar", "au", "ca", "cg", "ch", "cl", "cz", "de", "fi", "fr", "gb", "hk", "il", "in", "jp", "kr", "mx", "ng", "nl", "qa", "sa", "se", "sg", "us", "za" ] }, "minItems": 1, "maxItems": 3, "description": "Publisher countries to include, as lowercase ISO 3166-1 alpha-2 codes. Up to 3." }, "articleLanguage": { "type": "array", "items": { "type": "string", "enum": [ "ar", "de", "en", "es", "fr", "hi", "it", "ja", "ko", "nl", "pt", "ru", "zh" ] }, "minItems": 1, "maxItems": 3, "description": "Article languages to include. Up to 3." }, "articleType": { "type": "array", "items": { "type": "string", "enum": [ "editorial", "press_release", "regulatory_filing", "advisory" ] }, "minItems": 1, "maxItems": 3, "description": "Article types to include. Up to 3." }, "date": { "type": "object", "properties": { "from": { "type": "integer", "description": "Inclusive start of the published-at window, in epoch milliseconds." }, "to": { "type": "integer", "description": "Inclusive end of the published-at window, in epoch milliseconds." } }, "additionalProperties": false, "description": "Published-at window in epoch milliseconds." } }, "additionalProperties": false, "description": "Optional result filters." }, "sortBy": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "relevance", "newest" ], "description": "Result ordering." } }, "default": { "type": "newest" }, "required": [ "type" ], "additionalProperties": false, "description": "Result ordering. Defaults to newest." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Maximum results to return. Defaults to 10." }, "cursor": { "type": [ "string", "null" ], "maxLength": 300, "description": "Opaque next_cursor from the previous response, or null for the first page." }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "searchBy" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Company news results", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable unique identifier for this article. Use it to deduplicate or reference an article across requests." }, "story_id": { "type": "string", "description": "Shared by articles covering the same story on the same day. Use it to group or collapse syndicated copies of one announcement across outlets." }, "url": { "type": "string", "format": "uri", "description": "Link to the article on the publisher site." }, "title": { "type": "string", "description": "Article headline." }, "description": { "type": [ "string", "null" ], "description": "Short summary or excerpt of the article, when the publisher provides one." }, "language": { "type": [ "string", "null" ], "description": "Language the article is written in, as a lowercase ISO 639-1 code such as en. Null when unknown." }, "authors": { "type": "array", "items": { "type": "string" }, "description": "Bylined authors. Empty when no byline is available." }, "image_url": { "type": [ "string", "null" ], "description": "Lead image for the article, when one is available." }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the article was published, as an ISO 8601 timestamp. Null when the publisher does not state a reliable date." }, "type": { "type": "string", "enum": [ "editorial", "press_release", "regulatory_filing", "advisory" ], "description": "Kind of coverage. Use it to separate independent reporting (editorial) from company-issued content (press_release, regulatory_filing, advisory)." }, "source": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the publication, such as Reuters." }, "domain": { "type": "string", "description": "Website domain of the publication." }, "direct": { "type": "boolean", "description": "True when Context observed this article in the publisher-owned feed." } }, "required": [ "name", "domain", "direct" ], "description": "The publication that published the article." }, "match": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "primary", "secondary" ], "description": "primary when the article is mainly about the company, secondary when the company is mentioned but is not the main subject." }, "confidence": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "How confident the match is, from 0 to 1. Null when a score is unavailable." } }, "required": [ "level", "confidence" ], "description": "How the article relates to the company you searched for." } }, "required": [ "id", "story_id", "url", "title", "description", "language", "authors", "image_url", "published_at", "type", "source", "match" ] }, "description": "Articles matching the search, in the requested order." }, "has_more": { "type": "boolean", "description": "True when more results are available beyond this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor in the next request to fetch the following page. Null when there are no more results." }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "description": "Number of articles in this page." } }, "required": [ "count" ], "description": "Summary information about this response." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "has_more", "next_cursor", "meta", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Request exceeded the applicable rate limit.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "News search failed because the index or an upstream resolver was unavailable.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/parse": { "post": { "summary": "Parse Bytes", "description": "Converts raw text, source code, web/data, PDF, Microsoft Office, and image bytes into LLM-usable Markdown.", "requestBody": { "required": true, "description": "Raw file bytes. The request body must not exceed 25 MiB.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "Parsing" ], "x-mint": { "content": "1 Credit", "title": "Parse Bytes", "sidebarTitle": "Parse Bytes", "description": "Convert raw document bytes into Markdown" }, "parameters": [ { "schema": { "type": "string", "enum": [ "txt", "text", "md", "markdown", "html", "htm", "xhtml", "xml", "rss", "atom", "csv", "tsv", "yaml", "yml", "py", "java", "js", "jsx", "mjs", "cjs", "json", "jsonl", "ndjson", "php", "sh", "bash", "zsh", "fish", "rb", "ts", "tsx", "rtf", "srt", "css", "scss", "less", "styl", "sass", "svg", "pdf", "docx", "doc", "xlsx", "xlsm", "xlsb", "xltx", "xltm", "xls", "pptx", "pptm", "ppsx", "ppsm", "potx", "potm", "ppt", "pps", "pot", "jpg", "jpeg", "jpe", "png", "gif", "bmp", "tiff", "tif", "webp", "ppm", "pbm", "pgm", "pnm" ], "description": "Optional file extension hint, such as pdf, docx, xlsx, pptx, html, json, csv, md, py, rtf, jpg, png, or txt." }, "required": false, "description": "Optional file extension hint, such as pdf, docx, xlsx, pptx, html, json, csv, md, py, rtf, jpg, png, or txt.", "name": "extension", "in": "query" }, { "schema": { "type": "boolean", "default": true, "description": "Preserve hyperlinks in Markdown output" }, "required": false, "description": "Preserve hyperlinks in Markdown output", "name": "includeLinks", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "Include image references in Markdown output" }, "required": false, "description": "Include image references in Markdown output", "name": "includeImages", "in": "query" }, { "schema": { "type": "boolean", "default": true, "description": "Shorten base64-encoded image data in the Markdown output" }, "required": false, "description": "Shorten base64-encoded image data in the Markdown output", "name": "shortenBase64Images", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "Extract only the main content from HTML-like inputs" }, "required": false, "description": "Extract only the main content from HTML-like inputs", "name": "useMainContentOnly", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "When true for PDF inputs, OCR the selected pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. pdf.start/pdf.end limit the inclusive page range. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs." }, "required": false, "description": "When true for PDF inputs, OCR the selected pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. pdf.start/pdf.end limit the inclusive page range. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs.", "name": "ocr", "in": "query" }, { "schema": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 1, "description": "First 1-based PDF page to parse. When omitted, parsing starts at the first page." }, "end": { "type": "integer", "minimum": 1, "description": "Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided." } }, "additionalProperties": false, "description": "PDF page-range options as a JSON object, e.g. {\"start\": 2, \"end\": 5}." }, "required": false, "description": "PDF page-range options as a JSON object, e.g. {\"start\": 2, \"end\": 5}.", "name": "pdf", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Optional client identifier used for usage attribution." }, "required": false, "description": "Optional client identifier used for usage attribution.", "name": "client", "in": "query" }, { "schema": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true." }, "required": false, "description": "Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.", "name": "zdr", "in": "query" }, { "$ref": "#/components/parameters/RequestTags" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Context-ZDR": { "description": "Present with the value true when zero data retention was requested and honored.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Indicates success" }, "markdown": { "type": "string", "description": "Input bytes converted to GitHub Flavored Markdown" }, "type": { "type": "string", "enum": [ "html", "xml", "json", "jsonl", "text", "csv", "tsv", "markdown", "yaml", "python", "java", "javascript", "php", "shell", "ruby", "typescript", "rtf", "srt", "css", "scss", "less", "stylus", "sass", "svg", "pdf", "docx", "doc", "xlsx", "xls", "pptx", "ppt", "jpg", "png", "gif", "bmp", "tiff", "webp", "ppm", "pbm", "pgm", "pnm" ], "description": "Detected content type used for parsing" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "success", "markdown", "type" ] } } } }, "400": { "description": "Invalid input or no parseable content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "error_code": { "type": "string", "enum": [ "INPUT_VALIDATION_ERROR", "WEBSITE_ACCESS_ERROR" ] }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "413": { "description": "Request body exceeds the 25 MiB upload limit", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "error_code": { "type": "string", "enum": [ "INPUT_VALIDATION_ERROR" ] } } } } } }, "415": { "description": "Unsupported content type", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "error_code": { "type": "string", "enum": [ "UNSUPPORTED_CONTENT" ] }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR" ] }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } } } } }, "/web/scrape/html": { "get": { "summary": "Scrape HTML", "description": "Scrapes the given URL and returns the raw HTML content of the page. The base request costs 1 credit; requests with browser actions cost 2 credits.", "security": [ { "bearerAuth": [] } ], "tags": [ "Web Scraping" ], "x-mint": { "content": "1 CreditWith actions: 2 Credits", "title": "Scrape HTML", "sidebarTitle": "Scrape HTML", "description": "Scrape the raw HTML from a URL" }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "format": "uri", "description": "Full URL to scrape (must include http:// or https:// protocol)" }, "required": true, "description": "Full URL to scrape (must include http:// or https:// protocol)", "name": "url", "in": "query" }, { "schema": { "type": "object", "properties": { "shouldParse": { "type": "boolean", "default": true, "description": "When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and a 400 PDF_SKIPPED is returned." }, "start": { "type": "integer", "minimum": 1, "description": "First 1-based PDF page to parse. When omitted, parsing starts at the first page." }, "end": { "type": "integer", "minimum": 1, "description": "Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided." }, "ocr": { "type": "boolean", "default": false, "description": "When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs." } }, "default": { "shouldParse": true, "ocr": false }, "description": "PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range." }, "required": false, "description": "PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range.", "name": "pdf", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "When true, iframes are rendered inline into the returned HTML." }, "required": false, "description": "When true, iframes are rendered inline into the returned HTML.", "name": "includeFrames", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "When true, return only the page's main content in the HTML response, excluding headers, footers, sidebars, and navigation when detectable." }, "required": false, "description": "When true, return only the page's main content in the HTML response, excluding headers, footers, sidebars, and navigation when detectable.", "name": "useMainContentOnly", "in": "query" }, { "schema": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "maxItems": 50, "description": "CSS selectors. When provided, only matching subtrees (and their descendants) are kept and everything else is dropped. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\"." }, "required": false, "description": "CSS selectors. When provided, only matching subtrees (and their descendants) are kept and everything else is dropped. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\".", "name": "includeSelectors", "in": "query" }, { "schema": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "maxItems": 50, "description": "CSS selectors to remove from the result. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\"." }, "required": false, "description": "CSS selectors to remove from the result. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\".", "name": "excludeSelectors", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2592000000, "default": 86400000, "description": "Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh." }, "required": false, "description": "Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.", "name": "maxAgeMs", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 30000, "description": "Optional browser wait time in milliseconds after initial page load. Min: 0. Max: 30000 (30 seconds). When combined with timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT." }, "required": false, "description": "Optional browser wait time in milliseconds after initial page load. Min: 0. Max: 30000 (30 seconds). When combined with timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT.", "name": "waitForMs", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "When true, waits briefly for CSS and transition animations to settle before extracting HTML. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages." }, "required": false, "description": "When true, waits briefly for CSS and transition animations to settle before extracting HTML. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.", "name": "settleAnimations", "in": "query" }, { "schema": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/WebScrapeAction" }, "maxItems": 5, "description": "Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions." }, "required": false, "description": "Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.", "name": "actions", "in": "query" }, { "schema": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 8192, "pattern": "^[^\\r\\n]*$" }, "description": "Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache." }, "required": false, "description": "Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.", "name": "headers", "in": "query" }, { "schema": { "$ref": "#/components/schemas/BrowserCountryCode" }, "required": false, "description": "Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).", "name": "country", "in": "query" }, { "schema": { "$ref": "#/components/schemas/LenientTimeoutMS" }, "required": false, "description": "Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).", "name": "timeoutMS", "in": "query" }, { "schema": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true." }, "required": false, "description": "Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.", "name": "zdr", "in": "query" }, { "$ref": "#/components/parameters/RequestTags" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Context-ZDR": { "description": "Present with the value true when zero data retention was requested and honored.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Indicates success" }, "html": { "type": "string", "description": "The scraped content of the page. For normal pages this is the raw HTML. When the page is a sitemap or feed served behind an XSL stylesheet (which browsers render into HTML), this is the underlying XML instead — see the `type` field." }, "url": { "type": "string", "description": "The URL that was scraped" }, "type": { "type": "string", "enum": [ "html", "xml", "json", "text", "csv", "markdown", "svg", "pdf", "docx", "doc", "xlsx", "xls", "pptx", "ppt" ], "description": "Detected content type of the returned `html` field. Sitemaps and feeds are surfaced as `xml`; ordinary pages are `html`. Excel workbooks are surfaced as `xlsx`/`xls` with the extracted sheets as HTML tables; PowerPoint presentations are surfaced as `pptx`/`ppt` with the extracted slides as HTML." }, "metadata": { "$ref": "#/components/schemas/PageMetadata" }, "cache_metadata": { "$ref": "#/components/schemas/CacheMetadata" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "actionsApplied": { "type": "array", "description": "One verified outcome per requested browser action, in request order.", "items": { "type": "object", "properties": { "instruction": { "type": "string" }, "status": { "type": "string", "enum": [ "applied", "failed", "skipped" ], "description": "Applied means the requested page state was visibly verified. Failed means it was not verified. Skipped means it was not attempted." }, "method": { "type": "string" }, "targetDescription": { "type": "string" }, "completionEvidence": { "type": "string", "description": "Visible page evidence used to verify an applied action." }, "error": { "type": "string" }, "durationMs": { "type": "number" } }, "required": [ "instruction", "status" ] } }, "actionsHtmlStale": { "type": "boolean", "description": "True when an action was applied but the returned content could not be refreshed afterward." } }, "required": [ "request_id", "success", "html", "url", "type", "metadata", "cache_metadata" ] } } } }, "400": { "description": "Bad request - Invalid URL or failed to scrape", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the issue" }, "error_code": { "type": "string", "enum": [ "INPUT_VALIDATION_ERROR", "TIMEOUT_TOO_SHORT_FOR_WAIT", "WEBSITE_ACCESS_ERROR", "WEBSITE_BLOCKED" ], "description": "Error code indicating the type of error. TIMEOUT_TOO_SHORT_FOR_WAIT means timeoutMS is shorter than waitForMs plus the page-load margin, so the request could never complete; raise timeoutMS or lower waitForMs. WEBSITE_BLOCKED means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (often as an HTTP 200) — the request is not billed, and retrying later or from another country sometimes succeeds." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Error code indicating unauthorized access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions or usage limit exceeded", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "FORBIDDEN", "USAGE_EXCEEDED", "DISABLED", "INSUFFICIENT_PERMISSIONS" ], "description": "Error code indicating forbidden access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "404": { "description": "Target page returned a 404", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the issue" }, "error_code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Error code indicating the target page was not found" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "408": { "description": "Request timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Timeout error message" }, "error_code": { "type": "string", "enum": [ "REQUEST_TIMEOUT" ], "description": "Error code indicating request timeout" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "413": { "description": "Content too large - the target content exceeds the maximum supported download size, so it cannot be scraped", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message naming the URL and the maximum supported size" }, "error_code": { "type": "string", "enum": [ "CONTENT_TOO_LARGE" ], "description": "Error code indicating the target content exceeds the maximum supported size" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "415": { "description": "Unsupported content type - the URL resolved to a content type that is not supported (e.g. an image, presentation, media, or archive). Supported types are HTML, XML, PDF, DOCX, DOC, XLSX, XLS, PPTX, PPT, and CSV.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the unsupported content type" }, "error_code": { "type": "string", "enum": [ "UNSUPPORTED_CONTENT" ], "description": "Error code indicating an unsupported content type" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR" ], "description": "Error code indicating internal server error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } } } } }, "/web/scrape/markdown": { "get": { "summary": "Scrape Markdown", "description": "Scrapes the given URL into LLM usable Markdown. Inspect key_metadata on JSON responses from a recognized API key; use error_code to distinguish stable failure categories.\n\n### YouTube\n\nYouTube URLs return the video or channel itself rather than the surrounding player and navigation chrome. A URL addressing a single video (`/watch`, `youtu.be`, `/shorts`, `/embed`, `/live`) returns its title, channel, duration, view count, keywords, full description, and the transcript when the video has captions that can be retrieved; videos without captions return everything except the transcript. A channel URL (`/channel/UC…`, `/@handle`, `/c/…`, `/user/…`) returns its name, handle, subscriber count, video count, and full description. When `includeImages=true`, video responses also include the thumbnail and channel responses include the avatar. Costs the same as any other scrape.\n\n### Billing & errors\n\n| HTTP status | Billed? | Meaning |\n| --- | --- | --- |\n| 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing |\n| 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds |\n| 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code |\n| 404 | No | Target page returned or fingerprinted as not found |\n| 408 | No | Request timed out |\n| 413 | No | Target content exceeds the maximum supported size (20 MB) |\n| 415 | No | Unsupported content type |\n| 429 | No | Per-minute rate limit exceeded; honor Retry-After |\n| 500 | No | Internal error |", "security": [ { "bearerAuth": [] } ], "tags": [ "Web Scraping" ], "x-mint": { "content": "1 CreditWith actions: 2 Credits", "title": "Scrape Markdown", "sidebarTitle": "Scrape markdown", "description": "Scrape the given URL into LLM usable Markdown" }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "format": "uri", "description": "Full URL to scrape into LLM usable Markdown (must include http:// or https:// protocol)" }, "required": true, "description": "Full URL to scrape into LLM usable Markdown (must include http:// or https:// protocol)", "name": "url", "in": "query" }, { "schema": { "type": "boolean", "default": true, "description": "Preserve hyperlinks in Markdown output" }, "required": false, "description": "Preserve hyperlinks in Markdown output", "name": "includeLinks", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "Include image references in Markdown output" }, "required": false, "description": "Include image references in Markdown output", "name": "includeImages", "in": "query" }, { "schema": { "type": "boolean", "default": true, "description": "Shorten base64-encoded image data in the Markdown output" }, "required": false, "description": "Shorten base64-encoded image data in the Markdown output", "name": "shortenBase64Images", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "Extract only the main content of the page, excluding headers, footers, sidebars, and navigation" }, "required": false, "description": "Extract only the main content of the page, excluding headers, footers, sidebars, and navigation", "name": "useMainContentOnly", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "When true, the response also includes an `html` field with the page HTML the Markdown was converted from — the same body the Scrape HTML endpoint returns for the equivalent request." }, "required": false, "description": "When true, the response also includes an `html` field with the page HTML the Markdown was converted from — the same body the Scrape HTML endpoint returns for the equivalent request.", "name": "includeHTML", "in": "query" }, { "schema": { "type": "object", "properties": { "shouldParse": { "type": "boolean", "default": true, "description": "When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and a 400 PDF_SKIPPED is returned." }, "start": { "type": "integer", "minimum": 1, "description": "First 1-based PDF page to parse. When omitted, parsing starts at the first page." }, "end": { "type": "integer", "minimum": 1, "description": "Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided." }, "ocr": { "type": "boolean", "default": false, "description": "When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs." } }, "default": { "shouldParse": true, "ocr": false }, "description": "PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range." }, "required": false, "description": "PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range.", "name": "pdf", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "When true, the contents of iframes are rendered to Markdown." }, "required": false, "description": "When true, the contents of iframes are rendered to Markdown.", "name": "includeFrames", "in": "query" }, { "schema": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "maxItems": 50, "description": "CSS selectors. When provided, only matching HTML subtrees (and their descendants) are kept before conversion to Markdown. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\"." }, "required": false, "description": "CSS selectors. When provided, only matching HTML subtrees (and their descendants) are kept before conversion to Markdown. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\".", "name": "includeSelectors", "in": "query" }, { "schema": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "maxItems": 50, "description": "CSS selectors to remove before conversion to Markdown. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\"." }, "required": false, "description": "CSS selectors to remove before conversion to Markdown. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\".", "name": "excludeSelectors", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2592000000, "default": 86400000, "description": "Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh." }, "required": false, "description": "Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.", "name": "maxAgeMs", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 30000, "description": "Optional browser wait time in milliseconds after initial page load before converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). When combined with timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT." }, "required": false, "description": "Optional browser wait time in milliseconds after initial page load before converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). When combined with timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT.", "name": "waitForMs", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "When true, waits briefly for CSS and transition animations to settle before converting to Markdown. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages." }, "required": false, "description": "When true, waits briefly for CSS and transition animations to settle before converting to Markdown. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.", "name": "settleAnimations", "in": "query" }, { "schema": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/WebScrapeAction" }, "maxItems": 5, "description": "Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions." }, "required": false, "description": "Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.", "name": "actions", "in": "query" }, { "schema": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 8192, "pattern": "^[^\\r\\n]*$" }, "description": "Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache." }, "required": false, "description": "Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.", "name": "headers", "in": "query" }, { "schema": { "$ref": "#/components/schemas/BrowserCountryCode" }, "required": false, "description": "Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).", "name": "country", "in": "query" }, { "schema": { "$ref": "#/components/schemas/LenientTimeoutMS" }, "required": false, "description": "Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).", "name": "timeoutMS", "in": "query" }, { "schema": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true." }, "required": false, "description": "Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.", "name": "zdr", "in": "query" }, { "$ref": "#/components/parameters/RequestTags" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Context-ZDR": { "description": "Present with the value true when zero data retention was requested and honored.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Indicates success" }, "markdown": { "type": "string", "description": "Page content converted to GitHub Flavored Markdown" }, "html": { "type": "string", "description": "Only present when includeHTML=true: the page HTML the Markdown was converted from — the same body the Scrape HTML endpoint returns for the equivalent request." }, "contentLength": { "type": "integer", "minimum": 0, "description": "UTF-8 byte length of the returned Markdown. Use 0 to identify an empty result and compare small values against your workload's minimum useful-content threshold." }, "url": { "type": "string", "description": "The URL that was scraped" }, "metadata": { "$ref": "#/components/schemas/PageMetadata" }, "cache_metadata": { "$ref": "#/components/schemas/CacheMetadata" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "actionsApplied": { "type": "array", "description": "One verified outcome per requested browser action, in request order.", "items": { "type": "object", "properties": { "instruction": { "type": "string" }, "status": { "type": "string", "enum": [ "applied", "failed", "skipped" ], "description": "Applied means the requested page state was visibly verified. Failed means it was not verified. Skipped means it was not attempted." }, "method": { "type": "string" }, "targetDescription": { "type": "string" }, "completionEvidence": { "type": "string", "description": "Visible page evidence used to verify an applied action." }, "error": { "type": "string" }, "durationMs": { "type": "number" } }, "required": [ "instruction", "status" ] } }, "actionsHtmlStale": { "type": "boolean", "description": "True when an action was applied but the returned content could not be refreshed afterward." } }, "required": [ "request_id", "success", "markdown", "contentLength", "url", "metadata", "cache_metadata" ] } } } }, "400": { "description": "Bad request - Invalid URL or failed to scrape", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the issue" }, "error_code": { "type": "string", "enum": [ "INPUT_VALIDATION_ERROR", "TIMEOUT_TOO_SHORT_FOR_WAIT", "WEBSITE_ACCESS_ERROR", "WEBSITE_BLOCKED" ], "description": "Error code indicating the type of error. TIMEOUT_TOO_SHORT_FOR_WAIT means timeoutMS is shorter than waitForMs plus the page-load margin, so the request could never complete; raise timeoutMS or lower waitForMs. WEBSITE_BLOCKED means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (often as an HTTP 200) — the request is not billed, and retrying later or from another country sometimes succeeds." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Error code indicating unauthorized access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions or usage limit exceeded", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "FORBIDDEN", "USAGE_EXCEEDED", "DISABLED", "INSUFFICIENT_PERMISSIONS" ], "description": "Error code indicating forbidden access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "404": { "description": "Target page returned a 404", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the issue" }, "error_code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Error code indicating the target page was not found" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "408": { "description": "Request timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Timeout error message" }, "error_code": { "type": "string", "enum": [ "REQUEST_TIMEOUT" ], "description": "Error code indicating request timeout" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "413": { "description": "Content too large - the target content exceeds the maximum supported download size, so it cannot be scraped", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message naming the URL and the maximum supported size" }, "error_code": { "type": "string", "enum": [ "CONTENT_TOO_LARGE" ], "description": "Error code indicating the target content exceeds the maximum supported size" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "415": { "description": "Unsupported content type - the URL resolved to a content type that is not supported (e.g. an image, presentation, media, or archive). Supported types are HTML, XML, PDF, DOCX, DOC, XLSX, XLS, PPTX, PPT, and CSV.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the unsupported content type" }, "error_code": { "type": "string", "enum": [ "UNSUPPORTED_CONTENT" ], "description": "Error code indicating an unsupported content type" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR" ], "description": "Error code indicating internal server error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } } } } }, "/web/scrape/images": { "get": { "summary": "Scrape Images", "description": "Extract image assets from a web page, including standard URLs, inline SVGs, data URIs, responsive image sources, metadata, CSS backgrounds, video posters, and embeds. The base request costs 1 credit, or 2 credits with browser actions. When enrichment is enabled, the entire call costs 5 credits, including requests that also use actions.", "security": [ { "bearerAuth": [] } ], "tags": [ "Web Scraping" ], "x-mint": { "content": "1 CreditWith actions: 2 CreditsEnriched: 5 Credits", "title": "Scrape Images", "sidebarTitle": "Scrape images", "description": "Extract image assets from a page." }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "format": "uri", "description": "Page URL to inspect. Must include http:// or https://." }, "required": true, "description": "Page URL to inspect. Must include http:// or https://.", "name": "url", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2592000000, "default": 86400000, "description": "Reuse a cached result this many milliseconds old or newer. Default: 86400000 (1 day). Set to 0 to bypass cache. Maximum: 2592000000 (30 days)." }, "required": false, "description": "Reuse a cached result this many milliseconds old or newer. Default: 86400000 (1 day). Set to 0 to bypass cache. Maximum: 2592000000 (30 days).", "name": "maxAgeMs", "in": "query" }, { "schema": { "type": [ "object", "null" ], "properties": { "resolution": { "type": "boolean", "default": false, "description": "Measure image width and height when possible." }, "hostedUrl": { "type": "boolean", "default": false, "description": "Host materializable images on the Brand.dev CDN and return their URL and MIME type." }, "classification": { "type": "boolean", "default": false, "description": "Classify each image by visual asset type." }, "maxTimePerMs": { "type": "integer", "minimum": 1, "maximum": 60000, "default": 30000, "description": "Per-image enrichment timeout in milliseconds. Default: 30000. Maximum: 60000." } }, "additionalProperties": false, "description": "Optional per-image processing, sent as deep-object query params such as enrichment[resolution]=true." }, "required": false, "description": "Optional per-image processing, sent as deep-object query params such as enrichment[resolution]=true.", "name": "enrichment", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "When true, visually duplicate images are removed: every image is loaded and perceptually hashed, and only the highest-resolution copy of each duplicate group is kept. Images that cannot be downloaded or hashed are kept. Default: false." }, "required": false, "description": "When true, visually duplicate images are removed: every image is loaded and perceptually hashed, and only the highest-resolution copy of each duplicate group is kept. Images that cannot be downloaded or hashed are kept. Default: false.", "name": "dedupe", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 30000, "description": "Optional browser wait time in milliseconds after initial page load before collecting images. Min: 0. Max: 30000 (30 seconds). When combined with timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT." }, "required": false, "description": "Optional browser wait time in milliseconds after initial page load before collecting images. Min: 0. Max: 30000 (30 seconds). When combined with timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT.", "name": "waitForMs", "in": "query" }, { "schema": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/WebScrapeAction" }, "maxItems": 5, "description": "Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions." }, "required": false, "description": "Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.", "name": "actions", "in": "query" }, { "schema": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 8192, "pattern": "^[^\\r\\n]*$" }, "description": "Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache." }, "required": false, "description": "Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.", "name": "headers", "in": "query" }, { "schema": { "$ref": "#/components/schemas/LenientTimeoutMS" }, "required": false, "description": "Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).", "name": "timeoutMS", "in": "query" }, { "$ref": "#/components/parameters/RequestTags" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Always true on success." }, "images": { "type": "array", "description": "Images found on the page.", "items": { "type": "object", "properties": { "src": { "type": "string", "description": "Original image value: URL, inline SVG or HTML, or base64 data URI." }, "element": { "type": "string", "enum": [ "img", "svg", "link", "source", "video", "css", "object", "meta", "background" ], "description": "Where the image was found." }, "type": { "type": "string", "enum": [ "url", "html", "base64" ], "description": "Format of src." }, "alt": { "type": [ "string", "null" ], "description": "Image alt text, or null when unavailable." }, "enrichment": { "type": "object", "description": "Requested metadata for images that could be processed.", "properties": { "width": { "type": "integer", "description": "Image width in pixels, when measured." }, "height": { "type": "integer", "description": "Image height in pixels, when measured." }, "mimetype": { "type": "string", "description": "Detected MIME type, when hosted." }, "url": { "type": "string", "format": "uri", "description": "Brand.dev CDN URL, when hosted." }, "type": { "type": "string", "enum": [ "photography", "illustration", "logo", "wordmark", "icon", "pattern", "graphic", "other" ], "description": "Visual asset category, when classified." } } } }, "required": [ "src", "element", "type", "alt" ] } }, "url": { "type": "string", "description": "Page URL that was scraped." }, "cache_metadata": { "$ref": "#/components/schemas/CacheMetadata" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "actionsApplied": { "type": "array", "description": "One verified outcome per requested browser action, in request order.", "items": { "type": "object", "properties": { "instruction": { "type": "string" }, "status": { "type": "string", "enum": [ "applied", "failed", "skipped" ], "description": "Applied means the requested page state was visibly verified. Failed means it was not verified. Skipped means it was not attempted." }, "method": { "type": "string" }, "targetDescription": { "type": "string" }, "completionEvidence": { "type": "string", "description": "Visible page evidence used to verify an applied action." }, "error": { "type": "string" }, "durationMs": { "type": "number" } }, "required": [ "instruction", "status" ] } } }, "required": [ "request_id", "success", "images", "url", "cache_metadata" ] } } } }, "400": { "description": "Invalid URL or scrape failed.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the issue" }, "error_code": { "type": "string", "enum": [ "INPUT_VALIDATION_ERROR", "TIMEOUT_TOO_SHORT_FOR_WAIT", "WEBSITE_ACCESS_ERROR" ], "description": "Error code indicating the type of error. TIMEOUT_TOO_SHORT_FOR_WAIT means timeoutMS is shorter than waitForMs plus the page-load margin; raise timeoutMS or lower waitForMs." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Error code indicating unauthorized access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions or usage limit exceeded", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "FORBIDDEN", "USAGE_EXCEEDED", "DISABLED", "INSUFFICIENT_PERMISSIONS" ], "description": "Error code indicating forbidden access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "408": { "description": "Request timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Timeout error message" }, "error_code": { "type": "string", "enum": [ "REQUEST_TIMEOUT" ], "description": "Error code indicating request timeout" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR" ], "description": "Error code indicating internal server error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } } } } }, "/web/scrape/sitemap": { "get": { "summary": "Crawl Sitemap", "description": "Crawl an entire website's sitemap and return all discovered page URLs. Set `includeSubdomains=true` to also discover public pages and sitemaps on child hosts such as `docs.example.com` or `brand.example.com`. Pass `search` to have the discovered URLs filtered down to the pages about a phrase (for example `pricing and plans` or `api authentication docs`), most relevant first — a searched crawl scans the whole sitemap and costs 2 credits instead of 1.", "security": [ { "bearerAuth": [] } ], "tags": [ "Web Scraping" ], "x-mint": { "content": "1 Credit", "title": "Crawl Sitemap", "sidebarTitle": "Crawl sitemap", "description": "Crawl a domain's sitemap, optionally including its subdomains, and return all discovered page URLs" }, "parameters": [ { "schema": { "type": "string", "minLength": 3, "description": "Domain to build a sitemap for" }, "required": true, "description": "Domain to build a sitemap for", "name": "domain", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "When true, discover and include public pages and sitemaps on subdomains of the requested domain. Defaults to false." }, "required": false, "description": "When true, discover and include public pages and sitemaps on subdomains of the requested domain. Defaults to false.", "name": "includeSubdomains", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 10000, "description": "Maximum number of links to return from the sitemap crawl. Defaults to 10,000. Minimum is 1, maximum is 100,000." }, "required": false, "description": "Maximum number of links to return from the sitemap crawl. Defaults to 10,000. Minimum is 1, maximum is 100,000.", "name": "maxLinks", "in": "query" }, { "schema": { "type": "string", "format": "uri", "description": "Optional explicit sitemap URL. When provided, exactly this sitemap is crawled instead of discovering the domain's sitemaps." }, "required": false, "description": "Optional explicit sitemap URL. When provided, exactly this sitemap is crawled instead of discovering the domain's sitemaps.", "name": "sitemapUrl", "in": "query" }, { "schema": { "type": "string", "maxLength": 256, "description": "Optional RE2-compatible regex pattern. Only URLs matching this pattern are returned and counted against maxLinks.", "example": "^https?://[^/]+/blog/" }, "required": false, "description": "Optional RE2-compatible regex pattern. Only URLs matching this pattern are returned and counted against maxLinks.", "name": "urlRegex", "in": "query" }, { "schema": { "type": "string", "minLength": 2, "maxLength": 200, "description": "Optional search phrase. When provided, the crawled sitemap is filtered to the pages whose URLs are about that phrase, most relevant first, and the request costs 2 credits instead of 1.", "example": "help center and troubleshooting articles" }, "required": false, "description": "Optional search phrase. When provided, the crawled sitemap is filtered to the pages whose URLs are about that phrase, most relevant first, and the request costs 2 credits instead of 1.", "name": "search", "in": "query" }, { "schema": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 8192, "pattern": "^[^\\r\\n]*$" }, "description": "Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache." }, "required": false, "description": "Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.", "name": "headers", "in": "query" }, { "schema": { "$ref": "#/components/schemas/LenientTimeoutMS" }, "required": false, "description": "Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).", "name": "timeoutMS", "in": "query" }, { "schema": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true." }, "required": false, "description": "Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.", "name": "zdr", "in": "query" }, { "$ref": "#/components/parameters/RequestTags" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Context-ZDR": { "description": "Present with the value true when zero data retention was requested and honored.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Indicates success" }, "domain": { "type": "string", "description": "The normalized domain that was crawled" }, "urls": { "type": "array", "items": { "type": "string" }, "description": "Discovered page URLs from the sitemap, up to `maxLinks`. When `search` is set these are only the matching pages, most relevant first." }, "meta": { "type": "object", "description": "Metadata about the sitemap crawl operation", "properties": { "sitemapsDiscovered": { "type": "integer", "description": "Total number of sitemap files discovered" }, "sitemapsFetched": { "type": "integer", "description": "Number of sitemap files successfully fetched and parsed" }, "sitemapsSkipped": { "type": "integer", "description": "Number of sitemap files skipped (due to errors, timeouts, or limits)" }, "errors": { "type": "integer", "description": "Number of errors encountered during crawling" } }, "required": [ "sitemapsDiscovered", "sitemapsFetched", "sitemapsSkipped", "errors" ] }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "success", "domain", "urls", "meta" ] } } } }, "400": { "description": "Bad request - Invalid domain", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the issue" }, "error_code": { "type": "string", "enum": [ "INPUT_VALIDATION_ERROR", "WEBSITE_ACCESS_ERROR" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Error code indicating unauthorized access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions or usage limit exceeded", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "FORBIDDEN", "USAGE_EXCEEDED", "DISABLED", "INSUFFICIENT_PERMISSIONS" ], "description": "Error code indicating forbidden access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "408": { "description": "Request timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Timeout error message" }, "error_code": { "type": "string", "enum": [ "REQUEST_TIMEOUT" ], "description": "Error code indicating request timeout" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR" ], "description": "Error code indicating internal server error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } } } } }, "/web/crawl": { "post": { "summary": "Crawl Website & Scrape Markdown", "description": "Performs a crawl starting from a given URL, extracts page content as Markdown, and returns results for all crawled pages.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The starting URL for the crawl (must include http:// or https:// protocol)" }, "maxPages": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100, "description": "Maximum number of pages to crawl. Hard cap: 500." }, "maxDepth": { "type": "integer", "minimum": 0, "description": "Maximum link depth from the starting URL (0 = only the starting page)" }, "urlRegex": { "type": "string", "description": "Regex pattern. Only URLs matching this pattern will be followed and scraped. An automatic prefix scope in the form ^ follows a redirect of the starting page.", "example": "^https?://[^/]+/blog/" }, "includeLinks": { "type": "boolean", "default": true, "description": "Preserve hyperlinks in the Markdown output" }, "includeImages": { "type": "boolean", "default": false, "description": "Include image references in the Markdown output" }, "shortenBase64Images": { "type": "boolean", "default": true, "description": "Truncate base64-encoded image data in the Markdown output" }, "useMainContentOnly": { "type": "boolean", "default": false, "description": "Extract only the main content, stripping headers, footers, sidebars, and navigation" }, "followSubdomains": { "type": "boolean", "default": false, "description": "When true, follow links on subdomains of the starting URL's domain (e.g. docs.example.com when starting from example.com). www and apex are always treated as equivalent." }, "pdf": { "type": "object", "properties": { "shouldParse": { "type": "boolean", "default": true, "description": "When true, PDF pages are fetched and parsed. When false, PDF pages are skipped entirely (not included in results and not counted as failures)." }, "ocr": { "type": "boolean", "default": false, "description": "When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost." }, "start": { "type": "integer", "minimum": 1, "description": "First 1-based PDF page to parse. When omitted, parsing starts at the first page." }, "end": { "type": "integer", "minimum": 1, "description": "Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided." } }, "additionalProperties": false, "default": { "shouldParse": true, "ocr": false }, "description": "PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range." }, "includeFrames": { "type": "boolean", "default": false, "description": "When true, the contents of iframes are rendered to Markdown for each crawled page." }, "includeSelectors": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 2048 }, "description": "CSS selectors. When provided, only matching HTML subtrees (and their descendants) are kept before each crawled page is converted to Markdown. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\"." }, "excludeSelectors": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 2048 }, "description": "CSS selectors to remove before each crawled page is converted to Markdown. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\"." }, "maxAgeMs": { "type": "integer", "minimum": 0, "maximum": 2592000000, "default": 86400000, "description": "Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh." }, "waitForMs": { "type": "integer", "minimum": 0, "maximum": 30000, "default": 3500, "description": "Browser wait time in milliseconds after initial page load for each crawled page. Defaults to 3500 (3.5 seconds). Min: 0. Max: 30000 (30 seconds)." }, "settleAnimations": { "type": "boolean", "default": false, "description": "When true, waits briefly for CSS and transition animations to settle before extracting each crawled page. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages." }, "stopAfterMs": { "type": "integer", "minimum": 10000, "maximum": 110000, "default": 80000, "description": "Soft time budget for the crawl in milliseconds. After each scrape, the crawler checks the elapsed time and, if exceeded, returns the pages collected so far instead of continuing. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 (80s)." }, "country": { "$ref": "#/components/schemas/BrowserCountryCode" }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" }, "zdr": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true." }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "url" ] } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "Web Scraping" ], "x-mint": { "content": "1 Credit Per Page", "title": "Crawl Website & Scrape Markdown", "sidebarTitle": "Crawl website & scrape markdown", "description": "Crawl an entire website and extract pages' content as LLM usable Markdown" }, "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Context-ZDR": { "description": "Present with the value true when zero data retention was requested and honored.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "markdown": { "type": "string", "description": "Extracted page content as Markdown (empty string on failure)" }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/PageMetadata" }, { "type": "object", "properties": { "url": { "type": "string", "description": "The crawl URL fetched for this page." }, "title": { "type": "string", "description": "Best page title extracted from the page (empty string if unavailable)." }, "crawlDepth": { "type": "integer", "description": "Depth relative to the start URL. 0 = start URL, 1 = one link away." }, "statusCode": { "type": "integer", "description": "HTTP status code of the response" }, "success": { "type": "boolean", "description": "true if the page was fetched and parsed successfully" } }, "required": [ "url", "title", "crawlDepth", "statusCode", "success" ] } ] } }, "required": [ "markdown", "metadata" ] } }, "metadata": { "type": "object", "properties": { "numUrls": { "type": "integer", "description": "Total number of URLs crawled" }, "maxCrawlDepth": { "type": "integer", "description": "Maximum crawl depth reached during the crawl" }, "numSucceeded": { "type": "integer", "description": "Number of pages successfully crawled" }, "numFailed": { "type": "integer", "description": "Number of pages that failed to crawl" }, "numSkipped": { "type": "integer", "description": "Number of URLs skipped (PDFs when pdf.shouldParse=false, or URLs not matching urlRegex)" } }, "required": [ "numUrls", "maxCrawlDepth", "numSucceeded", "numFailed", "numSkipped" ] }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "cache_metadata": { "$ref": "#/components/schemas/CacheMetadata" } }, "required": [ "request_id", "results", "metadata", "cache_metadata" ] } } } }, "400": { "description": "Bad request - Invalid URL or parameters", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the issue" }, "error_code": { "type": "string", "enum": [ "INPUT_VALIDATION_ERROR", "WEBSITE_ACCESS_ERROR" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Error code indicating unauthorized access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions or usage limit exceeded", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "FORBIDDEN", "USAGE_EXCEEDED", "DISABLED", "INSUFFICIENT_PERMISSIONS" ], "description": "Error code indicating forbidden access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "404": { "description": "Start URL returned a 404", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the issue" }, "error_code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Error code indicating the start URL was not found" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "408": { "description": "Request timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Timeout error message" }, "error_code": { "type": "string", "enum": [ "REQUEST_TIMEOUT" ], "description": "Error code indicating request timeout" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "415": { "description": "Unsupported content type - the start URL resolved to a content type that is not supported (e.g. an image, presentation, media, or archive). Supported types are HTML, XML, PDF, DOCX, DOC, XLSX, XLS, PPTX, PPT, and CSV.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the unsupported content type" }, "error_code": { "type": "string", "enum": [ "UNSUPPORTED_CONTENT" ], "description": "Error code indicating an unsupported content type" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR" ], "description": "Error code indicating internal server error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } } } } }, "/web/extract": { "post": { "summary": "Extract Structured Website Data", "description": "Crawl a website, use the provided JSON Schema and instructions to prioritize relevant internal links, and extract structured data from the selected pages.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The starting website URL to crawl and extract from. Must include http:// or https://." }, "schema": { "type": "object", "description": "JSON Schema for the returned data object. Image fields such as `image_urls` or `product_photos` automatically make page image references available to extraction, so product data and photos can be returned in one call. TypeScript Zod users can pass a JSON Schema generated from a Zod object; Python users can pass the equivalent JSON Schema object.", "additionalProperties": true, "example": { "type": "object", "properties": { "mission_statement": { "type": "string", "description": "The company's stated mission." }, "case_studies": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "title", "url" ], "additionalProperties": false } } }, "required": [ "mission_statement", "case_studies" ], "additionalProperties": false } }, "instructions": { "type": "string", "maxLength": 2000, "description": "Optional extraction guidance, such as which facts to prioritize or how to interpret fields in the schema." }, "factCheck": { "type": "boolean", "default": false, "description": "When true, every returned value must be grounded in facts stated on the page; fields that cannot be supported by the page are returned as null/empty. When false (default), the model may make reasonable inferences and derivations from the page content (e.g. ideal customer, competitor analysis, recommendations) while keeping verifiable specifics (names, quotes, URLs, dates, metrics) faithful to the source." }, "followSubdomains": { "type": "boolean", "default": false, "description": "When true, follow links on subdomains of the starting URL's domain." }, "maxPages": { "type": "integer", "minimum": 1, "maximum": 50, "default": 5, "description": "Maximum number of pages to analyze for extraction. Hard cap: 50. Defaults to 5." }, "maxDepth": { "type": "integer", "minimum": 0, "description": "Optional maximum link depth from the starting URL (0 = only the starting page). If omitted, there is no crawl depth limit." }, "pdf": { "type": "object", "properties": { "shouldParse": { "type": "boolean", "default": true, "description": "When true, PDF pages are fetched and parsed. When false, PDF pages are skipped." }, "start": { "type": "integer", "minimum": 1, "description": "First 1-based PDF page to parse." }, "end": { "type": "integer", "minimum": 1, "description": "Last 1-based PDF page to parse. Must be greater than or equal to start when both are provided." } }, "additionalProperties": false, "default": { "shouldParse": true } }, "includeFrames": { "type": "boolean", "default": false, "description": "When true, iframe contents are included in Markdown before extraction." }, "maxAgeMs": { "type": "integer", "minimum": 0, "maximum": 2592000000, "default": 604800000, "description": "Return cached scrape results if a prior scrape for the same parameters is younger than this many milliseconds. Defaults to 7 days (604800000 ms)." }, "waitForMs": { "type": "integer", "minimum": 0, "maximum": 30000, "description": "Optional browser wait time in milliseconds after initial page load for each crawled page." }, "settleAnimations": { "type": "boolean", "default": false, "description": "When true, waits briefly for CSS and transition animations to settle before extracting each crawled page. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages." }, "actions": { "type": "array", "maxItems": 5, "description": "Optional browser actions executed in order on the requested page after it loads, before links are discovered or additional pages are crawled. Requires a paid plan. When actions are provided and stopAfterMs is omitted, the crawl budget defaults to 110000 ms.", "items": { "$ref": "#/components/schemas/WebScrapeAction" } }, "stopAfterMs": { "type": "integer", "minimum": 10000, "maximum": 110000, "default": 80000, "description": "Soft time budget for the crawl in milliseconds. Min: 10000 (10s). Max: 110000 (110s). Defaults to 80000 (80s), or 110000 (110s) when browser actions are provided." }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "url", "schema" ], "additionalProperties": false } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "Web Extraction" ], "x-mint": { "content": "10 Credits", "title": "Extract Structured Website Data", "sidebarTitle": "Extract structured data", "description": "Crawl a website, use the provided JSON Schema and instructions to prioritize relevant internal links, and extract structured data from the selected pages." }, "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the response, e.g., 'ok'" }, "url": { "type": "string", "description": "The starting URL that was analyzed" }, "urls_analyzed": { "type": "array", "description": "List of URLs whose Markdown was used for extraction", "items": { "type": "string" } }, "data": { "type": "object", "description": "Extracted data matching the request schema", "additionalProperties": true }, "metadata": { "type": "object", "properties": { "numUrls": { "type": "integer" }, "maxCrawlDepth": { "type": "integer" }, "numSucceeded": { "type": "integer" }, "numFailed": { "type": "integer" }, "numSkipped": { "type": "integer" }, "numBlocked": { "type": "integer", "description": "Number of crawled pages excluded because they were anti-bot challenges, error pages, or parked-domain placeholders." }, "actionsApplied": { "type": "array", "description": "One verified outcome per requested browser action, in request order.", "items": { "type": "object", "properties": { "instruction": { "type": "string" }, "status": { "type": "string", "enum": [ "applied", "failed", "skipped" ], "description": "Applied means the requested page state was visibly verified. Failed means it was not verified. Skipped means it was not attempted." }, "method": { "type": "string" }, "targetDescription": { "type": "string" }, "completionEvidence": { "type": "string", "description": "Visible page evidence used to verify an applied action." }, "error": { "type": "string" }, "durationMs": { "type": "number" } }, "required": [ "instruction", "status" ] } } }, "required": [ "numUrls", "maxCrawlDepth", "numSucceeded", "numFailed", "numSkipped", "numBlocked" ] }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "cache_metadata": { "$ref": "#/components/schemas/CacheMetadata" } }, "required": [ "request_id", "status", "url", "urls_analyzed", "data", "metadata", "cache_metadata" ] } } } }, "400": { "description": "Bad request - Invalid URL, schema, or inaccessible website", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "error_code": { "type": "string", "enum": [ "INPUT_VALIDATION_ERROR", "TIMEOUT_TOO_SHORT_FOR_WAIT", "WEBSITE_ACCESS_ERROR" ], "description": "TIMEOUT_TOO_SHORT_FOR_WAIT means timeoutMS is shorter than waitForMs plus the page-load margin; raise timeoutMS or lower waitForMs." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Insufficient permissions or usage limit exceeded", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "408": { "description": "Request timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/web/search": { "post": { "summary": "Web Search", "description": "Search the web and optionally scrape each result to Markdown in one round-trip.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Search query. Accepts natural language as well as Google-style search operators such as `site:`, `-site:`, `inurl:`, `intitle:`, quoted phrases, and `OR`." }, "numResults": { "type": "integer", "minimum": 10, "maximum": 100, "default": 10, "description": "Number of results to request and return (10–100). Defaults to 10." }, "includeDomains": { "type": "array", "items": { "type": "string" }, "description": "Allowlist — only return results from these domains. Example: [\"arxiv.org\", \"github.com\"]." }, "excludeDomains": { "type": "array", "items": { "type": "string" }, "description": "Blocklist — drop results from these domains. Example: [\"pinterest.com\", \"reddit.com\"]." }, "freshness": { "type": "string", "enum": [ "last_24_hours", "last_week", "last_month", "last_year" ], "description": "Restrict results to content published within this window." }, "country": { "type": "string", "enum": [ "af", "al", "dz", "as", "ad", "ao", "ai", "aq", "ag", "ar", "am", "aw", "au", "at", "az", "bs", "bh", "bd", "bb", "by", "be", "bz", "bj", "bm", "bt", "bo", "ba", "bw", "bv", "br", "io", "bn", "bg", "bf", "bi", "kh", "cm", "ca", "cv", "ky", "cf", "td", "cl", "cn", "cx", "cc", "co", "km", "cg", "cd", "ck", "cr", "ci", "hr", "cu", "cy", "cz", "dk", "dj", "dm", "do", "ec", "eg", "sv", "gq", "er", "ee", "et", "fk", "fo", "fj", "fi", "fr", "gf", "pf", "tf", "ga", "gm", "ge", "de", "gh", "gi", "gr", "gl", "gd", "gp", "gu", "gt", "gn", "gw", "gy", "ht", "hm", "va", "hn", "hk", "hu", "is", "in", "id", "ir", "iq", "ie", "il", "it", "jm", "jp", "jo", "kz", "ke", "ki", "kp", "kr", "kw", "kg", "la", "lv", "lb", "ls", "lr", "ly", "li", "lt", "lu", "mo", "mk", "mg", "mw", "my", "mv", "ml", "mt", "mh", "mq", "mr", "mu", "yt", "mx", "fm", "md", "mc", "mn", "ms", "ma", "mz", "mm", "na", "nr", "np", "nl", "an", "nc", "nz", "ni", "ne", "ng", "nu", "nf", "mp", "no", "om", "pk", "pw", "ps", "pa", "pg", "py", "pe", "ph", "pn", "pl", "pt", "pr", "qa", "re", "ro", "ru", "rw", "sh", "kn", "lc", "pm", "vc", "ws", "sm", "st", "sa", "sn", "rs", "sc", "sl", "sg", "sk", "si", "sb", "so", "za", "gs", "es", "lk", "sd", "sr", "sj", "sz", "se", "ch", "sy", "tw", "tj", "tz", "th", "tl", "tg", "tk", "to", "tt", "tn", "tr", "tm", "tc", "tv", "ug", "ua", "ae", "gb", "us", "um", "uy", "uz", "vu", "ve", "vn", "vg", "vi", "wf", "eh", "ye", "zm", "zw" ], "description": "Two-letter ISO 3166-1 alpha-2 country code to localize results to a specific country (maps to Google's `gl` parameter). Example: \"us\", \"gb\", \"de\"." }, "queryFanout": { "type": "boolean", "description": "Expand the query into multiple parallel variants for broader recall." }, "markdownOptions": { "type": "object", "additionalProperties": false, "description": "Inline Markdown scraping for each result. Set `enabled: true` to activate.", "properties": { "enabled": { "type": "boolean", "default": false, "description": "Scrape each result to Markdown. Off by default to keep search cheap and fast." }, "includeLinks": { "type": "boolean", "default": true, "description": "Keep hyperlinks in the Markdown." }, "includeImages": { "type": "boolean", "default": false, "description": "Emit image references in the Markdown." }, "shortenBase64Images": { "type": "boolean", "default": true, "description": "Truncate inline base64 image payloads to keep responses small." }, "useMainContentOnly": { "type": "boolean", "default": false, "description": "Strip nav, header, footer, and sidebar — keep only the primary article content." }, "pdf": { "type": "object", "properties": { "shouldParse": { "type": "boolean", "default": true, "description": "Parse PDF URLs. When false, PDF results are skipped with WEBSITE_ACCESS_ERROR." }, "start": { "type": "integer", "minimum": 1, "description": "First PDF page to parse (1-based, inclusive). Defaults to page 1." }, "end": { "type": "integer", "minimum": 1, "description": "Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must be >= start." } }, "additionalProperties": false, "default": { "shouldParse": true }, "description": "PDF handling. Use start/end to bound text extraction and OCR to a page range." }, "includeFrames": { "type": "boolean", "default": false, "description": "Render iframe contents into the Markdown." }, "maxAgeMs": { "type": "integer", "minimum": 0, "maximum": 2592000000, "default": 86400000, "description": "Cache TTL in ms for scraped Markdown keyed by URL + options. Default 1 day, max 30 days. Set to 0 to force a fresh scrape." }, "waitForMs": { "type": "integer", "minimum": 0, "maximum": 30000, "description": "Extra wait after page load before rendering, in ms (0–30000). Useful for JS-heavy pages." }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" } } }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "query" ], "additionalProperties": false } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "Web Scraping" ], "x-mint": { "content": "1 Credit Per 10 Results" }, "responses": { "200": { "description": "Search succeeded. Results are ordered by relevance.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Canonical result URL." }, "title": { "type": "string", "description": "Page title." }, "description": { "type": "string", "description": "Snippet excerpt from the page." }, "relevance": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Relevance to the original query." }, "markdown": { "type": "object", "properties": { "markdown": { "type": [ "string", "null" ], "description": "GFM Markdown of the page. Null unless markdownOptions.enabled is true and scraping succeeded." }, "code": { "type": "string", "enum": [ "SUCCESS", "NOT_REQUESTED", "TIMEOUT", "CONTENT_TOO_LARGE", "WEBSITE_ACCESS_ERROR", "ERROR" ], "description": "Per-result scrape outcome. Inspect this before reading `markdown`." } }, "required": [ "markdown", "code" ], "additionalProperties": false, "description": "Markdown scrape status and content for this result." } }, "required": [ "url", "title", "description", "relevance", "markdown" ] } }, "query": { "type": "string", "description": "Echo of the original query (useful when fanout was enabled)." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "cache_metadata": { "$ref": "#/components/schemas/CacheMetadata" } }, "required": [ "request_id", "results", "query", "cache_metadata" ] } } } }, "400": { "description": "Bad request - Invalid parameters", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the issue" }, "error_code": { "type": "string", "enum": [ "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Error code indicating unauthorized access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions or usage limit exceeded", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "FORBIDDEN", "USAGE_EXCEEDED", "DISABLED", "INSUFFICIENT_PERMISSIONS" ], "description": "Error code indicating forbidden access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "408": { "description": "Request timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Timeout error message" }, "error_code": { "type": "string", "enum": [ "REQUEST_TIMEOUT" ], "description": "Error code indicating request timeout" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR" ], "description": "Error code indicating internal server error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } } } } }, "/people/enrich": { "post": { "summary": "Enrich Person", "description": "Finds and normalizes the best available person candidate from additive identity clues, then assigns an identity match score from 0 to 100. Available on all paid plans. Successful requests cost 20 credits. Disposable and free email addresses (like gmail.com, yahoo.com) will throw a 422 error.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonEnrichmentRequest" }, "example": { "social_urls": [ "https://www.linkedin.com/in/ada-lovelace/" ], "name": { "first": "Ada", "last": "Lovelace" }, "company": { "name": "Analytical Engines", "domain": "analyticalengines.example" } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "People" ], "x-mint": { "content": "20 Credits All Paid Plans Beta Feature", "title": "Enrich Person", "sidebarTitle": "Enrich person", "description": "Enrich a person from combined identity clues and receive an identity match score." }, "responses": { "200": { "description": "The highest-scoring candidate, including weak matches, or a not-found result when no usable candidate exists.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonEnrichmentResponse" } } } }, "400": { "description": "Bad request - Insufficient or invalid identity clues", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Insufficient permissions or usage limit exceeded", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "408": { "description": "Request timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity - Free email or disposable email detected", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "status": { "type": "string", "description": "Status of the response, e.g., 'error'" }, "error_code": { "type": "string", "enum": [ "FREE_EMAIL_DETECTED", "DISPOSABLE_EMAIL_DETECTED" ], "description": "Error code indicating whether a free email provider or disposable email was detected" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "External provider error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/brand/retrieve": { "post": { "summary": "Retrieve brand data", "description": "Retrieve logos, backdrops, colors, industry, description, and more. Provide exactly one lookup identifier in the request body: a domain, company name, email address, stock ticker, transaction descriptor, or direct URL. Note: `by_direct_url` fetches brand data only from the provided URL — not from the entire internet.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandRetrieveRequest" }, "examples": { "domain": { "summary": "By domain", "value": { "type": "by_domain", "domain": "stripe.com" } }, "name": { "summary": "By name", "value": { "type": "by_name", "name": "Stripe" } }, "email": { "summary": "By email", "value": { "type": "by_email", "email": "jane@stripe.com" } }, "ticker": { "summary": "By stock", "value": { "type": "by_ticker", "ticker": "AAPL", "ticker_exchange": "NASDAQ" } }, "direct_url": { "summary": "By direct URL", "value": { "type": "by_direct_url", "direct_url": "https://stripe.com/enterprise" } }, "transaction": { "summary": "By transaction", "value": { "type": "by_transaction", "transaction_info": "SQ *COFFEE SHOP", "country_gl": "us", "mcc": 5814, "high_confidence_only": true } } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "Brand Intelligence" ], "x-mint": { "content": "10 Credits" }, "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandResponse" } } } }, "400": { "description": "Bad Request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "408": { "description": "Request Timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity - Free email or disposable email detected", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/brand/search": { "get": { "summary": "Brand Search", "description": "Search indexed brands by name or domain", "security": [ { "bearerAuth": [] } ], "tags": [ "Brand Intelligence" ], "x-mint": { "content": "Free on Pro and Scale1 Credit on Free and Starter" }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Search term, matched against the fields selected by queryBy (e.g. 'nike', 'nike.com', 'nik')." }, "required": true, "description": "Search term, matched against the fields selected by queryBy (e.g. 'nike', 'nike.com', 'nik').", "name": "query", "in": "query" }, { "schema": { "type": "boolean", "default": true, "description": "Whether the search term matches by prefix, so partial words match as they are typed (e.g. 'nik' matches Nike). Set to false to match whole words only." }, "required": false, "description": "Whether the search term matches by prefix, so partial words match as they are typed (e.g. 'nik' matches Nike). Set to false to match whole words only.", "name": "autocomplete", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "name", "domain" ] }, "minItems": 1, "default": [ "name", "domain" ], "description": "Fields to match the search term against, as a comma-separated list or repeated parameter: 'name', 'domain', or both. Defaults to both." }, "required": false, "description": "Fields to match the search term against, as a comma-separated list or repeated parameter: 'name', 'domain', or both. Defaults to both.", "name": "queryBy", "in": "query" }, { "schema": { "type": "integer", "minimum": 0, "maximum": 2, "default": 0, "description": "Maximum number of typos tolerated when matching, from 0 to 2. Defaults to 0 (no typo tolerance)." }, "required": false, "description": "Maximum number of typos tolerated when matching, from 0 to 2. Defaults to 0 (no typo tolerance).", "name": "typoTolerance", "in": "query" }, { "$ref": "#/components/parameters/RequestTags" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "maxItems": 10, "description": "Up to 10 matching brands, name matches first, then domain matches, most popular first within each group. Empty when nothing matches.", "items": { "type": "object", "properties": { "domain": { "type": "string", "description": "The brand's domain.", "example": "nike.com" }, "name": { "type": "string", "description": "The brand's name. Empty string when unknown.", "example": "Nike" }, "logo": { "type": "string", "description": "Logo link URL that serves the brand's logo, generated per request for the calling organization.", "example": "https://logos.context.dev/?publicClientId=pub_1a2b3c&domain=nike.com" } }, "required": [ "domain", "name", "logo" ] } }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "results" ] } } } }, "400": { "description": "Bad Request - Invalid or missing search query", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the issue" }, "error_code": { "type": "string", "enum": [ "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Error code indicating unauthorized access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions or usage limit exceeded", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "FORBIDDEN", "USAGE_EXCEEDED", "DISABLED", "INSUFFICIENT_PERMISSIONS" ], "description": "Error code indicating forbidden access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "408": { "description": "Request timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Timeout error message" }, "error_code": { "type": "string", "enum": [ "REQUEST_TIMEOUT" ], "description": "Error code indicating request timeout" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR" ], "description": "Error code indicating internal server error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } } } } }, "/web/styleguide": { "get": { "summary": "Scrape Styleguide", "description": "Extract a comprehensive design system from a website including colors, typography, spacing, shadows, and UI components.", "x-oneOf-query": [ { "title": "By Domain", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Domain name to extract styleguide from (e.g., 'example.com', 'google.com')." }, "maxAgeMs": { "type": "integer", "minimum": 86400000, "maximum": 31536000000, "default": 7776000000, "description": "Maximum age in milliseconds for cached styleguide data before a hard refresh. Defaults to 3 months. Values below 1 day are clamped to 1 day." }, "colorScheme": { "type": "string", "enum": [ "light", "dark" ], "description": "Optional browser color scheme to emulate for websites that respond to prefers-color-scheme. This value is part of the styleguide cache key." }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" } } }, { "title": "By Direct URL", "required": [ "directUrl" ], "properties": { "directUrl": { "type": "string", "format": "uri", "description": "A specific URL to fetch the styleguide from directly, bypassing domain resolution." }, "maxAgeMs": { "type": "integer", "minimum": 86400000, "maximum": 31536000000, "default": 7776000000, "description": "Maximum age in milliseconds for cached styleguide data before a hard refresh. Defaults to 3 months. Values below 1 day are clamped to 1 day." }, "colorScheme": { "type": "string", "enum": [ "light", "dark" ], "description": "Optional browser color scheme to emulate for websites that respond to prefers-color-scheme. This value is part of the styleguide cache key." }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ "Web Extraction" ], "x-mint": { "content": "10 Credits", "title": "Scrape Styleguide", "sidebarTitle": "Scrape styleguide", "description": "Extract a comprehensive design system from a website including colors, typography, spacing, shadows, and UI components." }, "parameters": [ { "schema": { "type": "string", "minLength": 3, "description": "Domain name to extract styleguide from (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both." }, "required": false, "description": "Domain name to extract styleguide from (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both.", "name": "domain", "in": "query" }, { "schema": { "type": "string", "format": "uri", "description": "A specific URL to fetch the styleguide from directly, bypassing domain resolution (e.g., 'https://example.com/design-system'). When provided, the styleguide is extracted from this exact URL. You must provide either 'domain' or 'directUrl', but not both." }, "required": false, "description": "A specific URL to fetch the styleguide from directly, bypassing domain resolution (e.g., 'https://example.com/design-system'). When provided, the styleguide is extracted from this exact URL. You must provide either 'domain' or 'directUrl', but not both.", "name": "directUrl", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "default": 7776000000, "description": "Maximum age in milliseconds for cached brand data before the API performs a hard refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 year." }, "required": false, "description": "Maximum age in milliseconds for cached brand data before the API performs a hard refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 year.", "name": "maxAgeMs", "in": "query" }, { "schema": { "$ref": "#/components/schemas/TimeoutMS" }, "required": false, "description": "Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).", "name": "timeoutMS", "in": "query" }, { "schema": { "type": "string", "enum": [ "light", "dark" ], "description": "Optional browser color scheme to emulate for websites that respond to prefers-color-scheme. This value is part of the styleguide cache key." }, "required": false, "description": "Optional browser color scheme to emulate for websites that respond to prefers-color-scheme. This value is part of the styleguide cache key.", "name": "colorScheme", "in": "query" }, { "$ref": "#/components/parameters/RequestTags" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the response, e.g., 'ok'" }, "domain": { "type": "string", "description": "The normalized domain that was processed" }, "styleguide": { "type": "object", "description": "Comprehensive styleguide data extracted from the website", "required": [ "mode", "colors", "typography", "elementSpacing", "shadows", "components", "fontLinks" ], "properties": { "mode": { "type": "string", "enum": [ "light", "dark" ], "description": "The primary color mode of the website design" }, "colors": { "type": "object", "description": "Primary colors used on the website", "required": [ "accent", "background", "text" ], "properties": { "accent": { "type": "string", "description": "Accent color (hex format)" }, "background": { "type": "string", "description": "Background color (hex format)" }, "text": { "type": "string", "description": "Text color (hex format)" } } }, "typography": { "type": "object", "description": "Typography styles used on the website", "required": [ "headings" ], "properties": { "headings": { "type": "object", "description": "Heading styles", "properties": { "h1": { "type": "object", "required": [ "fontFamily", "fontFallbacks", "fontSize", "fontWeight", "lineHeight", "letterSpacing" ], "properties": { "fontFamily": { "type": "string", "description": "Primary face (first family in the computed stack)" }, "fontFallbacks": { "type": "array", "items": { "type": "string" }, "description": "Full ordered font list from resolved computed font-family" }, "fontSize": { "type": "string" }, "fontWeight": { "type": "number" }, "lineHeight": { "type": "string" }, "letterSpacing": { "type": "string" } } }, "h2": { "type": "object", "required": [ "fontFamily", "fontFallbacks", "fontSize", "fontWeight", "lineHeight", "letterSpacing" ], "properties": { "fontFamily": { "type": "string", "description": "Primary face (first family in the computed stack)" }, "fontFallbacks": { "type": "array", "items": { "type": "string" }, "description": "Full ordered font list from resolved computed font-family" }, "fontSize": { "type": "string" }, "fontWeight": { "type": "number" }, "lineHeight": { "type": "string" }, "letterSpacing": { "type": "string" } } }, "h3": { "type": "object", "required": [ "fontFamily", "fontFallbacks", "fontSize", "fontWeight", "lineHeight", "letterSpacing" ], "properties": { "fontFamily": { "type": "string", "description": "Primary face (first family in the computed stack)" }, "fontFallbacks": { "type": "array", "items": { "type": "string" }, "description": "Full ordered font list from resolved computed font-family" }, "fontSize": { "type": "string" }, "fontWeight": { "type": "number" }, "lineHeight": { "type": "string" }, "letterSpacing": { "type": "string" } } }, "h4": { "type": "object", "required": [ "fontFamily", "fontFallbacks", "fontSize", "fontWeight", "lineHeight", "letterSpacing" ], "properties": { "fontFamily": { "type": "string", "description": "Primary face (first family in the computed stack)" }, "fontFallbacks": { "type": "array", "items": { "type": "string" }, "description": "Full ordered font list from resolved computed font-family" }, "fontSize": { "type": "string" }, "fontWeight": { "type": "number" }, "lineHeight": { "type": "string" }, "letterSpacing": { "type": "string" } } } } }, "p": { "type": "object", "required": [ "fontFamily", "fontFallbacks", "fontSize", "fontWeight", "lineHeight", "letterSpacing" ], "properties": { "fontFamily": { "type": "string", "description": "Primary face (first family in the computed stack)" }, "fontFallbacks": { "type": "array", "items": { "type": "string" }, "description": "Full ordered font list from resolved computed font-family" }, "fontSize": { "type": "string" }, "fontWeight": { "type": "number" }, "lineHeight": { "type": "string" }, "letterSpacing": { "type": "string" } } } } }, "elementSpacing": { "type": "object", "description": "Spacing system used on the website", "required": [ "xs", "sm", "md", "lg", "xl" ], "properties": { "xs": { "type": "string" }, "sm": { "type": "string" }, "md": { "type": "string" }, "lg": { "type": "string" }, "xl": { "type": "string" } } }, "shadows": { "type": "object", "description": "Shadow styles used on the website", "required": [ "sm", "md", "lg", "xl", "inner" ], "properties": { "sm": { "type": "string" }, "md": { "type": "string" }, "lg": { "type": "string" }, "xl": { "type": "string" }, "inner": { "type": "string" } } }, "fontLinks": { "type": "object", "description": "Font assets keyed by family name as it appears in fontFamily/fontFallbacks (non-generic names only). Clients match typography.fontFamily / fontWeight or button styles to pick a file URL from files.", "additionalProperties": { "type": "object", "required": [ "type", "files" ], "properties": { "type": { "type": "string", "enum": [ "google", "custom" ] }, "files": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Upright font files keyed by weight string (e.g. \"400\" for regular, \"500\", \"700\"). Values are absolute URLs." }, "category": { "type": "string", "description": "Google Fonts category when type is google (e.g. sans-serif, serif, monospace, display, handwriting). Omitted for custom fonts when unknown." }, "displayName": { "type": "string", "description": "Present when type is custom: human-readable name derived from the fontLinks key (strip build/hash suffixes, split camelCase / PascalCase, normalize separators). Google entries omit this." } } } }, "components": { "type": "object", "description": "UI component styles", "required": [ "button" ], "properties": { "button": { "type": "object", "description": "Button component styles", "properties": { "primary": { "type": "object", "required": [ "backgroundColor", "color", "borderColor", "borderRadius", "borderWidth", "borderStyle", "padding", "minWidth", "minHeight", "fontSize", "fontWeight", "textDecoration", "boxShadow", "css" ], "properties": { "backgroundColor": { "type": "string" }, "color": { "type": "string" }, "borderColor": { "type": "string", "description": "Border color as CSS hex (#RRGGBB or #RRGGBBAA when computed border-color has alpha)" }, "borderRadius": { "type": "string" }, "borderWidth": { "type": "string" }, "borderStyle": { "type": "string" }, "padding": { "type": "string" }, "minWidth": { "type": "string", "description": "Sampled minimum width of the button box (typically px)" }, "minHeight": { "type": "string", "description": "Sampled minimum height of the button box (typically px)" }, "fontSize": { "type": "string" }, "fontWeight": { "type": "number" }, "fontFamily": { "type": "string", "description": "Primary button typeface (first in fontFallbacks)" }, "fontFallbacks": { "type": "array", "items": { "type": "string" }, "description": "Full ordered font list from computed font-family" }, "textDecoration": { "type": "string" }, "textDecorationColor": { "type": "string", "description": "Hex color of the underline when it differs from the text color" }, "boxShadow": { "type": "string", "description": "Computed box-shadow (comma-separated layers when present)" }, "css": { "type": "string", "description": "Ready-to-use CSS declaration block for this component style" } } }, "secondary": { "type": "object", "required": [ "backgroundColor", "color", "borderColor", "borderRadius", "borderWidth", "borderStyle", "padding", "minWidth", "minHeight", "fontSize", "fontWeight", "textDecoration", "boxShadow", "css" ], "properties": { "backgroundColor": { "type": "string" }, "color": { "type": "string" }, "borderColor": { "type": "string", "description": "Border color as CSS hex (#RRGGBB or #RRGGBBAA when computed border-color has alpha)" }, "borderRadius": { "type": "string" }, "borderWidth": { "type": "string" }, "borderStyle": { "type": "string" }, "padding": { "type": "string" }, "minWidth": { "type": "string", "description": "Sampled minimum width of the button box (typically px)" }, "minHeight": { "type": "string", "description": "Sampled minimum height of the button box (typically px)" }, "fontSize": { "type": "string" }, "fontWeight": { "type": "number" }, "fontFamily": { "type": "string", "description": "Primary button typeface (first in fontFallbacks)" }, "fontFallbacks": { "type": "array", "items": { "type": "string" }, "description": "Full ordered font list from computed font-family" }, "textDecoration": { "type": "string" }, "textDecorationColor": { "type": "string", "description": "Hex color of the underline when it differs from the text color" }, "boxShadow": { "type": "string", "description": "Computed box-shadow (comma-separated layers when present)" }, "css": { "type": "string", "description": "Ready-to-use CSS declaration block for this component style" } } }, "link": { "type": "object", "required": [ "backgroundColor", "color", "borderColor", "borderRadius", "borderWidth", "borderStyle", "padding", "minWidth", "minHeight", "fontSize", "fontWeight", "textDecoration", "boxShadow", "css" ], "properties": { "backgroundColor": { "type": "string" }, "color": { "type": "string" }, "borderColor": { "type": "string", "description": "Border color as CSS hex (#RRGGBB or #RRGGBBAA when computed border-color has alpha)" }, "borderRadius": { "type": "string" }, "borderWidth": { "type": "string" }, "borderStyle": { "type": "string" }, "padding": { "type": "string" }, "minWidth": { "type": "string", "description": "Sampled minimum width of the button box (typically px)" }, "minHeight": { "type": "string", "description": "Sampled minimum height of the button box (typically px)" }, "fontSize": { "type": "string" }, "fontWeight": { "type": "number" }, "fontFamily": { "type": "string", "description": "Primary button typeface (first in fontFallbacks)" }, "fontFallbacks": { "type": "array", "items": { "type": "string" }, "description": "Full ordered font list from computed font-family" }, "textDecoration": { "type": "string" }, "textDecorationColor": { "type": "string", "description": "Hex color of the underline when it differs from the text color" }, "boxShadow": { "type": "string", "description": "Computed box-shadow (comma-separated layers when present)" }, "css": { "type": "string", "description": "Ready-to-use CSS declaration block for this component style" } } } } }, "card": { "type": "object", "description": "Card component style", "required": [ "backgroundColor", "borderColor", "borderRadius", "borderWidth", "borderStyle", "padding", "boxShadow", "textColor", "css" ], "properties": { "backgroundColor": { "type": "string" }, "borderColor": { "type": "string", "description": "Border color as CSS hex (#RRGGBB or #RRGGBBAA when computed border-color has alpha)" }, "borderRadius": { "type": "string" }, "borderWidth": { "type": "string" }, "borderStyle": { "type": "string" }, "padding": { "type": "string" }, "boxShadow": { "type": "string" }, "textColor": { "type": "string" }, "css": { "type": "string", "description": "Ready-to-use CSS declaration block for this component style" } } } } } } }, "code": { "type": "integer", "description": "HTTP status code" }, "cache_metadata": { "$ref": "#/components/schemas/CacheMetadata" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "cache_metadata" ] } } } }, "400": { "description": "Bad Request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR", "VALID", "NOT_FOUND", "FORBIDDEN", "USAGE_EXCEEDED", "RATE_LIMITED", "UNAUTHORIZED", "DISABLED", "INSUFFICIENT_PERMISSIONS", "TIMEOUT_EXCEEDS_MAXIMUM", "WEBSITE_ACCESS_ERROR", "WEBSITE_BLOCKED", "WEBSITE_NOT_FOUND", "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating the type of error. WEBSITE_BLOCKED means the site answered with an anti-bot challenge or blocked automated access instead of the page — the request is not billed, and retrying later sometimes succeeds. WEBSITE_NOT_FOUND means the target page returned or fingerprinted as a 404." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR", "VALID", "NOT_FOUND", "FORBIDDEN", "USAGE_EXCEEDED", "RATE_LIMITED", "UNAUTHORIZED", "DISABLED", "INSUFFICIENT_PERMISSIONS", "TIMEOUT_EXCEEDS_MAXIMUM", "WEBSITE_ACCESS_ERROR", "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "408": { "description": "Request Timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Timeout error message" }, "error_code": { "type": "string", "enum": [ "REQUEST_TIMEOUT" ], "description": "Error code indicating request timeout" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR" ], "description": "Error code indicating internal server error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } } } } }, "/web/fonts": { "get": { "summary": "Scrape Fonts", "description": "Scrape font information from a website including font families, usage statistics, fallbacks, and element/word counts.", "x-oneOf-query": [ { "title": "By Domain", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Domain name to extract fonts from (e.g., 'example.com', 'google.com')." }, "maxAgeMs": { "type": "integer", "minimum": 86400000, "maximum": 31536000000, "default": 7776000000, "description": "Maximum age in milliseconds for cached font data before a hard refresh. Defaults to 3 months. Ignored when 'directUrl' is used." }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" } } }, { "title": "By Direct URL", "required": [ "directUrl" ], "properties": { "directUrl": { "type": "string", "format": "uri", "description": "A specific URL to fetch fonts from directly, bypassing domain resolution." }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ "Web Extraction" ], "x-mint": { "content": "5 Credits", "title": "Scrape Fonts", "sidebarTitle": "Scrape fonts", "description": "Scrape font information from a website including font families, usage statistics, fallbacks, and element/word counts." }, "parameters": [ { "schema": { "type": "string", "format": "uri", "description": "A specific URL to fetch fonts from directly, bypassing domain resolution (e.g., 'https://example.com/design-system'). When provided, fonts are extracted from this exact URL. You must provide either 'domain' or 'directUrl', but not both." }, "required": false, "description": "A specific URL to fetch fonts from directly, bypassing domain resolution (e.g., 'https://example.com/design-system'). When provided, fonts are extracted from this exact URL. You must provide either 'domain' or 'directUrl', but not both.", "name": "directUrl", "in": "query" }, { "schema": { "type": "string", "minLength": 3, "description": "Domain name to extract fonts from (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both." }, "required": false, "description": "Domain name to extract fonts from (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both.", "name": "domain", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "default": 7776000000, "description": "Maximum age in milliseconds for cached brand data before the API performs a hard refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 year." }, "required": false, "description": "Maximum age in milliseconds for cached brand data before the API performs a hard refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 year.", "name": "maxAgeMs", "in": "query" }, { "schema": { "$ref": "#/components/schemas/TimeoutMS" }, "required": false, "description": "Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).", "name": "timeoutMS", "in": "query" }, { "$ref": "#/components/parameters/RequestTags" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the response, e.g., 'ok'" }, "domain": { "type": "string", "description": "The normalized domain that was processed" }, "fonts": { "type": "array", "description": "Array of font usage information", "items": { "type": "object", "properties": { "font": { "type": "string", "description": "Font family name" }, "uses": { "type": "array", "items": { "type": "string" }, "description": "Array of CSS selectors or element types where this font is used" }, "fallbacks": { "type": "array", "items": { "type": "string" }, "description": "Array of fallback font families" }, "num_elements": { "type": "number", "description": "Number of elements using this font" }, "num_words": { "type": "number", "description": "Number of words using this font" }, "percent_words": { "type": "number", "description": "Percentage of words using this font" }, "percent_elements": { "type": "number", "description": "Percentage of elements using this font" } }, "required": [ "font", "uses", "fallbacks", "num_elements", "num_words", "percent_words", "percent_elements" ] } }, "fontLinks": { "type": "object", "description": "Font assets keyed by family name as it appears in the fonts array (non-generic names only). Clients match entries in fonts to pick a file URL from files. Omitted when no families resolve to Google or custom @font-face URLs.", "additionalProperties": { "type": "object", "required": [ "type", "files" ], "properties": { "type": { "type": "string", "enum": [ "google", "custom" ] }, "files": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Upright font files keyed by weight string (e.g. \"400\" for regular, \"500\", \"700\"). Values are absolute URLs." }, "category": { "type": "string", "description": "Google Fonts category when type is google (e.g. sans-serif, serif, monospace, display, handwriting). Omitted for custom fonts when unknown." }, "displayName": { "type": "string", "description": "Present when type is custom: human-readable name derived from the fontLinks key (strip build/hash suffixes, split camelCase / PascalCase, normalize separators). Google entries omit this." } } } }, "code": { "type": "integer", "description": "HTTP status code, e.g., 200" }, "cache_metadata": { "$ref": "#/components/schemas/CacheMetadata" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "status", "domain", "fonts", "code", "cache_metadata" ] } } } }, "400": { "description": "Bad request - Invalid input parameters", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing the validation error" }, "error_code": { "type": "string", "enum": [ "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating input validation error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Error code indicating unauthorized access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions or usage limit exceeded", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "FORBIDDEN", "USAGE_EXCEEDED", "DISABLED", "INSUFFICIENT_PERMISSIONS" ], "description": "Error code indicating forbidden access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "408": { "description": "Request timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Timeout error message" }, "error_code": { "type": "string", "enum": [ "REQUEST_TIMEOUT" ], "description": "Error code indicating request timeout" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR" ], "description": "Error code indicating internal server error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } } } } }, "/web/screenshot": { "get": { "summary": "Scrape Screenshot", "description": "Capture a screenshot of a website.", "x-oneOf-query": [ { "title": "By Domain", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Domain name to take screenshot of (e.g., 'example.com', 'google.com')." }, "fullScreenshot": { "type": "string", "enum": [ "true", "false" ] }, "handleCookiePopup": { "type": "string", "enum": [ "true", "false" ], "default": "false", "description": "Optional parameter to control cookie/consent popup handling. If 'true', the browser service dismisses cookie consent before capture. If 'false' or omitted, captures without that step. " }, "clearPopups": { "type": "string", "enum": [ "true", "false" ], "default": "false", "description": "Optional parameter for comprehensive popup cleanup. If 'true', the browser dismisses detected cookie/consent UI and clears other detected obstructive popups and overlays before capture. If 'false' or omitted, this parameter requests no cleanup; handleCookiePopup can still request cookie/consent handling independently." }, "colorScheme": { "type": "string", "enum": [ "light", "dark" ], "description": "Optional parameter to choose the site's visual theme in the screenshot. Use 'light' or 'dark' when the site offers both appearances." }, "viewport": { "type": "object", "additionalProperties": false, "default": { "width": 1920, "height": 1080 }, "properties": { "width": { "type": "integer", "minimum": 240, "maximum": 7680, "default": 1920, "description": "Viewport width in pixels." }, "height": { "type": "integer", "minimum": 240, "maximum": 4320, "default": 1080, "description": "Viewport height in pixels." } }, "description": "Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080." }, "maxAgeMs": { "type": "integer", "minimum": 0, "maximum": 2592000000, "default": 86400000, "description": "Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh." }, "page": { "type": "string", "enum": [ "login", "signup", "blog", "careers", "pricing", "terms", "privacy", "contact" ] }, "waitForMs": { "type": "integer", "minimum": 0, "maximum": 30000, "default": 3000, "description": "Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. When combined with timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT." }, "country": { "$ref": "#/components/schemas/BrowserCountryCode" }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" } } }, { "title": "By Direct URL", "required": [ "directUrl" ], "properties": { "directUrl": { "type": "string", "format": "uri", "description": "A specific URL to screenshot directly, bypassing domain resolution." }, "fullScreenshot": { "type": "string", "enum": [ "true", "false" ] }, "handleCookiePopup": { "type": "string", "enum": [ "true", "false" ], "default": "false", "description": "Optional parameter to control cookie/consent popup handling. If 'true', the browser service dismisses cookie consent before capture. If 'false' or omitted, captures without that step. " }, "clearPopups": { "type": "string", "enum": [ "true", "false" ], "default": "false", "description": "Optional parameter for comprehensive popup cleanup. If 'true', the browser dismisses detected cookie/consent UI and clears other detected obstructive popups and overlays before capture. If 'false' or omitted, this parameter requests no cleanup; handleCookiePopup can still request cookie/consent handling independently." }, "colorScheme": { "type": "string", "enum": [ "light", "dark" ], "description": "Optional parameter to choose the site's visual theme in the screenshot. Use 'light' or 'dark' when the site offers both appearances." }, "viewport": { "type": "object", "additionalProperties": false, "default": { "width": 1920, "height": 1080 }, "properties": { "width": { "type": "integer", "minimum": 240, "maximum": 7680, "default": 1920, "description": "Viewport width in pixels." }, "height": { "type": "integer", "minimum": 240, "maximum": 4320, "default": 1080, "description": "Viewport height in pixels." } }, "description": "Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080." }, "maxAgeMs": { "type": "integer", "minimum": 0, "maximum": 2592000000, "default": 86400000, "description": "Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh." }, "waitForMs": { "type": "integer", "minimum": 0, "maximum": 30000, "default": 3000, "description": "Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. When combined with timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT." }, "country": { "$ref": "#/components/schemas/BrowserCountryCode" }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ "Web Scraping" ], "x-mint": { "content": "1 Credit", "title": "Scrape Screenshot", "sidebarTitle": "Scrape screenshot", "description": "Capture a screenshot of a website." }, "parameters": [ { "schema": { "type": "string", "minLength": 3, "description": "Domain name to take screenshot of (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both." }, "required": false, "description": "Domain name to take screenshot of (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both.", "name": "domain", "in": "query" }, { "schema": { "type": "string", "format": "uri", "description": "A specific URL to screenshot directly, bypassing domain resolution (e.g., 'https://example.com/pricing'). When provided, the screenshot is taken of this exact URL. You must provide either 'domain' or 'directUrl', but not both." }, "required": false, "description": "A specific URL to screenshot directly, bypassing domain resolution (e.g., 'https://example.com/pricing'). When provided, the screenshot is taken of this exact URL. You must provide either 'domain' or 'directUrl', but not both.", "name": "directUrl", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Optional parameter to determine screenshot type. If 'true', takes a full page screenshot capturing all content. If 'false' or not provided, takes a viewport screenshot (standard browser view)." }, "required": false, "description": "Optional parameter to determine screenshot type. If 'true', takes a full page screenshot capturing all content. If 'false' or not provided, takes a viewport screenshot (standard browser view).", "name": "fullScreenshot", "in": "query" }, { "schema": { "type": "string", "enum": [ "login", "signup", "blog", "careers", "pricing", "terms", "privacy", "contact" ], "description": "Optional parameter to specify which page type to screenshot. If provided, the system will scrape the domain's links and use heuristics to find the most appropriate URL for the specified page type (30 supported languages). If not provided, screenshots the main domain landing page. Only applicable when using 'domain', not 'directUrl'." }, "required": false, "description": "Optional parameter to specify which page type to screenshot. If provided, the system will scrape the domain's links and use heuristics to find the most appropriate URL for the specified page type (30 supported languages). If not provided, screenshots the main domain landing page. Only applicable when using 'domain', not 'directUrl'.", "name": "page", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 30000, "default": 3000, "description": "Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. When combined with timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT." }, "required": false, "description": "Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. When combined with timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT.", "name": "waitForMs", "in": "query" }, { "schema": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 240, "maximum": 7680, "default": 1920, "description": "Viewport width in pixels." }, "height": { "type": "integer", "minimum": 240, "maximum": 4320, "default": 1080, "description": "Viewport height in pixels." } }, "default": { "width": 1920, "height": 1080 }, "description": "Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080." }, "required": false, "description": "Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080.", "name": "viewport", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step." }, "required": false, "description": "Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step.", "name": "handleCookiePopup", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "Optional parameter for comprehensive popup cleanup. If 'true', the browser dismisses detected cookie/consent UI and clears other detected obstructive popups and overlays before capture. If 'false' or not provided, this parameter requests no cleanup; handleCookiePopup can still request cookie/consent handling independently." }, "required": false, "description": "Optional parameter for comprehensive popup cleanup. If 'true', the browser dismisses detected cookie/consent UI and clears other detected obstructive popups and overlays before capture. If 'false' or not provided, this parameter requests no cleanup; handleCookiePopup can still request cookie/consent handling independently.", "name": "clearPopups", "in": "query" }, { "schema": { "type": "string", "enum": [ "light", "dark" ], "description": "Optional parameter to choose the site's visual theme in the screenshot. Use 'light' or 'dark' when the site offers both appearances." }, "required": false, "description": "Optional parameter to choose the site's visual theme in the screenshot. Use 'light' or 'dark' when the site offers both appearances.", "name": "colorScheme", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000, "description": "Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000." }, "required": false, "description": "Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000.", "name": "scrollOffset", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2592000000, "default": 86400000, "description": "Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh." }, "required": false, "description": "Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh.", "name": "maxAgeMs", "in": "query" }, { "schema": { "$ref": "#/components/schemas/BrowserCountryCode" }, "required": false, "description": "Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).", "name": "country", "in": "query" }, { "schema": { "$ref": "#/components/schemas/LenientTimeoutMS" }, "required": false, "description": "Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).", "name": "timeoutMS", "in": "query" }, { "schema": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true." }, "required": false, "description": "Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.", "name": "zdr", "in": "query" }, { "$ref": "#/components/parameters/RequestTags" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "X-Context-ZDR": { "description": "Present with the value true when zero data retention was requested and honored.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the response, e.g., 'ok'" }, "domain": { "type": "string", "description": "The normalized domain that was processed" }, "screenshot": { "type": "string", "description": "Public image URL for standard requests, or an in-memory data URL when ZDR is enabled." }, "screenshotType": { "type": "string", "enum": [ "viewport", "fullPage" ], "description": "Type of screenshot that was captured" }, "width": { "type": "integer", "description": "Width in pixels of the returned screenshot image" }, "height": { "type": "integer", "description": "Height in pixels of the returned screenshot image" }, "code": { "type": "integer", "description": "HTTP status code" }, "cache_metadata": { "$ref": "#/components/schemas/CacheMetadata" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "cache_metadata" ] } } } }, "400": { "description": "Bad Request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR", "VALID", "NOT_FOUND", "FORBIDDEN", "USAGE_EXCEEDED", "RATE_LIMITED", "UNAUTHORIZED", "DISABLED", "INSUFFICIENT_PERMISSIONS", "TIMEOUT_EXCEEDS_MAXIMUM", "TIMEOUT_TOO_SHORT_FOR_WAIT", "WEBSITE_ACCESS_ERROR", "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating the type of error. TIMEOUT_TOO_SHORT_FOR_WAIT means timeoutMS is shorter than waitForMs plus the page-load margin, so the screenshot could never complete before the deadline; raise timeoutMS or lower waitForMs." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR", "VALID", "NOT_FOUND", "FORBIDDEN", "USAGE_EXCEEDED", "RATE_LIMITED", "UNAUTHORIZED", "DISABLED", "INSUFFICIENT_PERMISSIONS", "TIMEOUT_EXCEEDS_MAXIMUM", "WEBSITE_ACCESS_ERROR", "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR" ], "description": "Error code indicating internal server error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } } } } }, "/web/naics": { "get": { "summary": "Classify NAICS industries", "description": "Classify any brand into 2022 NAICS industry codes from its domain or name.", "security": [ { "bearerAuth": [] } ], "tags": [ "Web Extraction" ], "x-mint": { "content": "10 Credits", "title": "Classify NAICS industries", "sidebarTitle": "Classify NAICS industries", "description": "Classify any brand into 2022 NAICS industry codes from its domain or name." }, "parameters": [ { "schema": { "type": "string", "minLength": 4, "description": "Brand domain or title to retrieve NAICS code for. If a valid domain is provided, it will be used for classification, otherwise, we will search for the brand using the provided title." }, "required": true, "description": "Brand domain or title to retrieve NAICS code for. If a valid domain is provided, it will be used for classification, otherwise, we will search for the brand using the provided title.", "name": "input", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "description": "Minimum number of NAICS codes to return. Must be at least 1. Defaults to 1." }, "required": false, "description": "Minimum number of NAICS codes to return. Must be at least 1. Defaults to 1.", "name": "minResults", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5, "description": "Maximum number of NAICS codes to return. Must be between 1 and 10. Defaults to 5." }, "required": false, "description": "Maximum number of NAICS codes to return. Must be between 1 and 10. Defaults to 5.", "name": "maxResults", "in": "query" }, { "schema": { "$ref": "#/components/schemas/TimeoutMS" }, "required": false, "description": "Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).", "name": "timeoutMS", "in": "query" }, { "$ref": "#/components/parameters/RequestTags" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the response, e.g., 'ok'" }, "domain": { "type": "string", "description": "Domain found for the brand" }, "type": { "type": "string", "description": "Industry classification type, for naics api it will be `naics`" }, "codes": { "type": "array", "description": "Array of NAICS codes and titles.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "NAICS code" }, "name": { "type": "string", "description": "NAICS title" }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Confidence level for how well this NAICS code matches the company description" } }, "required": [ "code", "name", "confidence" ] } }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "400": { "description": "Bad Request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR", "VALID", "NOT_FOUND", "FORBIDDEN", "USAGE_EXCEEDED", "RATE_LIMITED", "UNAUTHORIZED", "DISABLED", "INSUFFICIENT_PERMISSIONS", "TIMEOUT_EXCEEDS_MAXIMUM", "WEBSITE_ACCESS_ERROR", "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR", "VALID", "NOT_FOUND", "FORBIDDEN", "USAGE_EXCEEDED", "RATE_LIMITED", "UNAUTHORIZED", "DISABLED", "INSUFFICIENT_PERMISSIONS", "TIMEOUT_EXCEEDS_MAXIMUM", "WEBSITE_ACCESS_ERROR", "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "404": { "description": "Brand not found.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "408": { "description": "Request Timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Timeout error message" }, "error_code": { "type": "string", "enum": [ "REQUEST_TIMEOUT" ], "description": "Error code indicating request timeout" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/web/sic": { "get": { "summary": "Classify SIC industries", "description": "Classify any brand into Standard Industrial Classification (SIC) codes from its domain or name. Choose between the original SIC system (`original_sic`) or the latest SIC list maintained by the SEC (`latest_sec`).", "security": [ { "bearerAuth": [] } ], "tags": [ "Web Extraction" ], "x-mint": { "content": "10 Credits", "title": "Classify SIC industries", "sidebarTitle": "Classify SIC industries", "description": "Classify any brand into Standard Industrial Classification (SIC) codes from its domain or name." }, "parameters": [ { "schema": { "type": "string", "minLength": 4, "description": "Brand domain or title to retrieve SIC code for. If a valid domain is provided, it will be used for classification, otherwise, we will search for the brand using the provided title." }, "required": true, "description": "Brand domain or title to retrieve SIC code for. If a valid domain is provided, it will be used for classification, otherwise, we will search for the brand using the provided title.", "name": "input", "in": "query" }, { "schema": { "type": "string", "enum": [ "original_sic", "latest_sec" ], "default": "original_sic", "description": "Which SIC dataset to classify against. `original_sic` uses the 1987 Standard Industrial Classification system; `latest_sec` uses the current SIC list as published by the SEC. Defaults to `original_sic`." }, "required": false, "description": "Which SIC dataset to classify against. `original_sic` uses the 1987 Standard Industrial Classification system; `latest_sec` uses the current SIC list as published by the SEC. Defaults to `original_sic`.", "name": "type", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "description": "Minimum number of SIC codes to return. Must be at least 1. Defaults to 1." }, "required": false, "description": "Minimum number of SIC codes to return. Must be at least 1. Defaults to 1.", "name": "minResults", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5, "description": "Maximum number of SIC codes to return. Must be between 1 and 10. Defaults to 5." }, "required": false, "description": "Maximum number of SIC codes to return. Must be between 1 and 10. Defaults to 5.", "name": "maxResults", "in": "query" }, { "schema": { "$ref": "#/components/schemas/TimeoutMS" }, "required": false, "description": "Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).", "name": "timeoutMS", "in": "query" }, { "$ref": "#/components/parameters/RequestTags" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the response, e.g., 'ok'" }, "domain": { "type": "string", "description": "Domain found for the brand" }, "type": { "type": "string", "description": "Industry classification type, for sic api it will be `sic`" }, "classification": { "type": "string", "enum": [ "original_sic", "latest_sec" ], "description": "Echoes back which SIC dataset was used to classify the brand." }, "codes": { "type": "array", "description": "Array of SIC codes with confidence scores. Extra fields depend on the requested classification: `original_sic` results include `majorGroup` and `majorGroupName`; `latest_sec` results include `office`.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "SIC code (4-digit)." }, "name": { "type": "string", "description": "SIC industry title." }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Confidence level for how well this SIC code matches the company description." }, "majorGroup": { "type": "string", "description": "2-digit major group identifier (the leading two digits of the code). Only present when `classification` is `original_sic`." }, "majorGroupName": { "type": "string", "description": "Description of the 2-digit major group. Only present when `classification` is `original_sic`." }, "office": { "type": "string", "description": "SEC review office responsible for filings under this code. Only present when `classification` is `latest_sec`." } }, "required": [ "code", "name", "confidence" ] } }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "400": { "description": "Bad Request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR", "VALID", "NOT_FOUND", "FORBIDDEN", "USAGE_EXCEEDED", "RATE_LIMITED", "UNAUTHORIZED", "DISABLED", "INSUFFICIENT_PERMISSIONS", "TIMEOUT_EXCEEDS_MAXIMUM", "WEBSITE_ACCESS_ERROR", "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR", "VALID", "NOT_FOUND", "FORBIDDEN", "USAGE_EXCEEDED", "RATE_LIMITED", "UNAUTHORIZED", "DISABLED", "INSUFFICIENT_PERMISSIONS", "TIMEOUT_EXCEEDS_MAXIMUM", "WEBSITE_ACCESS_ERROR", "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "404": { "description": "Brand not found.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "408": { "description": "Request Timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Timeout error message" }, "error_code": { "type": "string", "enum": [ "REQUEST_TIMEOUT" ], "description": "Error code indicating request timeout" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/brand/ai/product": { "post": { "summary": "Extract a single product from a URL", "description": "Given a single URL, determines if it is a product page and extracts the product information.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The product page URL to extract product data from." }, "maxAgeMs": { "type": "integer", "minimum": 0, "maximum": 2592000000, "default": 604800000, "description": "Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 7 days (604800000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh." }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" }, "tags": { "$ref": "#/components/schemas/RequestTags" } } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "Web Extraction" ], "x-mint": { "content": "10 Credits" }, "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "is_product_page": { "type": "boolean", "description": "Whether the given URL is a product detail page" }, "platform": { "type": [ "string", "null" ], "enum": [ "amazon", "tiktok_shop", "etsy", "generic", null ], "description": "The detected ecommerce platform, or null if not a product page" }, "product": { "type": [ "object", "null" ], "description": "The extracted product data, or null if not a product page", "properties": { "name": { "type": "string", "description": "Name of the product" }, "description": { "type": "string", "description": "Description of the product" }, "price": { "type": [ "number", "null" ], "description": "Price of the product" }, "regular_price": { "type": [ "number", "null" ], "description": "Original or regular price before a displayed discount" }, "currency": { "type": [ "string", "null" ], "description": "Currency code for the price (e.g., USD, EUR)" }, "billing_frequency": { "type": [ "string", "null" ], "enum": [ "monthly", "yearly", "one_time", "usage_based", null ], "description": "Billing frequency for the product" }, "pricing_model": { "type": [ "string", "null" ], "enum": [ "per_seat", "flat", "tiered", "freemium", "custom", null ], "description": "Pricing model for the product" }, "url": { "type": [ "string", "null" ], "description": "URL to the product page" }, "category": { "type": [ "string", "null" ], "description": "Category of the product" }, "availability": { "type": [ "string", "null" ], "enum": [ "in_stock", "out_of_stock", "limited_availability", "preorder", "backorder", "made_to_order", "discontinued", null ], "description": "Normalized stock or ordering availability" }, "dimensions": { "type": "array", "description": "Dimension statements shown for the product, preserving labels, values, and units", "items": { "type": "string" } }, "features": { "type": "array", "description": "List of product features", "items": { "type": "string" } }, "target_audience": { "type": "array", "description": "Target audience for the product (array of strings)", "items": { "type": "string" } }, "tags": { "type": "array", "description": "Tags associated with the product", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ], "description": "URL to the product image" }, "images": { "type": "array", "description": "URLs to product images on the page (up to 7)", "items": { "type": "string" } }, "sku": { "type": [ "string", "null" ], "description": "Stock Keeping Unit (product identifier). Null if no identifier is found." } }, "required": [ "name", "description", "features", "target_audience", "tags", "images", "sku" ] }, "cache_metadata": { "$ref": "#/components/schemas/CacheMetadata" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "cache_metadata" ] } } } }, "400": { "description": "Bad Request - validation error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR", "VALID", "NOT_FOUND", "FORBIDDEN", "USAGE_EXCEEDED", "RATE_LIMITED", "UNAUTHORIZED", "DISABLED", "INSUFFICIENT_PERMISSIONS", "TIMEOUT_EXCEEDS_MAXIMUM", "WEBSITE_ACCESS_ERROR", "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR", "VALID", "NOT_FOUND", "FORBIDDEN", "USAGE_EXCEEDED", "RATE_LIMITED", "UNAUTHORIZED", "DISABLED", "INSUFFICIENT_PERMISSIONS", "TIMEOUT_EXCEEDS_MAXIMUM", "WEBSITE_ACCESS_ERROR", "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "408": { "description": "Request Timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Timeout error message" }, "error_code": { "type": "string", "enum": [ "REQUEST_TIMEOUT" ], "description": "Error code indicating request timeout" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR" ], "description": "Error code indicating internal server error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } } } } }, "/brand/ai/products": { "post": { "summary": "Extract products from a brand's website", "description": "Extract product information from a brand's website. We will analyze the website and return a list of products with details such as name, description, image, pricing, features, and more.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "By Domain", "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "The domain name to analyze." }, "maxProducts": { "type": "integer", "minimum": 1, "maximum": 12, "description": "Maximum number of products to extract." }, "maxAgeMs": { "type": "integer", "minimum": 0, "maximum": 2592000000, "default": 604800000, "description": "Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 7 days (604800000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh." }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" }, "tags": { "$ref": "#/components/schemas/RequestTags" } } }, { "title": "By Direct URL", "type": "object", "required": [ "directUrl" ], "properties": { "directUrl": { "type": "string", "format": "uri", "description": "A specific URL to use directly as the starting point for extraction without domain resolution." }, "maxProducts": { "type": "integer", "minimum": 1, "maximum": 12, "description": "Maximum number of products to extract." }, "maxAgeMs": { "type": "integer", "minimum": 0, "maximum": 2592000000, "default": 604800000, "description": "Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 7 days (604800000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh." }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" }, "tags": { "$ref": "#/components/schemas/RequestTags" } } } ] } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "Web Extraction" ], "x-mint": { "content": "10 Credits Beta Feature" }, "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "description": "Array of products extracted from the website", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the product" }, "description": { "type": "string", "description": "Description of the product" }, "price": { "type": [ "number", "null" ], "description": "Price of the product" }, "regular_price": { "type": [ "number", "null" ], "description": "Original or regular price before a displayed discount" }, "currency": { "type": [ "string", "null" ], "description": "Currency code for the price (e.g., USD, EUR)" }, "billing_frequency": { "type": [ "string", "null" ], "enum": [ "monthly", "yearly", "one_time", "usage_based", null ], "description": "Billing frequency for the product" }, "pricing_model": { "type": [ "string", "null" ], "enum": [ "per_seat", "flat", "tiered", "freemium", "custom", null ], "description": "Pricing model for the product" }, "url": { "type": [ "string", "null" ], "description": "URL to the product page" }, "category": { "type": [ "string", "null" ], "description": "Category of the product" }, "availability": { "type": [ "string", "null" ], "enum": [ "in_stock", "out_of_stock", "limited_availability", "preorder", "backorder", "made_to_order", "discontinued", null ], "description": "Normalized stock or ordering availability" }, "dimensions": { "type": "array", "description": "Dimension statements shown for the product, preserving labels, values, and units", "items": { "type": "string" } }, "features": { "type": "array", "description": "List of product features", "items": { "type": "string" } }, "target_audience": { "type": "array", "description": "Target audience for the product (array of strings)", "items": { "type": "string" } }, "tags": { "type": "array", "description": "Tags associated with the product", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ], "description": "URL to the product image" }, "images": { "type": "array", "description": "URLs to product images on the page (up to 7)", "items": { "type": "string" } }, "sku": { "type": [ "string", "null" ], "description": "Stock Keeping Unit (product identifier). Null if no identifier is found." } }, "required": [ "name", "description", "features", "target_audience", "tags", "images", "sku" ] } }, "cache_metadata": { "$ref": "#/components/schemas/CacheMetadata" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "cache_metadata" ] } } } }, "400": { "description": "Bad Request - validation error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR", "VALID", "NOT_FOUND", "FORBIDDEN", "USAGE_EXCEEDED", "RATE_LIMITED", "UNAUTHORIZED", "DISABLED", "INSUFFICIENT_PERMISSIONS", "TIMEOUT_EXCEEDS_MAXIMUM", "WEBSITE_ACCESS_ERROR", "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR", "VALID", "NOT_FOUND", "FORBIDDEN", "USAGE_EXCEEDED", "RATE_LIMITED", "UNAUTHORIZED", "DISABLED", "INSUFFICIENT_PERMISSIONS", "TIMEOUT_EXCEEDS_MAXIMUM", "WEBSITE_ACCESS_ERROR", "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "408": { "description": "Request Timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Timeout error message" }, "error_code": { "type": "string", "enum": [ "REQUEST_TIMEOUT" ], "description": "Error code indicating request timeout" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR" ], "description": "Error code indicating internal server error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } } } } }, "/utility/prefetch": { "post": { "summary": "Prefetch data", "description": "Signal that you may fetch data soon to improve latency. The type field selects what to prefetch ('brand' queues a brand data fetch, 'styleguide' queues a styleguide extraction) and identifier carries exactly one lookup key: a domain, or an email whose domain is extracted and validated (free email providers and disposable email addresses are not allowed).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "identifier" ], "properties": { "type": { "type": "string", "enum": [ "brand", "styleguide" ], "description": "What to prefetch: 'brand' warms the brand data cache, 'styleguide' warms the styleguide cache." }, "identifier": { "$ref": "#/components/schemas/UtilityPrefetchIdentifier" }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" }, "tags": { "$ref": "#/components/schemas/RequestTags" } } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "Utility" ], "x-mint": { "content": "0 Credits Only for Subscribers" }, "responses": { "200": { "description": "Successful response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the response, e.g., 'ok'" }, "message": { "type": "string", "description": "Success message" }, "type": { "type": "string", "enum": [ "brand", "styleguide" ], "description": "The type of prefetch that was queued, echoed from the request" }, "domain": { "type": "string", "description": "The domain that was queued for prefetching" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "400": { "description": "Bad Request - validation error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR", "VALID", "NOT_FOUND", "FORBIDDEN", "USAGE_EXCEEDED", "RATE_LIMITED", "UNAUTHORIZED", "DISABLED", "INSUFFICIENT_PERMISSIONS", "TIMEOUT_EXCEEDS_MAXIMUM", "WEBSITE_ACCESS_ERROR", "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR", "VALID", "NOT_FOUND", "FORBIDDEN", "USAGE_EXCEEDED", "RATE_LIMITED", "UNAUTHORIZED", "DISABLED", "INSUFFICIENT_PERMISSIONS", "TIMEOUT_EXCEEDS_MAXIMUM", "WEBSITE_ACCESS_ERROR", "INPUT_VALIDATION_ERROR" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "403": { "description": "Forbidden - Paid subscription required", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "status": { "type": "string", "description": "Status of the response, e.g., 'error'" }, "error_code": { "type": "string", "enum": [ "FORBIDDEN" ], "description": "Error code indicating forbidden access" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "408": { "description": "Request Timeout", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Timeout error message" }, "error_code": { "type": "string", "enum": [ "REQUEST_TIMEOUT" ], "description": "Error code indicating request timeout" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "422": { "description": "Unprocessable Entity - Free email or disposable email detected", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "status": { "type": "string", "description": "Status of the response, e.g., 'error'" }, "error_code": { "type": "string", "enum": [ "FREE_EMAIL_DETECTED", "DISPOSABLE_EMAIL_DETECTED" ], "description": "Error code indicating whether a free email provider or disposable email was detected" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR" ], "description": "Error code indicating internal server error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } } } } }, "/monitors": { "post": { "summary": "Create a monitor", "description": "Creates a monitor. The request body is a union of the supported target/change detection combinations. The monitor runs immediately after creation to create its initial baseline.", "operationId": "createMonitor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsCreateMonitorRequest" }, "examples": { "page_exact": { "summary": "Exact page monitor", "value": { "mode": "web", "name": "Acme pricing page", "target": { "type": "page", "url": "https://acme.com/pricing" }, "change_detection": { "type": "exact" }, "schedule": { "type": "interval", "frequency": 6, "unit": "hours" }, "webhook": { "url": "https://example.com/webhook" } } }, "sitemap_exact": { "summary": "Exact sitemap monitor", "value": { "mode": "web", "name": "Acme sitemap", "target": { "type": "sitemap", "url": "https://acme.com/sitemap.xml" }, "change_detection": { "type": "exact" }, "schedule": { "type": "interval", "frequency": 1, "unit": "days" }, "webhook": { "url": "https://example.com/webhook" } } }, "extract_semantic": { "summary": "Semantic extract monitor", "value": { "mode": "web", "name": "Acme website positioning", "target": { "type": "extract", "url": "https://acme.com", "instructions": "Extract the product positioning, pricing, packaging, and headline feature claims.", "max_pages": 10 }, "change_detection": { "type": "semantic" }, "schedule": { "type": "interval", "frequency": 1, "unit": "days" }, "webhook": { "url": "https://example.com/webhook" } } } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "responses": { "201": { "description": "Monitor created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsCreateMonitorResponse" } } } }, "400": { "$ref": "#/components/responses/MonitorsBadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "403": { "$ref": "#/components/responses/MonitorsLimitExceeded" } } }, "get": { "summary": "List monitors", "description": "Lists monitors for the authenticated organization. Supports free-text search (`q` over `search_by` fields, `prefix` or `exact` via `search_type`) plus status/type/tag filters. Results are paginated via the opaque `cursor`.", "operationId": "listMonitors", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "parameters": [ { "schema": { "type": "string", "maxLength": 200, "description": "Free-text search term, matched against the fields named in `search_by`.", "example": "pricing" }, "required": false, "description": "Free-text search term, matched against the fields named in `search_by`.", "name": "q", "in": "query" }, { "schema": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "name", "url", "instructions", "tags" ] }, "description": "Comma-separated fields to search with `q`. Defaults to all of them. Note `instructions` only exists on extract monitors.", "example": "name,url" }, "required": false, "description": "Comma-separated fields to search with `q`. Defaults to all of them. Note `instructions` only exists on extract monitors.", "name": "search_by", "in": "query" }, { "schema": { "type": "string", "enum": [ "exact", "prefix" ], "description": "`prefix` for as-you-type prefix matching (default), `exact` for full-token matching." }, "required": false, "description": "`prefix` for as-you-type prefix matching (default), `exact` for full-token matching.", "name": "search_type", "in": "query" }, { "schema": { "type": "string", "enum": [ "active", "paused", "failed" ], "description": "Filter monitors by lifecycle status." }, "required": false, "description": "Filter monitors by lifecycle status.", "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "page", "sitemap", "extract" ], "description": "Filter by target type." }, "required": false, "description": "Filter by target type.", "name": "target_type", "in": "query" }, { "schema": { "type": "string", "enum": [ "exact", "semantic" ], "description": "Filter by change detection type." }, "required": false, "description": "Filter by change detection type.", "name": "change_detection_type", "in": "query" }, { "schema": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "maxItems": 20, "description": "Comma-separated list of tags to filter by (matches monitors having any of them).", "example": "pricing,competitor" }, "required": false, "description": "Comma-separated list of tags to filter by (matches monitors having any of them).", "name": "tags", "in": "query" }, { "schema": { "type": "string", "description": "Filter to items that have this tag.", "example": "pricing" }, "required": false, "description": "Filter to items that have this tag.", "name": "tag", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1-100). Defaults to 25." }, "required": false, "description": "Maximum number of items to return per page (1-100). Defaults to 25.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque pagination cursor from a previous response." }, "required": false, "description": "Opaque pagination cursor from a previous response.", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "A paginated list of monitors", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsListMonitorsResponse" } } } }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" } } } }, "/monitors/{monitor_id}": { "get": { "summary": "Get a monitor", "operationId": "getMonitor", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "parameters": [ { "schema": { "type": "string", "example": "mon_123" }, "required": true, "name": "monitor_id", "in": "path" } ], "responses": { "200": { "description": "Monitor", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsMonitor" } } } }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "404": { "$ref": "#/components/responses/MonitorsNotFound" } } }, "patch": { "summary": "Update a monitor", "description": "Updates a monitor. If `target` or `change_detection` changes, the monitor creates a new baseline. Unsupported target/change detection combinations are rejected.", "operationId": "updateMonitor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsUpdateMonitorRequest" }, "example": { "name": "Acme pricing monitor", "status": "active", "schedule": { "type": "interval", "frequency": 1, "unit": "hours" }, "webhook": { "url": "https://example.com/webhook" } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "parameters": [ { "schema": { "type": "string", "example": "mon_123" }, "required": true, "name": "monitor_id", "in": "path" } ], "responses": { "200": { "description": "Updated monitor", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsMonitor" } } } }, "400": { "$ref": "#/components/responses/MonitorsBadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "404": { "$ref": "#/components/responses/MonitorsNotFound" } } }, "delete": { "summary": "Delete a monitor", "operationId": "deleteMonitor", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "parameters": [ { "schema": { "type": "string", "example": "mon_123" }, "required": true, "name": "monitor_id", "in": "path" } ], "responses": { "200": { "description": "Monitor deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsDeleteMonitorResponse" } } } }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "404": { "$ref": "#/components/responses/MonitorsNotFound" } } } }, "/monitors/{monitor_id}/runs": { "get": { "summary": "List monitor runs", "operationId": "listMonitorRuns", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "parameters": [ { "schema": { "type": "string", "example": "mon_123" }, "required": true, "name": "monitor_id", "in": "path" }, { "schema": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "skipped" ], "description": "Filter runs by lifecycle status." }, "required": false, "description": "Filter runs by lifecycle status.", "name": "status", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1-100). Defaults to 25." }, "required": false, "description": "Maximum number of items to return per page (1-100). Defaults to 25.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque pagination cursor from a previous response." }, "required": false, "description": "Opaque pagination cursor from a previous response.", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "A paginated list of runs for the monitor", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsListRunsResponse" } } } }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "404": { "$ref": "#/components/responses/MonitorsNotFound" } } } }, "/monitors/{monitor_id}/runs/{run_id}": { "get": { "summary": "Retrieve a monitor run", "description": "Fetches one run for a monitor, including lifecycle status, timing, credits charged, and any detected change.", "operationId": "getMonitorRun", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "x-mint": { "content": "0 Credits" }, "parameters": [ { "schema": { "type": "string", "example": "mon_123" }, "required": true, "name": "monitor_id", "in": "path" }, { "schema": { "type": "string", "example": "run_123" }, "required": true, "name": "run_id", "in": "path" } ], "responses": { "200": { "description": "The requested monitor run", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsRun" } } } }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "404": { "$ref": "#/components/responses/MonitorsNotFound" } } } }, "/monitors/{monitor_id}/changes": { "get": { "summary": "List changes for a monitor", "operationId": "listMonitorChanges", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "parameters": [ { "schema": { "type": "string", "example": "mon_123" }, "required": true, "name": "monitor_id", "in": "path" }, { "schema": { "type": "string", "description": "Filter to items that have this tag.", "example": "pricing" }, "required": false, "description": "Filter to items that have this tag.", "name": "tag", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Only include items at or after this ISO 8601 timestamp.", "example": "2026-06-01T00:00:00Z" }, "required": false, "description": "Only include items at or after this ISO 8601 timestamp.", "name": "since", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Only include items before this ISO 8601 timestamp.", "example": "2026-06-28T00:00:00Z" }, "required": false, "description": "Only include items before this ISO 8601 timestamp.", "name": "until", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1-100). Defaults to 25." }, "required": false, "description": "Maximum number of items to return per page (1-100). Defaults to 25.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque pagination cursor from a previous response." }, "required": false, "description": "Opaque pagination cursor from a previous response.", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "A paginated list of changes for the monitor", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsListChangesResponse" } } } }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "404": { "$ref": "#/components/responses/MonitorsNotFound" } } } }, "/monitors/runs": { "get": { "summary": "List runs", "description": "Returns an account-wide feed of monitor runs across all monitors.", "operationId": "listAccountRuns", "tags": [ "Monitors" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "skipped" ], "description": "Filter runs by lifecycle status." }, "required": false, "description": "Filter runs by lifecycle status.", "name": "status", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1-100). Defaults to 25." }, "required": false, "description": "Maximum number of items to return per page (1-100). Defaults to 25.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque pagination cursor from a previous response." }, "required": false, "description": "Opaque pagination cursor from a previous response.", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "A paginated list of runs", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsListRunsResponse" } } } }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" } } } }, "/monitors/credit-usage": { "get": { "summary": "Monitor credit usage", "description": "Returns credits charged per monitor over an optional [since, until] window, newest spenders first.", "operationId": "listMonitorCreditUsage", "tags": [ "Monitors" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "date-time", "description": "Only include items at or after this ISO 8601 timestamp.", "example": "2026-06-01T00:00:00Z" }, "required": false, "description": "Only include items at or after this ISO 8601 timestamp.", "name": "since", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Only include items before this ISO 8601 timestamp.", "example": "2026-06-28T00:00:00Z" }, "required": false, "description": "Only include items before this ISO 8601 timestamp.", "name": "until", "in": "query" } ], "responses": { "200": { "description": "Per-monitor credit usage", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsCreditUsageResponse" } } } }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" } } } }, "/monitors/limits": { "get": { "summary": "Monitor limits", "description": "Returns how many monitors the account has and the maximum it allows.", "operationId": "getMonitorLimits", "tags": [ "Monitors" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Monitor usage and plan limit", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsLimitsResponse" } } } }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" } } } }, "/monitors/changes": { "get": { "summary": "List changes", "description": "Returns an account-wide feed of detected changes across monitors.", "operationId": "listChanges", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "parameters": [ { "schema": { "type": "string", "description": "Filter changes to a single monitor.", "example": "mon_123" }, "required": false, "description": "Filter changes to a single monitor.", "name": "monitor_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "page", "sitemap", "extract" ], "description": "Filter by target type." }, "required": false, "description": "Filter by target type.", "name": "target_type", "in": "query" }, { "schema": { "type": "string", "enum": [ "exact", "semantic" ], "description": "Filter by change detection type." }, "required": false, "description": "Filter by change detection type.", "name": "change_detection_type", "in": "query" }, { "schema": { "type": "string", "description": "Filter to items that have this tag.", "example": "pricing" }, "required": false, "description": "Filter to items that have this tag.", "name": "tag", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Only include items at or after this ISO 8601 timestamp.", "example": "2026-06-01T00:00:00Z" }, "required": false, "description": "Only include items at or after this ISO 8601 timestamp.", "name": "since", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Only include items before this ISO 8601 timestamp.", "example": "2026-06-28T00:00:00Z" }, "required": false, "description": "Only include items before this ISO 8601 timestamp.", "name": "until", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per page (1-100). Defaults to 25." }, "required": false, "description": "Maximum number of items to return per page (1-100). Defaults to 25.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque pagination cursor from a previous response." }, "required": false, "description": "Opaque pagination cursor from a previous response.", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "A paginated list of changes", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsListChangesResponse" } } } }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" } } } }, "/monitors/changes/{change_id}": { "get": { "summary": "Get a change", "operationId": "getChange", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "parameters": [ { "schema": { "type": "string", "example": "chg_123" }, "required": true, "name": "change_id", "in": "path" } ], "responses": { "200": { "description": "Change details", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsChange" } } } }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "404": { "$ref": "#/components/responses/MonitorsNotFound" } } } }, "/monitors/{monitor_id}/run": { "post": { "summary": "Run a monitor now", "description": "Triggers an immediate run of the monitor outside its normal schedule. The run is queued and processed asynchronously.", "operationId": "runMonitorNow", "tags": [ "Monitors" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "mon_123" }, "required": true, "name": "monitor_id", "in": "path" } ], "responses": { "202": { "description": "Run queued", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsRunNowResponse" } } } }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "404": { "$ref": "#/components/responses/MonitorsNotFound" } } } }, "/monitors/{monitor_id}/webhook/rotate-secret": { "post": { "summary": "Rotate a monitor webhook secret", "description": "Generates a new signing secret for the monitor's webhook and returns the updated monitor (including the new `webhook.secret`). The previous secret stops signing deliveries immediately, so update your endpoint before rotating.", "operationId": "rotateMonitorWebhookSecret", "tags": [ "Monitors" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "mon_123" }, "required": true, "name": "monitor_id", "in": "path" } ], "responses": { "200": { "description": "Monitor with the rotated webhook secret", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsMonitor" } } } }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "404": { "$ref": "#/components/responses/MonitorsNotFound" }, "409": { "$ref": "#/components/responses/MonitorsBadRequest" } } } }, "/batch/submit": { "post": { "summary": "Submit a batch", "description": "Scrape 25K URLs or crawl large websites asynchronously. ", "operationId": "submitBatch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchSubmitRequest" }, "examples": { "scrapeMarkdown": { "summary": "Scrape URLs as Markdown", "value": { "input": { "type": "scrape", "data": { "type": "markdown", "urls": [ { "url": "https://example.com/products/anvil", "itemId": "sku-1", "meta": { "category": "tools" } }, { "url": "https://example.com/products/hammer", "itemId": "sku-2" } ], "options": { "useMainContentOnly": true } } } } }, "scrapeHtml": { "summary": "Scrape URLs as HTML", "value": { "input": { "type": "scrape", "data": { "type": "html", "urls": [ { "url": "https://example.com/about" }, { "url": "https://example.com/pricing" } ] } } } }, "crawlStartUrlMarkdown": { "summary": "Crawl from a URL as Markdown", "value": { "input": { "type": "crawl", "data": { "type": "markdown", "source": { "type": "start_url", "url": "https://example.com/docs", "controls": { "maxUrls": 500, "maxDepth": 3, "followSubdomains": false, "regex": "^https://example\\.com/docs/" } }, "options": { "includeLinks": true } } } } }, "crawlStartUrlHtml": { "summary": "Crawl from a URL as HTML", "value": { "input": { "type": "crawl", "data": { "type": "html", "source": { "type": "start_url", "url": "https://example.com/blog", "controls": { "maxUrls": 100 } } } } } }, "crawlSitemapMarkdown": { "summary": "Crawl a sitemap as Markdown", "value": { "input": { "type": "crawl", "data": { "type": "markdown", "source": { "type": "sitemap", "domain": "example.com", "controls": { "maxUrls": 500, "regex": "^https://example\\.com/docs/" } } } } } }, "crawlSitemapHtml": { "summary": "Crawl a sitemap as HTML", "value": { "input": { "type": "crawl", "data": { "type": "html", "source": { "type": "sitemap", "domain": "example.com", "controls": { "maxUrls": 500, "maxDepth": 0 } } } } } } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "Batch" ], "parameters": [ { "schema": { "type": "string", "maxLength": 200, "description": "Any string unique to this submission. Retries with the same key return the original batch." }, "required": false, "description": "Any string unique to this submission. Retries with the same key return the original batch.", "name": "Idempotency-Key", "in": "header" } ], "responses": { "202": { "description": "Batch accepted. Read progress and results from `GET /batch/{batch_id}`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BatchAccepted" }, { "type": "object", "properties": { "key_metadata": { "$ref": "#/components/schemas/KeyMetadata", "description": "API key usage for this request." }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Concurrent batch limit reached (error_code BATCH_LIMIT_EXCEEDED).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency-Key reused with a different body (error_code IDEMPOTENCY_KEY_CONFLICT).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Batch input could not be staged or queued.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/batch/list": { "get": { "summary": "List batches", "description": "List your batches from newest to oldest. Filter by status or continue with a cursor.", "operationId": "listBatches", "security": [ { "bearerAuth": [] } ], "tags": [ "Batch" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Batches per page. Defaults to 25." }, "required": false, "description": "Batches per page. Defaults to 25.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Cursor from the previous page." }, "required": false, "description": "Cursor from the previous page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "queued", "running", "cancelling", "completed", "cancelled", "failed" ], "description": "Filter by status." }, "required": false, "description": "Filter by status.", "name": "status", "in": "query" }, { "schema": { "type": "string", "maxLength": 200, "description": "Free-text search term, matched against the batch id, crawl source (start URL or sitemap domain), and tags.", "example": "batch_1a2b" }, "required": false, "description": "Free-text search term, matched against the batch id, crawl source (start URL or sitemap domain), and tags.", "name": "q", "in": "query" }, { "schema": { "type": "string", "enum": [ "exact", "prefix" ], "description": "`prefix` for as-you-type prefix matching (default), `exact` for full-token matching." }, "required": false, "description": "`prefix` for as-you-type prefix matching (default), `exact` for full-token matching.", "name": "search_type", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated list of tags to filter by (matches batches having any of them).", "example": "docs,competitor" }, "required": false, "description": "Comma-separated list of tags to filter by (matches batches having any of them).", "name": "tags", "in": "query" } ], "responses": { "200": { "description": "Your batches, newest first. Use `next_cursor` to page through the rest.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Batch" }, "description": "Batches on this page." }, "has_more": { "type": "boolean", "description": "Whether another page is available." }, "next_cursor": { "type": "string", "nullable": true, "description": "Cursor for the next page." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/batch/{batch_id}": { "get": { "summary": "Get a batch", "description": "Check progress, and get download links once the batch finishes.", "operationId": "getBatch", "security": [ { "bearerAuth": [] } ], "tags": [ "Batch" ], "parameters": [ { "schema": { "type": "string", "example": "batch_9f2c8a", "description": "ID of the batch to retrieve or cancel." }, "required": true, "description": "ID of the batch to retrieve or cancel.", "name": "batch_id", "in": "path" } ], "responses": { "200": { "description": "Current state of the batch, with download links once it has finished.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Batch" }, { "type": "object", "properties": { "key_metadata": { "$ref": "#/components/schemas/KeyMetadata", "description": "API key usage for this request." }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] }, { "$ref": "#/components/schemas/BatchDetail" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete a batch", "description": "Permanently delete a finished batch and its stored results. Active batches must settle first.", "operationId": "deleteBatch", "security": [ { "bearerAuth": [] } ], "tags": [ "Batch" ], "parameters": [ { "schema": { "type": "string", "example": "batch_9f2c8a", "description": "ID of the batch to retrieve or cancel." }, "required": true, "description": "ID of the batch to retrieve or cancel.", "name": "batch_id", "in": "path" } ], "responses": { "200": { "description": "Batch and its stored results are permanently deleted.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the deleted batch." }, "deleted": { "type": "boolean", "description": "Always true on success." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Batch is still active. Cancel it and let it settle before deleting.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/batch/{batch_id}/results": { "get": { "summary": "Get batch results", "description": "Page through a finished batch's results as JSON instead of downloading the NDJSON files.", "operationId": "getBatchResults", "security": [ { "bearerAuth": [] } ], "tags": [ "Batch" ], "parameters": [ { "schema": { "type": "string", "example": "batch_9f2c8a", "description": "ID of the batch to retrieve or cancel." }, "required": true, "description": "ID of the batch to retrieve or cancel.", "name": "batch_id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Records per page. Defaults to 25. A page can close early so its payload stays under ~8 MB; rely on next_cursor rather than counting records." }, "required": false, "description": "Records per page. Defaults to 25. A page can close early so its payload stays under ~8 MB; rely on next_cursor rather than counting records.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "next_cursor from the previous page." }, "required": false, "description": "next_cursor from the previous page.", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "One page of result records. Keep paging with `next_cursor` while `has_more` is true.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BatchResultRecord" }, "description": "Result records on this page." }, "has_more": { "type": "boolean", "description": "Whether another page is available." }, "next_cursor": { "type": "string", "nullable": true, "description": "Cursor for the next page." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Batch has not finished yet (error_code BATCH_NOT_COMPLETED).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/batch/{batch_id}/cancel": { "post": { "summary": "Cancel a batch", "description": "Stop a batch from starting new pages. In-progress pages finish, and unused credits are refunded.", "operationId": "cancelBatch", "security": [ { "bearerAuth": [] } ], "tags": [ "Batch" ], "parameters": [ { "schema": { "type": "string", "example": "batch_9f2c8a", "description": "ID of the batch to retrieve or cancel." }, "required": true, "description": "ID of the batch to retrieve or cancel.", "name": "batch_id", "in": "path" } ], "responses": { "202": { "description": "Cancellation started. Poll `GET /batch/{batch_id}` until the batch settles.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BatchCancelling" }, { "type": "object", "properties": { "key_metadata": { "$ref": "#/components/schemas/KeyMetadata", "description": "API key usage for this request." }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Batch already reached a terminal state, so there is nothing to cancel.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "webhooks": { "monitorChangeDetected": { "post": { "summary": "Monitor change detected", "description": "Sent when a monitor detects a change. Return any 2xx response to acknowledge delivery.", "operationId": "monitorChangeDetected", "tags": [ "Monitors" ], "security": [], "parameters": [ { "name": "User-Agent", "in": "header", "required": true, "description": "Identifies the Context.dev webhook sender.", "schema": { "type": "string", "example": "Context.dev-Webhooks/1.0" } }, { "name": "X-Context-Event", "in": "header", "required": true, "description": "Event type for this delivery.", "schema": { "type": "string", "enum": [ "change.detected" ] } }, { "name": "X-Context-Id", "in": "header", "required": true, "description": "Unique event ID. Matches the top-level `id` field in the request body.", "schema": { "type": "string", "example": "evt_123" } }, { "name": "X-Context-Delivery-Id", "in": "header", "description": "Delivery ID for status checks and retries.", "schema": { "type": "string", "example": "whd_0123456789abcdef0123456789abcdef" } }, { "name": "X-Context-Attempt", "in": "header", "description": "Attempt number, starting at 1.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "X-Context-Signature", "in": "header", "description": "HMAC signature in the form `t=,v1=`. The HMAC is SHA-256 over `\"{t}.{rawRequestBody}\"`, keyed with the monitor webhook secret. Verify the unmodified request body with a constant-time comparison and reject stale timestamps.", "schema": { "type": "string", "example": "t=1783620012,v1=087d98aada1e39f9d24d65951f51e672da12b2f9ea1c02c7c8c5ef254f5d4068" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsChangeDetectedWebhookPayload" } } } }, "responses": { "2XX": { "description": "Webhook accepted." } } } }, "monitorRunCompleted": { "post": { "summary": "Monitor run completed", "description": "Sent after each completed monitor run, including runs with no changes. Return any 2xx response to acknowledge delivery.", "operationId": "monitorRunCompleted", "tags": [ "Monitors" ], "security": [], "parameters": [ { "name": "User-Agent", "in": "header", "required": true, "description": "Identifies the Context.dev webhook sender.", "schema": { "type": "string", "example": "Context.dev-Webhooks/1.0" } }, { "name": "X-Context-Event", "in": "header", "required": true, "description": "Event type for this delivery.", "schema": { "type": "string", "enum": [ "run.completed" ] } }, { "name": "X-Context-Id", "in": "header", "required": true, "description": "Unique event ID. Matches the top-level `id` field in the request body.", "schema": { "type": "string", "example": "evt_123" } }, { "name": "X-Context-Delivery-Id", "in": "header", "description": "Delivery ID for status checks and retries.", "schema": { "type": "string", "example": "whd_0123456789abcdef0123456789abcdef" } }, { "name": "X-Context-Attempt", "in": "header", "description": "Attempt number, starting at 1.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "X-Context-Signature", "in": "header", "description": "HMAC signature in the form `t=,v1=`. The HMAC is SHA-256 over `\"{t}.{rawRequestBody}\"`, keyed with the monitor webhook secret. Verify the unmodified request body with a constant-time comparison and reject stale timestamps.", "schema": { "type": "string", "example": "t=1783620012,v1=087d98aada1e39f9d24d65951f51e672da12b2f9ea1c02c7c8c5ef254f5d4068" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsRunCompletedWebhookPayload" } } } }, "responses": { "2XX": { "description": "Webhook accepted." } } } }, "batchCompleted": { "post": { "summary": "Batch completed", "description": "Sent when a batch completes. Return any 2xx response to acknowledge delivery.", "operationId": "batchCompleted", "tags": [ "Batches" ], "security": [], "parameters": [ { "name": "User-Agent", "in": "header", "required": true, "description": "Identifies the Context.dev webhook sender.", "schema": { "type": "string", "example": "Context.dev-Webhooks/1.0" } }, { "name": "X-Context-Event", "in": "header", "required": true, "description": "Which final status the batch reached. Matches the `event` field in the request body.", "schema": { "type": "string", "enum": [ "batch.completed" ] } }, { "name": "X-Context-Id", "in": "header", "required": true, "description": "Unique event ID. Matches the top-level `id` field in the request body.", "schema": { "type": "string", "example": "evt_123" } }, { "name": "X-Context-Delivery-Id", "in": "header", "description": "Delivery ID for status checks and retries.", "schema": { "type": "string", "example": "whd_0123456789abcdef0123456789abcdef" } }, { "name": "X-Context-Attempt", "in": "header", "description": "Attempt number, starting at 1.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "X-Context-Signature", "in": "header", "description": "HMAC signature in the form `t=,v1=`. The HMAC is SHA-256 over `\"{t}.{rawRequestBody}\"`, keyed with the `webhook_secret` from the submit response. Sent when a webhook was configured through either `webhook` or `webhookUrl`. Verify the unmodified request body with a constant-time comparison and reject stale timestamps.", "schema": { "type": "string", "example": "t=1783620012,v1=087d98aada1e39f9d24d65951f51e672da12b2f9ea1c02c7c8c5ef254f5d4068" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCompletedWebhookPayload" } } } }, "responses": { "2XX": { "description": "Webhook accepted." } } } }, "batchFailed": { "post": { "summary": "Batch failed", "description": "Sent when a batch fails. Return any 2xx response to acknowledge delivery.", "operationId": "batchFailed", "tags": [ "Batches" ], "security": [], "parameters": [ { "name": "User-Agent", "in": "header", "required": true, "description": "Identifies the Context.dev webhook sender.", "schema": { "type": "string", "example": "Context.dev-Webhooks/1.0" } }, { "name": "X-Context-Event", "in": "header", "required": true, "description": "Which final status the batch reached. Matches the `event` field in the request body.", "schema": { "type": "string", "enum": [ "batch.failed" ] } }, { "name": "X-Context-Id", "in": "header", "required": true, "description": "Unique event ID. Matches the top-level `id` field in the request body.", "schema": { "type": "string", "example": "evt_123" } }, { "name": "X-Context-Delivery-Id", "in": "header", "description": "Delivery ID for status checks and retries.", "schema": { "type": "string", "example": "whd_0123456789abcdef0123456789abcdef" } }, { "name": "X-Context-Attempt", "in": "header", "description": "Attempt number, starting at 1.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "X-Context-Signature", "in": "header", "description": "HMAC signature in the form `t=,v1=`. The HMAC is SHA-256 over `\"{t}.{rawRequestBody}\"`, keyed with the `webhook_secret` from the submit response. Sent when a webhook was configured through either `webhook` or `webhookUrl`. Verify the unmodified request body with a constant-time comparison and reject stale timestamps.", "schema": { "type": "string", "example": "t=1783620012,v1=087d98aada1e39f9d24d65951f51e672da12b2f9ea1c02c7c8c5ef254f5d4068" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchFailedWebhookPayload" } } } }, "responses": { "2XX": { "description": "Webhook accepted." } } } }, "batchCancelled": { "post": { "summary": "Batch cancelled", "description": "Sent when a batch is cancelled. Return any 2xx response to acknowledge delivery.", "operationId": "batchCancelled", "tags": [ "Batches" ], "security": [], "parameters": [ { "name": "User-Agent", "in": "header", "required": true, "description": "Identifies the Context.dev webhook sender.", "schema": { "type": "string", "example": "Context.dev-Webhooks/1.0" } }, { "name": "X-Context-Event", "in": "header", "required": true, "description": "Which final status the batch reached. Matches the `event` field in the request body.", "schema": { "type": "string", "enum": [ "batch.cancelled" ] } }, { "name": "X-Context-Id", "in": "header", "required": true, "description": "Unique event ID. Matches the top-level `id` field in the request body.", "schema": { "type": "string", "example": "evt_123" } }, { "name": "X-Context-Delivery-Id", "in": "header", "description": "Delivery ID for status checks and retries.", "schema": { "type": "string", "example": "whd_0123456789abcdef0123456789abcdef" } }, { "name": "X-Context-Attempt", "in": "header", "description": "Attempt number, starting at 1.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "X-Context-Signature", "in": "header", "description": "HMAC signature in the form `t=,v1=`. The HMAC is SHA-256 over `\"{t}.{rawRequestBody}\"`, keyed with the `webhook_secret` from the submit response. Sent when a webhook was configured through either `webhook` or `webhookUrl`. Verify the unmodified request body with a constant-time comparison and reject stale timestamps.", "schema": { "type": "string", "example": "t=1783620012,v1=087d98aada1e39f9d24d65951f51e672da12b2f9ea1c02c7c8c5ef254f5d4068" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCancelledWebhookPayload" } } } }, "responses": { "2XX": { "description": "Webhook accepted." } } } } }, "components": { "parameters": { "RequestTags": { "name": "tags", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "$ref": "#/components/schemas/RequestTags" }, "description": "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.", "example": "production,team-alpha" } }, "headers": { "RequestId": { "description": "Unique id of this API call, sent on every response and mirrored as request_id in JSON bodies. Quote it when contacting support.", "schema": { "type": "string", "format": "uuid" } }, "RateLimitLimit": { "description": "Maximum requests per minute.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimitRemaining": { "description": "Requests remaining in the current minute.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimitReset": { "description": "Unix timestamp in seconds when the rate limit resets.", "schema": { "type": "integer" } } }, "responses": { "RateLimited": { "description": "Rate limit exceeded", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "description": "Seconds until the per-minute rate limit window resets", "schema": { "type": "integer", "minimum": 1, "maximum": 60 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "RATE_LIMITED" ], "description": "Error code indicating the rate limit was exceeded" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id", "message", "error_code" ] } } } }, "MonitorsBadRequest": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "MonitorsUnauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "MonitorsNotFound": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "MonitorsLimitExceeded": { "description": "Monitor limit for the account reached (error_code MONITOR_LIMIT_EXCEEDED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "BadRequest": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "NotFound": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer authentication header of the form `Bearer `, where `` is your api key." } }, "schemas": { "RequestTags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "maxItems": 20, "description": "Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.", "example": [ "production", "team-alpha" ] }, "BrowserCountryCode": { "type": "string", "enum": [ "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "ar", "at", "au", "aw", "az", "ba", "bb", "bd", "be", "bf", "bg", "bh", "bi", "bj", "bm", "bn", "bo", "bq", "br", "bs", "bw", "by", "bz", "ca", "cd", "cf", "cg", "ch", "ci", "cl", "cm", "cn", "co", "cr", "cv", "cw", "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec", "ee", "eg", "es", "et", "fi", "fj", "fr", "ga", "gb", "gd", "ge", "gf", "gg", "gh", "gm", "gn", "gp", "gq", "gr", "gt", "gu", "gw", "gy", "hk", "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in", "iq", "ir", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh", "kn", "kr", "kw", "ky", "kz", "la", "lb", "lc", "lk", "lr", "ls", "lt", "lu", "lv", "ly", "ma", "mc", "md", "me", "mf", "mg", "mk", "ml", "mm", "mn", "mo", "mq", "mr", "mt", "mu", "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "ng", "ni", "nl", "no", "np", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk", "pl", "pr", "ps", "pt", "py", "qa", "re", "ro", "rs", "ru", "rw", "sa", "sc", "sd", "se", "sg", "si", "sk", "sl", "sm", "sn", "so", "sr", "ss", "st", "sv", "sx", "sy", "sz", "tc", "td", "tg", "th", "tj", "tl", "tm", "tn", "tr", "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz", "vc", "ve", "vg", "vi", "vn", "ye", "yt", "za", "zm", "zw" ], "example": "de", "description": "Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2)." }, "PageMetadataValue": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "PageMetadataAlternate": { "type": "object", "properties": { "href": { "type": "string", "description": "Resolved alternate URL." }, "hreflang": { "type": "string", "description": "Language or locale for the alternate URL, when present." }, "type": { "type": "string", "description": "Alternate resource MIME type, when present." }, "title": { "type": "string", "description": "Alternate resource title, when present." } }, "required": [ "href" ], "additionalProperties": false }, "PageMetadataHeading": { "type": "object", "properties": { "level": { "type": "integer", "minimum": 1, "maximum": 6, "description": "Heading level, 1–6 (from h1–h6)." }, "text": { "type": "string", "description": "Heading text with whitespace collapsed, truncated to 1000 characters." } }, "required": [ "level", "text" ], "additionalProperties": false }, "PageMetadata": { "type": "object", "properties": { "sourceUrl": { "type": "string", "description": "Original URL requested by the caller." }, "finalUrl": { "type": "string", "description": "Final URL scraped after redirects or scraper fallback, when known. Falls back to sourceUrl when unavailable." }, "title": { "type": "string", "description": "Best title extracted from the page." }, "description": { "type": "string", "description": "Best description extracted from standard, Open Graph, or Twitter metadata." }, "language": { "type": "string", "description": "Language extracted from html lang or language meta tags." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords extracted from the page's keywords meta tag." }, "canonicalUrl": { "type": "string", "description": "Resolved canonical URL, when present." }, "author": { "type": "string", "description": "Author metadata, when present." }, "siteName": { "type": "string", "description": "Site or application name from page metadata." }, "image": { "type": "string", "description": "Primary resolved preview image from Open Graph, Twitter, or image metadata." }, "favicon": { "type": "string", "description": "Resolved favicon URL, when present." }, "publishedTime": { "type": "string", "description": "Published timestamp/date from page metadata, when present." }, "modifiedTime": { "type": "string", "description": "Modified timestamp/date from page metadata, when present." }, "robots": { "type": "string", "description": "Robots meta directive, when present." }, "openGraph": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PageMetadataValue" }, "description": "Open Graph metadata with the og: prefix removed and keys camel-cased." }, "twitter": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PageMetadataValue" }, "description": "Twitter card metadata with the twitter: prefix removed and keys camel-cased." }, "alternates": { "type": "array", "items": { "$ref": "#/components/schemas/PageMetadataAlternate" }, "description": "Resolved alternate links from link rel=alternate tags." }, "headings": { "type": "array", "items": { "$ref": "#/components/schemas/PageMetadataHeading" }, "description": "Page headings (h1–h6) in document order, extracted from the unfiltered document. Capped at the first 500 headings. Omitted when the page has none." }, "jsonLd": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "JSON-LD structured data blocks parsed from the page." }, "additionalMeta": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PageMetadataValue" }, "description": "Additional non-social meta tags not promoted to top-level metadata fields." } }, "required": [ "sourceUrl", "finalUrl" ], "description": "Metadata extracted from the scraped page HTML." }, "Industry": { "type": "string", "enum": [ "Aerospace & Defense", "Technology", "Finance", "Healthcare", "Retail & E-commerce", "Entertainment", "Education", "Government & Nonprofit", "Industrial & Energy", "Automotive & Transportation", "Lifestyle & Leisure", "Luxury & Fashion", "News & Media", "Sports", "Real Estate & PropTech", "Legal & Compliance", "Telecommunications", "Agriculture & Food", "Professional Services & Agencies", "Chemicals & Materials", "Logistics & Supply Chain", "Hospitality & Tourism", "Construction & Built Environment", "Consumer Packaged Goods (CPG)" ], "description": "Industry classification enum" }, "Subindustry": { "type": "string", "enum": [ "Defense Systems & Military Hardware", "Aerospace Manufacturing", "Avionics & Navigation Technology", "Subsea & Naval Defense Systems", "Space & Satellite Technology", "Defense IT & Systems Integration", "Software (B2B)", "Software (B2C)", "Cloud Infrastructure & DevOps", "Cybersecurity", "Artificial Intelligence & Machine Learning", "Data Infrastructure & Analytics", "Hardware & Semiconductors", "Fintech Infrastructure", "eCommerce & Marketplace Platforms", "Developer Tools & APIs", "Web3 & Blockchain", "XR & Spatial Computing", "Banking & Lending", "Investment Management & WealthTech", "Insurance & InsurTech", "Payments & Money Movement", "Accounting, Tax & Financial Planning Tools", "Capital Markets & Trading Platforms", "Financial Infrastructure & APIs", "Credit Scoring & Risk Management", "Cryptocurrency & Digital Assets", "BNPL & Alternative Financing", "Healthcare Providers & Services", "Pharmaceuticals & Drug Development", "Medical Devices & Diagnostics", "Biotechnology & Genomics", "Digital Health & Telemedicine", "Health Insurance & Benefits Tech", "Clinical Trials & Research Platforms", "Mental Health & Wellness", "Healthcare IT & EHR Systems", "Consumer Health & Wellness Products", "Online Marketplaces", "Direct-to-Consumer (DTC) Brands", "Retail Tech & Point-of-Sale Systems", "Omnichannel & In-Store Retail", "E-commerce Enablement & Infrastructure", "Subscription & Membership Commerce", "Social Commerce & Influencer Platforms", "Fashion & Apparel Retail", "Food, Beverage & Grocery E-commerce", "Streaming Platforms (Video, Music, Audio)", "Gaming & Interactive Entertainment", "Creator Economy & Influencer Platforms", "Film, TV & Production Studios", "Events, Venues & Live Entertainment", "Virtual Worlds & Metaverse Experiences", "K-12 Education Platforms & Tools", "Higher Education & University Tech", "Online Learning & MOOCs", "Test Prep & Certification", "Corporate Training & Upskilling", "Tutoring & Supplemental Learning", "Education Management Systems (LMS/SIS)", "Language Learning", "Creator-Led & Cohort-Based Courses", "Special Education & Accessibility Tools", "Government Technology & Digital Services", "Civic Engagement & Policy Platforms", "International Development & Humanitarian Aid", "Philanthropy & Grantmaking", "Nonprofit Operations & Fundraising Tools", "Public Health & Social Services", "Education & Youth Development Programs", "Environmental & Climate Action Organizations", "Legal Aid & Social Justice Advocacy", "Municipal & Infrastructure Services", "Manufacturing & Industrial Automation", "Energy Production (Oil, Gas, Nuclear)", "Renewable Energy & Cleantech", "Utilities & Grid Infrastructure", "Industrial IoT & Monitoring Systems", "Construction & Heavy Equipment", "Mining & Natural Resources", "Environmental Engineering & Sustainability", "Energy Storage & Battery Technology", "Automotive OEMs & Vehicle Manufacturing", "Electric Vehicles (EVs) & Charging Infrastructure", "Mobility-as-a-Service (MaaS)", "Fleet Management", "Public Transit & Urban Mobility", "Autonomous Vehicles & ADAS", "Aftermarket Parts & Services", "Telematics & Vehicle Connectivity", "Aviation & Aerospace Transport", "Maritime Shipping", "Fitness & Wellness", "Beauty & Personal Care", "Home & Living", "Dating & Relationships", "Hobbies, Crafts & DIY", "Outdoor & Recreational Gear", "Events, Experiences & Ticketing Platforms", "Designer & Luxury Apparel", "Accessories, Jewelry & Watches", "Footwear & Leather Goods", "Beauty, Fragrance & Skincare", "Fashion Marketplaces & Retail Platforms", "Sustainable & Ethical Fashion", "Resale, Vintage & Circular Fashion", "Fashion Tech & Virtual Try-Ons", "Streetwear & Emerging Luxury", "Couture & Made-to-Measure", "News Publishing & Journalism", "Advertising, Adtech & Media Buying", "Digital Media & Content Platforms", "Broadcasting (TV & Radio)", "Podcasting & Audio Media", "News Aggregators & Curation Tools", "Independent & Creator-Led Media", "Newsletters & Substack-Style Platforms", "Political & Investigative Media", "Trade & Niche Publications", "Media Monitoring & Analytics", "Professional Teams & Leagues", "Sports Media & Broadcasting", "Sports Betting & Fantasy Sports", "Fitness & Athletic Training Platforms", "Sportswear & Equipment", "Esports & Competitive Gaming", "Sports Venues & Event Management", "Athlete Management & Talent Agencies", "Sports Tech & Performance Analytics", "Youth, Amateur & Collegiate Sports", "Real Estate Marketplaces", "Property Management Software", "Rental Platforms", "Mortgage & Lending Tech", "Real Estate Investment Platforms", "Law Firms & Legal Services", "Legal Tech & Automation", "Regulatory Compliance", "E-Discovery & Litigation Tools", "Contract Management", "Governance, Risk & Compliance (GRC)", "IP & Trademark Management", "Legal Research & Intelligence", "Compliance Training & Certification", "Whistleblower & Ethics Reporting", "Mobile & Wireless Networks (3G/4G/5G)", "Broadband & Fiber Internet", "Satellite & Space-Based Communications", "Network Equipment & Infrastructure", "Telecom Billing & OSS/BSS Systems", "VoIP & Unified Communications", "Internet Service Providers (ISPs)", "Edge Computing & Network Virtualization", "IoT Connectivity Platforms", "Precision Agriculture & AgTech", "Crop & Livestock Production", "Food & Beverage Manufacturing & Processing", "Food Distribution", "Restaurants & Food Service", "Agricultural Inputs & Equipment", "Sustainable & Regenerative Agriculture", "Seafood & Aquaculture", "Management Consulting", "Marketing & Advertising Agencies", "Design, Branding & Creative Studios", "IT Services & Managed Services", "Staffing, Recruiting & Talent", "Accounting & Tax Firms", "Public Relations & Communications", "Business Process Outsourcing (BPO)", "Professional Training & Coaching", "Specialty Chemicals", "Commodity & Petrochemicals", "Polymers, Plastics & Rubber", "Coatings, Adhesives & Sealants", "Industrial Gases", "Advanced Materials & Composites", "Battery Materials & Energy Storage", "Electronic Materials & Semiconductor Chemicals", "Agrochemicals & Fertilizers", "Freight & Transportation Tech", "Last-Mile Delivery", "Warehouse Automation", "Supply Chain Visibility Platforms", "Logistics Marketplaces", "Shipping & Freight Forwarding", "Cold Chain Logistics", "Reverse Logistics & Returns", "Cross-Border Trade Tech", "Transportation Management Systems (TMS)", "Hotels & Accommodation", "Vacation Rentals & Short-Term Stays", "Restaurant Tech & Management", "Travel Booking Platforms", "Tourism Experiences & Activities", "Cruise Lines & Marine Tourism", "Hospitality Management Systems", "Event & Venue Management", "Corporate Travel Management", "Travel Insurance & Protection", "Construction Management Software", "BIM/CAD & Design Tools", "Construction Marketplaces", "Equipment Rental & Management", "Building Materials & Procurement", "Construction Workforce Management", "Project Estimation & Bidding", "Modular & Prefab Construction", "Construction Safety & Compliance", "Smart Building Technology", "Food & Beverage CPG", "Home & Personal Care CPG", "CPG Analytics & Insights", "Direct-to-Consumer CPG Brands", "CPG Supply Chain & Distribution", "Private Label Manufacturing", "CPG Retail Intelligence", "Sustainable CPG & Packaging", "Beauty & Cosmetics CPG", "Health & Wellness CPG" ], "description": "Subindustry classification enum" }, "SupportedLanguage": { "type": "string", "enum": [ "afrikaans", "albanian", "amharic", "arabic", "armenian", "assamese", "aymara", "azeri", "basque", "belarusian", "bengali", "bosnian", "bulgarian", "burmese", "cantonese", "catalan", "cebuano", "chinese", "corsican", "croatian", "czech", "danish", "dutch", "english", "esperanto", "estonian", "farsi", "fijian", "finnish", "french", "galician", "georgian", "german", "greek", "guarani", "gujarati", "haitian-creole", "hausa", "hawaiian", "hebrew", "hindi", "hmong", "hungarian", "icelandic", "igbo", "indonesian", "irish", "italian", "japanese", "javanese", "kannada", "kazakh", "khmer", "kinyarwanda", "korean", "kurdish", "kyrgyz", "lao", "latin", "latvian", "lingala", "lithuanian", "luxembourgish", "macedonian", "malagasy", "malay", "malayalam", "maltese", "maori", "marathi", "mongolian", "nepali", "norwegian", "odia", "oromo", "pashto", "pidgin", "polish", "portuguese", "punjabi", "quechua", "romanian", "russian", "samoan", "scottish-gaelic", "serbian", "sesotho", "shona", "sindhi", "sinhala", "slovak", "slovene", "somali", "spanish", "sundanese", "swahili", "swedish", "tagalog", "tajik", "tamil", "tatar", "telugu", "thai", "tibetan", "tigrinya", "tongan", "tswana", "turkish", "turkmen", "ukrainian", "urdu", "uyghur", "uzbek", "vietnamese", "welsh", "wolof", "xhosa", "yiddish", "yoruba", "zulu" ], "description": "Language to force for the retrieved brand data." }, "RequestId": { "type": "string", "format": "uuid", "description": "Unique id of this API call, also sent in the X-Request-Id response header. Quote it when contacting support about a failed request.", "example": "3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91" }, "KeyMetadata": { "type": "object", "properties": { "credits_consumed": { "type": "integer", "description": "Credits used by this request." }, "credits_remaining": { "type": "integer", "description": "Credits remaining for your organization." } }, "required": [ "credits_consumed", "credits_remaining" ], "description": "Credit usage, included whenever a valid API key is provided." }, "CacheMetadata": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "hit", "miss", "zdr" ], "description": "Whether the response was served from cache, required fresh work, or honored zero-data-retention cache bypass." }, "age_ms": { "type": "integer", "minimum": 0, "description": "Age of the cached data in milliseconds. Zero for miss and zdr responses." } }, "required": [ "status", "age_ms" ], "additionalProperties": false, "description": "Cache outcome for this response. Composite responses are hits only when every cache-controlled fetch contributing to the output was a hit; age_ms is the oldest contributing hit." }, "BrandResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the response, e.g., 'ok'" }, "brand": { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain name of the brand" }, "title": { "type": "string", "description": "The title or name of the brand" }, "description": { "type": "string", "description": "A brief description of the brand" }, "slogan": { "type": "string", "description": "The brand's slogan" }, "colors": { "type": "array", "items": { "type": "object", "properties": { "hex": { "type": "string", "description": "Color in hexadecimal format" }, "name": { "type": "string", "description": "Name of the color" }, "source": { "type": "string", "enum": [ "site", "logo" ], "description": "Where the color was observed: 'site' colors come from the website's own theme signals (rendered page colors, manifest, theme-color meta), 'logo' colors from logo image pixels." } } }, "description": "An array of brand colors" }, "logos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "CDN hosted url of the logo (ready for display)" }, "mode": { "type": "string", "enum": [ "light", "dark", "has_opaque_background" ], "description": "Indicates when this logo is best used: 'light' = best for light mode, 'dark' = best for dark mode, 'has_opaque_background' = can be used for either as image has its own background" }, "colors": { "type": "array", "items": { "type": "object", "properties": { "hex": { "type": "string", "description": "Color in hexadecimal format" }, "name": { "type": "string", "description": "Name of the color" } } }, "description": "Array of colors in the logo" }, "resolution": { "type": "object", "properties": { "width": { "type": "integer", "description": "Width of the image in pixels" }, "height": { "type": "integer", "description": "Height of the image in pixels" }, "aspect_ratio": { "type": "number", "description": "Aspect ratio of the image (width/height)" } }, "description": "Resolution of the logo image" }, "type": { "type": "string", "enum": [ "icon", "logo" ], "description": "Type of the logo based on resolution (e.g., 'icon', 'logo')" } } }, "description": "An array of logos associated with the brand. When a similarly shaped SVG variant exists, it is returned ahead of its raster equivalent; otherwise relevance order is preserved" }, "backdrops": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the backdrop image" }, "colors": { "type": "array", "items": { "type": "object", "properties": { "hex": { "type": "string", "description": "Color in hexadecimal format" }, "name": { "type": "string", "description": "Name of the color" } } }, "description": "Array of colors in the backdrop image" }, "resolution": { "type": "object", "properties": { "width": { "type": "integer", "description": "Width of the image in pixels" }, "height": { "type": "integer", "description": "Height of the image in pixels" }, "aspect_ratio": { "type": "number", "description": "Aspect ratio of the image (width/height)" } }, "description": "Resolution of the backdrop image" } } }, "description": "An array of backdrop images for the brand" }, "socials": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "x", "facebook", "instagram", "linkedin", "youtube", "pinterest", "tiktok", "dribbble", "github", "behance", "snapchat", "whatsapp", "telegram", "line", "discord", "twitch", "vimeo", "imdb", "tumblr", "flickr", "giphy", "medium", "spotify", "soundcloud", "tripadvisor", "yelp", "producthunt", "reddit", "crunchbase", "appstore", "playstore" ], "description": "Type of social media platform" }, "url": { "type": "string", "description": "URL of the social media page" } } }, "description": "An array of social media links for the brand" }, "address": { "type": "object", "properties": { "street": { "type": "string", "description": "Street address" }, "city": { "type": "string", "description": "City name" }, "country": { "type": "string", "description": "Country name" }, "country_code": { "type": "string", "description": "Country code" }, "state_province": { "type": "string", "description": "State or province name" }, "state_code": { "type": "string", "description": "State or province code" }, "postal_code": { "type": "string", "description": "Postal or ZIP code" } }, "description": "Physical address of the brand" }, "stock": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Stock ticker symbol" }, "exchange": { "type": "string", "description": "Stock exchange name" } }, "description": "Stock market information for this brand (will be null if not a publicly traded company)" }, "employees": { "type": "object", "properties": { "range": { "type": "string", "enum": [ "1 to 10", "11 to 50", "51 to 200", "201 to 500", "501 to 1000", "1001 to 5000", "5001 to 10000", "10001+" ], "description": "Employee count range for the brand (e.g. '11 to 50')" }, "exact": { "type": "integer", "description": "Exact employee count when a precise headcount is known" } }, "description": "Employee headcount information for the brand (will be null if unknown)" }, "is_nsfw": { "type": "boolean", "description": "Indicates whether the brand content is not safe for work (NSFW)" }, "email": { "type": "string", "description": "Company email address" }, "phone": { "type": "string", "description": "Company phone number" }, "industries": { "type": "object", "properties": { "eic": { "type": "array", "items": { "type": "object", "properties": { "industry": { "$ref": "#/components/schemas/Industry" }, "subindustry": { "$ref": "#/components/schemas/Subindustry" } }, "required": [ "industry", "subindustry" ] }, "description": "Easy Industry Classification - array of industry and subindustry pairs" } }, "description": "Industry classification information for the brand" }, "links": { "type": "object", "properties": { "careers": { "type": [ "string", "null" ], "description": "URL to the brand's careers or job opportunities page" }, "privacy": { "type": [ "string", "null" ], "description": "URL to the brand's privacy policy page" }, "terms": { "type": [ "string", "null" ], "description": "URL to the brand's terms of service or terms and conditions page" }, "contact": { "type": [ "string", "null" ], "description": "URL to the brand's contact or contact us page" }, "blog": { "type": [ "string", "null" ], "description": "URL to the brand's blog or news page" }, "pricing": { "type": [ "string", "null" ], "description": "URL to the brand's pricing or plans page" } }, "description": "Important website links for the brand" }, "primary_language": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SupportedLanguage" } ] }, { "type": "null" } ], "description": "The primary language of the brand's website content. Detected from the HTML lang tag, page content analysis, or social media descriptions." } }, "description": "Detailed brand information" }, "code": { "type": "integer", "description": "HTTP status code" }, "cache_metadata": { "$ref": "#/components/schemas/CacheMetadata" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "cache_metadata", "request_id" ] }, "ErrorResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "error_code": { "type": "string", "enum": [ "INTERNAL_ERROR", "VALID", "NOT_FOUND", "FORBIDDEN", "USAGE_EXCEEDED", "RATE_LIMITED", "UNAUTHORIZED", "DISABLED", "PAID_PLAN_REQUIRED", "INSUFFICIENT_PERMISSIONS", "TIMEOUT_EXCEEDS_MAXIMUM", "TIMEOUT_TOO_SHORT_FOR_WAIT", "WEBSITE_ACCESS_ERROR", "WEBSITE_BLOCKED", "WEBSITE_NOT_FOUND", "PDF_SKIPPED", "PDF_IMAGES_ONLY", "EXTERNAL_PROVIDER_ERROR", "INPUT_VALIDATION_ERROR", "ZDR_NOT_SUPPORTED", "ZDR_NOT_ENABLED", "FREE_EMAIL_DETECTED", "DISPOSABLE_EMAIL_DETECTED", "REQUEST_TIMEOUT", "COLD_DOMAIN_TIMEOUT_TOO_LOW", "UNSUPPORTED_CONTENT", "CONTENT_TOO_LARGE", "MONITOR_PAUSED", "MONITOR_NO_WEBHOOK", "COLLECTION_PAUSED", "MONITOR_LIMIT_EXCEEDED", "SEARCH_UNAVAILABLE", "BATCH_LIMIT_EXCEEDED", "BATCH_NOT_CANCELLABLE", "BATCH_NOT_COMPLETED", "IDEMPOTENCY_KEY_CONFLICT", "DELIVERY_IN_PROGRESS", "DELIVERY_ALREADY_DELIVERED", "DELIVERY_EXPIRED", "DELIVERY_CANCELLED" ], "description": "Error code indicating the type of error" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] }, "TimeoutMS": { "type": "integer", "minimum": 1000, "maximum": 300000, "description": "Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes)." }, "LenientTimeoutMS": { "type": "integer", "minimum": 1, "maximum": 300000, "description": "Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes)." }, "UtilityPrefetchDomainIdentifier": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 3, "description": "Domain name to prefetch data for" } }, "required": [ "domain" ], "additionalProperties": false, "title": "By domain", "description": "Prefetch by domain." }, "UtilityPrefetchEmailIdentifier": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1, "format": "email", "description": "Email address to prefetch data for. The domain will be extracted from the email. Free email providers (gmail.com, yahoo.com, etc.) and disposable email addresses are not allowed." } }, "required": [ "email" ], "additionalProperties": false, "title": "By email", "description": "Prefetch by email. The domain will be extracted and validated." }, "UtilityPrefetchIdentifier": { "oneOf": [ { "$ref": "#/components/schemas/UtilityPrefetchDomainIdentifier" }, { "$ref": "#/components/schemas/UtilityPrefetchEmailIdentifier" } ], "description": "Identifier of the target to prefetch. Provide exactly one of domain or email." }, "BrandRetrieveByDomainRequest": { "type": "object", "properties": { "force_language": { "allOf": [ { "$ref": "#/components/schemas/SupportedLanguage" }, { "type": [ "string", "null" ] } ] }, "maxSpeed": { "type": "boolean", "description": "Optional parameter to optimize the API call for maximum speed. When set to true, the API will skip time-consuming operations for faster response at the cost of less comprehensive data." }, "maxAgeMs": { "type": "integer", "description": "Maximum age in milliseconds for cached brand data before the API performs a hard refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 year." }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" }, "type": { "type": "string", "enum": [ "by_domain" ], "description": "Discriminator for domain-based brand retrieval." }, "domain": { "type": "string", "minLength": 3, "description": "Domain name to retrieve brand data for (e.g., 'stripe.com')." }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "type", "domain" ], "additionalProperties": false, "title": "By domain", "description": "Retrieve brand data by domain. Cannot be combined with name, email, or ticker." }, "BrandRetrieveByNameRequest": { "type": "object", "properties": { "force_language": { "allOf": [ { "$ref": "#/components/schemas/SupportedLanguage" }, { "type": [ "string", "null" ] } ] }, "maxSpeed": { "type": "boolean", "description": "Optional parameter to optimize the API call for maximum speed. When set to true, the API will skip time-consuming operations for faster response at the cost of less comprehensive data." }, "maxAgeMs": { "type": "integer", "description": "Maximum age in milliseconds for cached brand data before the API performs a hard refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 year." }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" }, "type": { "type": "string", "enum": [ "by_name" ], "description": "Discriminator for name-based brand retrieval." }, "name": { "type": "string", "minLength": 3, "maxLength": 30, "description": "Company name to retrieve brand data for (e.g., 'Apple Inc')." }, "country_gl": { "type": "string", "description": "Optional country code hint (GL parameter) to specify the country when looking up by company name." }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "type", "name" ], "additionalProperties": false, "title": "By name", "description": "Retrieve brand data by company name. Cannot be combined with domain, email, or ticker." }, "BrandRetrieveByEmailRequest": { "type": "object", "properties": { "force_language": { "allOf": [ { "$ref": "#/components/schemas/SupportedLanguage" }, { "type": [ "string", "null" ] } ] }, "maxSpeed": { "type": "boolean", "description": "Optional parameter to optimize the API call for maximum speed. When set to true, the API will skip time-consuming operations for faster response at the cost of less comprehensive data." }, "maxAgeMs": { "type": "integer", "description": "Maximum age in milliseconds for cached brand data before the API performs a hard refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 year." }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" }, "type": { "type": "string", "enum": [ "by_email" ], "description": "Discriminator for email-based brand retrieval." }, "email": { "type": "string", "minLength": 1, "format": "email", "description": "Email address to retrieve brand data for (e.g., 'jane@stripe.com')." }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "type", "email" ], "additionalProperties": false, "title": "By email", "description": "Retrieve brand data by email address. The domain is extracted from the email. Free and disposable email providers are rejected with 422. Cannot be combined with domain, name, or ticker." }, "BrandRetrieveByTickerRequest": { "type": "object", "properties": { "force_language": { "allOf": [ { "$ref": "#/components/schemas/SupportedLanguage" }, { "type": [ "string", "null" ] } ] }, "maxSpeed": { "type": "boolean", "description": "Optional parameter to optimize the API call for maximum speed. When set to true, the API will skip time-consuming operations for faster response at the cost of less comprehensive data." }, "maxAgeMs": { "type": "integer", "description": "Maximum age in milliseconds for cached brand data before the API performs a hard refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 year." }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" }, "type": { "type": "string", "enum": [ "by_ticker" ], "description": "Discriminator for ticker-based brand retrieval." }, "ticker": { "type": "string", "minLength": 1, "maxLength": 15, "pattern": "^[A-Za-z0-9.]+$", "description": "Stock ticker symbol to retrieve brand data for (e.g., 'AAPL')." }, "ticker_exchange": { "type": "string", "description": "Optional stock exchange for the ticker. Defaults to NASDAQ if not specified." }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "type", "ticker" ], "additionalProperties": false, "title": "By stock", "description": "Retrieve brand data by stock ticker. Cannot be combined with domain, name, or email." }, "BrandRetrieveByDirectUrlRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "by_direct_url" ], "description": "Discriminator for direct-URL-based brand retrieval." }, "direct_url": { "type": "string", "format": "uri", "description": "Full http(s) URL to fetch brand data from (e.g., 'https://stripe.com/enterprise'). Only this URL is fetched — not the entire internet." }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "type", "direct_url" ], "additionalProperties": false, "title": "By direct URL", "description": "Retrieve brand data by fetching the provided URL directly. Note: if you use this, brand data is fetched only from the provided URL — not from the entire internet — so results are limited to what that single page contains. No domain resolution, database lookup, or cross-source enrichment is performed. Cannot be combined with domain, name, email, or ticker." }, "BrandRetrieveFromTransactionRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "by_transaction" ], "description": "Discriminator for transaction-based brand retrieval." }, "transaction_info": { "type": "string", "minLength": 3, "maxLength": 500, "description": "Transaction information to identify the brand." }, "force_language": { "allOf": [ { "$ref": "#/components/schemas/SupportedLanguage" }, { "type": [ "string", "null" ] } ] }, "maxSpeed": { "type": "boolean", "description": "Optional parameter to optimize the API call for maximum speed. When set to true, the API will skip time-consuming operations for faster response at the cost of less comprehensive data." }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" }, "country_gl": { "type": "string", "description": "Optional country code hint (GL parameter) to specify the country when identifying a transaction." }, "city": { "type": "string", "description": "Optional city name to prioritize when searching for the brand." }, "mcc": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Optional Merchant Category Code (MCC) to help identify the business category or industry." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Optional phone number from the transaction to help verify brand match." }, "high_confidence_only": { "type": "boolean", "description": "When set to true, the API performs additional verification to ensure the identified brand matches the transaction with high confidence." }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "type", "transaction_info" ], "additionalProperties": false, "title": "By transaction", "description": "Identify brand data from a transaction descriptor. Cannot be combined with domain, name, email, or ticker." }, "BrandRetrieveRequest": { "oneOf": [ { "$ref": "#/components/schemas/BrandRetrieveByDomainRequest" }, { "$ref": "#/components/schemas/BrandRetrieveByNameRequest" }, { "$ref": "#/components/schemas/BrandRetrieveByEmailRequest" }, { "$ref": "#/components/schemas/BrandRetrieveByTickerRequest" }, { "$ref": "#/components/schemas/BrandRetrieveByDirectUrlRequest" }, { "$ref": "#/components/schemas/BrandRetrieveFromTransactionRequest" } ], "discriminator": { "propertyName": "type", "mapping": { "by_domain": "#/components/schemas/BrandRetrieveByDomainRequest", "by_name": "#/components/schemas/BrandRetrieveByNameRequest", "by_email": "#/components/schemas/BrandRetrieveByEmailRequest", "by_ticker": "#/components/schemas/BrandRetrieveByTickerRequest", "by_direct_url": "#/components/schemas/BrandRetrieveByDirectUrlRequest", "by_transaction": "#/components/schemas/BrandRetrieveFromTransactionRequest" } }, "description": "Exactly one lookup type must be provided." }, "PersonEnrichmentRequest": { "type": "object", "properties": { "social_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 20 }, "name": { "type": "object", "properties": { "first": { "type": "string", "minLength": 1, "maxLength": 100 }, "last": { "type": "string", "minLength": 1, "maxLength": 100 } }, "additionalProperties": false }, "email": { "type": "string", "maxLength": 320, "format": "email" }, "company": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "domain": { "type": "string", "minLength": 1, "maxLength": 253 } }, "additionalProperties": false }, "education": { "type": "array", "items": { "type": "object", "properties": { "institution": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "domain": { "type": "string", "minLength": 1, "maxLength": 253 } }, "additionalProperties": false }, "degree": { "type": "string", "minLength": 1, "maxLength": 200 }, "field_of_study": { "type": "string", "minLength": 1, "maxLength": 200 }, "graduation_year": { "type": "integer", "minimum": 1900, "maximum": 2200 } }, "additionalProperties": false }, "minItems": 1, "maxItems": 10 }, "location": { "type": "object", "properties": { "city": { "type": "string", "minLength": 1, "maxLength": 200 }, "region": { "type": "string", "minLength": 1, "maxLength": 200 }, "country": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "timeoutMS": { "$ref": "#/components/schemas/TimeoutMS" }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "additionalProperties": false, "description": "Identity clues for one person. Provide a person email, a person-profile social URL, or both first and last name with company, education, or location. All supplied clues are considered together." }, "PersonEnrichmentCandidateMatch": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "candidate" ] }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "person": { "type": "object", "properties": { "name": { "type": "object", "properties": { "full": { "type": "string" }, "first": { "type": "string" }, "last": { "type": "string" } }, "additionalProperties": false }, "email": { "type": "string", "format": "email" }, "avatar_url": { "type": "string", "pattern": "^https:\\/\\/media\\.brand\\.dev\\/pfp\\/[0-9a-f-]{36}$" }, "bio": { "type": "string" }, "location": { "type": "object", "properties": { "display": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "country": { "type": "string" }, "country_code": { "type": "string" } }, "additionalProperties": false }, "social_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "website_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "current_role": { "type": "object", "properties": { "title": { "type": "string" }, "organization": { "type": "object", "properties": { "name": { "type": "string" }, "domain": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "location": { "type": "string" }, "description": { "type": "string" }, "start_date": { "type": "object", "properties": { "year": { "type": "integer" }, "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "year" ], "additionalProperties": false }, "end_date": { "type": "object", "properties": { "year": { "type": "integer" }, "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "year" ], "additionalProperties": false }, "is_current": { "type": "boolean" } }, "required": [ "title", "organization" ], "additionalProperties": false }, "current_role_status": { "type": "string", "enum": [ "present", "none", "unknown" ], "description": "Whether the person's current role is known. `present` — current_role is populated. `none` — the work history explicitly shows every role has ended. `unknown` — our data sources could not confirm either way; treat a missing current_role as unverified rather than vacant." }, "experience": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "organization": { "type": "object", "properties": { "name": { "type": "string" }, "domain": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "location": { "type": "string" }, "description": { "type": "string" }, "start_date": { "type": "object", "properties": { "year": { "type": "integer" }, "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "year" ], "additionalProperties": false }, "end_date": { "type": "object", "properties": { "year": { "type": "integer" }, "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "year" ], "additionalProperties": false }, "is_current": { "type": "boolean" } }, "required": [ "title", "organization" ], "additionalProperties": false } }, "education": { "type": "array", "items": { "type": "object", "properties": { "institution": { "type": "object", "properties": { "name": { "type": "string" }, "domain": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "degree": { "type": "string" }, "field_of_study": { "type": "string" }, "description": { "type": "string" }, "start_date": { "type": "object", "properties": { "year": { "type": "integer" }, "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "year" ], "additionalProperties": false }, "end_date": { "type": "object", "properties": { "year": { "type": "integer" }, "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "year" ], "additionalProperties": false } }, "required": [ "institution" ], "additionalProperties": false } }, "skills": { "type": "array", "items": { "type": "string" } }, "last_updated": { "type": "string", "description": "When the underlying profile data last changed in our data sources (ISO 8601). Omitted when unknown." }, "checked_at": { "type": "string", "description": "When we last refreshed this profile from our data sources (ISO 8601)." } }, "required": [ "social_urls", "website_urls", "current_role_status", "experience", "education", "skills" ], "additionalProperties": false } }, "required": [ "status", "score", "person" ], "additionalProperties": false, "title": "Candidate match", "description": "The highest-scoring person candidate." }, "PersonEnrichmentNotFoundMatch": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_found" ] }, "score": { "type": "null" }, "person": { "type": "null" } }, "required": [ "status", "score", "person" ], "additionalProperties": false, "title": "No match", "description": "No usable person candidate was found." }, "PersonEnrichmentMatch": { "oneOf": [ { "$ref": "#/components/schemas/PersonEnrichmentCandidateMatch" }, { "$ref": "#/components/schemas/PersonEnrichmentNotFoundMatch" } ], "discriminator": { "propertyName": "status", "mapping": { "candidate": "#/components/schemas/PersonEnrichmentCandidateMatch", "not_found": "#/components/schemas/PersonEnrichmentNotFoundMatch" } } }, "PersonEnrichmentResponse": { "type": "object", "properties": { "match": { "$ref": "#/components/schemas/PersonEnrichmentMatch" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "match", "request_id" ], "additionalProperties": false }, "MonitorsMode": { "type": "string", "enum": [ "web" ], "description": "Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`.", "title": "Monitor mode" }, "MonitorsPageTarget": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "page" ] }, "url": { "type": "string", "format": "uri", "example": "https://acme.com/pricing" }, "instructions": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred.", "example": "Report pricing or plan availability changes. Ignore counters, timestamps, testimonials, and navigation." }, "normalize_whitespace": { "type": "boolean", "default": true, "description": "Normalize whitespace before comparing or analyzing text." } }, "required": [ "type", "url" ], "additionalProperties": false, "description": "Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`.", "title": "Page target" }, "MonitorsSitemapTarget": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "sitemap" ] }, "url": { "type": "string", "format": "uri", "description": "Sitemap URL to monitor.", "example": "https://acme.com/sitemap.xml" }, "include": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 50, "description": "URL path patterns to include (max 50).", "example": [ "/blog/*", "/pricing*" ] }, "exclude": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 50, "description": "URL path patterns to exclude (max 50).", "example": [ "/legal/*", "/privacy" ] }, "max_urls": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 5000, "description": "Maximum number of sitemap URLs to track (capped at 10,000)." } }, "required": [ "type", "url" ], "additionalProperties": false, "description": "Watch a sitemap for URL additions and removals. Crawled URLs are normalized (lowercased host, no trailing slash/fragment) and scoped to the monitored site and its subdomains before comparison. On a detected difference the sitemap is re-fetched within the same run and only URLs both observations agree on are reported, suppressing transient crawl flaps.", "title": "Sitemap target" }, "MonitorsExtractTarget": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "extract" ] }, "url": { "type": "string", "format": "uri", "description": "Root URL to extract structured data from.", "example": "https://acme.com" }, "schema": { "type": "object", "additionalProperties": {}, "description": "JSON Schema describing the data you care about. It is used three ways: it guides which pages are selected for tracking, it gives the change judge extra context on which changes matter (alongside `instructions`), and it defines the shape of the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most about once a day). It is not a response format for changes: change events and webhook payloads always contain diffs, summaries, and evidence excerpts — never data in this schema's shape. If omitted, a default summary + key-points schema is used.", "example": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price": { "type": "string" } } } } } } }, "instructions": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Natural-language instructions guiding which pages and facts to track and which changes to report.", "example": "Extract every pricing plan with its monthly price and included limits." }, "max_pages": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "Maximum number of pages to track." }, "max_depth": { "type": "integer", "minimum": 0, "maximum": 10, "description": "Optional maximum link depth from the starting URL (0 = only the starting page)." }, "follow_subdomains": { "type": "boolean", "default": false } }, "required": [ "type", "url", "instructions" ], "additionalProperties": false, "title": "Extract target" }, "MonitorsTarget": { "oneOf": [ { "$ref": "#/components/schemas/MonitorsPageTarget" }, { "$ref": "#/components/schemas/MonitorsSitemapTarget" }, { "allOf": [ { "$ref": "#/components/schemas/MonitorsExtractTarget" }, { "description": "Watch the monitor-relevant pages of a site for meaningful changes. A crawl guided by `schema`/`instructions` selects up to `max_pages` relevant pages to track; each run re-checks exactly those pages, and confirmed content changes are judged for relevance against the monitor's `instructions` (and `schema`, when provided). The tracked page set is refreshed by a periodic re-discovery crawl." } ] } ], "discriminator": { "propertyName": "type", "mapping": { "page": "#/components/schemas/MonitorsPageTarget", "sitemap": "#/components/schemas/MonitorsSitemapTarget", "extract": "#/components/schemas/MonitorsExtractTarget" } }, "description": "Discriminated union describing what the monitor watches." }, "MonitorsExactChangeDetection": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "exact" ] } }, "required": [ "type" ], "additionalProperties": false, "description": "Detect exact changes. For page targets, this means visible text diffs. For sitemap targets, this means URL additions and removals.", "title": "Exact" }, "MonitorsSemanticChangeDetection": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "semantic" ] }, "confidence_threshold": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.75 } }, "required": [ "type" ], "additionalProperties": false, "description": "Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided).", "title": "Semantic" }, "MonitorsChangeDetection": { "oneOf": [ { "$ref": "#/components/schemas/MonitorsExactChangeDetection" }, { "$ref": "#/components/schemas/MonitorsSemanticChangeDetection" } ], "discriminator": { "propertyName": "type", "mapping": { "exact": "#/components/schemas/MonitorsExactChangeDetection", "semantic": "#/components/schemas/MonitorsSemanticChangeDetection" } }, "description": "Discriminated union describing how changes are detected." }, "MonitorsScheduleUnit": { "type": "string", "enum": [ "minutes", "hours", "days" ], "example": "hours" }, "MonitorsIntervalSchedule": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "interval" ] }, "frequency": { "type": "integer", "minimum": 1, "maximum": 525600, "description": "Number of units between runs. The resulting interval (frequency × unit) must be at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; maximum 365 when unit is days).", "example": 6 }, "unit": { "$ref": "#/components/schemas/MonitorsScheduleUnit" } }, "required": [ "type", "frequency", "unit" ], "additionalProperties": false, "description": "Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year.", "title": "Interval" }, "MonitorsSchedule": { "oneOf": [ { "$ref": "#/components/schemas/MonitorsIntervalSchedule" } ], "discriminator": { "propertyName": "type", "mapping": { "interval": "#/components/schemas/MonitorsIntervalSchedule" } }, "description": "Discriminated union describing how the monitor is scheduled. Only `interval` is supported today; `cron` and `exact_time` are reserved for future use." }, "WebhookRetry": { "type": "object", "properties": { "delays_seconds": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 86400 }, "maxItems": 10, "description": "Retry delays in seconds, totaling at most 72 hours. Use [] to disable automatic retries.", "example": [ 30, 300, 3600 ] } }, "additionalProperties": false, "description": "Webhook retry settings. Use {} for the default schedule.", "example": { "delays_seconds": [ 10, 60, 300, 1800, 7200, 21600, 57600 ] } }, "MonitorsWebhookConfig": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook URL events are delivered to.", "example": "https://example.com/webhook" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "change.detected", "run.completed" ] }, "minItems": 1, "maxItems": 2, "uniqueItems": true, "description": "Events delivered to this endpoint. `change.detected` fires only when a run detects a change; `run.completed` fires on every completed run — including runs that detected no change — and embeds the change when one was detected. Defaults to `[\"change.detected\"]` when omitted.", "example": [ "change.detected", "run.completed" ] }, "retry": { "$ref": "#/components/schemas/WebhookRetry" }, "secret": { "type": "string", "readOnly": true, "description": "Signing secret used to verify webhook authenticity. Each delivery includes an `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over `\"{t}.{rawRequestBody}\"` keyed by this secret. Recompute it with a constant-time compare and reject stale timestamps to prevent replay. Generated by the API; cannot be set by clients.", "example": "whsec_8f3a…" } }, "required": [ "url" ], "additionalProperties": false }, "MonitorsNullableWebhookConfig": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/MonitorsWebhookConfig" } ] }, { "type": "null" } ] }, "MonitorsCreateMonitorRequest": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/MonitorsMode" }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "example": "Acme pricing monitor" }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "maxItems": 20, "uniqueItems": true, "description": "User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.", "example": [ "pricing", "competitor" ] }, "target": { "$ref": "#/components/schemas/MonitorsTarget" }, "change_detection": { "$ref": "#/components/schemas/MonitorsChangeDetection" }, "schedule": { "$ref": "#/components/schemas/MonitorsSchedule" }, "webhook": { "$ref": "#/components/schemas/MonitorsNullableWebhookConfig" } }, "required": [ "name", "target" ], "additionalProperties": false, "title": "Create monitor request", "description": "Creates a web monitor. `mode` is the constant `web`; the behavior is described by `target` (page, sitemap, or extract) and `change_detection` (exact or semantic). Supported combinations: page + exact, page + semantic, sitemap + exact, extract + semantic. `change_detection` is optional; page targets with `instructions` infer semantic detection, while page targets without them infer exact detection. Other targets default to their supported detection type. `schedule` is optional and defaults to once per day." }, "MonitorsUpdateMonitorRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "example": "Acme pricing monitor" }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "maxItems": 20, "uniqueItems": true, "description": "User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.", "example": [ "pricing", "competitor" ] }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "target": { "$ref": "#/components/schemas/MonitorsTarget" }, "change_detection": { "$ref": "#/components/schemas/MonitorsChangeDetection" }, "schedule": { "$ref": "#/components/schemas/MonitorsSchedule" }, "webhook": { "$ref": "#/components/schemas/MonitorsNullableWebhookConfig", "description": "Set to null to remove the webhook." } }, "additionalProperties": false, "description": "Shared monitor update fields. `target` and `change_detection` can be updated, but the final combination must be supported." }, "MonitorsMonitorStatus": { "type": "string", "enum": [ "active", "paused", "failed" ], "description": "Monitor lifecycle status. `failed` means the most recent run failed (see the monitor's `last_error`); failed monitors keep running on schedule and flip back to `active` on the next successful run. Monitors are auto-`paused` after repeated consecutive failures or insufficient-credit skips; resume by PATCHing status to `active`." }, "MonitorsRunError": { "type": "object", "properties": { "code": { "type": "string", "example": "fetch_failed" }, "message": { "type": "string", "example": "The target URL could not be fetched." } }, "required": [ "code", "message" ], "additionalProperties": false }, "MonitorsWebhookFailure": { "type": "object", "properties": { "consecutive_failures": { "type": "integer", "minimum": 1, "description": "Number of consecutive delivery attempts that did not succeed.", "example": 3 }, "last_status": { "type": "string", "enum": [ "rejected", "failed", "skipped_unsafe_url" ], "description": "Outcome of the most recent failed delivery. rejected means a non-2xx response; failed means no HTTP response was received; skipped_unsafe_url means the URL failed the public-endpoint safety check." }, "last_message": { "type": "string", "description": "Human-readable description of the most recent failure.", "example": "Webhook endpoint returned HTTP 429." }, "last_failed_at": { "type": "string", "format": "date-time" } }, "required": [ "consecutive_failures", "last_status", "last_message", "last_failed_at" ], "additionalProperties": false }, "MonitorsPageBaseline": { "type": "object", "properties": { "text": { "type": "string", "description": "The page's visible text as last observed.", "example": "Acme Pricing\nStarter $9/mo…" }, "captured_at": { "type": "string", "format": "date-time", "description": "When this baseline was last captured or replaced." } }, "required": [ "text", "captured_at" ], "additionalProperties": false, "title": "Page baseline", "description": "Current baseline of a `page` monitor: the visible page text as last observed." }, "MonitorsSitemapBaseline": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string" }, "description": "The sitemap URLs as last observed (sorted, normalized).", "example": [ "https://acme.com/blog/launch", "https://acme.com/pricing" ] }, "url_count": { "type": "integer", "description": "Number of URLs in the baseline.", "example": 2 }, "captured_at": { "type": "string", "format": "date-time", "description": "When this baseline was last captured or replaced." } }, "required": [ "urls", "url_count", "captured_at" ], "additionalProperties": false, "title": "Sitemap baseline", "description": "Current baseline of a `sitemap` monitor: the normalized URL set as last observed." }, "MonitorsExtractBaseline": { "type": "object", "properties": { "data": { "description": "The extracted structured data, matching the monitor's extraction schema (same shape as the /web/extract endpoint's `data`). Refreshed when the monitor re-discovers its page set (at most about once a day); `null` when no extraction has been captured yet.", "example": { "plans": [ { "name": "Starter", "price": "$9/mo" } ] } }, "urls_analyzed": { "type": "array", "items": { "type": "string" }, "description": "The page URLs the monitor tracks and analyzes for changes.", "example": [ "https://acme.com/pricing" ] }, "captured_at": { "type": "string", "format": "date-time", "description": "When this baseline was last captured or replaced." } }, "required": [ "data", "urls_analyzed", "captured_at" ], "additionalProperties": false, "title": "Extract baseline", "description": "Current baseline of an `extract` monitor: the pages it tracks and the structured data as last extracted." }, "MonitorsMonitor": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/MonitorsMode" }, "id": { "type": "string", "example": "mon_123" }, "name": { "type": "string", "example": "Acme pricing monitor" }, "target": { "$ref": "#/components/schemas/MonitorsTarget" }, "change_detection": { "$ref": "#/components/schemas/MonitorsChangeDetection" }, "schedule": { "$ref": "#/components/schemas/MonitorsSchedule" }, "webhook": { "$ref": "#/components/schemas/MonitorsNullableWebhookConfig" }, "status": { "$ref": "#/components/schemas/MonitorsMonitorStatus" }, "last_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_change_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the next scheduled run is due." }, "last_error": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/MonitorsRunError" } ] }, { "type": "null" } ], "description": "Error from the most recent failed run; null when the last run succeeded." }, "webhook_failure": { "allOf": [ { "$ref": "#/components/schemas/MonitorsWebhookFailure" } ], "nullable": true, "description": "Present while webhook deliveries are failing consecutively; null when deliveries are healthy or no webhook is configured. Cleared on the next successful delivery and when the webhook URL changes." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "maxItems": 20, "uniqueItems": true, "description": "User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.", "example": [ "pricing", "competitor" ] }, "baseline": { "oneOf": [ { "$ref": "#/components/schemas/MonitorsPageBaseline" }, { "$ref": "#/components/schemas/MonitorsSitemapBaseline" }, { "$ref": "#/components/schemas/MonitorsExtractBaseline" }, { "type": "null" } ], "description": "Current baseline: the last observed value the monitor compares new snapshots against. Its shape follows `target.type` (page/sitemap/extract). Only populated on GET /monitors/{monitor_id}; null until the first baseline run completes (and after a target or change_detection update, which resets the baseline)." } }, "required": [ "mode", "id", "name", "target", "change_detection", "schedule", "status", "created_at", "updated_at" ], "additionalProperties": false, "title": "Monitor", "description": "A web monitor. `mode` is the constant `web`; behavior is described by `target` (page/sitemap/extract) and `change_detection` (exact/semantic)." }, "MonitorsCreateMonitorResponse": { "allOf": [ { "$ref": "#/components/schemas/MonitorsMonitor" }, { "type": "object", "required": [ "initial_run_id" ], "properties": { "initial_run_id": { "type": [ "string", "null" ], "description": "The baseline run queued by this create call, or null if it could not be queued immediately (in which case the baseline runs on the next scheduled tick). Poll GET /monitors/{monitor_id}/runs/{run_id}.", "example": "run_123" } } } ], "title": "Create monitor response", "description": "A newly created monitor plus `initial_run_id`, the id of the baseline run queued at creation." }, "MonitorsTargetType": { "type": "string", "enum": [ "page", "sitemap", "extract" ] }, "MonitorsChangeDetectionType": { "type": "string", "enum": [ "exact", "semantic" ] }, "MonitorsRunStatus": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "skipped" ], "description": "Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` (insufficient credits, monitor paused, or superseded by a concurrent run)." }, "MonitorsNullableRunError": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/MonitorsRunError" } ] }, { "type": "null" } ] }, "MonitorsWebhookDelivery": { "type": "object", "properties": { "delivery_id": { "type": "string", "description": "Delivery ID for status checks and retries, when available." }, "event_id": { "type": "string", "description": "Identifier sent in the X-Context-Id header.", "example": "evt_123" }, "event": { "type": "string", "enum": [ "change.detected", "run.completed" ], "description": "The event this delivery carried. Deliveries recorded before event selection existed report change.detected." }, "status": { "type": "string", "enum": [ "delivered", "rejected", "failed", "skipped_unsafe_url" ], "description": "Delivery outcome. delivered means any 2xx response; rejected means a non-2xx response; failed means no HTTP response was received; skipped_unsafe_url means the URL failed the public-endpoint safety check." }, "http_status": { "type": [ "integer", "null" ], "minimum": 100, "maximum": 599, "description": "The endpoint's final HTTP response status, or null when no response was received.", "example": 200 }, "attempted_at": { "type": "string", "format": "date-time" }, "error": { "$ref": "#/components/schemas/MonitorsNullableRunError" } }, "required": [ "event_id", "event", "status", "http_status", "attempted_at", "error" ], "additionalProperties": false, "x-stainless-model": "monitors.webhook_delivery" }, "MonitorsRun": { "type": "object", "properties": { "webhook_delivery_ids": { "type": "array", "items": { "type": "string" }, "description": "Webhook delivery IDs for this run." }, "id": { "type": "string", "example": "run_123" }, "monitor_id": { "type": "string", "example": "mon_123" }, "status": { "$ref": "#/components/schemas/MonitorsRunStatus" }, "run_type": { "type": "string", "enum": [ "baseline", "scheduled" ], "description": "The first run after monitor creation is a baseline run." }, "target_type": { "$ref": "#/components/schemas/MonitorsTargetType" }, "change_detection_type": { "$ref": "#/components/schemas/MonitorsChangeDetectionType" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "change_detected": { "type": "boolean", "example": true }, "change_id": { "type": [ "string", "null" ], "example": "chg_123" }, "baseline_created": { "type": "boolean", "description": "True when this run established the monitor's initial baseline; baseline runs perform no change detection." }, "credits_charged": { "type": "integer", "minimum": 0, "description": "Credits charged for this run (0 for skipped/failed runs).", "example": 1 }, "skip_reason": { "type": [ "string", "null" ], "enum": [ "insufficient_credits", "monitor_paused", "superseded", null ], "description": "Why a skipped run never executed; null unless status is `skipped`." }, "error": { "$ref": "#/components/schemas/MonitorsNullableRunError" }, "webhook_delivery": { "$ref": "#/components/schemas/MonitorsWebhookDelivery", "deprecated": true, "description": "Deprecated: use `webhook_deliveries`, which records every attempt now that a run can deliver multiple events. Omitted when no webhook was attempted, including historical runs created before delivery tracking was added." }, "webhook_deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorsWebhookDelivery" }, "description": "All webhook deliveries attempted by this run — one per subscribed event that fired. Omitted when no webhook was attempted, including runs created before event selection was added." } }, "required": [ "id", "monitor_id", "status", "run_type", "target_type", "change_detection_type", "change_detected", "baseline_created", "credits_charged" ], "additionalProperties": false }, "MonitorsImportance": { "type": "string", "enum": [ "low", "medium", "high" ] }, "MonitorsChangeSummary": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/MonitorsMode" }, "id": { "type": "string", "example": "chg_123" }, "monitor_id": { "type": "string", "example": "mon_123" }, "target_type": { "$ref": "#/components/schemas/MonitorsTargetType" }, "change_detection_type": { "$ref": "#/components/schemas/MonitorsChangeDetectionType" }, "title": { "type": "string", "example": "Acme pricing page changed" }, "summary": { "type": "string", "example": "The visible text on the page changed." }, "detected_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "importance": { "$ref": "#/components/schemas/MonitorsImportance" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "added_url_count": { "type": "integer", "minimum": 0 }, "removed_url_count": { "type": "integer", "minimum": 0 }, "matched_url_count": { "type": "integer", "minimum": 0 }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "maxItems": 20, "uniqueItems": true, "description": "User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.", "example": [ "pricing", "competitor" ] } }, "required": [ "mode", "id", "monitor_id", "target_type", "change_detection_type", "title", "summary", "detected_at", "url" ], "additionalProperties": false, "title": "Change summary", "description": "A lightweight change summary. `mode` is the constant `web`; `target_type` and `change_detection_type` describe the change, and which optional fields are present depends on them (e.g. sitemap changes include `added_url_count`/`removed_url_count`; semantic changes include `confidence`/`importance`)." }, "MonitorsEvidence": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Optional URL the evidence relates to. Absent for whole-target diffs." }, "before": { "type": "string", "description": "Snapshot of the content before the change." }, "after": { "type": "string", "description": "Snapshot of the content after the change." } }, "required": [ "before", "after" ], "additionalProperties": false }, "MonitorsChange": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/MonitorsMode" }, "id": { "type": "string", "example": "chg_123" }, "monitor_id": { "type": "string", "example": "mon_123" }, "run_id": { "type": "string", "example": "run_123", "description": "The run that detected this change." }, "target_type": { "$ref": "#/components/schemas/MonitorsTargetType" }, "change_detection_type": { "$ref": "#/components/schemas/MonitorsChangeDetectionType" }, "title": { "type": "string", "example": "Acme pricing page changed" }, "summary": { "type": "string", "example": "The visible text on the page changed." }, "detected_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "importance": { "$ref": "#/components/schemas/MonitorsImportance" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "diff": { "type": "string", "description": "Text diff between the previous and current page baseline (page targets)." }, "before_text_excerpt": { "type": "string" }, "after_text_excerpt": { "type": "string" }, "added_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "At most 500 URLs are included; the corresponding count field is always exact." }, "removed_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "At most 500 URLs are included; the corresponding count field is always exact." }, "added_url_count": { "type": "integer", "minimum": 0 }, "removed_url_count": { "type": "integer", "minimum": 0 }, "matched_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "At most 500 URLs are included; the corresponding count field is always exact." }, "matched_url_count": { "type": "integer", "minimum": 0 }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorsEvidence" } }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "maxItems": 20, "uniqueItems": true, "description": "User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.", "example": [ "pricing", "competitor" ] } }, "required": [ "mode", "id", "monitor_id", "run_id", "target_type", "change_detection_type", "title", "summary", "detected_at", "url", "tags" ], "additionalProperties": false, "title": "Change", "description": "A detected change. `mode` is the constant `web`; `target_type` and `change_detection_type` describe the change, and which optional fields are present depends on them (page: `diff` + excerpts; sitemap: `added_urls`/`removed_urls`; semantic: `confidence`/`importance`/`evidence`/`matched_urls`)." }, "MonitorsListMonitorsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorsMonitor" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next_cursor" ], "additionalProperties": false }, "MonitorsListRunsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorsRun" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next_cursor" ], "additionalProperties": false }, "MonitorsListChangesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorsChangeSummary" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next_cursor" ], "additionalProperties": false }, "MonitorsDeleteMonitorResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "mon_123" }, "deleted": { "type": "boolean", "example": true } }, "required": [ "id", "deleted" ], "additionalProperties": false }, "MonitorsChangeDetectedWebhookPayload": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "change.detected" ] }, "id": { "type": "string", "example": "evt_123" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-09T18:00:12.000Z" }, "data": { "type": "object", "properties": { "change": { "$ref": "#/components/schemas/MonitorsChange" } }, "required": [ "change" ], "additionalProperties": false } }, "required": [ "event", "id", "created_at", "data" ], "additionalProperties": false, "title": "Monitor change detected webhook payload", "description": "Payload sent when a monitor detects a change. The nested change is the same full change record returned by GET /monitors/changes/{change_id}." }, "MonitorsRunCompletedWebhookPayload": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "run.completed" ] }, "id": { "type": "string", "example": "evt_123" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-09T18:00:12.000Z" }, "data": { "type": "object", "properties": { "run": { "type": "object", "properties": { "id": { "type": "string", "example": "run_123" }, "monitor_id": { "type": "string", "example": "mon_123" }, "status": { "type": "string", "enum": [ "completed" ] }, "run_type": { "type": "string", "enum": [ "baseline", "scheduled" ], "description": "The first run after monitor creation is a baseline run." }, "target_type": { "$ref": "#/components/schemas/MonitorsTargetType" }, "change_detection_type": { "$ref": "#/components/schemas/MonitorsChangeDetectionType" }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "change_detected": { "type": "boolean", "example": false }, "change_id": { "type": [ "string", "null" ], "example": null }, "baseline_created": { "type": "boolean", "description": "True when this run established the monitor's initial baseline; baseline runs perform no change detection." } }, "required": [ "id", "monitor_id", "status", "run_type", "target_type", "change_detection_type", "started_at", "completed_at", "change_detected", "change_id", "baseline_created" ], "additionalProperties": false, "title": "Completed run snapshot", "description": "Snapshot of the run at delivery time. Billing detail (credits_charged) is settled after delivery, so fetch the run via GET /monitors/{monitor_id}/runs for the full record." }, "change": { "anyOf": [ { "$ref": "#/components/schemas/MonitorsChange" }, { "type": "null" } ], "description": "The detected change — the same full change record delivered by change.detected — or null when the run found no change." } }, "required": [ "run", "change" ], "additionalProperties": false } }, "required": [ "event", "id", "created_at", "data" ], "additionalProperties": false, "title": "Monitor run completed webhook payload", "description": "Payload sent after every completed run when the monitor's webhook subscribes to run.completed. A run with `change_detected: false` is a confirmation that the monitor ran and found no change." }, "MonitorsRunNowResponse": { "type": "object", "properties": { "monitor_id": { "type": "string", "example": "mon_123" }, "run_id": { "type": "string", "example": "run_123", "description": "The queued run. Poll GET /monitors/{monitor_id}/runs or use it to correlate results." }, "queued": { "type": "boolean", "example": true } }, "required": [ "monitor_id", "run_id", "queued" ], "additionalProperties": false }, "MonitorsCreditUsage": { "type": "object", "properties": { "monitor_id": { "type": "string", "example": "mon_123" }, "name": { "type": "string", "description": "Monitor name (falls back to the id when the monitor was deleted)." }, "credits": { "type": "integer", "description": "Credits charged to this monitor over the window." }, "runs": { "type": "integer", "description": "Number of billed runs over the window." } }, "required": [ "monitor_id", "name", "credits", "runs" ], "additionalProperties": false, "title": "Monitor credit usage" }, "MonitorsCreditUsageResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorsCreditUsage" } }, "total_credits": { "type": "integer", "description": "Sum of credits across all monitors in the window." } }, "required": [ "data", "total_credits" ], "additionalProperties": false, "title": "Monitor credit usage response" }, "MonitorsLimitsResponse": { "type": "object", "properties": { "monitors_used": { "type": "integer", "description": "Number of monitors the account currently has." }, "monitors_limit": { "type": "integer", "description": "Maximum number of monitors allowed for the account. Defaults to the plan allowance unless a custom limit is set for the organization." }, "plan": { "type": "string", "enum": [ "free", "starter", "pro", "scale" ], "description": "The plan tier the limit was resolved from." } }, "required": [ "monitors_used", "monitors_limit", "plan" ], "additionalProperties": false, "title": "Monitor limits response" }, "BatchSubmitRequest": { "type": "object", "properties": { "input": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "scrape" ], "description": "Scrape the pages in `data.urls`." }, "data": { "oneOf": [ { "type": "object", "properties": { "format": { "type": "string", "enum": [ "markdown" ], "description": "Return page content as Markdown." }, "urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Page URL to scrape.", "example": "https://example.com/products/anvil" }, "itemId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Your ID for this page, returned with its result. The same URL can use different IDs.", "example": "sku-1" }, "meta": { "type": "object", "additionalProperties": {}, "description": "Custom JSON returned unchanged with this page result." } }, "required": [ "url" ], "additionalProperties": false, "description": "A page to scrape, with optional data for matching results." }, "minItems": 1, "maxItems": 25000, "description": "Pages to scrape. Maximum 25000." }, "options": { "type": "object", "properties": { "includeLinks": { "type": "boolean", "default": true, "description": "Include links in the Markdown." }, "includeImages": { "type": "boolean", "default": false, "description": "Include image references in the Markdown." }, "shortenBase64Images": { "type": "boolean", "default": true, "description": "Shorten inline base64 image data." }, "useMainContentOnly": { "type": "boolean", "default": false, "description": "Return the main content without navigation or footers." }, "includeHTML": { "type": "boolean", "default": false, "description": "Also include each page's HTML in its result record, as an `html` field alongside the Markdown." }, "pdf": { "type": "object", "properties": { "shouldParse": { "type": "boolean", "default": true, "description": "When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and a 400 PDF_SKIPPED is returned." }, "start": { "type": "integer", "minimum": 1, "description": "First 1-based PDF page to parse. When omitted, parsing starts at the first page." }, "end": { "type": "integer", "minimum": 1, "description": "Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided." }, "ocr": { "type": "boolean", "default": false, "description": "When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs." } }, "default": { "shouldParse": true, "ocr": false }, "description": "PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range." }, "includeSelectors": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "maxItems": 50, "description": "Keep only the subtrees matching these CSS selectors. Filtered pages are always fetched fresh, ignoring `maxAgeMs`." }, "excludeSelectors": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "maxItems": 50, "description": "Remove elements matching these CSS selectors. Applied after `includeSelectors`, so an element matching both is removed." }, "waitForMs": { "type": "integer", "minimum": 0, "maximum": 15000, "description": "How long to wait after initial page load, in milliseconds. `0` waits 500 ms." }, "settleAnimations": { "type": "boolean", "default": false, "description": "Wait briefly for CSS and transition animations to settle before extraction, on pages that render in a browser." }, "country": { "$ref": "#/components/schemas/BrowserCountryCode" }, "maxAgeMs": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2592000000, "default": 86400000, "description": "Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh." } }, "default": { "includeLinks": true, "includeImages": false, "shortenBase64Images": true, "useMainContentOnly": false, "includeHTML": false, "pdf": { "shouldParse": true, "ocr": false }, "settleAnimations": false, "maxAgeMs": 86400000 }, "additionalProperties": false, "description": "Options for Markdown output." } }, "required": [ "format", "urls" ], "additionalProperties": false, "description": "Scrape the listed pages as Markdown.", "title": "Markdown" }, { "type": "object", "properties": { "format": { "type": "string", "enum": [ "html" ], "description": "Return page content as HTML." }, "urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Page URL to scrape.", "example": "https://example.com/products/anvil" }, "itemId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Your ID for this page, returned with its result. The same URL can use different IDs.", "example": "sku-1" }, "meta": { "type": "object", "additionalProperties": {}, "description": "Custom JSON returned unchanged with this page result." } }, "required": [ "url" ], "additionalProperties": false, "description": "A page to scrape, with optional data for matching results." }, "minItems": 1, "maxItems": 25000, "description": "Pages to scrape. Maximum 25000." }, "options": { "type": "object", "properties": { "useMainContentOnly": { "type": "boolean", "default": false, "description": "Return the main content without navigation or footers." }, "pdf": { "type": "object", "properties": { "shouldParse": { "type": "boolean", "default": true, "description": "When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and a 400 PDF_SKIPPED is returned." }, "start": { "type": "integer", "minimum": 1, "description": "First 1-based PDF page to parse. When omitted, parsing starts at the first page." }, "end": { "type": "integer", "minimum": 1, "description": "Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided." }, "ocr": { "type": "boolean", "default": false, "description": "When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs." } }, "default": { "shouldParse": true, "ocr": false }, "description": "PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range." }, "includeSelectors": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "maxItems": 50, "description": "Keep only the subtrees matching these CSS selectors. Filtered pages are always fetched fresh, ignoring `maxAgeMs`." }, "excludeSelectors": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "maxItems": 50, "description": "Remove elements matching these CSS selectors. Applied after `includeSelectors`, so an element matching both is removed." }, "waitForMs": { "type": "integer", "minimum": 0, "maximum": 15000, "description": "How long to wait after initial page load, in milliseconds. `0` waits 500 ms." }, "settleAnimations": { "type": "boolean", "default": false, "description": "Wait briefly for CSS and transition animations to settle before extraction, on pages that render in a browser." }, "country": { "$ref": "#/components/schemas/BrowserCountryCode" }, "maxAgeMs": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2592000000, "default": 86400000, "description": "Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh." } }, "default": { "useMainContentOnly": false, "pdf": { "shouldParse": true, "ocr": false }, "settleAnimations": false, "maxAgeMs": 86400000 }, "additionalProperties": false, "description": "Options for HTML output." } }, "required": [ "format", "urls" ], "additionalProperties": false, "description": "Scrape the listed pages as HTML.", "title": "HTML" } ], "discriminator": { "propertyName": "format" }, "title": "Scrape data", "description": "Pages to scrape and their output format." } }, "required": [ "mode", "data" ], "additionalProperties": false, "title": "Scrape", "description": "Scrape up to 25K URLs in one batch." }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "crawl" ], "description": "Discover and scrape pages from `data.source`." }, "data": { "oneOf": [ { "type": "object", "properties": { "format": { "type": "string", "enum": [ "markdown" ], "description": "Return page content as Markdown." }, "source": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "start_url" ], "description": "Start from one page." }, "url": { "type": "string", "minLength": 1, "description": "Page where crawling begins. A URL without a scheme is read as https://.", "example": "https://example.com/docs" }, "controls": { "type": "object", "properties": { "maxUrls": { "type": "integer", "minimum": 1, "maximum": 25000, "default": 100, "description": "Maximum pages to fetch. Unused reserved credits are refunded. Maximum 25000." }, "maxDepth": { "type": "integer", "minimum": 0, "maximum": 50, "description": "Maximum link depth. Source pages are depth 0. No limit when omitted." }, "followSubdomains": { "type": "boolean", "default": false, "description": "Follow links to subdomains." }, "regex": { "type": "string", "maxLength": 256, "description": "RE2 pattern for URLs to include. The `start_url` itself is always included.", "example": "^https://example\\.com/docs/" } }, "default": { "maxUrls": 100, "followSubdomains": false }, "additionalProperties": false, "description": "Limits and filters for page discovery." } }, "required": [ "type", "url" ], "additionalProperties": false, "description": "Discover pages by following links from one URL.", "title": "Start URL" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "sitemap" ], "description": "Scrape the URLs in the domain's sitemap." }, "domain": { "type": "string", "minLength": 3, "description": "Domain whose sitemap lists the pages to scrape. A full URL is reduced to its domain.", "example": "example.com" }, "controls": { "type": "object", "properties": { "maxUrls": { "type": "integer", "minimum": 1, "maximum": 25000, "default": 100, "description": "Maximum pages to fetch. Unused reserved credits are refunded. Maximum 25000." }, "regex": { "type": "string", "maxLength": 256, "description": "RE2 pattern; only sitemap URLs matching it are scraped.", "example": "^https://example\\.com/docs/" } }, "default": { "maxUrls": 100 }, "additionalProperties": false, "description": "Limits and filters for the sitemap URLs. A sitemap batch scrapes exactly those URLs and never follows links off them, so there is no crawl depth here." } }, "required": [ "type", "domain" ], "additionalProperties": false, "description": "Scrape the pages listed in a domain's sitemap. Links on those pages are not followed.", "title": "Sitemap" } ], "discriminator": { "propertyName": "type" }, "title": "Crawl source", "description": "How to find pages to crawl." }, "options": { "type": "object", "properties": { "includeLinks": { "type": "boolean", "default": true, "description": "Include links in the Markdown." }, "includeImages": { "type": "boolean", "default": false, "description": "Include image references in the Markdown." }, "shortenBase64Images": { "type": "boolean", "default": true, "description": "Shorten inline base64 image data." }, "useMainContentOnly": { "type": "boolean", "default": false, "description": "Return the main content without navigation or footers." }, "includeHTML": { "type": "boolean", "default": false, "description": "Also include each page's HTML in its result record, as an `html` field alongside the Markdown." }, "pdf": { "type": "object", "properties": { "shouldParse": { "type": "boolean", "default": true, "description": "When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and a 400 PDF_SKIPPED is returned." }, "start": { "type": "integer", "minimum": 1, "description": "First 1-based PDF page to parse. When omitted, parsing starts at the first page." }, "end": { "type": "integer", "minimum": 1, "description": "Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided." }, "ocr": { "type": "boolean", "default": false, "description": "When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs." } }, "default": { "shouldParse": true, "ocr": false }, "description": "PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range." }, "includeSelectors": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "maxItems": 50, "description": "Keep only the subtrees matching these CSS selectors. Filtered pages are always fetched fresh, ignoring `maxAgeMs`." }, "excludeSelectors": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "maxItems": 50, "description": "Remove elements matching these CSS selectors. Applied after `includeSelectors`, so an element matching both is removed." }, "waitForMs": { "type": "integer", "minimum": 0, "maximum": 15000, "description": "How long to wait after initial page load, in milliseconds. `0` waits 500 ms." }, "settleAnimations": { "type": "boolean", "default": false, "description": "Wait briefly for CSS and transition animations to settle before extraction, on pages that render in a browser." }, "country": { "$ref": "#/components/schemas/BrowserCountryCode" }, "maxAgeMs": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2592000000, "default": 86400000, "description": "Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh." } }, "default": { "includeLinks": true, "includeImages": false, "shortenBase64Images": true, "useMainContentOnly": false, "includeHTML": false, "pdf": { "shouldParse": true, "ocr": false }, "settleAnimations": false, "maxAgeMs": 86400000 }, "additionalProperties": false, "description": "Options for Markdown output." } }, "required": [ "format", "source" ], "additionalProperties": false, "title": "Markdown", "description": "Crawl pages and return Markdown." }, { "type": "object", "properties": { "format": { "type": "string", "enum": [ "html" ], "description": "Return page content as HTML." }, "source": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "start_url" ], "description": "Start from one page." }, "url": { "type": "string", "minLength": 1, "description": "Page where crawling begins. A URL without a scheme is read as https://.", "example": "https://example.com/docs" }, "controls": { "type": "object", "properties": { "maxUrls": { "type": "integer", "minimum": 1, "maximum": 25000, "default": 100, "description": "Maximum pages to fetch. Unused reserved credits are refunded. Maximum 25000." }, "maxDepth": { "type": "integer", "minimum": 0, "maximum": 50, "description": "Maximum link depth. Source pages are depth 0. No limit when omitted." }, "followSubdomains": { "type": "boolean", "default": false, "description": "Follow links to subdomains." }, "regex": { "type": "string", "maxLength": 256, "description": "RE2 pattern for URLs to include. The `start_url` itself is always included.", "example": "^https://example\\.com/docs/" } }, "default": { "maxUrls": 100, "followSubdomains": false }, "additionalProperties": false, "description": "Limits and filters for page discovery." } }, "required": [ "type", "url" ], "additionalProperties": false, "description": "Discover pages by following links from one URL.", "title": "Start URL" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "sitemap" ], "description": "Scrape the URLs in the domain's sitemap." }, "domain": { "type": "string", "minLength": 3, "description": "Domain whose sitemap lists the pages to scrape. A full URL is reduced to its domain.", "example": "example.com" }, "controls": { "type": "object", "properties": { "maxUrls": { "type": "integer", "minimum": 1, "maximum": 25000, "default": 100, "description": "Maximum pages to fetch. Unused reserved credits are refunded. Maximum 25000." }, "regex": { "type": "string", "maxLength": 256, "description": "RE2 pattern; only sitemap URLs matching it are scraped.", "example": "^https://example\\.com/docs/" } }, "default": { "maxUrls": 100 }, "additionalProperties": false, "description": "Limits and filters for the sitemap URLs. A sitemap batch scrapes exactly those URLs and never follows links off them, so there is no crawl depth here." } }, "required": [ "type", "domain" ], "additionalProperties": false, "description": "Scrape the pages listed in a domain's sitemap. Links on those pages are not followed.", "title": "Sitemap" } ], "discriminator": { "propertyName": "type" }, "title": "Crawl source", "description": "How to find pages to crawl." }, "options": { "type": "object", "properties": { "useMainContentOnly": { "type": "boolean", "default": false, "description": "Return the main content without navigation or footers." }, "pdf": { "type": "object", "properties": { "shouldParse": { "type": "boolean", "default": true, "description": "When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and a 400 PDF_SKIPPED is returned." }, "start": { "type": "integer", "minimum": 1, "description": "First 1-based PDF page to parse. When omitted, parsing starts at the first page." }, "end": { "type": "integer", "minimum": 1, "description": "Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided." }, "ocr": { "type": "boolean", "default": false, "description": "When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs." } }, "default": { "shouldParse": true, "ocr": false }, "description": "PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range." }, "includeSelectors": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "maxItems": 50, "description": "Keep only the subtrees matching these CSS selectors. Filtered pages are always fetched fresh, ignoring `maxAgeMs`." }, "excludeSelectors": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "maxItems": 50, "description": "Remove elements matching these CSS selectors. Applied after `includeSelectors`, so an element matching both is removed." }, "waitForMs": { "type": "integer", "minimum": 0, "maximum": 15000, "description": "How long to wait after initial page load, in milliseconds. `0` waits 500 ms." }, "settleAnimations": { "type": "boolean", "default": false, "description": "Wait briefly for CSS and transition animations to settle before extraction, on pages that render in a browser." }, "country": { "$ref": "#/components/schemas/BrowserCountryCode" }, "maxAgeMs": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2592000000, "default": 86400000, "description": "Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh." } }, "default": { "useMainContentOnly": false, "pdf": { "shouldParse": true, "ocr": false }, "settleAnimations": false, "maxAgeMs": 86400000 }, "additionalProperties": false, "description": "Options for HTML output." } }, "required": [ "format", "source" ], "additionalProperties": false, "title": "HTML", "description": "Crawl pages and return HTML." } ], "discriminator": { "propertyName": "format" }, "title": "Crawl data", "description": "Crawl source and output format." } }, "required": [ "mode", "data" ], "additionalProperties": false, "title": "Crawl", "description": "Crawl pages starting from a URL or from a domain's sitemap." } ], "discriminator": { "propertyName": "mode" }, "title": "Batch input", "description": "Choose a URL list or a site crawl." }, "webhookUrl": { "type": "string", "description": "Legacy URL notified when the batch finishes. Preserves one best-effort attempt. Cannot be combined with webhook." }, "webhook": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "retry": { "$ref": "#/components/schemas/WebhookRetry" } }, "required": [ "url" ], "additionalProperties": false, "description": "Completion webhook settings. Cannot be combined with webhookUrl. Omitting retry preserves legacy delivery; retry: {} opts into durable retries." }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "maxItems": 20, "description": "Tags stored on the batch. Filter the batch list by them later.", "example": [ "docs", "competitor" ] } }, "required": [ "input" ], "title": "Submit batch request", "description": "Create an asynchronous scraping job." }, "BatchPageErrorCount": { "type": "object", "properties": { "code": { "type": "string", "example": "WEBSITE_ACCESS_ERROR", "description": "Error code for these failures." }, "count": { "type": "integer", "example": 204, "description": "Pages that failed with this code." } }, "required": [ "code", "count" ], "x-stainless-model": "batch.page_error_count", "description": "Page failures sharing one error code." }, "BatchFailure": { "type": "object", "properties": { "code": { "type": "string", "example": "stalled", "description": "Why the batch itself stopped." }, "message": { "type": "string", "example": "Batch stopped reporting progress and was finalized automatically", "description": "Human-readable explanation." } }, "required": [ "code", "message" ], "x-stainless-model": "batch.failure", "description": "A failure of the batch as a whole, distinct from the per-page failures in `page_errors`." }, "BatchNullableFailure": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/BatchFailure" } ] }, { "type": "null" } ], "description": "Why the batch as a whole stopped. Null unless `status` is `failed`. Individual pages that failed are counted in `page_errors` instead." }, "BatchCrawlControls": { "type": "object", "properties": { "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "start_url" ] }, "url": { "type": "string", "example": "https://example.com/docs", "description": "Page the crawl started from." } }, "required": [ "type", "url" ], "title": "Start URL", "description": "The crawl discovered pages by following links from one URL." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "sitemap" ] }, "domain": { "type": "string", "example": "example.com", "description": "Domain whose sitemap supplied the pages." } }, "required": [ "type", "domain" ], "title": "Sitemap", "description": "The crawl scraped the pages listed in the domain's sitemap." } ], "description": "Where the crawl started." }, "max_pages": { "type": "integer", "example": 500, "description": "The `maxUrls` submitted with the crawl. A sitemap crawl scrapes only the URLs its sitemap actually lists, up to this many, so `input.reserved` is often lower." }, "max_depth": { "type": [ "integer", "null" ], "example": 0, "description": "Link depth limit. Always 0 for a sitemap crawl, which never follows links off its URLs; null when a `start_url` crawl set no limit." }, "follow_subdomains": { "type": "boolean", "description": "Whether links to subdomains were followed. Always false for a sitemap crawl." }, "url_pattern": { "type": [ "string", "null" ], "example": "^https://example\\.com/docs/", "description": "RE2 pattern URLs had to match to be crawled. Null when the crawl set none." } }, "required": [ "source", "max_pages", "max_depth", "follow_subdomains", "url_pattern" ], "x-stainless-model": "batch.crawl_controls", "title": "Crawl controls", "description": "The crawl controls as submitted, so the limits requested can be compared against what the crawl reached." }, "BatchNullableCrawlControls": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/BatchCrawlControls" } ] }, { "type": "null" } ], "description": "How the crawl was configured. Null for scrape batches." }, "BatchIntake": { "type": "object", "properties": { "reserved": { "type": "integer", "example": 24817, "description": "Pages credits were reserved for. Everything else — progress, the refund, the completion percentage — is measured against this." }, "reserved_is_ceiling": { "type": "boolean", "example": false, "description": "Whether `reserved` is an upper bound the batch may finish under. True only for a crawl that follows links, whose reachable page count is unknowable until it runs. False for a scrape and for a sitemap crawl, where `reserved` is an exact page count." }, "submitted": { "type": [ "integer", "null" ], "example": 25000, "description": "URLs in the list you sent, before validation and de-duplication. Null for a crawl, which is given a source rather than a list." }, "duplicates": { "type": "integer", "example": 183, "description": "URLs dropped before reserving because another entry resolved to the same page. Non-zero for sitemap crawls too, whose sitemaps routinely list a page more than once." }, "invalid": { "type": [ "integer", "null" ], "example": 0, "description": "URLs from your list rejected as unusable; the same ones are itemised in `invalid_urls` at submission. Null for a crawl — a crawl that resolves no usable page is rejected outright with a 400 rather than accepted with an empty list." } }, "required": [ "reserved", "reserved_is_ceiling", "submitted", "duplicates", "invalid" ], "x-stainless-model": "batch.intake", "description": "What submission took in, and what it charged for." }, "Batch": { "type": "object", "properties": { "id": { "type": "string", "example": "batch_9f2c8a", "description": "Batch ID used to retrieve or cancel the job." }, "status": { "type": "string", "enum": [ "queued", "running", "cancelling", "completed", "cancelled", "failed" ], "description": "Current state. `completed`, `cancelled`, and `failed` are final." }, "mode": { "type": "string", "enum": [ "scrape", "crawl" ], "description": "How pages were selected. Matches `input.mode` on the submit request." }, "format": { "type": "string", "enum": [ "markdown", "html" ], "description": "What each page is returned as. Matches `input.data.format` on the submit request." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags stored on the batch at submission.", "example": [ "docs" ] }, "crawl": { "$ref": "#/components/schemas/BatchNullableCrawlControls" }, "input": { "$ref": "#/components/schemas/BatchIntake" }, "progress": { "type": "object", "properties": { "succeeded": { "type": "integer", "example": 18091, "description": "Pages scraped successfully." }, "failed": { "type": "integer", "example": 311, "description": "Pages that could not be scraped." }, "pending": { "type": "integer", "example": 6415, "description": "Reserved pages not yet attempted. A cancelled batch keeps reporting the URLs it never reached; a crawl whose `input.reserved_is_ceiling` is true reports 0 once final, because its unspent budget was never real pages." } }, "required": [ "succeeded", "failed", "pending" ], "description": "Pages attempted so far. Use `status` to check completion." }, "credits": { "type": "object", "properties": { "reserved": { "type": "integer", "example": 24817, "description": "Credits debited from your balance the moment the batch was accepted. This is a charge, not a forecast — the whole amount leaves the balance up front." }, "refunded": { "type": "integer", "example": 6726, "description": "Credits returned for pages that did not succeed. Stays 0 until the batch reaches a final status, then settles in one movement." }, "ocr_charged": { "type": "integer", "example": 42, "description": "Credits charged for PDF pages recovered by OCR (pdf.ocr=true), 1 per recovered page, on top of `reserved`. Stays 0 until the batch settles." }, "net": { "type": "integer", "example": 18091, "description": "`reserved` minus `refunded` plus `ocr_charged` — what the batch has cost so far. Equal to `reserved` until the batch settles." } }, "required": [ "reserved", "refunded", "ocr_charged", "net" ], "description": "What this batch has done to your credit balance." }, "timing": { "type": "object", "properties": { "created_at": { "type": "string", "description": "When the batch was created." }, "started_at": { "type": [ "string", "null" ], "description": "When processing started. Null while queued." }, "completed_at": { "type": [ "string", "null" ], "description": "When processing finished. Null while active." } }, "required": [ "created_at", "started_at", "completed_at" ] }, "page_errors": { "type": "array", "items": { "$ref": "#/components/schemas/BatchPageErrorCount" }, "description": "Individual page failures grouped by error code, sorted by count. Unrelated to `failure`, which is the batch itself failing." }, "failure": { "$ref": "#/components/schemas/BatchNullableFailure" }, "results": { "type": [ "object", "null" ], "properties": { "expires_at": { "type": "string", "description": "When the download URLs expire." }, "files": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Temporary URL for a gzipped NDJSON file." }, "items": { "type": "integer", "description": "Results in this file." }, "bytes": { "type": "integer", "description": "Compressed file size in bytes." } }, "required": [ "url", "items", "bytes" ] }, "description": "Result files. Order is not guaranteed." } }, "required": [ "expires_at", "files" ], "description": "Download links, available once the batch reaches a final status and null before then. GET /batch/{batch_id}/results serves the same records as paginated JSON." } }, "required": [ "id", "status", "mode", "format", "tags", "crawl", "input", "progress", "credits", "timing", "page_errors", "failure", "results" ], "title": "Batch", "description": "An asynchronous web scraping job." }, "BatchDetail": { "type": "object", "properties": { "invalid_urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Rejected URL." }, "reason": { "type": "string", "description": "Why it was rejected.", "example": "Must be a public http:// or https:// URL" } }, "required": [ "url", "reason" ] }, "description": "Rejected URLs, up to 100. These are not charged." }, "webhook_delivery_id": { "type": "string", "description": "Batch completion delivery ID, when available." } }, "required": [ "invalid_urls" ], "title": "Batch detail", "description": "What a single-batch read adds to the batch itself." }, "BatchCancelling": { "type": "object", "properties": { "id": { "type": "string", "example": "batch_9f2c8a", "description": "Batch ID." }, "status": { "type": "string", "enum": [ "cancelling" ], "description": "Always `cancelling`. Work already in flight finishes; the batch reaches `cancelled` shortly after." }, "mode": { "type": "string", "enum": [ "scrape", "crawl" ], "description": "How pages were selected." }, "format": { "type": "string", "enum": [ "markdown", "html" ], "description": "What each page is returned as." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags stored on the batch at submission.", "example": [ "docs" ] }, "crawl": { "$ref": "#/components/schemas/BatchNullableCrawlControls" }, "input": { "$ref": "#/components/schemas/BatchIntake" }, "progress": { "type": "object", "properties": { "succeeded": { "type": "integer", "example": 4120, "description": "Pages scraped successfully before the request landed." }, "failed": { "type": "integer", "example": 37, "description": "Pages that could not be scraped before the request landed." }, "pending": { "type": "integer", "example": 20660, "description": "Reserved pages that will now be skipped, and refunded when the batch settles." } }, "required": [ "succeeded", "failed", "pending" ], "description": "How far the batch got before cancellation." }, "credits": { "type": "object", "properties": { "reserved": { "type": "integer", "example": 24817, "description": "Credits debited at submission. The unspent remainder is refunded once the batch settles — read `credits.refunded` from GET /batch/{batch_id} then." } }, "required": [ "reserved" ], "description": "What this batch cost so far." }, "timing": { "type": "object", "properties": { "created_at": { "type": "string", "description": "When the batch was created." }, "started_at": { "type": [ "string", "null" ], "description": "When processing started. Null if it was cancelled while still queued." } }, "required": [ "created_at", "started_at" ], "description": "There is no finish time yet — the batch is still winding down." }, "page_errors": { "type": "array", "items": { "$ref": "#/components/schemas/BatchPageErrorCount" }, "description": "Page failures so far, grouped by error code and sorted by count." } }, "required": [ "id", "status", "mode", "format", "tags", "crawl", "input", "progress", "credits", "timing", "page_errors" ], "title": "Cancelling batch", "description": "Acknowledgement that cancellation was requested. The batch has not settled, so it carries no results, no failure, no refund and no finish time; poll GET /batch/{batch_id} for those." }, "BatchAccepted": { "type": "object", "properties": { "id": { "type": "string", "example": "batch_9f2c8a", "description": "Batch ID. Poll GET /batch/{batch_id} with it." }, "status": { "type": "string", "enum": [ "queued" ], "description": "Always `queued`. An accepted batch has not started yet." }, "mode": { "type": "string", "enum": [ "scrape", "crawl" ], "description": "How pages will be selected." }, "format": { "type": "string", "enum": [ "markdown", "html" ], "description": "What each page will be returned as." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags stored on the batch.", "example": [ "docs" ] }, "crawl": { "$ref": "#/components/schemas/BatchNullableCrawlControls" }, "input": { "$ref": "#/components/schemas/BatchIntake" }, "credits": { "type": "object", "properties": { "reserved": { "type": "integer", "example": 24817, "description": "Credits just debited from your balance. Whatever the batch does not spend is refunded when it settles." } }, "required": [ "reserved" ], "description": "What accepting this batch cost." }, "created_at": { "type": "string", "description": "When the batch was created." }, "invalid_urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Rejected URL." }, "reason": { "type": "string", "description": "Why it was rejected.", "example": "Must be a public http:// or https:// URL" } }, "required": [ "url", "reason" ] }, "description": "Rejected URLs, up to 100. These are not charged." }, "cache_metadata": { "$ref": "#/components/schemas/CacheMetadata" }, "webhook_secret": { "type": "string", "description": "Signing secret for the completion webhook, returned only here and never again. Store it now; it is not repeated by GET /batch/{batch_id}." } }, "required": [ "id", "status", "mode", "format", "tags", "crawl", "input", "credits", "created_at", "invalid_urls", "cache_metadata" ], "title": "Accepted batch" }, "BatchCompletedWebhookPayload": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "batch.completed" ], "description": "Which final status the batch reached. Mirrors the `X-Context-Event` header." }, "id": { "type": "string", "example": "evt_123", "description": "Unique event ID. Mirrors the `X-Context-Id` header." }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-09T18:00:12.000Z", "description": "When the delivery was generated." }, "data": { "type": "object", "properties": { "batch": { "allOf": [ { "$ref": "#/components/schemas/Batch" } ], "description": "The settled batch, identical to the body of GET /batch/{batch_id} minus `invalid_urls`. Its `results` carry download links that expire, so fetch them promptly or re-read the batch." } }, "required": [ "batch" ] } }, "required": [ "event", "id", "created_at", "data" ], "title": "Batch completed webhook payload", "description": "Payload sent when a batch completes." }, "BatchFailedWebhookPayload": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "batch.failed" ], "description": "Which final status the batch reached. Mirrors the `X-Context-Event` header." }, "id": { "type": "string", "example": "evt_123", "description": "Unique event ID. Mirrors the `X-Context-Id` header." }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-09T18:00:12.000Z", "description": "When the delivery was generated." }, "data": { "type": "object", "properties": { "batch": { "allOf": [ { "$ref": "#/components/schemas/Batch" } ], "description": "The settled batch, identical to the body of GET /batch/{batch_id} minus `invalid_urls`. Its `results` carry download links that expire, so fetch them promptly or re-read the batch." } }, "required": [ "batch" ] } }, "required": [ "event", "id", "created_at", "data" ], "title": "Batch failed webhook payload", "description": "Payload sent when a batch fails." }, "BatchCancelledWebhookPayload": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "batch.cancelled" ], "description": "Which final status the batch reached. Mirrors the `X-Context-Event` header." }, "id": { "type": "string", "example": "evt_123", "description": "Unique event ID. Mirrors the `X-Context-Id` header." }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-09T18:00:12.000Z", "description": "When the delivery was generated." }, "data": { "type": "object", "properties": { "batch": { "allOf": [ { "$ref": "#/components/schemas/Batch" } ], "description": "The settled batch, identical to the body of GET /batch/{batch_id} minus `invalid_urls`. Its `results` carry download links that expire, so fetch them promptly or re-read the batch." } }, "required": [ "batch" ] } }, "required": [ "event", "id", "created_at", "data" ], "title": "Batch cancelled webhook payload", "description": "Payload sent when a batch is cancelled." }, "BatchResultRecord": { "oneOf": [ { "type": "object", "properties": { "url": { "type": "string", "example": "https://example.com/products/anvil", "description": "URL as submitted, or as discovered by the crawl." }, "itemId": { "type": "string", "example": "sku-1", "description": "Caller-supplied identifier echoed from submission." }, "meta": { "type": "object", "additionalProperties": {}, "description": "Caller-supplied metadata echoed from submission." }, "status": { "type": "string", "enum": [ "ok" ], "description": "The page was scraped." }, "http_status": { "type": [ "integer", "null" ], "example": 200, "description": "HTTP status of the final response, when known." }, "final_url": { "type": "string", "description": "URL the content was read from, after redirects." }, "markdown": { "type": "string", "description": "Page content as Markdown. Present on markdown batches." }, "html": { "type": "string", "description": "Page HTML. Present on html batches, and on markdown batches submitted with `options.includeHTML`." }, "metadata": { "$ref": "#/components/schemas/PageMetadata" }, "cache_metadata": { "$ref": "#/components/schemas/CacheMetadata" }, "ocr_pages": { "type": "integer", "example": 3, "description": "PDF pages of this document recovered by OCR (pdf.ocr=true). Each recovered page bills 1 credit on top of the page base credit; absent when no OCR ran." } }, "required": [ "url", "status", "http_status", "final_url", "metadata", "cache_metadata" ], "title": "Scraped page", "description": "A page the batch fetched successfully." }, { "type": "object", "properties": { "url": { "type": "string", "example": "https://example.com/products/anvil", "description": "URL as submitted, or as discovered by the crawl." }, "itemId": { "type": "string", "example": "sku-1", "description": "Caller-supplied identifier echoed from submission." }, "meta": { "type": "object", "additionalProperties": {}, "description": "Caller-supplied metadata echoed from submission." }, "status": { "type": "string", "enum": [ "error" ], "description": "The page could not be scraped." }, "error_code": { "type": "string", "example": "NOT_FOUND", "description": "Why the page failed." }, "message": { "type": "string", "example": "Page returned 404", "description": "Human-readable failure detail." } }, "required": [ "url", "status", "error_code", "message" ], "title": "Failed page", "description": "A page the batch could not fetch." } ], "discriminator": { "propertyName": "status" }, "title": "Batch result record", "description": "One page outcome from a finished batch." }, "LogEntry": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Request ID of the logged API call." }, "timestamp": { "type": "string", "format": "date-time", "description": "When the request completed." }, "method": { "type": "string", "description": "HTTP method.", "example": "GET" }, "path": { "type": "string", "description": "Endpoint path as called.", "example": "/v1/brand/retrieve" }, "status_code": { "type": "integer", "description": "HTTP status code returned.", "example": 500 }, "error_code": { "type": [ "string", "null" ], "description": "The `error_code` from the response, or null on success.", "example": "WEBSITE_ACCESS_ERROR" }, "latency_ms": { "type": "number", "description": "Server-side processing time in milliseconds." }, "credits_used": { "type": "integer", "description": "Credits charged for this request." }, "key_id": { "type": [ "string", "null" ], "description": "ID of the API key that made the request." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Request tags supplied by the caller." }, "zdr": { "type": "boolean", "description": "Whether the request was made under zero data retention." } }, "required": [ "request_id", "timestamp", "method", "path", "status_code", "error_code", "latency_ms", "credits_used", "key_id", "tags", "zdr" ] }, "LogDetail": { "allOf": [ { "$ref": "#/components/schemas/LogEntry" }, { "type": "object", "properties": { "input": { "type": "object", "properties": { "query": { "type": "object", "additionalProperties": {}, "description": "Query parameters as sent." }, "body": { "description": "Request body with credentials and uploaded content redacted." } }, "required": [ "query" ], "description": "What was sent with the request." }, "response": { "description": "The retained JSON response with credentials redacted, or null when unavailable." }, "user_agent": { "type": [ "string", "null" ], "description": "User-Agent header of the request." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" } }, "required": [ "input", "user_agent" ] } ] }, "ListLogsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" }, "description": "Log entries, newest first." }, "page": { "type": "integer", "description": "Current page number." }, "limit": { "type": "integer", "description": "Entries per page." }, "has_more": { "type": "boolean", "description": "Whether a next page exists." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "page", "limit", "has_more", "request_id" ] }, "GetLogResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LogDetail" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "request_id" ] }, "WebhookAttempt": { "type": "object", "properties": { "attempt": { "type": "integer", "minimum": 1, "description": "Attempt number, starting at 1." }, "trigger": { "type": "string", "enum": [ "initial", "automatic", "manual" ], "description": "What started this attempt." }, "url": { "type": "string", "format": "uri", "description": "URL used for this attempt." }, "started_at": { "type": "string", "format": "date-time", "description": "Attempt start time." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Completion time, or null while in progress." }, "http_status": { "type": [ "integer", "null" ], "description": "HTTP response status, or null if no response was received." }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "description": "Error code." }, "message": { "type": "string", "description": "Error details." } }, "required": [ "code", "message" ], "description": "Attempt error, or null if none." } }, "required": [ "attempt", "trigger", "url", "started_at", "completed_at", "http_status", "error" ] }, "WebhookDeliverySummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Delivery ID." }, "event": { "type": "string", "enum": [ "batch.completed", "batch.failed", "batch.cancelled", "change.detected", "run.completed" ], "description": "Webhook event type." }, "source": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "batch" ], "description": "Delivery source." }, "batch_id": { "type": "string", "description": "Batch ID." } }, "required": [ "type", "batch_id" ], "title": "Batch" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "monitor" ], "description": "Delivery source." }, "monitor_id": { "type": "string", "description": "Monitor ID." }, "run_id": { "type": "string", "description": "Monitor run ID." } }, "required": [ "type", "monitor_id", "run_id" ], "title": "Monitor" } ], "description": "Batch or monitor run that produced the event." }, "url": { "type": "string", "format": "uri", "description": "Webhook destination URL." }, "status": { "type": "string", "enum": [ "pending", "delivering", "retrying", "delivered", "failed", "cancelled" ], "description": "Current delivery status." }, "created_at": { "type": "string", "format": "date-time", "description": "Event creation time." }, "retry_expires_at": { "type": "string", "format": "date-time", "description": "Manual retry deadline, seven days after event creation." }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last successful delivery time, or null if never delivered." }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Next scheduled attempt, or null if none." }, "last_error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "description": "Error code." }, "message": { "type": "string", "description": "Error details." } }, "required": [ "code", "message" ], "description": "Latest delivery error, or null if none." } }, "required": [ "id", "event", "source", "url", "status", "created_at", "retry_expires_at", "delivered_at", "next_attempt_at", "last_error" ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "description": "Delivery ID." }, "event": { "type": "string", "enum": [ "batch.completed", "batch.failed", "batch.cancelled", "change.detected", "run.completed" ], "description": "Webhook event type." }, "source": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "batch" ], "description": "Delivery source." }, "batch_id": { "type": "string", "description": "Batch ID." } }, "required": [ "type", "batch_id" ], "title": "Batch" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "monitor" ], "description": "Delivery source." }, "monitor_id": { "type": "string", "description": "Monitor ID." }, "run_id": { "type": "string", "description": "Monitor run ID." } }, "required": [ "type", "monitor_id", "run_id" ], "title": "Monitor" } ], "description": "Batch or monitor run that produced the event." }, "url": { "type": "string", "format": "uri", "description": "Webhook destination URL." }, "status": { "type": "string", "enum": [ "pending", "delivering", "retrying", "delivered", "failed", "cancelled" ], "description": "Current delivery status." }, "created_at": { "type": "string", "format": "date-time", "description": "Event creation time." }, "retry_expires_at": { "type": "string", "format": "date-time", "description": "Manual retry deadline, seven days after event creation." }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last successful delivery time, or null if never delivered." }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Next scheduled attempt, or null if none." }, "last_error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "description": "Error code." }, "message": { "type": "string", "description": "Error details." } }, "required": [ "code", "message" ], "description": "Latest delivery error, or null if none." }, "event_id": { "type": "string", "description": "Stable event ID for deduplicating received webhooks." }, "retry": { "allOf": [ { "$ref": "#/components/schemas/WebhookRetry" }, { "description": "Automatic retry settings for this event." } ] }, "last_attempt": { "anyOf": [ { "$ref": "#/components/schemas/WebhookAttempt" }, { "type": "null" } ], "description": "Latest attempt, or null if none." } }, "required": [ "id", "event", "source", "url", "status", "created_at", "retry_expires_at", "delivered_at", "next_attempt_at", "last_error", "event_id", "retry", "last_attempt" ] }, "RetryWebhookDeliveryResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Delivery ID." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "id", "request_id" ] }, "ListWebhookDeliveriesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliverySummary" }, "description": "Webhook deliveries." }, "has_more": { "type": "boolean", "description": "Whether more deliveries are available." }, "next_cursor": { "type": [ "string", "null" ], "description": "Next page cursor, or null on the last page." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "has_more", "next_cursor", "request_id" ] }, "ListWebhookAttemptsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookAttempt" }, "description": "Delivery attempts." }, "has_more": { "type": "boolean", "description": "Whether more attempts are available." }, "next_cursor": { "type": [ "string", "null" ], "description": "Next page cursor, or null on the last page." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "has_more", "next_cursor", "request_id" ] }, "NewsSearchEntityByName": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "name" ] }, "name": { "type": "string", "minLength": 2, "maxLength": 200, "description": "Company name." } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "Identify the company by name.", "title": "By Name" }, "NewsSearchEntityByDomain": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "domain" ] }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Company website domain, such as apple.com." } }, "required": [ "type", "domain" ], "additionalProperties": false, "description": "Identify the company by website domain.", "title": "By Domain" }, "NewsSearchEntityByTicker": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ticker" ] }, "ticker": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9.-]+$", "description": "Public-company ticker." }, "exchange": { "type": "string", "enum": [ "AMEX", "AMS", "AQS", "ASX", "ATH", "BER", "BME", "BRU", "BSE", "BUD", "BUE", "BVC", "CBOE", "CNQ", "CPH", "DFM", "DOH", "DUB", "DUS", "DXE", "EGX", "FSX", "HAM", "HEL", "HKSE", "HOSE", "ICE", "IOB", "IST", "JKT", "JNB", "JPX", "KLS", "KOE", "KSC", "KUW", "LIS", "LSE", "MCX", "MEX", "MIL", "MUN", "NASDAQ", "NEO", "NSE", "NYSE", "NZE", "OSL", "OTC", "PAR", "PNK", "PRA", "RIS", "SAO", "SAU", "SES", "SET", "SGO", "SHH", "SHZ", "SIX", "STO", "STU", "TAI", "TAL", "TLV", "TSX", "TSXV", "TWO", "VIE", "WSE", "XETRA" ], "description": "Stock exchange the ticker trades on, used to disambiguate tickers listed on multiple exchanges." } }, "required": [ "type", "ticker" ], "additionalProperties": false, "description": "Identify the company by stock ticker, optionally scoped to an exchange.", "title": "By Ticker" }, "NewsSearchEntityByIsin": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "isin" ] }, "isin": { "type": "string", "pattern": "^[A-Za-z]{2}[A-Za-z0-9]{9}[0-9]$", "description": "International Securities Identification Number." } }, "required": [ "type", "isin" ], "additionalProperties": false, "description": "Identify the company by International Securities Identification Number.", "title": "By ISIN" }, "WebScrapeAction": { "oneOf": [ { "$ref": "#/components/schemas/WebScrapeWaitAction" }, { "$ref": "#/components/schemas/WebScrapePerformAction" }, { "$ref": "#/components/schemas/WebScrapeScrollAction" } ], "discriminator": { "propertyName": "do", "mapping": { "wait": "#/components/schemas/WebScrapeWaitAction", "perform": "#/components/schemas/WebScrapePerformAction", "scroll": "#/components/schemas/WebScrapeScrollAction" } }, "description": "Browser action discriminated by `do`. Each variant exposes only its applicable fields." }, "WebScrapeWaitAction": { "type": "object", "properties": { "do": { "type": "string", "enum": [ "wait" ] }, "timeMs": { "type": "integer", "minimum": 0, "maximum": 30000 } }, "required": [ "do", "timeMs" ], "additionalProperties": false, "description": "Pause for a fixed number of milliseconds before continuing to the next action.", "title": "Wait" }, "WebScrapePerformAction": { "type": "object", "properties": { "do": { "type": "string", "enum": [ "perform" ] }, "action": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "do", "action" ], "additionalProperties": false, "description": "Resolve and perform one natural-language browser action.", "title": "Perform" }, "WebScrapeScrollAction": { "type": "object", "properties": { "do": { "type": "string", "enum": [ "scroll" ] }, "direction": { "type": "string", "enum": [ "up", "down", "left", "right" ], "description": "Direction to scroll. Defaults to down." }, "amount": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000 }, { "type": "string", "enum": [ "viewport", "max" ] } ], "description": "Pixels per scroll, one visible viewport, or the current scroll boundary. Defaults to viewport." }, "container": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "CSS selector for the first matching scroll container. Defaults to the page." }, "maxScrolls": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum scroll iterations. Stops early when scrolling and scrollable extent stop changing. Defaults to 1." } }, "required": [ "do" ], "additionalProperties": false, "description": "Scroll the page or a selected scrollable container, waiting adaptively for content and dimensions to settle after each iteration.", "title": "Scroll" } } } }