{ "openapi": "3.1.0", "info": { "title": "Context.dev API", "description": "Scrape, crawl, search, and monitor websites, and retrieve brand, people, and news data.", "version": "1.0.0" }, "servers": [ { "url": "https://api.context.dev/v1" } ], "tags": [ { "name": "Webhooks", "description": "Inspect and retry batch and monitor webhook deliveries." }, { "name": "Logs", "description": "Read your organization's API request logs." }, { "name": "Usage", "description": "Read your organization's credit balance and usage history." }, { "name": "Agent Feedback", "description": "Report API issues and documentation mismatches." }, { "name": "Batches", "description": "Scrape many pages or crawl a site asynchronously." }, { "name": "Monitors", "description": "Watch websites for exact or meaningful changes." }, { "name": "News", "description": "Search live and historical news about a company." }, { "name": "Answers", "description": "Answer a research task from the live web in the JSON shape you ask for." } ], "paths": { "/feedback": { "post": { "operationId": "submitFeedback", "summary": "Submit agent feedback", "tags": [ "Agent Feedback" ], "security": [ { "bearerAuth": [] } ], "description": "Report an API issue or documentation mismatch, including request IDs when available.", "x-mint": { "content": "0 credits" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "The request_id of the API call the feedback is about, from its response body or X-Request-Id header.", "example": "3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91" }, "category": { "type": "string", "enum": [ "bug", "docs_mismatch", "friction", "feature_gap", "quality_degradation", "other" ], "description": "Kind of issue." }, "note": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "What went wrong and what you expected instead.", "example": "Markdown drops the plan comparison table; expected all 4 rows." }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "The page the feedback is about, such as one page of a crawl or a docs page.", "example": "https://stripe.com/pricing" }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "category", "note" ], "additionalProperties": false }, "example": { "request_id": "3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91", "category": "bug", "note": "Markdown drops the plan comparison table; expected all 4 rows.", "url": "https://stripe.com/pricing" } } } }, "responses": { "200": { "description": "Feedback for this request_id was already recorded", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitFeedbackResponse" }, "example": { "feedback_id": "fb_8f14e45fceea167a5a36dedd4bea2543", "already_submitted": true, "key_metadata": { "credits_consumed": 0, "credits_remaining": 9500 }, "request_id": "b9bec613-44ed-4ee5-9d5b-3a87da5f8efe" } } } }, "201": { "description": "Feedback recorded", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitFeedbackResponse" }, "example": { "feedback_id": "fb_8f14e45fceea167a5a36dedd4bea2543", "already_submitted": false, "key_metadata": { "credits_consumed": 0, "credits_remaining": 9500 }, "request_id": "b9bec613-44ed-4ee5-9d5b-3a87da5f8efe" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "description": "Rate limit exceeded (10 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Feedback could not be saved. Retry the 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/org/logs": { "get": { "operationId": "listLogs", "summary": "List request logs", "tags": [ "Logs" ], "description": "List your organization’s request logs with filters and pagination. Logs also include batch settlements and monitor runs.", "security": [ { "bearerAuth": [] } ], "x-mint": { "content": "0 credits" }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/org/logs/{request_id}": { "get": { "operationId": "getLog", "summary": "Retrieve a request log", "tags": [ "Logs" ], "description": "Retrieve a request’s metadata, retained input, and response.", "security": [ { "bearerAuth": [] } ], "x-mint": { "content": "0 credits" }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/deliveries": { "post": { "operationId": "listWebhookDeliveries", "summary": "List webhook deliveries", "tags": [ "Webhooks" ], "description": "List batch and monitor webhook deliveries from the last 30 days.", "security": [ { "bearerAuth": [] } ], "x-mint": { "content": "0 credits" }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/deliveries/{delivery_id}": { "get": { "operationId": "getWebhookDelivery", "summary": "Retrieve a webhook delivery", "tags": [ "Webhooks" ], "description": "Retrieve a webhook delivery’s status and original payload.", "security": [ { "bearerAuth": [] } ], "x-mint": { "content": "0 credits" }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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 a delivery’s attempts, newest first.", "security": [ { "bearerAuth": [] } ], "x-mint": { "content": "0 credits" }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/deliveries/{delivery_id}/retry": { "post": { "operationId": "retryWebhookDelivery", "summary": "Retry a webhook delivery", "tags": [ "Webhooks" ], "description": "Resend the original payload using the source’s current URL and secret. Available for 7 days after the event.", "security": [ { "bearerAuth": [] } ], "x-mint": { "content": "0 credits" }, "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 even if the delivery already succeeded. Defaults to false." }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/web/scrape": { "post": { "operationId": "scrapeWeb", "summary": "Scrape Anything", "description": "Scrape anything from a URL on the internet. Returns the outputs you enable in formats. Handles PDFs, DOCX, PPT, XLSX, and 40 other file formats.", "tags": [ "Web Scraping" ], "security": [ { "bearerAuth": [] } ], "x-mint": { "content": "From 1 credit", "metadata": { "mode": "wide" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeRequest" }, "examples": { "Default": { "summary": "Markdown", "value": { "url": "https://example.com", "formats": { "markdown": true } } }, "Screenshot": { "summary": "Take a screenshot", "value": { "url": "https://example.com", "formats": { "screenshot": true } } }, "Highlights": { "summary": "Extract passages that answer a question", "value": { "url": "https://en.wikipedia.org/wiki/IEEE_Frank_Rosenblatt_Award", "formats": { "highlights": true }, "highlightsParams": { "query": "Who received the IEEE Frank Rosenblatt Award in 2010?" } } }, "Parse fields": { "summary": "Parse fields", "value": { "url": "https://example.com", "formats": { "parse": true }, "parseParams": { "rules": { "title": "h1" } } } }, "All outputs": { "summary": "Every output except JSON", "value": { "url": "https://example.com", "formats": { "html": true, "markdown": true, "screenshot": true, "images": true, "bytes": true, "parse": true, "highlights": true, "product": true }, "parseParams": { "rules": { "title": "h1" } }, "highlightsParams": { "query": "What is this page about?" } } }, "With options": { "summary": "Shared settings, specific params, and request controls", "value": { "url": "https://example.com", "formats": { "markdown": true, "screenshot": true, "images": true }, "sharedParams": { "theme": "dark", "waitFor": "main", "mainContentOnly": true, "excludeSelectors": [ "nav", "footer" ] }, "markdownParams": { "includeLinks": false }, "screenshotParams": { "area": "fullPage" }, "imageParams": { "enrich": [ "dimensions" ] }, "maxAgeMs": 0, "timeoutOpts": { "milliseconds": 60000, "behavior": "fail" }, "tags": [ "product-sync" ] } }, "Shared inputs": { "summary": "Country, headers, waiting, and freshness", "value": { "url": "https://example.com", "formats": { "screenshot": true, "images": true, "bytes": true }, "sharedParams": { "country": "US", "headers": { "Accept-Language": "en-US" }, "waitFor": 500 }, "maxAgeMs": 0 } }, "JSON extraction": { "summary": "Extract JSON with a schema", "value": { "url": "https://example.com", "formats": { "json": true }, "jsonParams": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Main heading." }, "isPlaceholder": { "type": "boolean", "description": "Whether the page is a placeholder domain." } }, "required": [ "title", "isPlaceholder" ], "additionalProperties": false }, "instructions": "Use the first heading as the title." } } }, "Product": { "summary": "Extract a product", "value": { "url": "https://example.com/products/travel-mug", "formats": { "product": true }, "productParams": { "dedupeImages": true } } } } } } }, "responses": { "200": { "description": "Every output key is present; check each output's `success`. Failed outputs include `error_code` and `message`.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeResponse" }, "examples": { "Default": { "summary": "Markdown", "value": { "url": "https://example.com/", "html": { "requested": false, "success": null, "data": null }, "markdown": { "requested": true, "success": true, "data": "# Example Domain" }, "screenshot": { "requested": false, "success": null, "data": null }, "images": { "requested": false, "success": null, "data": null }, "bytes": { "requested": false, "success": null, "data": null }, "parsed": { "requested": false, "success": null, "data": null }, "highlights": { "requested": false, "success": null, "data": null }, "json": { "requested": false, "success": null, "data": null }, "product": { "requested": false, "success": null, "data": null }, "metadata": { "sourceUrl": "https://example.com", "finalUrl": "https://example.com/", "title": "Example Domain" }, "cache_metadata": { "status": "miss", "age_ms": 0 }, "key_metadata": { "credits_consumed": 1, "credits_remaining": 999 }, "request_id": "d7aa1c3a-38d2-4fb5-92c8-0f0cac3efa37" } }, "Partial success": { "summary": "HTML and Markdown returned when a screenshot fails", "value": { "url": "https://example.com/", "isPartial": true, "html": { "requested": true, "success": true, "data": "

Example Domain

" }, "markdown": { "requested": true, "success": true, "data": "# Example Domain" }, "screenshot": { "requested": true, "success": false, "data": null, "error_code": "REQUEST_TIMEOUT", "message": "This output was not ready before the deadline. Raise timeoutOpts.milliseconds or retry." }, "images": { "requested": false, "success": null, "data": null }, "bytes": { "requested": false, "success": null, "data": null }, "parsed": { "requested": false, "success": null, "data": null }, "highlights": { "requested": false, "success": null, "data": null }, "json": { "requested": false, "success": null, "data": null }, "product": { "requested": false, "success": null, "data": null }, "metadata": { "sourceUrl": "https://example.com/", "finalUrl": "https://example.com/" }, "cache_metadata": { "status": "miss", "age_ms": 0 }, "request_id": "d7aa1c3a-38d2-4fb5-92c8-0f0cac3efa37" } }, "Screenshot": { "summary": "Screenshot", "value": { "url": "https://example.com/", "html": { "requested": false, "success": null, "data": null }, "markdown": { "requested": false, "success": null, "data": null }, "screenshot": { "requested": true, "success": true, "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9Y9ZQmcAAAAASUVORK5CYII=" }, "images": { "requested": false, "success": null, "data": null }, "bytes": { "requested": false, "success": null, "data": null }, "parsed": { "requested": false, "success": null, "data": null }, "highlights": { "requested": false, "success": null, "data": null }, "json": { "requested": false, "success": null, "data": null }, "product": { "requested": false, "success": null, "data": null }, "metadata": { "sourceUrl": "https://example.com/", "finalUrl": "https://example.com/" }, "cache_metadata": { "status": "miss", "age_ms": 0 }, "request_id": "d7aa1c3a-38d2-4fb5-92c8-0f0cac3efa37" } }, "All outputs": { "summary": "Every output except JSON", "value": { "url": "https://example.com/", "html": { "requested": true, "success": true, "data": "

Example Domain

" }, "markdown": { "requested": true, "success": true, "data": "# Example Domain" }, "screenshot": { "requested": true, "success": true, "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9Y9ZQmcAAAAASUVORK5CYII=" }, "images": { "requested": true, "success": true, "data": [ { "url": "https://example.com/hero.jpg", "alt": "Product photo" } ] }, "bytes": { "requested": true, "success": true, "data": { "contentType": "text/html", "base64": "PGgxPkV4YW1wbGUgRG9tYWluPC9oMT4=" } }, "parsed": { "requested": true, "success": true, "data": { "title": "Example Domain" } }, "highlights": { "requested": true, "success": true, "data": [ "Example Domain" ] }, "json": { "requested": false, "success": null, "data": null }, "product": { "requested": true, "success": true, "data": { "isProductPage": false, "product": null } }, "metadata": { "sourceUrl": "https://example.com/", "finalUrl": "https://example.com/" }, "cache_metadata": { "status": "miss", "age_ms": 0 }, "request_id": "d7aa1c3a-38d2-4fb5-92c8-0f0cac3efa37" } }, "Parse fields": { "summary": "Parsed fields without an HTML output", "value": { "url": "https://example.com/", "html": { "requested": false, "success": null, "data": null }, "markdown": { "requested": false, "success": null, "data": null }, "screenshot": { "requested": false, "success": null, "data": null }, "images": { "requested": false, "success": null, "data": null }, "bytes": { "requested": false, "success": null, "data": null }, "parsed": { "requested": true, "success": true, "data": { "title": "Example Domain" } }, "highlights": { "requested": false, "success": null, "data": null }, "json": { "requested": false, "success": null, "data": null }, "product": { "requested": false, "success": null, "data": null }, "metadata": { "sourceUrl": "https://example.com/", "finalUrl": "https://example.com/" }, "cache_metadata": { "status": "miss", "age_ms": 0 }, "request_id": "d7aa1c3a-38d2-4fb5-92c8-0f0cac3efa37" } }, "Shared inputs": { "summary": "Shared browser settings", "value": { "url": "https://example.com/", "html": { "requested": false, "success": null, "data": null }, "markdown": { "requested": false, "success": null, "data": null }, "screenshot": { "requested": true, "success": true, "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9Y9ZQmcAAAAASUVORK5CYII=" }, "images": { "requested": true, "success": true, "data": [ { "url": "https://example.com/hero.jpg", "alt": "Product photo" } ] }, "bytes": { "requested": true, "success": true, "data": { "contentType": "text/html; charset=utf-8", "base64": "PGh0bWw+PGJvZHk+PGgxPkV4YW1wbGUgRG9tYWluPC9oMT48L2JvZHk+PC9odG1sPg==" } }, "parsed": { "requested": false, "success": null, "data": null }, "highlights": { "requested": false, "success": null, "data": null }, "json": { "requested": false, "success": null, "data": null }, "product": { "requested": false, "success": null, "data": null }, "metadata": { "sourceUrl": "https://example.com/", "finalUrl": "https://example.com/" }, "cache_metadata": { "status": "miss", "age_ms": 0 }, "request_id": "d7aa1c3a-38d2-4fb5-92c8-0f0cac3efa37" } }, "JSON": { "summary": "JSON extraction", "value": { "url": "https://example.com/", "html": { "requested": false, "success": null, "data": null }, "markdown": { "requested": false, "success": null, "data": null }, "screenshot": { "requested": false, "success": null, "data": null }, "images": { "requested": false, "success": null, "data": null }, "bytes": { "requested": false, "success": null, "data": null }, "parsed": { "requested": false, "success": null, "data": null }, "json": { "requested": true, "success": true, "data": { "title": "Example Domain", "isPlaceholder": true } }, "highlights": { "requested": false, "success": null, "data": null }, "product": { "requested": false, "success": null, "data": null }, "metadata": { "sourceUrl": "https://example.com/", "finalUrl": "https://example.com/" }, "cache_metadata": { "status": "miss", "age_ms": 0 }, "request_id": "d7aa1c3a-38d2-4fb5-92c8-0f0cac3efa37" } }, "Product": { "summary": "Product detail page", "value": { "url": "https://example.com/products/travel-mug", "html": { "requested": false, "success": null, "data": null }, "markdown": { "requested": false, "success": null, "data": null }, "screenshot": { "requested": false, "success": null, "data": null }, "images": { "requested": false, "success": null, "data": null }, "bytes": { "requested": false, "success": null, "data": null }, "parsed": { "requested": false, "success": null, "data": null }, "product": { "requested": true, "success": true, "data": { "isProductPage": true, "product": { "name": "Insulated Travel Mug 16 oz", "description": "Double-wall stainless steel mug that keeps drinks hot for six hours.", "brand": "Example Goods", "sku": "MUG-16-BLK", "price": 24.99, "regularPrice": 29.99, "currency": "USD", "availability": "in_stock", "category": "Drinkware", "imageUrl": "https://example.com/images/travel-mug-black.jpg", "images": [ "https://example.com/images/travel-mug-black.jpg", "https://example.com/images/travel-mug-lid.jpg" ], "dimensions": [ "Height: 18 cm" ], "features": [ "Capacity: 16 oz", "Dishwasher safe" ], "targetAudience": [], "tags": [ "travel", "insulated" ], "variants": [ { "sku": "MUG-16-BLK", "attributes": { "color": "Black" }, "url": "https://example.com/products/travel-mug?variant=1", "images": [ "https://example.com/images/travel-mug-black.jpg" ] } ] } } }, "json": { "requested": false, "success": null, "data": null }, "highlights": { "requested": false, "success": null, "data": null }, "metadata": { "sourceUrl": "https://example.com/products/travel-mug", "finalUrl": "https://example.com/products/travel-mug" }, "cache_metadata": { "status": "miss", "age_ms": 0 }, "request_id": "d7aa1c3a-38d2-4fb5-92c8-0f0cac3efa37" } } } } } }, "400": { "description": "Invalid request: unknown or conflicting options, a non-public URL, or waits longer than the 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid, or disabled API key, or not enough credits.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Browser actions need a paid plan, `zdr` isn't enabled, or the API key lacks permission.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "408": { "description": "The request reached its deadline with `behavior: \"fail\"`.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The scrape could not be 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/news/search": { "post": { "summary": "Search news", "description": "Find company news by name, domain, ticker, or ISIN. Filter articles and continue through results with a cursor.", "tags": [ "News" ], "x-mint": { "content": "1 credit per 10 results" }, "security": [ { "bearerAuth": [] } ], "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. from must be before or equal to to." } }, "additionalProperties": false, "description": "Optional result filters. Use at most one of sourceDomain, sourceCountry, articleLanguage, or articleType. A date range may accompany that category; date.from must not exceed date.to.", "allOf": [ { "not": { "required": [ "sourceDomain", "sourceCountry" ] } }, { "not": { "required": [ "sourceDomain", "articleLanguage" ] } }, { "not": { "required": [ "sourceDomain", "articleType" ] } }, { "not": { "required": [ "sourceCountry", "articleLanguage" ] } }, { "not": { "required": [ "sourceCountry", "articleType" ] } }, { "not": { "required": [ "articleLanguage", "articleType" ] } } ] }, "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 }, "example": { "searchBy": { "type": "entity", "entity": { "type": "domain", "domain": "stripe.com" } } } } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/web/answers": { "post": { "summary": "Answer a research task", "description": "Research the web and return a sourced answer in your JSON shape. Choose `fast` for a short task or `ultra` for deeper research.", "security": [ { "bearerAuth": [] } ], "tags": [ "Answers" ], "x-mint": { "content": "10 or 100 credits" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswersRequest" }, "examples": { "fast": { "summary": "Fast", "value": { "mode": "fast", "task": "Find the pricing page URL and plan names for context.dev.", "json_format": { "pricing_page_url": "", "plans": [ { "name": "" } ] } } }, "ultra": { "summary": "Ultra", "value": { "mode": "ultra", "task": "Compare the monthly pricing and included credits for the plans on context.dev.", "json_format": { "plans": [ { "name": "", "monthly_price_usd": 0, "included_credits": 0, "pricing_page_url": "" } ] } } } } } } }, "responses": { "200": { "description": "The requested JSON shape, plus the sources used", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" }, "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": { "partial": { "type": "boolean", "description": "True when the request deadline ended research and the answer uses the evidence collected so far." }, "json_content": { "type": "object", "additionalProperties": {}, "description": "The answer, in the shape requested by json_format." }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Public evidence URLs from searches, pages, or company/profile records, in first-seen order. A listed URL may identify a record without its page being read." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" } }, "required": [ "json_content", "sources" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "408": { "description": "The request exceeded timeoutOpts.milliseconds.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Research could not gather usable evidence or produce the requested JSON answer.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The research exceeded its time 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/parse": { "post": { "summary": "Parse a file", "description": "Convert uploaded file bytes into Markdown and optional HTML.", "security": [ { "bearerAuth": [] } ], "tags": [ "Parsing" ], "x-mint": { "content": "From 1 credit" }, "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": "Read text from images and scanned PDF pages. PDF page ranges still apply." }, "required": false, "description": "Read text from images and scanned PDF pages. PDF page ranges still apply.", "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": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR." }, "required": false, "description": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR.", "name": "zdr", "in": "query" }, { "$ref": "#/components/parameters/RequestTags" } ], "requestBody": { "required": true, "description": "Raw file bytes, up to 50 MiB.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" }, "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": [ "success", "markdown", "type", "request_id" ] } } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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 50 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" ] } } } }, "503": { "description": "Document parsing is at capacity. Retry after the delay in Retry-After.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" }, "Retry-After": { "description": "Seconds to wait before retrying the upload", "schema": { "type": "integer", "minimum": 1 } } }, "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/urls": { "get": { "summary": "Map URLs", "description": "Discover a site's URLs, with page titles, descriptions, keywords, and language when available. Metadata can be missing on newly discovered URLs.", "security": [ { "bearerAuth": [] } ], "tags": [ "Web Scraping" ], "x-mint": { "content": "From 1 credit" }, "parameters": [ { "schema": { "type": "string", "minLength": 3, "description": "Domain to map, e.g. `stripe.com`.", "example": "stripe.com" }, "required": true, "description": "Domain to map, e.g. `stripe.com`.", "name": "domain", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "Include URLs on subdomains." }, "required": false, "description": "Include URLs on subdomains.", "name": "includeSubdomains", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 10000, "description": "Maximum number of URLs to return." }, "required": false, "description": "Maximum number of URLs to return.", "name": "maxLinks", "in": "query" }, { "schema": { "type": "string", "format": "uri", "description": "Fetch this sitemap instead of discovering sitemaps. Must belong to the domain or a subdomain." }, "required": false, "description": "Fetch this sitemap instead of discovering sitemaps. Must belong to the domain or a subdomain.", "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": "Filter URLs by a topic or phrase, most relevant first.", "example": "help center and troubleshooting articles" }, "required": false, "description": "Filter URLs by a topic or phrase, most relevant first.", "name": "search", "in": "query" }, { "schema": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 8192, "pattern": "^[^\\r\\n]*$" }, "description": "HTTP headers for the target origin. Non-empty headers bypass caching." }, "required": false, "description": "HTTP headers for the target origin. Non-empty headers bypass caching.", "name": "headers", "in": "query" }, { "schema": { "$ref": "#/components/schemas/LenientPartialTimeout" }, "required": false, "description": "Request deadline and what to return when it passes.", "style": "deepObject", "explode": true, "name": "timeoutOpts", "in": "query" }, { "schema": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR." }, "required": false, "description": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR.", "name": "zdr", "in": "query" }, { "$ref": "#/components/parameters/RequestTags" } ], "responses": { "200": { "description": "Discovered URLs with available page metadata", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" }, "X-Context-ZDR": { "description": "Present with the value true when zero data retention was requested and honored.", "schema": { "type": "string", "enum": [ "true" ] } }, "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "domain": { "type": "string" }, "urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "language": { "type": "string" } }, "required": [ "url" ] } }, "partial": { "type": "boolean" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "success", "domain", "urls", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Missing, invalid, or disabled API key, or no credits left (`USAGE_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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable 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 a website", "description": "Crawl a website and return page content as Markdown. Use a batch for crawls beyond 500 pages.", "security": [ { "bearerAuth": [] } ], "tags": [ "Web Scraping" ], "x-mint": { "content": "1 credit per page Rate limit weight: 10" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Start URL, including `http://` or `https://`." }, "maxPages": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100, "description": "Maximum pages to crawl." }, "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": "Read scanned PDF pages with OCR; preserve pages that already contain text." }, "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." } }, "default": { "shouldParse": true, "ocr": false }, "additionalProperties": false, "description": "PDF handling. `start`/`end` limit parsing 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", "items": { "type": "string", "maxLength": 2048 }, "maxItems": 50, "description": "Keep matching HTML subtrees before converting each page to Markdown." }, "excludeSelectors": { "type": "array", "items": { "type": "string", "maxLength": 2048 }, "maxItems": 50, "description": "Remove matching elements after inclusions. Exclusions take precedence." }, "maxAgeMs": { "type": "integer", "minimum": 0, "maximum": 2592000000, "default": 86400000, "description": "Maximum cache age in milliseconds. Defaults to 1 day; `0` fetches 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": "Wait briefly for CSS animations and transitions to settle before reading each page." }, "stopAfterMs": { "type": "integer", "minimum": 10000, "maximum": 110000, "default": 80000, "description": "Soft crawl deadline in milliseconds. Returns pages collected before the next deadline check." }, "country": { "$ref": "#/components/schemas/BrowserCountryCode" }, "timeoutOpts": { "$ref": "#/components/schemas/PartialTimeout" }, "zdr": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR." }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "url" ] }, "example": { "url": "https://example.com", "maxPages": 10 } } } }, "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" }, "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": { "partial": { "type": "boolean", "description": "True when timeoutOpts.behavior=return-partial returned the usable results collected before the deadline. Partial collections are not cached as complete results." }, "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": [ "results", "metadata", "request_id", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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": "Machine-readable error code." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "message", "error_code", "request_id" ] } } } }, "401": { "description": "Missing, invalid, or disabled API key, or no credits left (`USAGE_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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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": [ "message", "error_code", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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": "The start URL has an unsupported content type. Supported documents include PDF, Word, Excel, PowerPoint, 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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": [ "message", "error_code", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable 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 data", "description": "Extract website data using your JSON Schema and instructions.", "security": [ { "bearerAuth": [] } ], "tags": [ "Web Extraction" ], "x-mint": { "content": "10 credits" }, "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", "additionalProperties": {}, "description": "JSON Schema (not an example object) for the returned object. Image fields include relevant page image references.", "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": "Require facts stated on the page. Unsupported fields become null or empty." }, "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." } }, "default": { "shouldParse": true }, "additionalProperties": false, "description": "PDF parsing options, including whether to parse PDFs and the inclusive page range." }, "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": "Wait briefly for CSS animations and transitions to settle before reading each page." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/WebScrapeAction" }, "maxItems": 5, "description": "Browser steps before page discovery. Requires a paid plan; defaults the crawl budget to 110000 ms." }, "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." }, "timeoutOpts": { "$ref": "#/components/schemas/PartialTimeout" }, "zdr": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR." }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "url", "schema" ], "additionalProperties": false } } } }, "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" }, "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": { "partial": { "type": "boolean", "description": "True when the timeout ended processing and this response contains only usable results completed so far. Unfinished results are omitted." }, "status": { "type": "string", "description": "Always `ok` on success." }, "url": { "type": "string", "description": "The starting URL that was analyzed" }, "urls_analyzed": { "type": "array", "items": { "type": "string" }, "description": "List of URLs whose Markdown was used for extraction" }, "data": { "type": "object", "additionalProperties": {}, "description": "Extracted data matching the request schema" }, "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", "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" ] }, "description": "One verified outcome per requested browser action, in request order." } }, "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": [ "status", "url", "urls_analyzed", "data", "metadata", "request_id", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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 timeoutOpts.milliseconds is shorter than waitForMs plus the page-load margin; raise timeoutOpts.milliseconds or lower waitForMs." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "message", "error_code", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/web/search": { "post": { "summary": "Search the web", "description": "Search the web and optionally return page content or relevant passages with each result.", "security": [ { "bearerAuth": [] } ], "tags": [ "Web Scraping" ], "x-mint": { "content": "From 1 credit per 10 results" }, "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" }, "maxItems": 100, "description": "Allowlist — only return results from these domains. Up to 100 domains. Example: [\"arxiv.org\", \"github.com\"]." }, "excludeDomains": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Blocklist — drop results from these domains. Up to 100 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": "Currently has no effect." }, "markdownOptions": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false, "description": "Scrape each result to Markdown. Adds 1 credit per 10 results." }, "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." } }, "default": { "shouldParse": true }, "additionalProperties": false, "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": 31536000000, "default": 15552000000, "description": "Maximum cache age in milliseconds for result page content. Defaults to 180 days (15552000000 ms) when Markdown is requested, or 365 days (31536000000 ms) when only highlights are requested. Explicit values override either default. Maximum: 365 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." }, "timeoutOpts": { "$ref": "#/components/schemas/ScrapeTimeout" } }, "additionalProperties": false, "description": "Inline Markdown scraping for each result. Set `enabled: true` to activate." }, "highlightsOptions": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false, "description": "Return relevant passages for each result. Adds 1 credit per 10 results." }, "maxCharacters": { "type": "integer", "minimum": 100, "maximum": 20000, "default": 4000, "description": "Maximum combined length of passages per result." } }, "additionalProperties": false, "description": "Passages from each result page that are relevant to the query. Pages are read with the `markdownOptions` settings." }, "timeoutOpts": { "$ref": "#/components/schemas/PartialTimeout" }, "zdr": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR." }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "query" ], "additionalProperties": false }, "example": { "query": "Stripe API authentication", "numResults": 10 } } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" }, "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": { "partial": { "type": "boolean", "description": "True when timeoutOpts.behavior=return-partial returned the usable results collected before the deadline. Partial collections are not cached as complete results." }, "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. Empty string when the search provider does not supply a snippet." }, "relevance": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Relevance to the original query." }, "markdown": { "type": "object", "properties": { "finalDOMState": { "type": "string", "enum": [ "loaded", "still-loading" ], "description": "`loaded`, or `still-loading` when capture ended before the page finished loading." }, "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." }, "highlights": { "type": "object", "properties": { "highlights": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Passages relevant to the query, in page order. Null unless highlightsOptions.enabled is true and the page was read." }, "code": { "type": "string", "enum": [ "SUCCESS", "NOT_REQUESTED", "TIMEOUT", "CONTENT_TOO_LARGE", "WEBSITE_ACCESS_ERROR", "ERROR" ], "description": "Per-result highlights outcome. Inspect this before reading `highlights`." } }, "required": [ "highlights", "code" ], "additionalProperties": false, "description": "Highlights status and passages for this result." } }, "required": [ "url", "title", "description", "relevance", "markdown", "highlights" ] } }, "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": [ "results", "query", "request_id", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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": "Machine-readable error code." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "message", "error_code", "request_id" ] } } } }, "401": { "description": "Missing, invalid, or disabled API key, or no credits left (`USAGE_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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable 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 a person", "description": "Find a person from identity clues and return their profile with a match score. Requires a paid plan; free or disposable email addresses return 422.", "security": [ { "bearerAuth": [] } ], "tags": [ "People" ], "x-mint": { "content": "20 credits per match Paid plans Beta" }, "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" } } } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" }, "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": { "$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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Free or disposable email 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/brand/retrieve": { "post": { "summary": "Retrieve a brand", "description": "Retrieve logos, colors, company details, and social links using one lookup identifier. A direct URL limits extraction to that page.", "security": [ { "bearerAuth": [] } ], "tags": [ "Brand Intelligence" ], "x-mint": { "content": "10 credits" }, "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 } } } } } }, "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandResponse" } } } }, "400": { "description": "Invalid input, brand or company not found (`NOT_FOUND`), or the website could not be read.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key, or no credits left (`USAGE_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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Free or disposable email 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/brand/search": { "get": { "summary": "Search brands", "description": "Find up to 10 brands by name or domain, ordered by popularity. Use the returned domain to retrieve a full brand profile.", "security": [ { "bearerAuth": [] } ], "tags": [ "Brand Intelligence" ], "x-mint": { "content": "1 credit Free on Pro, Growth, and Scale" }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Search term, matched against the fields selected by queryBy (e.g. 'stripe', 'stripe.com', 'stri')." }, "required": true, "description": "Search term, matched against the fields selected by queryBy (e.g. 'stripe', 'stripe.com', 'stri').", "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. 'stri' matches Stripe). 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. 'stri' matches Stripe). 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "description": "The brand's domain.", "example": "stripe.com" }, "name": { "type": "string", "description": "The brand's name. Empty string when unknown.", "example": "Stripe" }, "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=brandLL_1a2b3c&domain=stripe.com" } }, "required": [ "domain", "name", "logo" ] }, "maxItems": 10, "description": "Up to 10 matching brands, name matches first, then domain matches, most popular first within each group. Empty when nothing matches." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "results", "request_id" ] } } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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": "Machine-readable error code." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "message", "error_code", "request_id" ] } } } }, "401": { "description": "Missing, invalid, or disabled API key, or no credits left (`USAGE_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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable 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": "Extract a styleguide", "description": "Extract colors, typography, spacing, and component styles from a website.", "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": 0, "maximum": 31536000000, "default": 7776000000, "description": "Maximum age in milliseconds for cached styleguide data before a hard refresh. Defaults to 3 months. Set to 0 to always perform a hard refresh." }, "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." }, "timeoutOpts": { "$ref": "#/components/schemas/ScrapeTimeout" }, "zdr": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR." } } }, { "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": 0, "maximum": 31536000000, "default": 7776000000, "description": "Maximum age in milliseconds for cached styleguide data before a hard refresh. Defaults to 3 months. Set to 0 to always perform a hard refresh." }, "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." }, "timeoutOpts": { "$ref": "#/components/schemas/ScrapeTimeout" }, "zdr": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR." } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ "Web Extraction" ], "x-mint": { "content": "10 credits" }, "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": "Exact URL to inspect. Provide either `domain` or `directUrl`, not both." }, "required": false, "description": "Exact URL to inspect. Provide either `domain` or `directUrl`, not both.", "name": "directUrl", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "default": 7776000000, "description": "Maximum age of cached brand data in ms. Defaults to 3 months; clamped to 0–1 year. `0` refreshes." }, "required": false, "description": "Maximum age of cached brand data in ms. Defaults to 3 months; clamped to 0–1 year. `0` refreshes.", "name": "maxAgeMs", "in": "query" }, { "schema": { "$ref": "#/components/schemas/ScrapeTimeout" }, "required": false, "description": "Request deadline and what to return when it passes.", "style": "deepObject", "explode": true, "name": "timeoutOpts", "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" }, { "schema": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR." }, "required": false, "description": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" }, "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": { "finalDOMState": { "type": "string", "enum": [ "loaded", "still-loading" ], "description": "`loaded`, or `still-loading` when capture ended before the page finished loading." }, "status": { "type": "string", "description": "Always `ok` on success." }, "domain": { "type": "string", "description": "The normalized domain that was processed" }, "styleguide": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "light", "dark" ], "description": "The primary color mode of the website design" }, "colors": { "type": "object", "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)" } }, "required": [ "accent", "background", "text" ], "description": "Primary colors used on the website" }, "typography": { "type": "object", "properties": { "headings": { "type": "object", "properties": { "h1": { "type": "object", "properties": { "fontFamily": { "type": "string", "description": "First font in the 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" } }, "required": [ "fontFamily", "fontFallbacks", "fontSize", "fontWeight", "lineHeight", "letterSpacing" ] }, "h2": { "type": "object", "properties": { "fontFamily": { "type": "string", "description": "First font in the 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" } }, "required": [ "fontFamily", "fontFallbacks", "fontSize", "fontWeight", "lineHeight", "letterSpacing" ] }, "h3": { "type": "object", "properties": { "fontFamily": { "type": "string", "description": "First font in the 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" } }, "required": [ "fontFamily", "fontFallbacks", "fontSize", "fontWeight", "lineHeight", "letterSpacing" ] }, "h4": { "type": "object", "properties": { "fontFamily": { "type": "string", "description": "First font in the 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" } }, "required": [ "fontFamily", "fontFallbacks", "fontSize", "fontWeight", "lineHeight", "letterSpacing" ] } }, "description": "Heading styles" }, "p": { "type": "object", "properties": { "fontFamily": { "type": "string", "description": "First font in the 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" } }, "required": [ "fontFamily", "fontFallbacks", "fontSize", "fontWeight", "lineHeight", "letterSpacing" ] } }, "required": [ "headings" ], "description": "Typography styles used on the website" }, "elementSpacing": { "type": "object", "properties": { "xs": { "type": "string" }, "sm": { "type": "string" }, "md": { "type": "string" }, "lg": { "type": "string" }, "xl": { "type": "string" } }, "required": [ "xs", "sm", "md", "lg", "xl" ], "description": "Spacing system used on the website" }, "shadows": { "type": "object", "properties": { "sm": { "type": "string" }, "md": { "type": "string" }, "lg": { "type": "string" }, "xl": { "type": "string" }, "inner": { "type": "string" } }, "required": [ "sm", "md", "lg", "xl", "inner" ], "description": "Shadow styles used on the website" }, "fontLinks": { "type": "object", "additionalProperties": { "type": "object", "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." } }, "required": [ "type", "files" ] }, "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." }, "components": { "type": "object", "properties": { "button": { "type": "object", "properties": { "primary": { "type": "object", "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": "Minimum width (usually 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" } }, "required": [ "backgroundColor", "color", "borderColor", "borderRadius", "borderWidth", "borderStyle", "padding", "minWidth", "minHeight", "fontSize", "fontWeight", "textDecoration", "boxShadow", "css" ] }, "secondary": { "type": "object", "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": "Minimum width (usually 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" } }, "required": [ "backgroundColor", "color", "borderColor", "borderRadius", "borderWidth", "borderStyle", "padding", "minWidth", "minHeight", "fontSize", "fontWeight", "textDecoration", "boxShadow", "css" ] }, "link": { "type": "object", "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": "Minimum width (usually 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" } }, "required": [ "backgroundColor", "color", "borderColor", "borderRadius", "borderWidth", "borderStyle", "padding", "minWidth", "minHeight", "fontSize", "fontWeight", "textDecoration", "boxShadow", "css" ] } }, "description": "Button component styles" }, "card": { "type": "object", "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" } }, "required": [ "backgroundColor", "borderColor", "borderRadius", "borderWidth", "borderStyle", "padding", "boxShadow", "textColor", "css" ], "description": "Card component style" } }, "required": [ "button" ], "description": "UI component styles" } }, "required": [ "mode", "colors", "typography", "elementSpacing", "shadows", "fontLinks", "components" ], "description": "Comprehensive styleguide data extracted from the website" }, "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" ] } } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable 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": "Machine-readable error code, such as `WEBSITE_BLOCKED` or `WEBSITE_NOT_FOUND`." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "401": { "description": "Missing or invalid API key, or no credits left (`USAGE_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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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": "Machine-readable error code." }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable 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": "Extract fonts", "description": "Identify fonts and available font files used by a website.", "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": 0, "maximum": 31536000000, "default": 7776000000, "description": "Maximum age in milliseconds for cached font data before a hard refresh. Defaults to 3 months. Set to 0 to always perform a hard refresh. Ignored when 'directUrl' is used." }, "timeoutOpts": { "$ref": "#/components/schemas/ScrapeTimeout" } } }, { "title": "By Direct URL", "required": [ "directUrl" ], "properties": { "directUrl": { "type": "string", "format": "uri", "description": "A specific URL to fetch fonts from directly, bypassing domain resolution." }, "timeoutOpts": { "$ref": "#/components/schemas/ScrapeTimeout" } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ "Web Extraction" ], "x-mint": { "content": "5 credits" }, "parameters": [ { "schema": { "type": "string", "format": "uri", "description": "Exact page to inspect. Provide either `domain` or `directUrl`." }, "required": false, "description": "Exact page to inspect. Provide either `domain` or `directUrl`.", "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 of cached brand data in ms. Defaults to 3 months; clamped to 0–1 year. `0` refreshes." }, "required": false, "description": "Maximum age of cached brand data in ms. Defaults to 3 months; clamped to 0–1 year. `0` refreshes.", "name": "maxAgeMs", "in": "query" }, { "schema": { "$ref": "#/components/schemas/ScrapeTimeout" }, "required": false, "description": "Request deadline and what to return when it passes.", "style": "deepObject", "explode": true, "name": "timeoutOpts", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "finalDOMState": { "type": "string", "enum": [ "loaded", "still-loading" ], "description": "`loaded`, or `still-loading` when capture ended before the page finished loading." }, "status": { "type": "string", "description": "Always `ok` on success." }, "domain": { "type": "string", "description": "The normalized domain that was processed" }, "fonts": { "type": "array", "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" ] }, "description": "Array of font usage information" }, "fontLinks": { "type": "object", "additionalProperties": { "type": "object", "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." } }, "required": [ "type", "files" ] }, "description": "Available font files keyed by family name. Omitted when no downloadable fonts are found." }, "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": [ "status", "domain", "fonts", "code", "cache_metadata", "request_id" ] } } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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": "Missing, invalid, or disabled API key, or no credits left (`USAGE_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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable 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 codes", "description": "Classify a company into NAICS industry codes.", "security": [ { "bearerAuth": [] } ], "tags": [ "Web Extraction" ], "x-mint": { "content": "10 credits" }, "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/PartialTimeout" }, "required": false, "description": "Request deadline and what to return when it passes.", "style": "deepObject", "explode": true, "name": "timeoutOpts", "in": "query" }, { "schema": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR." }, "required": false, "description": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" }, "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": { "partial": { "type": "boolean", "description": "True when the timeout ended processing and this response contains only usable results completed so far. Unfinished results are omitted." }, "status": { "type": "string", "description": "Always `ok` on success." }, "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", "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" ] }, "description": "Array of NAICS codes and titles." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "400": { "description": "Invalid input, company not found (`NOT_FOUND`), or the website could not be read.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable 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_NOT_FOUND", "WEBSITE_BLOCKED", "INPUT_VALIDATION_ERROR" ], "description": "Machine-readable error code." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "401": { "description": "Missing or invalid API key, or no credits left (`USAGE_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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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": "Machine-readable error code." }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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 codes", "description": "Classify a company into SIC industry codes.", "security": [ { "bearerAuth": [] } ], "tags": [ "Web Extraction" ], "x-mint": { "content": "10 credits" }, "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": "SIC dataset: `original_sic` (1987) or `latest_sec` (current SEC list)." }, "required": false, "description": "SIC dataset: `original_sic` (1987) or `latest_sec` (current SEC list).", "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/PartialTimeout" }, "required": false, "description": "Request deadline and what to return when it passes.", "style": "deepObject", "explode": true, "name": "timeoutOpts", "in": "query" }, { "schema": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR." }, "required": false, "description": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" }, "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": { "partial": { "type": "boolean", "description": "True when the timeout ended processing and this response contains only usable results completed so far. Unfinished results are omitted." }, "status": { "type": "string", "description": "Always `ok` on success." }, "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", "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" ] }, "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`." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "400": { "description": "Invalid input, company not found (`NOT_FOUND`), or the website could not be read.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable 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_NOT_FOUND", "WEBSITE_BLOCKED", "INPUT_VALIDATION_ERROR" ], "description": "Machine-readable error code." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "401": { "description": "Missing or invalid API key, or no credits left (`USAGE_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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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": "Machine-readable error code." }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" } } } }, "/utility/prefetch": { "post": { "summary": "Prefetch brand data", "description": "Queue brand or styleguide data so a later lookup can return sooner.", "security": [ { "bearerAuth": [] } ], "tags": [ "Utility" ], "x-mint": { "content": "0 credits Paid plans" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "brand", "styleguide" ], "description": "Data to prefetch." }, "identifier": { "$ref": "#/components/schemas/UtilityPrefetchIdentifier" }, "timeoutOpts": { "$ref": "#/components/schemas/Timeout" }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "type", "identifier" ] }, "example": { "type": "brand", "identifier": { "domain": "stripe.com" } } } } }, "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `ok` on success." }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable 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": "Machine-readable error code." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] } } } }, "401": { "description": "Missing or invalid API key, or no credits left (`USAGE_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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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": "Machine-readable error code." }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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": "Free or disposable email 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable 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": "Watch a page, URL inventory, or extracted website data on a schedule. A run starts immediately to capture the baseline.", "operationId": "createMonitor", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "x-mint": { "content": "1, 2, or 10 credits per run" }, "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" } } } } } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsCreateMonitorResponse" } } } }, "400": { "$ref": "#/components/responses/MonitorsBadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "403": { "$ref": "#/components/responses/MonitorsLimitExceeded" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "summary": "List monitors", "description": "List your monitors with optional search and filters.", "operationId": "listMonitors", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "x-mint": { "content": "0 credits" }, "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": "Fields to search with `q`. Defaults to all fields; page and extract targets can have instructions.", "example": "name,url" }, "required": false, "description": "Fields to search with `q`. Defaults to all fields; page and extract targets can have instructions.", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsListMonitorsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Search is temporarily unavailable (`SEARCH_UNAVAILABLE`). Retry or list without search filters.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/monitors/{monitor_id}": { "get": { "summary": "Retrieve a monitor", "operationId": "getMonitor", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "description": "Retrieve a monitor’s configuration and current state.", "x-mint": { "content": "0 credits" }, "parameters": [ { "schema": { "type": "string", "description": "ID of the monitor.", "example": "mon_123" }, "required": true, "description": "ID of the monitor.", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsMonitorResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/MonitorsNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "summary": "Update a monitor", "description": "Update a monitor. Changing its target or change detection replaces the baseline and queues a new baseline run.", "operationId": "updateMonitor", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "x-mint": { "content": "0 credits" }, "parameters": [ { "schema": { "type": "string", "description": "ID of the monitor.", "example": "mon_123" }, "required": true, "description": "ID of the monitor.", "name": "monitor_id", "in": "path" } ], "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" } } } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsMonitorResponse" } } } }, "400": { "$ref": "#/components/responses/MonitorsBadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/MonitorsNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "summary": "Delete a monitor", "operationId": "deleteMonitor", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "description": "Delete a monitor and stop future runs and webhook retries.", "x-mint": { "content": "0 credits" }, "parameters": [ { "schema": { "type": "string", "description": "ID of the monitor.", "example": "mon_123" }, "required": true, "description": "ID of the monitor.", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsDeleteMonitorResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/MonitorsNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors/{monitor_id}/runs": { "get": { "summary": "List monitor runs", "operationId": "listMonitorRuns", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "description": "List a monitor’s runs, newest first.", "x-mint": { "content": "0 credits" }, "parameters": [ { "schema": { "type": "string", "description": "ID of the monitor.", "example": "mon_123" }, "required": true, "description": "ID of the monitor.", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsListRunsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/MonitorsNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors/{monitor_id}/runs/{run_id}": { "get": { "summary": "Retrieve a monitor run", "description": "Retrieve the status, timing, and results of one monitor run.", "operationId": "getMonitorRun", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "x-mint": { "content": "0 credits" }, "parameters": [ { "schema": { "type": "string", "description": "ID of the monitor.", "example": "mon_123" }, "required": true, "description": "ID of the monitor.", "name": "monitor_id", "in": "path" }, { "schema": { "type": "string", "description": "ID of the monitor run.", "example": "run_123" }, "required": true, "description": "ID of the monitor run.", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsRunResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/MonitorsNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors/{monitor_id}/changes": { "get": { "summary": "List monitor changes", "operationId": "listMonitorChanges", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "description": "List full change records for a monitor, newest first.", "x-mint": { "content": "0 credits" }, "parameters": [ { "schema": { "type": "string", "description": "ID of the monitor.", "example": "mon_123" }, "required": true, "description": "ID of the monitor.", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsListChangesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/MonitorsNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors/runs": { "get": { "summary": "List runs for all monitors", "description": "List runs across your monitors, newest first.", "operationId": "listAccountRuns", "tags": [ "Monitors" ], "security": [ { "bearerAuth": [] } ], "x-mint": { "content": "0 credits" }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsListRunsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors/credit-usage": { "get": { "summary": "Retrieve monitor credit usage", "description": "Return usage per monitor, highest first, for up to the 10,000 most recent runs in the requested window.", "operationId": "listMonitorCreditUsage", "tags": [ "Monitors" ], "security": [ { "bearerAuth": [] } ], "x-mint": { "content": "0 credits" }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsCreditUsageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors/limits": { "get": { "summary": "Retrieve monitor limits", "description": "Retrieve your organization’s monitor allowance and usage.", "operationId": "getMonitorLimits", "tags": [ "Monitors" ], "security": [ { "bearerAuth": [] } ], "x-mint": { "content": "0 credits" }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsLimitsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors/changes": { "get": { "summary": "List changes for all monitors", "description": "List full change records across your monitors, newest first.", "operationId": "listChanges", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "x-mint": { "content": "0 credits" }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsListChangesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors/changes/{change_id}": { "get": { "summary": "Retrieve a monitor change", "operationId": "getChange", "security": [ { "bearerAuth": [] } ], "tags": [ "Monitors" ], "description": "Retrieve a detected change, including its diff and available evidence.", "x-mint": { "content": "0 credits" }, "parameters": [ { "schema": { "type": "string", "description": "ID of the detected change.", "example": "chg_123" }, "required": true, "description": "ID of the detected change.", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsChangeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/MonitorsNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors/{monitor_id}/run": { "post": { "summary": "Run a monitor now", "description": "Queue a run without changing the regular schedule. Paused monitors return 409.", "operationId": "runMonitorNow", "tags": [ "Monitors" ], "security": [ { "bearerAuth": [] } ], "x-mint": { "content": "1, 2, or 10 credits per run" }, "parameters": [ { "schema": { "type": "string", "description": "ID of the monitor.", "example": "mon_123" }, "required": true, "description": "ID of the monitor.", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsRunNowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/MonitorsNotFound" }, "409": { "description": "Monitor is paused (`MONITOR_PAUSED`). Resume it before running.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/monitors/{monitor_id}/webhook/rotate-secret": { "post": { "summary": "Rotate a monitor webhook secret", "description": "Generate and return a new signing secret. It takes effect immediately for all subsequent delivery attempts.", "operationId": "rotateMonitorWebhookSecret", "tags": [ "Monitors" ], "security": [ { "bearerAuth": [] } ], "x-mint": { "content": "0 credits" }, "parameters": [ { "schema": { "type": "string", "description": "ID of the monitor.", "example": "mon_123" }, "required": true, "description": "ID of the monitor.", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorsMonitorResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/MonitorsUnauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/MonitorsNotFound" }, "409": { "description": "Monitor has no webhook (`MONITOR_NO_WEBHOOK`). Add one with Update a 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/batch/submit": { "post": { "summary": "Submit a batch", "description": "Scrape up to 25,000 URLs, or crawl a site, asynchronously. Poll the batch ID or receive a webhook when it finishes.", "operationId": "submitBatch", "security": [ { "bearerAuth": [] } ], "tags": [ "Batches" ], "x-mint": { "content": "1 credit per page" }, "parameters": [ { "schema": { "type": "string", "maxLength": 200, "description": "Unique key per submission. Retrying with the same key and body returns the original batch; a different body returns `409`." }, "required": false, "description": "Unique key per submission. Retrying with the same key and body returns the original batch; a different body returns `409`.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchSubmitRequest" }, "examples": { "scrapeMarkdown": { "summary": "Scrape URLs as Markdown", "value": { "input": { "mode": "scrape", "data": { "format": "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": { "mode": "scrape", "data": { "format": "html", "urls": [ { "url": "https://example.com/about" }, { "url": "https://example.com/pricing" } ] } } } }, "crawlStartUrlMarkdown": { "summary": "Crawl from a URL as Markdown", "value": { "input": { "mode": "crawl", "data": { "format": "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": { "mode": "crawl", "data": { "format": "html", "source": { "type": "start_url", "url": "https://example.com/blog", "controls": { "maxUrls": 100 } } } } } }, "crawlSitemapMarkdown": { "summary": "Crawl a sitemap as Markdown", "value": { "input": { "mode": "crawl", "data": { "format": "markdown", "source": { "type": "sitemap", "domain": "example.com", "controls": { "maxUrls": 500, "regex": "^https://example\\.com/docs/" } } } } } }, "crawlSitemapHtml": { "summary": "Crawl a sitemap as HTML", "value": { "input": { "mode": "crawl", "data": { "format": "html", "source": { "type": "sitemap", "domain": "example.com", "controls": { "maxUrls": 500 } } } } } } } } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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": { "description": "Authentication failed, or the balance cannot cover the batch hold (`USAGE_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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Too many active batches (`BATCH_LIMIT_EXCEEDED`), or the key lacks `batches:write` (`INSUFFICIENT_PERMISSIONS`).", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/batch/list": { "get": { "summary": "List batches", "description": "List your batches, newest first, with optional filters.", "operationId": "listBatches", "security": [ { "bearerAuth": [] } ], "tags": [ "Batches" ], "x-mint": { "content": "0 credits" }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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", "null" ], "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" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Search is temporarily unavailable (`SEARCH_UNAVAILABLE`). Retry or list without search filters.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/batch/{batch_id}": { "get": { "summary": "Retrieve a batch", "description": "Get batch progress and result download links. Result files are deleted 180 days after the batch finishes.", "operationId": "getBatch", "security": [ { "bearerAuth": [] } ], "tags": [ "Batches" ], "x-mint": { "content": "0 credits" }, "parameters": [ { "schema": { "type": "string", "example": "batch_9f2c8a", "description": "Batch ID." }, "required": true, "description": "Batch ID.", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "summary": "Delete a batch", "description": "Permanently delete a finished batch and its results. Its webhook deliveries can no longer be retried.", "operationId": "deleteBatch", "security": [ { "bearerAuth": [] } ], "tags": [ "Batches" ], "x-mint": { "content": "0 credits" }, "parameters": [ { "schema": { "type": "string", "example": "batch_9f2c8a", "description": "Batch ID." }, "required": true, "description": "Batch ID.", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Batch is active or still settling (`BATCH_NOT_COMPLETED`). Cancel it, wait for a final status, then retry.", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/batch/{batch_id}/results": { "get": { "summary": "List batch results", "description": "Page through a finished batch’s results as JSON. Results remain available for 180 days.", "operationId": "getBatchResults", "security": [ { "bearerAuth": [] } ], "tags": [ "Batches" ], "x-mint": { "content": "0 credits" }, "parameters": [ { "schema": { "type": "string", "example": "batch_9f2c8a", "description": "Batch ID." }, "required": true, "description": "Batch ID.", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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", "null" ], "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" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/batch/{batch_id}/cancel": { "post": { "summary": "Cancel a batch", "description": "Stop a batch from starting new pages. Pages already in progress finish before the batch becomes cancelled.", "operationId": "cancelBatch", "security": [ { "bearerAuth": [] } ], "tags": [ "Batches" ], "x-mint": { "content": "0 credits" }, "parameters": [ { "schema": { "type": "string", "example": "batch_9f2c8a", "description": "Batch ID." }, "required": true, "description": "Batch ID.", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key permissions or organization settings do not allow this 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Batch already finished (`BATCH_NOT_CANCELLABLE`).", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/org/usage": { "get": { "operationId": "getUsage", "summary": "Retrieve credit usage", "tags": [ "Usage" ], "description": "Retrieve your organization’s credit balance, current-period usage, and next refill.", "security": [ { "bearerAuth": [] } ], "x-mint": { "content": "0 credits" }, "responses": { "200": { "description": "Current 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgUsageResponse" } } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Usage data 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/org/usage/history": { "get": { "operationId": "getUsageHistory", "summary": "Retrieve usage history", "tags": [ "Usage" ], "description": "Retrieve credits and requests over time, bucketed by hour, day, or month. History is kept for one year.", "security": [ { "bearerAuth": [] } ], "x-mint": { "content": "0 credits" }, "parameters": [ { "schema": { "type": "string", "format": "date-time", "description": "Start of the range, as an ISO 8601 timestamp. Defaults to 24 hours before `to` for `hour`, 30 days for `day`, and 366 days for `month`.", "example": "2026-09-01T00:00:00Z" }, "required": false, "description": "Start of the range, as an ISO 8601 timestamp. Defaults to 24 hours before `to` for `hour`, 30 days for `day`, and 366 days for `month`.", "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "End of the range, as an ISO 8601 timestamp. Defaults to now.", "example": "2026-10-01T00:00:00Z" }, "required": false, "description": "End of the range, as an ISO 8601 timestamp. Defaults to now.", "name": "to", "in": "query" }, { "schema": { "type": "string", "enum": [ "hour", "day", "month" ], "default": "day", "description": "Bucket size. `hour` covers up to 7 days; `day` and `month` cover up to 366 days. Buckets start on UTC boundaries." }, "required": false, "description": "Bucket size. `hour` covers up to 7 days; `day` and `month` cover up to 366 days. Buckets start on UTC boundaries.", "name": "interval", "in": "query" }, { "schema": { "type": "string", "enum": [ "path", "key_id", "status_code" ], "description": "Split each bucket by endpoint path, API key, or HTTP status code." }, "required": false, "description": "Split each bucket by endpoint path, API key, or HTTP status code.", "name": "group_by", "in": "query" } ], "responses": { "200": { "description": "Usage over time", "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-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageHistoryResponse" } } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Usage data 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } }, "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. Slack incoming webhook destinations receive a formatted Slack message instead of this event envelope.", "operationId": "monitorChangeDetected", "tags": [ "Monitors" ], "security": [], "parameters": [ { "schema": { "type": "string", "example": "Context.dev-Webhooks/1.0" }, "required": true, "description": "Identifies the Context.dev webhook sender.", "name": "User-Agent", "in": "header" }, { "schema": { "type": "string", "enum": [ "change.detected" ] }, "required": true, "description": "Event type for this delivery.", "name": "X-Context-Event", "in": "header" }, { "schema": { "type": "string", "example": "evt_123" }, "required": true, "description": "Unique event ID. Matches the top-level `id` field in the request body.", "name": "X-Context-Id", "in": "header" }, { "schema": { "type": "string", "example": "whd_0123456789abcdef0123456789abcdef" }, "required": false, "description": "Delivery ID for status checks and retries.", "name": "X-Context-Delivery-Id", "in": "header" }, { "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "Attempt number, starting at 1.", "name": "X-Context-Attempt", "in": "header" }, { "schema": { "type": "string", "example": "t=1783620012,v1=087d98aada1e39f9d24d65951f51e672da12b2f9ea1c02c7c8c5ef254f5d4068" }, "required": false, "description": "`t=,v1=`: SHA-256 HMAC of `t.rawRequestBody`, keyed with the webhook secret. Verify with a constant-time comparison and reject stale timestamps.", "name": "X-Context-Signature", "in": "header" } ], "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 run, including unchanged runs. Return a 2xx response to acknowledge delivery.", "operationId": "monitorRunCompleted", "tags": [ "Monitors" ], "security": [], "parameters": [ { "schema": { "type": "string", "example": "Context.dev-Webhooks/1.0" }, "required": true, "description": "Identifies the Context.dev webhook sender.", "name": "User-Agent", "in": "header" }, { "schema": { "type": "string", "enum": [ "run.completed" ] }, "required": true, "description": "Event type for this delivery.", "name": "X-Context-Event", "in": "header" }, { "schema": { "type": "string", "example": "evt_123" }, "required": true, "description": "Unique event ID. Matches the top-level `id` field in the request body.", "name": "X-Context-Id", "in": "header" }, { "schema": { "type": "string", "example": "whd_0123456789abcdef0123456789abcdef" }, "required": false, "description": "Delivery ID for status checks and retries.", "name": "X-Context-Delivery-Id", "in": "header" }, { "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "Attempt number, starting at 1.", "name": "X-Context-Attempt", "in": "header" }, { "schema": { "type": "string", "example": "t=1783620012,v1=087d98aada1e39f9d24d65951f51e672da12b2f9ea1c02c7c8c5ef254f5d4068" }, "required": false, "description": "`t=,v1=`: SHA-256 HMAC of `t.rawRequestBody`, keyed with the webhook secret. Verify with a constant-time comparison and reject stale timestamps.", "name": "X-Context-Signature", "in": "header" } ], "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. Slack incoming webhook destinations receive a formatted Slack message instead of this event envelope.", "operationId": "batchCompleted", "tags": [ "Batches" ], "security": [], "parameters": [ { "schema": { "type": "string", "example": "Context.dev-Webhooks/1.0" }, "required": true, "description": "Identifies the Context.dev webhook sender.", "name": "User-Agent", "in": "header" }, { "schema": { "type": "string", "enum": [ "batch.completed" ] }, "required": true, "description": "Which final status the batch reached. Matches the `event` field in the request body.", "name": "X-Context-Event", "in": "header" }, { "schema": { "type": "string", "example": "evt_123" }, "required": true, "description": "Unique event ID. Matches the top-level `id` field in the request body.", "name": "X-Context-Id", "in": "header" }, { "schema": { "type": "string", "example": "whd_0123456789abcdef0123456789abcdef" }, "required": false, "description": "Delivery ID for status checks and retries.", "name": "X-Context-Delivery-Id", "in": "header" }, { "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "Attempt number, starting at 1.", "name": "X-Context-Attempt", "in": "header" }, { "schema": { "type": "string", "example": "t=1783620012,v1=087d98aada1e39f9d24d65951f51e672da12b2f9ea1c02c7c8c5ef254f5d4068" }, "required": false, "description": "`t=,v1=`: SHA-256 HMAC of `t.rawRequestBody`, keyed with the webhook secret. Verify with a constant-time comparison and reject stale timestamps.", "name": "X-Context-Signature", "in": "header" } ], "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. Slack incoming webhook destinations receive a formatted Slack message instead of this event envelope.", "operationId": "batchFailed", "tags": [ "Batches" ], "security": [], "parameters": [ { "schema": { "type": "string", "example": "Context.dev-Webhooks/1.0" }, "required": true, "description": "Identifies the Context.dev webhook sender.", "name": "User-Agent", "in": "header" }, { "schema": { "type": "string", "enum": [ "batch.failed" ] }, "required": true, "description": "Which final status the batch reached. Matches the `event` field in the request body.", "name": "X-Context-Event", "in": "header" }, { "schema": { "type": "string", "example": "evt_123" }, "required": true, "description": "Unique event ID. Matches the top-level `id` field in the request body.", "name": "X-Context-Id", "in": "header" }, { "schema": { "type": "string", "example": "whd_0123456789abcdef0123456789abcdef" }, "required": false, "description": "Delivery ID for status checks and retries.", "name": "X-Context-Delivery-Id", "in": "header" }, { "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "Attempt number, starting at 1.", "name": "X-Context-Attempt", "in": "header" }, { "schema": { "type": "string", "example": "t=1783620012,v1=087d98aada1e39f9d24d65951f51e672da12b2f9ea1c02c7c8c5ef254f5d4068" }, "required": false, "description": "`t=,v1=`: SHA-256 HMAC of `t.rawRequestBody`, keyed with the webhook secret. Verify with a constant-time comparison and reject stale timestamps.", "name": "X-Context-Signature", "in": "header" } ], "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. Slack incoming webhook destinations receive a formatted Slack message instead of this event envelope.", "operationId": "batchCancelled", "tags": [ "Batches" ], "security": [], "parameters": [ { "schema": { "type": "string", "example": "Context.dev-Webhooks/1.0" }, "required": true, "description": "Identifies the Context.dev webhook sender.", "name": "User-Agent", "in": "header" }, { "schema": { "type": "string", "enum": [ "batch.cancelled" ] }, "required": true, "description": "Which final status the batch reached. Matches the `event` field in the request body.", "name": "X-Context-Event", "in": "header" }, { "schema": { "type": "string", "example": "evt_123" }, "required": true, "description": "Unique event ID. Matches the top-level `id` field in the request body.", "name": "X-Context-Id", "in": "header" }, { "schema": { "type": "string", "example": "whd_0123456789abcdef0123456789abcdef" }, "required": false, "description": "Delivery ID for status checks and retries.", "name": "X-Context-Delivery-Id", "in": "header" }, { "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "Attempt number, starting at 1.", "name": "X-Context-Attempt", "in": "header" }, { "schema": { "type": "string", "example": "t=1783620012,v1=087d98aada1e39f9d24d65951f51e672da12b2f9ea1c02c7c8c5ef254f5d4068" }, "required": false, "description": "`t=,v1=`: SHA-256 HMAC of `t.rawRequestBody`, keyed with the webhook secret. Verify with a constant-time comparison and reject stale timestamps.", "name": "X-Context-Signature", "in": "header" } ], "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 labels for filtering usage, e.g. `production,team-alpha`.", "example": "production,team-alpha" } }, "headers": { "RequestId": { "description": "Unique ID of this request; also `request_id` in JSON bodies.", "schema": { "type": "string", "format": "uuid" } }, "RateLimitLimit": { "description": "Maximum request units per minute, or maximum concurrent requests when X-RateLimit-Mode is concurrency.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimitRemaining": { "description": "Request units remaining in the current minute, or concurrent requests still available when X-RateLimit-Mode is concurrency.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimitReset": { "description": "Unix timestamp in seconds when the per-minute rate limit resets. Omitted for concurrency limits.", "schema": { "type": "integer" } }, "RateLimitMode": { "description": "Set to concurrency when the organization is limited by concurrent requests. Omitted for per-minute limits.", "schema": { "type": "string", "enum": [ "concurrency" ] } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1, "maximum": 60 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable 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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } } }, "MonitorsLimitExceeded": { "description": "Monitor limit reached (`MONITOR_LIMIT_EXCEEDED`), browser actions need a paid plan (`PAID_PLAN_REQUIRED`), or the key lacks `monitors:write` (`INSUFFICIENT_PERMISSIONS`).", "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } } }, "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" }, "X-RateLimit-Mode": { "$ref": "#/components/headers/RateLimitMode" } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Send `Authorization: Bearer `. Keys have full access unless restricted to scopes." } }, "schemas": { "ScrapeRequest": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https?://", "description": "Public HTTP or HTTPS URL to scrape." }, "formats": { "$ref": "#/components/schemas/ScrapeFormats", "description": "Outputs to return. Set at least one to `true`." }, "markdownParams": { "$ref": "#/components/schemas/ScrapeMarkdownParams", "description": "Markdown options. Requires `formats.markdown`." }, "screenshotParams": { "$ref": "#/components/schemas/ScrapeScreenshotParams", "description": "Screenshot options. Requires formats.screenshot: true." }, "imageParams": { "$ref": "#/components/schemas/ScrapeImageParams", "description": "Image options. Requires formats.images: true." }, "parseParams": { "$ref": "#/components/schemas/ScrapeParseParams", "description": "Requires `formats.parse: true`; required when it is set." }, "highlightsParams": { "$ref": "#/components/schemas/ScrapeHighlightsParams", "description": "Requires `formats.highlights: true`; required when it is set." }, "jsonParams": { "$ref": "#/components/schemas/ScrapeJsonParams", "description": "Requires `formats.json: true`; required when it is set." }, "productParams": { "$ref": "#/components/schemas/ScrapeProductParams", "description": "Product options. Requires formats.product: true." }, "sharedParams": { "$ref": "#/components/schemas/ScrapeSharedParams", "description": "Browser and content settings shared by all outputs." }, "maxAgeMs": { "type": "integer", "minimum": 0, "maximum": 31536000000, "default": 259200000, "description": "Maximum age of a cached output, in milliseconds. `0` fetches fresh. Defaults to 3 days (259200000 ms). Maximum: 1 year (31536000000 ms)." }, "zdr": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled", "description": "`enabled` turns on zero data retention. Your organization must have ZDR enabled." }, "timeoutOpts": { "$ref": "#/components/schemas/ScrapeTimeout", "default": { "milliseconds": 90000, "behavior": "fail" }, "description": "Deadline for the whole request. Defaults to 90000 ms with `fail`. Fixed waits must end before it." }, "tags": { "$ref": "#/components/schemas/RequestTags", "description": "Labels for tracking request usage. Not retained when zdr is enabled." } }, "required": [ "url", "formats" ], "allOf": [ { "if": { "required": [ "markdownParams" ] }, "then": { "properties": { "formats": { "required": [ "markdown" ], "properties": { "markdown": { "const": true } } } } } }, { "if": { "required": [ "screenshotParams" ] }, "then": { "properties": { "formats": { "required": [ "screenshot" ], "properties": { "screenshot": { "const": true } } } } } }, { "if": { "required": [ "imageParams" ] }, "then": { "properties": { "formats": { "required": [ "images" ], "properties": { "images": { "const": true } } } } } }, { "if": { "required": [ "parseParams" ] }, "then": { "properties": { "formats": { "required": [ "parse" ], "properties": { "parse": { "const": true } } } } } }, { "if": { "properties": { "formats": { "required": [ "parse" ], "properties": { "parse": { "const": true } } } } }, "then": { "required": [ "parseParams" ] } }, { "if": { "required": [ "highlightsParams" ] }, "then": { "properties": { "formats": { "required": [ "highlights" ], "properties": { "highlights": { "const": true } } } } } }, { "if": { "properties": { "formats": { "required": [ "highlights" ], "properties": { "highlights": { "const": true } } } } }, "then": { "required": [ "highlightsParams" ] } }, { "if": { "required": [ "jsonParams" ] }, "then": { "properties": { "formats": { "required": [ "json" ], "properties": { "json": { "const": true } } } } } }, { "if": { "properties": { "formats": { "required": [ "json" ], "properties": { "json": { "const": true } } } } }, "then": { "required": [ "jsonParams" ] } }, { "if": { "required": [ "productParams" ] }, "then": { "properties": { "formats": { "required": [ "product" ], "properties": { "product": { "const": true } } } } } } ] }, "ScrapeFormats": { "type": "object", "additionalProperties": false, "properties": { "html": { "type": "boolean", "default": false, "description": "Rendered HTML." }, "markdown": { "type": "boolean", "default": false, "description": "Page content as Markdown." }, "screenshot": { "type": "boolean", "default": false, "description": "A screenshot of the page." }, "images": { "type": "boolean", "default": false, "description": "Images found on the page." }, "bytes": { "type": "boolean", "default": false, "description": "The original HTTP response body." }, "parse": { "type": "boolean", "default": false, "description": "Fields extracted with `parseParams.rules`, returned as `parsed`." }, "highlights": { "type": "boolean", "default": false, "description": "Markdown excerpts relevant to `highlightsParams.query`." }, "json": { "type": "boolean", "default": false, "description": "An object matching `jsonParams.schema`, extracted from the page." }, "product": { "type": "boolean", "default": false, "description": "Product details such as name, price, and availability." } }, "not": { "allOf": [ { "not": { "required": [ "html" ], "properties": { "html": { "const": true } } } }, { "not": { "required": [ "markdown" ], "properties": { "markdown": { "const": true } } } }, { "not": { "required": [ "screenshot" ], "properties": { "screenshot": { "const": true } } } }, { "not": { "required": [ "images" ], "properties": { "images": { "const": true } } } }, { "not": { "required": [ "bytes" ], "properties": { "bytes": { "const": true } } } }, { "not": { "required": [ "parse" ], "properties": { "parse": { "const": true } } } }, { "not": { "required": [ "highlights" ], "properties": { "highlights": { "const": true } } } }, { "not": { "required": [ "json" ], "properties": { "json": { "const": true } } } }, { "not": { "required": [ "product" ], "properties": { "product": { "const": true } } } } ] } }, "ScrapeSharedParams": { "type": "object", "additionalProperties": false, "properties": { "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "examples": [ "US" ], "description": "Proxy country as a two-letter code, such as `US`. Case-insensitive." }, "headers": { "type": "object", "propertyNames": { "pattern": "^[!#$%&'*+.^_`|~0-9A-Za-z-]+$", "not": { "pattern": "^(?:[Hh][Oo][Ss][Tt]|[Cc][Oo][Nn][Tt][Ee][Nn][Tt]-[Ll][Ee][Nn][Gg][Tt][Hh]|[Cc][Oo][Nn][Nn][Ee][Cc][Tt][Ii][Oo][Nn]|[Kk][Ee][Ee][Pp]-[Aa][Ll][Ii][Vv][Ee]|[Pp][Rr][Oo][Xx][Yy]-[Aa][Uu][Tt][Hh][Ee][Nn][Tt][Ii][Cc][Aa][Tt][Ee]|[Pp][Rr][Oo][Xx][Yy]-[Aa][Uu][Tt][Hh][Oo][Rr][Ii][Zz][Aa][Tt][Ii][Oo][Nn]|[Pp][Rr][Oo][Xx][Yy]-[Cc][Oo][Nn][Nn][Ee][Cc][Tt][Ii][Oo][Nn]|[Tt][Ee]|[Tt][Rr][Aa][Ii][Ll][Ee][Rr]|[Tt][Rr][Aa][Nn][Ss][Ff][Ee][Rr]-[Ee][Nn][Cc][Oo][Dd][Ii][Nn][Gg]|[Uu][Pp][Gg][Rr][Aa][Dd][Ee]|[Ee][Xx][Pp][Ee][Cc][Tt])$" } }, "additionalProperties": { "type": "string", "maxLength": 8192, "pattern": "^[^\\r\\n]*$" }, "description": "HTTP headers to send to the target site. Requests with headers skip the cache.", "examples": [ { "Accept-Language": "en-US" } ] }, "viewport": { "type": "object", "additionalProperties": false, "properties": { "width": { "type": "integer", "description": "Browser viewport width in pixels.", "minimum": 240, "maximum": 7680, "default": 1440 }, "height": { "type": "integer", "description": "Browser viewport height in pixels.", "minimum": 240, "maximum": 4320, "default": 900 } }, "description": "Browser size in pixels. Omit for 1920 × 1080. When provided, missing dimensions default to 1440 × 900." }, "theme": { "type": "string", "enum": [ "light", "dark" ], "description": "Emulate a light or dark color scheme." }, "dismissCookies": { "type": "boolean", "default": true, "description": "Accept cookie banners before actions and capture." }, "dismissPopups": { "type": "boolean", "default": false, "description": "Close other popups before actions and capture." }, "actions": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "$ref": "#/components/schemas/ScrapeAction" }, "description": "Browser steps run in order before capture. Requires a paid plan. Skips the cache." }, "waitFor": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 30000, "title": "Milliseconds" }, { "type": "string", "pattern": "\\S", "maxLength": 2048, "title": "CSS selector" } ], "examples": [ 500, "#content" ], "description": "Milliseconds, or a CSS selector to wait for, after actions. Defaults to 500 (2000 with frames or XML)." }, "settleAnimations": { "type": "boolean", "description": "Wait for CSS animations to finish before capture. Defaults to `true` when `screenshot` is requested." }, "mainContentOnly": { "type": "boolean", "default": false, "description": "Keep only the main content. Doesn't affect `screenshot`, `bytes`, or `product`." }, "includeSelectors": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "pattern": "\\S", "maxLength": 2048 }, "description": "Keep only elements matching these CSS selectors." }, "excludeSelectors": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "pattern": "\\S", "maxLength": 2048 }, "description": "Remove elements matching these CSS selectors. Overrides `includeSelectors`." }, "includeFrames": { "type": "boolean", "default": false, "description": "Include iframe content in HTML and text outputs. Screenshots always show visible frames." }, "parsers": { "type": "object", "additionalProperties": false, "description": "Document parsing options.", "properties": { "pdf": { "$ref": "#/components/schemas/ScrapePdfOptions", "description": "PDF page range and OCR." } } } } }, "ScrapeScreenshotParams": { "type": "object", "additionalProperties": false, "properties": { "area": { "default": "viewport", "description": "What to capture: `viewport`, `fullPage`, one element, or a rectangle. Max 40 megapixels.", "oneOf": [ { "type": "string", "enum": [ "viewport", "fullPage" ], "title": "Page" }, { "type": "object", "additionalProperties": false, "properties": { "selector": { "type": "string", "pattern": "\\S", "maxLength": 2048, "description": "CSS selector matching exactly one visible element." } }, "required": [ "selector" ], "title": "Element" }, { "type": "object", "additionalProperties": false, "properties": { "x": { "type": "integer", "description": "Left edge of the capture, in pixels from the document origin.", "minimum": 0, "maximum": 100000 }, "y": { "type": "integer", "description": "Top edge of the capture, in pixels from the document origin.", "minimum": 0, "maximum": 100000 }, "width": { "type": "integer", "description": "Width of the capture in pixels.", "minimum": 1, "maximum": 7680 }, "height": { "type": "integer", "description": "Height of the capture in pixels.", "minimum": 1, "maximum": 100000 } }, "required": [ "x", "y", "width", "height" ], "title": "Rectangle", "description": "Pixels from the document origin." } ] }, "format": { "type": "string", "enum": [ "png", "jpeg", "webp" ], "default": "png", "description": "Image format for the screenshot." } } }, "ScrapeMarkdownParams": { "type": "object", "additionalProperties": false, "properties": { "includeLinks": { "type": "boolean", "default": true, "description": "Keep link URLs in the Markdown. Set false to return link text without URLs." }, "includeImages": { "type": "boolean", "default": false, "description": "Include images in the Markdown using image syntax with URLs and alt text." }, "inlineImages": { "type": "string", "enum": [ "placeholder", "preserve" ], "description": "How base64 images appear: `placeholder` (default) or `preserve`. Requires `includeImages`." } }, "allOf": [ { "if": { "required": [ "inlineImages" ] }, "then": { "required": [ "includeImages" ], "properties": { "includeImages": { "const": true } } } } ] }, "ScrapeImageParams": { "type": "object", "additionalProperties": false, "properties": { "enrich": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "dimensions", "classification", "file" ] }, "description": "Extra data per image: `dimensions`, `classification`, or a hosted `file` URL." }, "dedupe": { "type": "string", "enum": [ "none", "visual" ], "default": "none", "description": "Set `visual` to drop visual duplicates, keeping the largest copy." } } }, "ScrapeHighlightsParams": { "type": "object", "additionalProperties": false, "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The question or topic to find passages for." }, "maxCharacters": { "type": "integer", "minimum": 100, "maximum": 20000, "default": 4000, "description": "Maximum combined length of returned passages." } }, "required": [ "query" ] }, "ScrapeParseParams": { "type": "object", "additionalProperties": false, "properties": { "rules": { "$ref": "#/components/schemas/ScrapeParseRules" } }, "required": [ "rules" ] }, "ScrapePdfOptions": { "type": "object", "additionalProperties": false, "properties": { "startPage": { "type": "integer", "minimum": 1, "description": "First page to parse, starting at 1." }, "endPage": { "type": "integer", "minimum": 1, "description": "Last page to parse. Must be at least `startPage`." }, "ocr": { "type": "string", "enum": [ "off", "auto" ], "default": "off", "description": "Set `auto` to read scanned pages with OCR." } } }, "ScrapeAction": { "title": "Browser action", "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "perform" ], "description": "Use `perform` for a plain-language browser instruction." }, "action": { "type": "string", "minLength": 1, "maxLength": 500, "examples": [ "Click the product details tab" ], "description": "One browser instruction, such as clicking a button or entering text." } }, "required": [ "type", "action" ], "title": "Instruction" }, { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "scroll" ], "description": "Use `scroll` to move through the page or a container." }, "direction": { "type": "string", "enum": [ "down", "up", "left", "right" ], "default": "down", "description": "Direction to scroll." }, "amount": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100000 }, { "type": "string", "enum": [ "viewport", "max" ] } ], "default": "viewport", "description": "Distance per scroll: pixels, one `viewport`, or `max` to reach the end." }, "selector": { "type": "string", "pattern": "\\S", "maxLength": 2000, "description": "Scroll this container. Omit to scroll the page." }, "maxScrolls": { "type": "integer", "description": "Maximum number of scroll steps for this action.", "minimum": 1, "maximum": 50, "default": 1 } }, "required": [ "type" ], "title": "Scroll" }, { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "wait" ], "description": "Use `wait` to pause for a fixed duration." }, "milliseconds": { "type": "integer", "description": "Time to pause in milliseconds before the next action.", "minimum": 0, "maximum": 30000 } }, "required": [ "type", "milliseconds" ], "title": "Wait" }, { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "waitFor" ], "description": "Use `waitFor` to wait for a matching element." }, "selector": { "type": "string", "pattern": "\\S", "maxLength": 2048, "description": "CSS selector to wait for before continuing." } }, "required": [ "type", "selector" ], "title": "Wait for element" } ], "discriminator": { "propertyName": "type" } }, "ScrapeResponse": { "type": "object", "additionalProperties": false, "properties": { "isPartial": { "type": "boolean", "const": true, "description": "True when at least one requested output succeeds but the response has failed or incomplete outputs. Absent when all requested outputs fail." }, "url": { "type": "string", "format": "uri", "pattern": "^https?://", "description": "Final URL after redirects and browser actions." }, "html": { "type": "object", "additionalProperties": false, "properties": { "error_code": { "type": "string", "description": "Why the output failed. Present only when `success` is `false`." }, "message": { "type": "string", "description": "Explanation of the failure and possible next steps." }, "requested": { "type": "boolean" }, "success": { "type": [ "boolean", "null" ], "description": "`true` if returned, `false` if it failed, `null` if not requested." }, "data": { "type": [ "string", "null" ] } }, "required": [ "requested", "success", "data" ], "allOf": [ { "if": { "properties": { "requested": { "const": true } } }, "then": { "properties": { "success": { "type": "boolean" } } }, "else": { "properties": { "success": { "type": "null" } } } } ], "if": { "properties": { "success": { "const": true } } }, "then": { "properties": { "data": { "type": "string" } } }, "else": { "properties": { "data": { "type": "null" } } }, "description": "Rendered HTML after content filters." }, "markdown": { "type": "object", "additionalProperties": false, "properties": { "error_code": { "type": "string", "description": "Why the output failed. Present only when `success` is `false`." }, "message": { "type": "string", "description": "Explanation of the failure and possible next steps." }, "requested": { "type": "boolean" }, "success": { "type": [ "boolean", "null" ], "description": "`true` if returned, `false` if it failed, `null` if not requested." }, "data": { "type": [ "string", "null" ] } }, "required": [ "requested", "success", "data" ], "allOf": [ { "if": { "properties": { "requested": { "const": true } } }, "then": { "properties": { "success": { "type": "boolean" } } }, "else": { "properties": { "success": { "type": "null" } } } } ], "if": { "properties": { "success": { "const": true } } }, "then": { "properties": { "data": { "type": "string" } } }, "else": { "properties": { "data": { "type": "null" } } }, "description": "Markdown after content filters." }, "screenshot": { "type": "object", "additionalProperties": false, "properties": { "error_code": { "type": "string", "description": "Why the output failed. Present only when `success` is `false`." }, "message": { "type": "string", "description": "Explanation of the failure and possible next steps." }, "requested": { "type": "boolean" }, "success": { "type": [ "boolean", "null" ], "description": "`true` if returned, `false` if it failed, `null` if not requested." }, "data": { "type": [ "string", "null" ], "format": "uri", "pattern": "^data:image/(?:png|jpeg|webp);base64,[A-Za-z0-9+/]+={0,2}$" } }, "required": [ "requested", "success", "data" ], "allOf": [ { "if": { "properties": { "requested": { "const": true } } }, "then": { "properties": { "success": { "type": "boolean" } } }, "else": { "properties": { "success": { "type": "null" } } } } ], "if": { "properties": { "success": { "const": true } } }, "then": { "properties": { "data": { "type": "string", "format": "uri", "pattern": "^data:image/(?:png|jpeg|webp);base64,[A-Za-z0-9+/]+={0,2}$" } } }, "else": { "properties": { "data": { "type": "null" } } }, "description": "Screenshot as a base64 image data URL." }, "images": { "type": "object", "additionalProperties": false, "properties": { "error_code": { "type": "string", "description": "Why the output failed. Present only when `success` is `false`." }, "message": { "type": "string", "description": "Explanation of the failure and possible next steps." }, "requested": { "type": "boolean" }, "success": { "type": [ "boolean", "null" ], "description": "`true` if returned, `false` if it failed, `null` if not requested." }, "data": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ScrapeImage" } } }, "required": [ "requested", "success", "data" ], "allOf": [ { "if": { "properties": { "requested": { "const": true } } }, "then": { "properties": { "success": { "type": "boolean" } } }, "else": { "properties": { "success": { "type": "null" } } } } ], "if": { "properties": { "success": { "const": true } } }, "then": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScrapeImage" } } } }, "else": { "properties": { "data": { "type": "null" } } }, "description": "Images after content filters. `[]` when none are found." }, "bytes": { "type": "object", "additionalProperties": false, "properties": { "error_code": { "type": "string", "description": "Why the output failed. Present only when `success` is `false`." }, "message": { "type": "string", "description": "Explanation of the failure and possible next steps." }, "requested": { "type": "boolean" }, "success": { "type": [ "boolean", "null" ], "description": "`true` if returned, `false` if it failed, `null` if not requested." }, "data": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "contentType": { "type": "string", "examples": [ "text/html; charset=utf-8" ] }, "base64": { "type": "string", "contentEncoding": "base64", "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$", "description": "Body as base64, after HTTP decompression. Up to 50 MiB decoded." } }, "required": [ "contentType", "base64" ] } }, "required": [ "requested", "success", "data" ], "allOf": [ { "if": { "properties": { "requested": { "const": true } } }, "then": { "properties": { "success": { "type": "boolean" } } }, "else": { "properties": { "success": { "type": "null" } } } } ], "if": { "properties": { "success": { "const": true } } }, "then": { "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "contentType": { "type": "string", "examples": [ "text/html; charset=utf-8" ] }, "base64": { "type": "string", "contentEncoding": "base64", "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$", "description": "Body as base64, after HTTP decompression. Up to 50 MiB decoded." } }, "required": [ "contentType", "base64" ] } } }, "else": { "properties": { "data": { "type": "null" } } }, "description": "The original HTTP response body, unchanged by waits, actions, and filters." }, "parsed": { "type": "object", "additionalProperties": false, "properties": { "error_code": { "type": "string", "description": "Why the output failed. Present only when `success` is `false`." }, "message": { "type": "string", "description": "Explanation of the failure and possible next steps." }, "requested": { "type": "boolean" }, "success": { "type": [ "boolean", "null" ], "description": "`true` if returned, `false` if it failed, `null` if not requested." }, "data": { "type": [ "object", "null" ], "additionalProperties": true } }, "required": [ "requested", "success", "data" ], "allOf": [ { "if": { "properties": { "requested": { "const": true } } }, "then": { "properties": { "success": { "type": "boolean" } } }, "else": { "properties": { "success": { "type": "null" } } } } ], "if": { "properties": { "success": { "const": true } } }, "then": { "properties": { "data": { "type": "object", "additionalProperties": true } } }, "else": { "properties": { "data": { "type": "null" } } }, "description": "Fields from `parseParams.rules`, after content filters. Unmatched fields are `null` (`[]` for lists)." }, "highlights": { "type": "object", "additionalProperties": false, "properties": { "error_code": { "type": "string", "description": "Why the output failed. Present only when `success` is `false`." }, "message": { "type": "string", "description": "Explanation of the failure and possible next steps." }, "requested": { "type": "boolean" }, "success": { "type": [ "boolean", "null" ], "description": "`true` if returned, `false` if it failed, `null` if not requested." }, "data": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "requested", "success", "data" ], "allOf": [ { "if": { "properties": { "requested": { "const": true } } }, "then": { "properties": { "success": { "type": "boolean" } } }, "else": { "properties": { "success": { "type": "null" } } } } ], "if": { "properties": { "success": { "const": true } } }, "then": { "properties": { "data": { "type": "array", "items": { "type": "string" } } } }, "else": { "properties": { "data": { "type": "null" } } }, "description": "Relevant Markdown excerpts in page order. `[Heading]` adds context; `…` marks omitted text." }, "metadata": { "$ref": "#/components/schemas/ScrapeMetadata", "description": "Page metadata. Fields are omitted when not found." }, "cache_metadata": { "$ref": "#/components/schemas/CacheMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "json": { "type": "object", "additionalProperties": false, "properties": { "error_code": { "type": "string", "description": "Why the output failed. Present only when `success` is `false`." }, "message": { "type": "string", "description": "Explanation of the failure and possible next steps." }, "requested": { "type": "boolean" }, "success": { "type": [ "boolean", "null" ], "description": "`true` if returned, `false` if it failed, `null` if not requested." }, "data": { "type": [ "object", "null" ], "additionalProperties": true } }, "required": [ "requested", "success", "data" ], "allOf": [ { "if": { "properties": { "requested": { "const": true } } }, "then": { "properties": { "success": { "type": "boolean" } } }, "else": { "properties": { "success": { "type": "null" } } } } ], "if": { "properties": { "success": { "const": true } } }, "then": { "properties": { "data": { "type": "object", "additionalProperties": true } } }, "else": { "properties": { "data": { "type": "null" } } }, "description": "Object matching `jsonParams.schema`." }, "product": { "type": "object", "additionalProperties": false, "properties": { "error_code": { "type": "string", "description": "Why the output failed. Present only when `success` is `false`." }, "message": { "type": "string", "description": "Explanation of the failure and possible next steps." }, "requested": { "type": "boolean" }, "success": { "type": [ "boolean", "null" ], "description": "`true` if returned, `false` if it failed, `null` if not requested." }, "data": { "oneOf": [ { "$ref": "#/components/schemas/ScrapeProductResult" }, { "type": "null" } ] } }, "required": [ "requested", "success", "data" ], "allOf": [ { "if": { "properties": { "requested": { "const": true } } }, "then": { "properties": { "success": { "type": "boolean" } } }, "else": { "properties": { "success": { "type": "null" } } } } ], "if": { "properties": { "success": { "const": true } } }, "then": { "properties": { "data": { "$ref": "#/components/schemas/ScrapeProductResult" } } }, "else": { "properties": { "data": { "type": "null" } } }, "description": "Product details found on the page." } }, "required": [ "url", "html", "markdown", "screenshot", "images", "bytes", "parsed", "highlights", "metadata", "cache_metadata", "request_id", "json", "product" ], "not": { "properties": { "html": { "properties": { "requested": { "const": false } } }, "markdown": { "properties": { "requested": { "const": false } } }, "screenshot": { "properties": { "requested": { "const": false } } }, "images": { "properties": { "requested": { "const": false } } }, "bytes": { "properties": { "requested": { "const": false } } }, "parsed": { "properties": { "requested": { "const": false } } }, "highlights": { "properties": { "requested": { "const": false } } }, "json": { "properties": { "requested": { "const": false } } }, "product": { "properties": { "requested": { "const": false } } } } } }, "ScrapeImage": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "pattern": "^(https?://|data:image/)", "description": "Image URL, or a data URI for inline images." }, "alt": { "type": [ "string", "null" ], "description": "Alt text, if present." }, "width": { "type": "integer", "minimum": 1 }, "height": { "type": "integer", "minimum": 1 }, "classification": { "type": "string", "enum": [ "photography", "illustration", "logo", "wordmark", "icon", "pattern", "graphic", "other" ] }, "fileUrl": { "type": "string", "format": "uri", "pattern": "^https?://", "description": "Hosted image URL, valid for 24 hours after capture. Requires `file` enrichment and ZDR disabled." } }, "required": [ "url", "alt" ] }, "ScrapeMetadata": { "type": "object", "additionalProperties": false, "properties": { "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": "Up to 500 h1–h6 headings in document order, before content filtering." }, "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." } } }, "ScrapeParseRules": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048 }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "CSS selector to match within the current page or parent rule." }, "type": { "type": "string", "enum": [ "item", "list" ], "description": "Return the first match with `item` or all matches with `list`." }, "output": { "description": "Return text, HTML, an attribute such as `@href`, or nested field rules. Defaults to text.", "anyOf": [ { "type": "string", "enum": [ "text", "html" ] }, { "type": "string", "pattern": "^@.*$" }, { "$ref": "#/components/schemas/ScrapeParseRules" } ] } }, "required": [ "selector" ], "additionalProperties": false } ] }, "minProperties": 1, "description": "Field names mapped to CSS selectors (`h1`, `a@href`) or rule objects. Max 100 fields, 5 levels.", "examples": [ { "title": "h1", "links": { "selector": "a", "type": "list", "output": "@href" } } ] }, "ScrapeJsonParams": { "type": "object", "additionalProperties": false, "properties": { "schema": { "type": "object", "additionalProperties": true, "description": "JSON Schema (not an example object) for a top-level object, up to 50 KB. Use optional or nullable fields for missing facts.", "example": { "type": "object", "properties": { "name": { "type": "string", "description": "Product name." }, "price": { "type": "number", "description": "Current price as a plain number." }, "inStock": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "instructions": { "type": "string", "maxLength": 2000, "description": "Extra guidance, such as which facts to prefer or how to read a field." } }, "required": [ "schema" ] }, "ScrapeProduct": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Product name." }, "description": { "type": [ "string", "null" ], "description": "Product description." }, "brand": { "type": [ "string", "null" ], "description": "Brand or vendor." }, "sku": { "type": [ "string", "null" ], "description": "Product identifier such as a SKU or model number." }, "price": { "type": [ "number", "null" ], "description": "Current price." }, "regularPrice": { "type": [ "number", "null" ], "description": "List price before any discount." }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217 currency code." }, "availability": { "type": [ "string", "null" ], "enum": [ "in_stock", "out_of_stock", "limited_availability", "preorder", "backorder", "made_to_order", "discontinued", null ], "description": "Stock or ordering availability." }, "category": { "type": [ "string", "null" ], "description": "Product category." }, "imageUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Main product image URL." }, "images": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Product image URLs, main image first." }, "dimensions": { "type": "array", "items": { "type": "string" }, "description": "Product dimensions as shown on the page." }, "features": { "type": "array", "items": { "type": "string" }, "description": "Key features and specifications." }, "targetAudience": { "type": "array", "items": { "type": "string" }, "description": "Intended audience." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Product tags." }, "variants": { "$ref": "#/components/schemas/ProductVariants" } }, "required": [ "name", "description", "brand", "sku", "price", "regularPrice", "currency", "availability", "category", "imageUrl", "images", "dimensions", "features", "targetAudience", "tags", "variants" ] }, "ScrapeProductResult": { "type": "object", "additionalProperties": false, "properties": { "isProductPage": { "type": "boolean", "description": "Whether the page is a product detail page." }, "product": { "oneOf": [ { "$ref": "#/components/schemas/ScrapeProduct" }, { "type": "null" } ], "description": "The extracted product, or null when the page is not a product detail page." } }, "required": [ "isProductPage", "product" ] }, "ScrapeProductParams": { "type": "object", "additionalProperties": false, "properties": { "dedupeImages": { "type": "boolean", "default": false, "description": "Drop visually duplicate product images, keeping the largest copy." } } }, "RequestTags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "maxItems": 20, "description": "Labels for filtering usage in the dashboard.", "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 from 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, e.g. `english`." }, "RequestId": { "type": "string", "format": "uuid", "description": "Unique ID of this request, also in `X-Request-Id`. Include it when contacting support.", "example": "3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91" }, "KeyMetadata": { "type": "object", "properties": { "credits_consumed": { "type": "integer", "description": "Credits charged for this request." }, "credits_remaining": { "type": "integer", "description": "Credits remaining for your organization." } }, "required": [ "credits_consumed", "credits_remaining" ], "description": "Credits this request used and your remaining balance." }, "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": "Whether this response came from cache." }, "BrandResponse": { "type": "object", "properties": { "partial": { "type": "boolean", "description": "True when the timeout ended processing and this response contains the usable data completed so far. Unfinished fields are omitted." }, "status": { "type": "string", "description": "Always `ok` on success." }, "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": "Hosted logo URL." }, "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": [ "status", "brand", "code", "cache_metadata", "request_id" ] }, "ErrorResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable 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", "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": "Machine-readable error code." }, "required_permission": { "type": "string", "enum": [ "logs:read", "data:execute", "monitors:read", "monitors:write", "batches:read", "batches:write" ], "description": "Permission required for this request when error_code is INSUFFICIENT_PERMISSIONS. Manage (write) also grants read access to the same resource group." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ] }, "Timeout": { "type": "object", "properties": { "milliseconds": { "type": "integer", "minimum": 1000, "maximum": 300000, "description": "Deadline in milliseconds." }, "behavior": { "type": "string", "enum": [ "fail" ], "default": "fail", "description": "Only \"fail\" is supported: return 408 at the deadline." } }, "required": [ "milliseconds" ], "additionalProperties": false, "description": "Request deadline and what to return when it passes." }, "PartialTimeout": { "type": "object", "properties": { "milliseconds": { "type": "integer", "minimum": 1000, "maximum": 300000, "description": "Deadline in milliseconds." }, "behavior": { "type": "string", "enum": [ "fail", "return-partial" ], "default": "fail", "description": "\"fail\" returns 408 at the deadline. \"return-partial\" returns available results; inspect the response’s partial flag." } }, "required": [ "milliseconds" ], "additionalProperties": false, "description": "Request deadline and what to return when it passes." }, "LenientPartialTimeout": { "type": "object", "properties": { "milliseconds": { "type": "integer", "minimum": 1, "maximum": 300000, "description": "Deadline in milliseconds." }, "behavior": { "type": "string", "enum": [ "fail", "return-partial" ], "default": "fail", "description": "\"fail\" returns 408 at the deadline. \"return-partial\" returns available results; inspect the response’s partial flag." } }, "required": [ "milliseconds" ], "additionalProperties": false, "description": "Request deadline and what to return when it passes." }, "ScrapeTimeout": { "type": "object", "properties": { "milliseconds": { "type": "integer", "minimum": 1, "maximum": 300000, "description": "Deadline in milliseconds." }, "behavior": { "type": "string", "enum": [ "fail", "return-partial" ], "default": "fail", "description": "\"fail\" returns 408 at the deadline. \"return-partial\" returns available results; inspect the response’s partial flag. \"return-partial\" requires at least 5000 ms." } }, "required": [ "milliseconds" ], "additionalProperties": false, "description": "Request deadline and what to return when it passes." }, "UtilityPrefetchDomainIdentifier": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 3, "description": "Domain, e.g. `stripe.com`." } }, "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 of cached brand data in ms. Defaults to 3 months; clamped to 0–1 year. `0` refreshes." }, "timeoutOpts": { "$ref": "#/components/schemas/PartialTimeout" }, "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 of cached brand data in ms. Defaults to 3 months; clamped to 0–1 year. `0` refreshes." }, "timeoutOpts": { "$ref": "#/components/schemas/PartialTimeout" }, "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 of cached brand data in ms. Defaults to 3 months; clamped to 0–1 year. `0` refreshes." }, "timeoutOpts": { "$ref": "#/components/schemas/PartialTimeout" }, "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 of cached brand data in ms. Defaults to 3 months; clamped to 0–1 year. `0` refreshes." }, "timeoutOpts": { "$ref": "#/components/schemas/PartialTimeout" }, "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." }, "timeoutOpts": { "$ref": "#/components/schemas/PartialTimeout" }, "tags": { "$ref": "#/components/schemas/RequestTags" } }, "required": [ "type", "direct_url" ], "additionalProperties": false, "title": "By direct URL", "description": "Retrieve brand data from this exact URL. Cross-site enrichment and other lookup identifiers are excluded." }, "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." }, "timeoutOpts": { "$ref": "#/components/schemas/PartialTimeout" }, "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": "One lookup, chosen by `type`." }, "PersonEnrichmentRequest": { "type": "object", "properties": { "social_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 20, "description": "Public profile URLs for the person. A person-profile URL can identify the person without a name." }, "name": { "type": "object", "properties": { "first": { "type": "string", "minLength": 1, "maxLength": 100, "description": "First or given name." }, "last": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Last or family name." } }, "additionalProperties": false, "description": "Person name. Without an email or person-profile URL, provide both first and last name plus company, education, or location." }, "email": { "type": "string", "maxLength": 320, "format": "email", "description": "Email address of the person to find." }, "company": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Name of a company associated with the person." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Website domain of a company associated with the person." } }, "additionalProperties": false, "description": "Company context to help identify the person. Provide a name or domain." }, "education": { "type": "array", "items": { "type": "object", "properties": { "institution": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Name of the school or university." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Website domain of the school or university." } }, "additionalProperties": false, "description": "School or university, identified by name or domain." }, "degree": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Degree or qualification earned." }, "field_of_study": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Subject or major studied." }, "graduation_year": { "type": "integer", "minimum": 1900, "maximum": 2200, "description": "Four-digit graduation year." } }, "additionalProperties": false }, "minItems": 1, "maxItems": 10, "description": "Education history to help distinguish people with similar names." }, "location": { "type": "object", "properties": { "city": { "type": "string", "minLength": 1, "maxLength": 200, "description": "City associated with the person." }, "region": { "type": "string", "minLength": 1, "maxLength": 200, "description": "State, province, or region associated with the person." }, "country": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Country associated with the person." } }, "additionalProperties": false, "description": "Location context to help identify the person. Provide a city, region, or country." }, "timeoutOpts": { "$ref": "#/components/schemas/PartialTimeout" }, "zdr": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR." }, "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": { "partial": { "type": "boolean", "description": "True when the timeout ended processing and this response contains the usable data completed so far. Unfinished fields are omitted." }, "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": "Always `web`. Optional.", "title": "Monitor mode" }, "MonitorsPageTarget": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "page" ], "description": "Use `page` to watch one web page." }, "url": { "type": "string", "format": "uri", "description": "Public HTTP(S) page URL to monitor.", "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." }, "include_selectors": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "maxItems": 50, "description": "Monitor these CSS-selected regions. Empty or omitted uses main content. Changes create a new baseline.", "example": [ "#attraction-details" ] }, "exclude_selectors": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "maxItems": 50, "description": "Remove matching regions after inclusions. Changes create a new baseline.", "example": [ ".carousel", "[id^=\"TA_\"]" ] }, "actions": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/WebScrapeAction" }, "maxItems": 5, "description": "Optional browser actions executed in array order after the page loads, before content is captured, on every run. Requires a paid plan. Maximum: 5 actions. Changes create a new baseline." } }, "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" }, "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" ], "description": "Use `wait` to pause for a fixed duration." }, "timeMs": { "type": "integer", "minimum": 0, "maximum": 30000, "description": "Time to pause in milliseconds before the next action." } }, "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" ], "description": "Use `perform` for a plain-language browser instruction." }, "action": { "type": "string", "minLength": 1, "maxLength": 500, "description": "One browser instruction, such as clicking a button or entering text." } }, "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" ], "description": "Use `scroll` to move through the page or a container." }, "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" }, "MonitorsSitemapTarget": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "sitemap" ], "description": "Use `sitemap` to watch a site for added or removed URLs." }, "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 site’s URL inventory for confirmed additions and removals.", "title": "Sitemap target" }, "MonitorsExtractTarget": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "extract" ], "description": "Use `extract` to watch structured data across selected pages." }, "url": { "type": "string", "format": "uri", "description": "Root URL to extract structured data from.", "example": "https://acme.com" }, "schema": { "type": "object", "additionalProperties": {}, "description": "JSON Schema for page selection and the baseline snapshot. Changes return diffs and evidence.", "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, "description": "Allow page discovery on subdomains of the target site." } }, "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": "Track relevant pages selected by `schema` and `instructions`; refresh the page set periodically." } ] } ], "discriminator": { "propertyName": "type", "mapping": { "page": "#/components/schemas/MonitorsPageTarget", "sitemap": "#/components/schemas/MonitorsSitemapTarget", "extract": "#/components/schemas/MonitorsExtractTarget" } }, "description": "What to watch: a page, a sitemap, or data extracted from a site." }, "MonitorsExactChangeDetection": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "exact" ], "description": "Use `exact` to compare visible text or sitemap URLs." } }, "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" ], "description": "Use `semantic` to judge changes against the target instructions." }, "confidence_threshold": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.75, "description": "Minimum confidence required to report a meaningful change, from 0 to 1." } }, "required": [ "type" ], "additionalProperties": false, "description": "Detect meaningful content changes using the target’s instructions and optional schema.", "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": "How changes are judged. Defaults to `semantic` for extract targets and page targets with `instructions`, otherwise `exact`." }, "MonitorsScheduleUnit": { "type": "string", "enum": [ "minutes", "hours", "days" ], "description": "Time unit used with `frequency` to set the run interval.", "example": "hours" }, "MonitorsIntervalSchedule": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "interval" ], "description": "Use `interval` to run on a repeating schedule." }, "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": "How often the monitor runs. Defaults to once a day." }, "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": "Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted messages.", "example": "https://example.com/webhook" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "change.detected", "run.completed" ] }, "minItems": 1, "maxItems": 2, "uniqueItems": true, "description": "Events to deliver. Defaults to `change.detected`; `run.completed` also includes unchanged runs.", "example": [ "change.detected", "run.completed" ] }, "retry": { "$ref": "#/components/schemas/WebhookRetry" }, "secret": { "type": "string", "readOnly": true, "description": "API-generated signing secret. Visible only with full access or `monitors:write` permission.", "example": "whsec_8f3a…" } }, "required": [ "url" ], "additionalProperties": false }, "MonitorsNullableWebhookConfig": { "description": "Webhook destination and delivery settings. Null means no webhook is configured.", "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/MonitorsWebhookConfig" } ] }, { "type": "null" } ] }, "MonitorsCreateMonitorRequest": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/MonitorsMode" }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Display name for the monitor.", "example": "Acme pricing monitor" }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "maxItems": 20, "uniqueItems": true, "description": "Labels for filtering monitors, their changes, and their usage.", "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": "Monitor target, detection method, and schedule. Omitted schedules run daily." }, "MonitorsUpdateMonitorRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Display name for the monitor.", "example": "Acme pricing monitor" }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "maxItems": 20, "uniqueItems": true, "description": "Labels for filtering monitors, their changes, and their usage.", "example": [ "pricing", "competitor" ] }, "status": { "type": "string", "enum": [ "active", "paused" ], "description": "Set `paused` to stop scheduled runs or `active` to resume them." }, "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. Changing `url` issues a new secret." } }, "additionalProperties": false, "description": "Send only the fields to change. `target` replaces the whole target." }, "MonitorsMonitorStatus": { "type": "string", "enum": [ "active", "paused", "failed" ], "description": "Current state. Failed monitors keep running; paused monitors must be resumed with `status: \"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": "Latest structured snapshot matching the extraction schema, refreshed at most daily; `null` before capture.", "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; null while paused." }, "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": { "anyOf": [ { "$ref": "#/components/schemas/MonitorsWebhookFailure" }, { "type": "null" } ], "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": "Labels for filtering monitors, their changes, and their usage.", "example": [ "pricing", "competitor" ] }, "baseline": { "oneOf": [ { "$ref": "#/components/schemas/MonitorsPageBaseline" }, { "$ref": "#/components/schemas/MonitorsSitemapBaseline" }, { "$ref": "#/components/schemas/MonitorsExtractBaseline" }, { "type": "null" } ], "description": "Comparison baseline, included on Retrieve. Null until capture completes or after target changes." } }, "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": { "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; null while paused." }, "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": { "anyOf": [ { "$ref": "#/components/schemas/MonitorsWebhookFailure" }, { "type": "null" } ], "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": "Labels for filtering monitors, their changes, and their usage.", "example": [ "pricing", "competitor" ] }, "baseline": { "oneOf": [ { "$ref": "#/components/schemas/MonitorsPageBaseline" }, { "$ref": "#/components/schemas/MonitorsSitemapBaseline" }, { "$ref": "#/components/schemas/MonitorsExtractBaseline" }, { "type": "null" } ], "description": "Comparison baseline, included on Retrieve. Null until capture completes or after target changes." }, "initial_run_id": { "type": [ "string", "null" ], "description": "ID of the baseline run queued at creation; null if it will start on the next scheduled tick.", "example": "run_123" }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" } }, "required": [ "mode", "id", "name", "target", "change_detection", "status", "created_at", "updated_at", "initial_run_id", "request_id" ], "additionalProperties": false, "title": "Create monitor response" }, "MonitorsMonitorResponse": { "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; null while paused." }, "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": { "anyOf": [ { "$ref": "#/components/schemas/MonitorsWebhookFailure" }, { "type": "null" } ], "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": "Labels for filtering monitors, their changes, and their usage.", "example": [ "pricing", "competitor" ] }, "baseline": { "oneOf": [ { "$ref": "#/components/schemas/MonitorsPageBaseline" }, { "$ref": "#/components/schemas/MonitorsSitemapBaseline" }, { "$ref": "#/components/schemas/MonitorsExtractBaseline" }, { "type": "null" } ], "description": "Comparison baseline, included on Retrieve. Null until capture completes or after target changes." }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" } }, "required": [ "mode", "id", "name", "target", "change_detection", "status", "created_at", "updated_at", "request_id" ], "additionalProperties": false }, "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": "Outcome of the delivery attempt. Any 2xx response counts as delivered." }, "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": "A baseline run follows creation or a target or detection change." }, "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` for all attempts." }, "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" ] }, "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": "Labels for filtering monitors, their changes, and their usage.", "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": "Detected change, including applicable diffs, URLs, and supporting evidence." }, "MonitorsRunResponse": { "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": "A baseline run follows creation or a target or detection change." }, "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` for all attempts." }, "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." }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" } }, "required": [ "id", "monitor_id", "status", "run_type", "target_type", "change_detection_type", "change_detected", "baseline_created", "credits_charged", "request_id" ], "additionalProperties": false }, "MonitorsChangeResponse": { "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": "Labels for filtering monitors, their changes, and their usage.", "example": [ "pricing", "competitor" ] }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" } }, "required": [ "mode", "id", "monitor_id", "run_id", "target_type", "change_detection_type", "title", "summary", "detected_at", "url", "tags", "request_id" ], "additionalProperties": false }, "MonitorsListMonitorsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorsMonitor" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" } }, "required": [ "data", "has_more", "next_cursor", "request_id" ], "additionalProperties": false }, "MonitorsListRunsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorsRun" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" } }, "required": [ "data", "has_more", "next_cursor", "request_id" ], "additionalProperties": false }, "MonitorsListChangesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorsChange" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" } }, "required": [ "data", "has_more", "next_cursor", "request_id" ], "additionalProperties": false }, "MonitorsDeleteMonitorResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "mon_123" }, "deleted": { "type": "boolean", "example": true }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" } }, "required": [ "id", "deleted", "request_id" ], "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": "A baseline run follows creation or a target or detection change." }, "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": "Run snapshot at delivery time. Retrieve the run for its final usage details." }, "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": "ID of the queued run; pass it to Retrieve a monitor run." }, "queued": { "type": "boolean", "example": true }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" } }, "required": [ "monitor_id", "run_id", "queued", "request_id" ], "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." }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" } }, "required": [ "data", "total_credits", "request_id" ], "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": "Most monitors you can have: your plan's allowance or a custom limit." }, "plan": { "type": "string", "enum": [ "free", "starter", "pro", "scale" ], "description": "`starter` means Developer; `pro` means Pro or Growth; `scale` means Scale or Enterprise." }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" } }, "required": [ "monitors_used", "monitors_limit", "plan", "request_id" ], "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 return each page's HTML in `html`." }, "pdf": { "type": "object", "properties": { "shouldParse": { "type": "boolean", "default": true, "description": "Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`." }, "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": "Read scanned PDF pages with OCR; preserve pages that already have text." } }, "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 elements matching these CSS selectors. Filtered pages ignore `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 for CSS animations to finish before extracting, on browser-rendered pages." }, "country": { "$ref": "#/components/schemas/BrowserCountryCode" }, "maxAgeMs": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 31536000000, "default": 259200000, "description": "Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 year (31536000000 ms). `0` fetches fresh." } }, "default": { "includeLinks": true, "includeImages": false, "shortenBase64Images": true, "useMainContentOnly": false, "includeHTML": false, "pdf": { "shouldParse": true, "ocr": false }, "settleAnimations": false, "maxAgeMs": 259200000 }, "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": "Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`." }, "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": "Read scanned PDF pages with OCR; preserve pages that already have text." } }, "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 elements matching these CSS selectors. Filtered pages ignore `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 for CSS animations to finish before extracting, on browser-rendered pages." }, "country": { "$ref": "#/components/schemas/BrowserCountryCode" }, "maxAgeMs": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 31536000000, "default": 259200000, "description": "Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 year (31536000000 ms). `0` fetches fresh." } }, "default": { "useMainContentOnly": false, "pdf": { "shouldParse": true, "ocr": false }, "settleAnimations": false, "maxAgeMs": 259200000 }, "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 a list of up to 25,000 URLs." }, { "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 return each page's HTML in `html`." }, "pdf": { "type": "object", "properties": { "shouldParse": { "type": "boolean", "default": true, "description": "Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`." }, "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": "Read scanned PDF pages with OCR; preserve pages that already have text." } }, "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 elements matching these CSS selectors. Filtered pages ignore `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 for CSS animations to finish before extracting, on browser-rendered pages." }, "country": { "$ref": "#/components/schemas/BrowserCountryCode" }, "maxAgeMs": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 31536000000, "default": 259200000, "description": "Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 year (31536000000 ms). `0` fetches fresh." } }, "default": { "includeLinks": true, "includeImages": false, "shortenBase64Images": true, "useMainContentOnly": false, "includeHTML": false, "pdf": { "shouldParse": true, "ocr": false }, "settleAnimations": false, "maxAgeMs": 259200000 }, "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": "Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`." }, "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": "Read scanned PDF pages with OCR; preserve pages that already have text." } }, "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 elements matching these CSS selectors. Filtered pages ignore `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 for CSS animations to finish before extracting, on browser-rendered pages." }, "country": { "$ref": "#/components/schemas/BrowserCountryCode" }, "maxAgeMs": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 31536000000, "default": 259200000, "description": "Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 year (31536000000 ms). `0` fetches fresh." } }, "default": { "useMainContentOnly": false, "pdf": { "shouldParse": true, "ocr": false }, "settleAnimations": false, "maxAgeMs": 259200000 }, "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", "description": "Public HTTP(S) URL that receives batch completion, failure, or cancellation events." }, "retry": { "$ref": "#/components/schemas/WebhookRetry" } }, "required": [ "url" ], "additionalProperties": false, "description": "Where to send the batch's final-status event. Omit `retry` for one attempt; `{}` uses the default retry schedule." }, "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": "Crawl settings as submitted." }, "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 accepted; progress counts toward this total." }, "reserved_is_ceiling": { "type": "boolean", "example": false, "description": "True when `reserved` is a crawl ceiling; false when it is an exact URL 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": "Rejected input URLs; `null` for a crawl." } }, "required": [ "reserved", "reserved_is_ceiling", "submitted", "duplicates", "invalid" ], "x-stainless-model": "batch.intake", "description": "What the submission accepted." }, "Batch": { "type": "object", "properties": { "id": { "type": "string", "example": "batch_9f2c8a", "description": "Batch ID." }, "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": "`scrape` (URL list) or `crawl`." }, "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": "Accepted pages not yet attempted. Unused crawl capacity is excluded after completion." } }, "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 held when the batch was accepted." }, "refunded": { "type": "integer", "example": 6726, "description": "Credits returned for unsuccessful pages when the batch settles." }, "ocr_charged": { "type": "integer", "example": 42, "description": "OCR usage charged when the batch settles." }, "net": { "type": "integer", "example": 18091, "description": "`reserved` minus `refunded` plus `ocr_charged`." } }, "required": [ "reserved", "refunded", "ocr_charged", "net" ], "description": "Batch credit usage and settlement." }, "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 these links expire (24 hours after this response)." }, "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": "Result download links; null until the batch finishes. Files are deleted 180 days after the batch finishes." } }, "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 (first 100)." }, "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": "Pages that will be skipped." } }, "required": [ "succeeded", "failed", "pending" ], "description": "How far the batch got before cancellation." }, "credits": { "type": "object", "properties": { "reserved": { "type": "integer", "example": 24817, "description": "Credits held at submission; unused credits are refunded when the batch settles." } }, "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": "Batch timestamps." }, "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 held at submission." } }, "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 (first 100)." }, "cache_metadata": { "$ref": "#/components/schemas/CacheMetadata" }, "webhook_secret": { "type": "string", "description": "Secret for verifying `X-Context-Signature`. Only submit returns it, so store it." } }, "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 batch reached its final status." }, "data": { "type": "object", "properties": { "batch": { "allOf": [ { "$ref": "#/components/schemas/Batch" } ], "description": "The batch in its final state, as in Retrieve a batch without `invalid_urls`. Result links expire 24 hours after the event, and replays resend the original links." } }, "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 batch reached its final status." }, "data": { "type": "object", "properties": { "batch": { "allOf": [ { "$ref": "#/components/schemas/Batch" } ], "description": "The batch in its final state, as in Retrieve a batch without `invalid_urls`. Result links expire 24 hours after the event, and replays resend the original links." } }, "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 batch reached its final status." }, "data": { "type": "object", "properties": { "batch": { "allOf": [ { "$ref": "#/components/schemas/Batch" } ], "description": "The batch in its final state, as in Retrieve a batch without `invalid_urls`. Result links expire 24 hours after the event, and replays resend the original links." } }, "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": "Your `itemId` 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": "Number of PDF pages recovered by OCR. Omitted when OCR did not run." } }, "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": "Your `itemId` 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." }, "SubmitFeedbackResponse": { "type": "object", "properties": { "feedback_id": { "type": "string", "description": "ID of the stored feedback.", "example": "fb_8f14e45fceea167a5a36dedd4bea2543" }, "already_submitted": { "type": "boolean", "description": "True when feedback for this request_id was already recorded; the original feedback_id is returned." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "feedback_id", "already_submitted", "request_id" ] }, "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, or `MONITOR` / `BATCH` for monitor-run and batch-settlement entries.", "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." } }, "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": "`initial`, `automatic` (scheduled retry), or `manual` (Retry endpoint)." }, "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": "Which deliveries to list: `batch` or `monitor`." }, "batch_id": { "type": "string", "description": "Batch ID." } }, "required": [ "type", "batch_id" ], "title": "Batch" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "monitor" ], "description": "Which deliveries to list: `batch` or `monitor`." }, "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": "`pending`, `delivering`, `retrying`, `delivered`, `failed`, or `cancelled` (source or its webhook was removed)." }, "created_at": { "type": "string", "format": "date-time", "description": "Event creation time." }, "retry_expires_at": { "type": "string", "format": "date-time", "description": "Last time you can retry manually (7 days after the event)." }, "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": "Which deliveries to list: `batch` or `monitor`." }, "batch_id": { "type": "string", "description": "Batch ID." } }, "required": [ "type", "batch_id" ], "title": "Batch" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "monitor" ], "description": "Which deliveries to list: `batch` or `monitor`." }, "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": "`pending`, `delivering`, `retrying`, `delivered`, `failed`, or `cancelled` (source or its webhook was removed)." }, "created_at": { "type": "string", "format": "date-time", "description": "Event creation time." }, "retry_expires_at": { "type": "string", "format": "date-time", "description": "Last time you can retry manually (7 days after the event)." }, "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" ] }, "ProductVariants": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "attributes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Explicit variant attributes such as color, size, material, pattern and properties declared by page." }, "url": { "type": [ "string", "null" ], "description": "Variant or offer URL when provided by the source. May be shared by variants." }, "images": { "type": "array", "items": { "type": "string" }, "description": "Original source image URLs explicitly attached to this variant." } }, "required": [ "sku", "attributes", "url", "images" ] }, "description": "Product variations, such as different colors or sizes, with their attributes and images. Empty if none are found. May not include every variation offered by the store." }, "NewsSearchEntityByName": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "name" ], "description": "Use `name` to identify the company by 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" ], "description": "Use `domain` to identify the company by website 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" ], "description": "Use `ticker` to identify a publicly traded company." }, "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" ], "description": "Use `isin` to identify the company by its securities identifier." }, "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" }, "AnswersRequest": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "fast", "ultra" ], "description": "`fast` prioritizes speed, with extra verification for people and companies; `ultra` supports deeper research (default)." }, "task": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Research task. The agent selects company/profile lookups, web searches, or page reads. Include domains or URLs to focus the research." }, "json_format": { "type": "object", "additionalProperties": {}, "description": "Example answer object, not JSON Schema. Up to 8 levels, 500 values, and 16000 characters; unknowns may be null." }, "timeoutOpts": { "$ref": "#/components/schemas/PartialTimeout" }, "tags": { "$ref": "#/components/schemas/RequestTags" }, "zdr": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR." } }, "required": [ "task" ], "additionalProperties": false }, "OrgUsageResponse": { "type": "object", "properties": { "credits_remaining": { "type": "integer", "description": "Credits available to your organization right now.", "example": 41250 }, "period": { "type": [ "object", "null" ], "properties": { "start": { "type": "string", "format": "date-time", "description": "When the current credit period started.", "example": "2026-09-14T07:01:00.000Z" }, "credits_used": { "type": "integer", "description": "Credits charged since `start`.", "example": 8750 } }, "required": [ "start", "credits_used" ], "description": "The current monthly credit period, or null when your organization has no monthly credits or billing is paused." }, "next_refill": { "type": [ "object", "null" ], "properties": { "at": { "type": "string", "format": "date-time", "description": "When your credits next refill.", "example": "2026-10-14T07:01:00.000Z" }, "credits": { "type": "integer", "description": "Your balance is reset to this amount at the refill. Unused credits do not carry over.", "example": 50000 } }, "required": [ "at", "credits" ], "description": "The next monthly refill, or null when no refill is scheduled. While billing is paused, this is when billing resumes." }, "auto_topup": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether credits are added automatically when your balance runs out." }, "credits_used_this_period": { "type": "integer", "description": "Credits added by Auto-Topup in the current period.", "example": 0 }, "monthly_budget_credits": { "type": [ "integer", "null" ], "description": "Monthly Auto-Topup budget you are alerted against, or null when none is set.", "example": 100000 } }, "required": [ "enabled", "credits_used_this_period", "monthly_budget_credits" ], "description": "Auto-Topup settings and spend." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "credits_remaining", "period", "next_refill", "auto_topup", "request_id" ], "example": { "credits_remaining": 41250, "period": { "start": "2026-09-14T07:01:00.000Z", "credits_used": 8750 }, "next_refill": { "at": "2026-10-14T07:01:00.000Z", "credits": 50000 }, "auto_topup": { "enabled": true, "credits_used_this_period": 0, "monthly_budget_credits": 100000 }, "key_metadata": { "credits_consumed": 0, "credits_remaining": 41250 }, "request_id": "3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91" } }, "UsageHistoryBucket": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time", "description": "Start of the bucket, in UTC.", "example": "2026-09-30T00:00:00.000Z" }, "credits_used": { "type": "integer", "description": "Credits charged." }, "request_count": { "type": "integer", "description": "Requests made." }, "groups": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "The endpoint path, API key ID, or status code this group covers.", "example": "/v1/web/scrape" }, "credits_used": { "type": "integer", "description": "Credits charged." }, "request_count": { "type": "integer", "description": "Requests made." } }, "required": [ "value", "credits_used", "request_count" ] }, "description": "Per-group totals, highest credits first. Present only when `group_by` is set." } }, "required": [ "start", "credits_used", "request_count" ] }, "UsageHistoryResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageHistoryBucket" }, "description": "One bucket per interval, oldest first. Intervals without usage are included with zero totals." }, "total_credits_used": { "type": "integer", "description": "Credits charged across the range." }, "total_request_count": { "type": "integer", "description": "Requests made across the range." }, "interval": { "type": "string", "enum": [ "hour", "day", "month" ], "description": "Bucket size used." }, "from": { "type": "string", "format": "date-time", "description": "Start of the range." }, "to": { "type": "string", "format": "date-time", "description": "End of the range." }, "key_metadata": { "$ref": "#/components/schemas/KeyMetadata" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "total_credits_used", "total_request_count", "interval", "from", "to", "request_id" ], "example": { "data": [ { "start": "2026-09-29T00:00:00.000Z", "credits_used": 1250, "request_count": 830, "groups": [ { "value": "/v1/web/scrape", "credits_used": 1000, "request_count": 500 }, { "value": "/v1/brand/retrieve", "credits_used": 250, "request_count": 330 } ] }, { "start": "2026-09-30T00:00:00.000Z", "credits_used": 0, "request_count": 0, "groups": [] } ], "total_credits_used": 1250, "total_request_count": 830, "interval": "day", "from": "2026-09-29T00:00:00.000Z", "to": "2026-09-30T23:59:59.999Z", "key_metadata": { "credits_consumed": 0, "credits_remaining": 41250 }, "request_id": "3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91" } } } } }