{
"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": "Browser Profiles",
"description": "See the authenticated browser profiles your organization created."
},
{
"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": "Access Policies",
"description": "Control which websites your requests can access."
},
{
"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": {
"/access-policies": {
"post": {
"operationId": "createAccessPolicy",
"summary": "Create an access policy",
"description": "Create a list of domains your requests can or can't access.",
"tags": [
"Access Policies"
],
"security": [
{
"bearerAuth": []
}
],
"x-mint": {
"content": "0 credits"
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateAccessPolicyRequest"
},
"examples": {
"allowlist": {
"summary": "Allow only some domains",
"value": {
"name": "Research sources",
"allowed_domains": [
"arxiv.org",
"*.gov"
]
}
},
"api_key_allowlist": {
"summary": "Limit what one API key can reach",
"value": {
"name": "Agent sandbox",
"allowed_domains": [
"arxiv.org",
"*.gov"
],
"applies_to": "api_keys",
"api_key_ids": [
"ctxt_keyid_4b7e2f9a1c8d4e6fa3b5c7d9e1f20a4b"
]
}
},
"organization_blocklist": {
"summary": "Block domains on every request",
"value": {
"name": "No social media",
"blocked_domains": [
"facebook.com",
"tiktok.com"
],
"applies_to": "organization"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Access policy 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": {
"allOf": [
{
"$ref": "#/components/schemas/AccessPolicy"
},
{
"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"
},
"403": {
"description": "Access policies aren't enabled for your organization (`ACCESS_POLICIES_NOT_ENABLED`), or the API key lacks `access_policies: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"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"get": {
"operationId": "listAccessPolicies",
"summary": "List access policies",
"description": "List your access policies, newest first.",
"tags": [
"Access Policies"
],
"security": [
{
"bearerAuth": []
}
],
"x-mint": {
"content": "0 credits"
},
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Number of policies per page."
},
"required": false,
"description": "Number of policies per page.",
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"description": "The `next_cursor` from the previous page."
},
"required": false,
"description": "The `next_cursor` from the previous page.",
"name": "cursor",
"in": "query"
}
],
"responses": {
"200": {
"description": "A page of access policies",
"headers": {
"X-Request-Id": {
"$ref": "#/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/ListAccessPoliciesResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "Access policies aren't enabled for your organization (`ACCESS_POLICIES_NOT_ENABLED`), or the API key lacks `access_policies:read` (`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"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/access-policies/{policy_id}": {
"get": {
"operationId": "getAccessPolicy",
"summary": "Retrieve an access policy",
"description": "Retrieve an access policy.",
"tags": [
"Access Policies"
],
"security": [
{
"bearerAuth": []
}
],
"x-mint": {
"content": "0 credits"
},
"parameters": [
{
"schema": {
"type": "string",
"description": "Access policy ID. Pass it in `policies` on any request.",
"example": "pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
},
"required": true,
"description": "Access policy ID. Pass it in `policies` on any request.",
"name": "policy_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Access policy",
"headers": {
"X-Request-Id": {
"$ref": "#/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/AccessPolicy"
},
{
"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"
},
"403": {
"description": "Access policies aren't enabled for your organization (`ACCESS_POLICIES_NOT_ENABLED`), or the API key lacks `access_policies:read` (`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"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"patch": {
"operationId": "updateAccessPolicy",
"summary": "Update an access policy",
"description": "Update an access policy. Changes apply right away, including to running batches and monitors.",
"tags": [
"Access Policies"
],
"security": [
{
"bearerAuth": []
}
],
"x-mint": {
"content": "0 credits"
},
"parameters": [
{
"schema": {
"type": "string",
"description": "Access policy ID. Pass it in `policies` on any request.",
"example": "pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
},
"required": true,
"description": "Access policy ID. Pass it in `policies` on any request.",
"name": "policy_id",
"in": "path"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateAccessPolicyRequest"
},
"example": {
"blocked_domains": [
"facebook.com",
"tiktok.com",
"x.com"
]
}
}
}
},
"responses": {
"200": {
"description": "Updated access policy",
"headers": {
"X-Request-Id": {
"$ref": "#/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/AccessPolicy"
},
{
"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"
},
"403": {
"description": "Access policies aren't enabled for your organization (`ACCESS_POLICIES_NOT_ENABLED`), or the API key lacks `access_policies: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"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"delete": {
"operationId": "deleteAccessPolicy",
"summary": "Delete an access policy",
"description": "Delete an access policy. Requests, batches, and monitors that still list it will fail.",
"tags": [
"Access Policies"
],
"security": [
{
"bearerAuth": []
}
],
"x-mint": {
"content": "0 credits"
},
"parameters": [
{
"schema": {
"type": "string",
"description": "Access policy ID. Pass it in `policies` on any request.",
"example": "pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
},
"required": true,
"description": "Access policy ID. Pass it in `policies` on any request.",
"name": "policy_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Access policy 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/DeleteAccessPolicyResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "Access policies aren't enabled for your organization (`ACCESS_POLICIES_NOT_ENABLED`), or the API key lacks `access_policies: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"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/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"
}
}
}
}
}
}
},
"/org/browser/profiles": {
"get": {
"operationId": "listProfiles",
"summary": "List browser profiles",
"tags": [
"Browser Profiles"
],
"description": "List the browser profiles your organization created with `/web/scrape`, newest first.",
"security": [
{
"bearerAuth": []
}
],
"x-mint": {
"content": "0 credits"
},
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"description": "Number of profiles per page."
},
"required": false,
"description": "Number of profiles per page.",
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "string",
"pattern": "^prof_[a-f0-9]{32}$",
"description": "The `next_cursor` from the previous page."
},
"required": false,
"description": "The `next_cursor` from the previous page.",
"name": "cursor",
"in": "query"
}
],
"responses": {
"200": {
"description": "A page of browser profiles",
"headers": {
"X-Request-Id": {
"$ref": "#/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/ListProfilesResponse"
}
}
}
},
"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"
}
}
}
}
}
}
},
"/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"
}
}
}
},
"Google Maps": {
"summary": "Parse Google Maps businesses without custom rules",
"value": {
"url": "https://www.google.com/maps/search/pizza+in+New+York/",
"formats": {
"parse": true
},
"parseParams": {
"type": "prebuilt",
"parser": "google-maps"
}
}
},
"Google Play": {
"summary": "Parse a Google Play app without custom rules",
"value": {
"url": "https://play.google.com/store/apps/details?id=com.spotify.music",
"formats": {
"parse": true
},
"parseParams": {
"type": "prebuilt",
"parser": "google-play"
}
}
},
"App Store": {
"summary": "Parse an App Store app without custom rules",
"value": {
"url": "https://apps.apple.com/us/app/spotify-music-and-podcasts/id324684580",
"formats": {
"parse": true
},
"parseParams": {
"type": "prebuilt",
"parser": "app-store"
}
}
},
"Google Maps oldest reviews": {
"summary": "Get a place's oldest Google Maps reviews",
"value": {
"url": "https://maps.google.com/?cid=16537904221077587530",
"formats": {
"parse": true
},
"parseParams": {
"type": "prebuilt",
"parser": "google-maps-reviews",
"sort": "oldest",
"limit": 50
}
}
},
"G2 reviews": {
"summary": "Read the latest reviews of a G2 product",
"value": {
"url": "https://www.g2.com/products/slack/reviews",
"formats": {
"parse": true
},
"parseParams": {
"type": "prebuilt",
"parser": "g2-reviews"
}
}
},
"Yelp search": {
"summary": "Search Yelp businesses without ads",
"value": {
"url": "https://www.yelp.com/search?find_desc=coffee&find_loc=San+Francisco%2C+CA",
"formats": {
"parse": true
},
"parseParams": {
"type": "prebuilt",
"parser": "yelp-search"
}
}
},
"Yelp reviews": {
"summary": "Read the latest Yelp reviews for a business",
"value": {
"url": "https://www.yelp.com/biz/gary-danko-san-francisco",
"formats": {
"parse": true
},
"parseParams": {
"type": "prebuilt",
"parser": "yelp-reviews"
}
}
},
"Instagram profile": {
"summary": "Parse an Instagram profile and its latest posts",
"value": {
"url": "https://www.instagram.com/natgeo/",
"formats": {
"parse": true
},
"parseParams": {
"type": "prebuilt",
"parser": "instagram-profile"
}
}
},
"TikTok video": {
"summary": "Parse a TikTok video with its stats and author",
"value": {
"url": "https://www.tiktok.com/@scout2015/video/6718335390845095173",
"formats": {
"parse": true
},
"parseParams": {
"type": "prebuilt",
"parser": "tiktok-video"
}
}
},
"Reddit post": {
"summary": "Parse a Reddit post and its top comments",
"value": {
"url": "https://www.reddit.com/r/programming/comments/1x97lsb/its_still_ok_to_enjoy_programming/?sort=top",
"formats": {
"parse": true
},
"parseParams": {
"type": "prebuilt",
"parser": "reddit-post",
"limit": 200
}
}
},
"Emails": {
"summary": "List the email addresses on a page",
"value": {
"url": "https://www.eff.org/about/contact",
"formats": {
"parse": true
},
"parseParams": {
"type": "prebuilt",
"parser": "emails"
}
}
},
"Phone numbers": {
"summary": "List the phone numbers on a page",
"value": {
"url": "https://www.eff.org/about/contact",
"formats": {
"parse": true
},
"parseParams": {
"type": "prebuilt",
"parser": "phone-numbers"
}
}
},
"Links": {
"summary": "List the links on a page",
"value": {
"url": "https://www.eff.org/about/contact",
"formats": {
"parse": true
},
"parseParams": {
"type": "prebuilt",
"parser": "links"
}
}
},
"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": {
"type": "custom",
"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
},
"profile": null,
"metadata": {
"sourceUrl": "https://example.com",
"finalUrl": "https://example.com/",
"title": "Example Domain"
},
"request_id": "d7aa1c3a-38d2-4fb5-92c8-0f0cac3efa37",
"cache_metadata": {
"status": "miss",
"age_ms": 0
},
"key_metadata": {
"credits_consumed": 1,
"credits_remaining": 999
}
}
},
"Partial success": {
"summary": "HTML and Markdown returned when a screenshot fails",
"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": 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": {
"type": "custom",
"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
},
"profile": null,
"isPartial": true,
"metadata": {
"sourceUrl": "https://example.com/",
"finalUrl": "https://example.com/"
},
"request_id": "d7aa1c3a-38d2-4fb5-92c8-0f0cac3efa37",
"cache_metadata": {
"status": "miss",
"age_ms": 0
}
}
},
"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": {
"type": "custom",
"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
},
"profile": null,
"metadata": {
"sourceUrl": "https://example.com/",
"finalUrl": "https://example.com/"
},
"request_id": "d7aa1c3a-38d2-4fb5-92c8-0f0cac3efa37",
"cache_metadata": {
"status": "miss",
"age_ms": 0
}
}
},
"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": {
"type": "custom",
"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
}
},
"profile": null,
"metadata": {
"sourceUrl": "https://example.com/",
"finalUrl": "https://example.com/"
},
"request_id": "d7aa1c3a-38d2-4fb5-92c8-0f0cac3efa37",
"cache_metadata": {
"status": "miss",
"age_ms": 0
}
}
},
"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": {
"type": "custom",
"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
},
"profile": null,
"metadata": {
"sourceUrl": "https://example.com/",
"finalUrl": "https://example.com/"
},
"request_id": "d7aa1c3a-38d2-4fb5-92c8-0f0cac3efa37",
"cache_metadata": {
"status": "miss",
"age_ms": 0
}
}
},
"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": {
"type": "custom",
"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
},
"profile": null,
"metadata": {
"sourceUrl": "https://example.com/",
"finalUrl": "https://example.com/"
},
"request_id": "d7aa1c3a-38d2-4fb5-92c8-0f0cac3efa37",
"cache_metadata": {
"status": "miss",
"age_ms": 0
}
}
},
"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": {
"type": "custom",
"requested": false,
"success": null,
"data": null
},
"highlights": {
"requested": false,
"success": null,
"data": null
},
"json": {
"requested": true,
"success": true,
"data": {
"title": "Example Domain",
"isPlaceholder": true
}
},
"product": {
"requested": false,
"success": null,
"data": null
},
"profile": null,
"metadata": {
"sourceUrl": "https://example.com/",
"finalUrl": "https://example.com/"
},
"request_id": "d7aa1c3a-38d2-4fb5-92c8-0f0cac3efa37",
"cache_metadata": {
"status": "miss",
"age_ms": 0
}
}
},
"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": {
"type": "custom",
"requested": false,
"success": null,
"data": null
},
"highlights": {
"requested": false,
"success": null,
"data": null
},
"json": {
"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"
]
}
]
}
}
},
"profile": null,
"metadata": {
"sourceUrl": "https://example.com/products/travel-mug",
"finalUrl": "https://example.com/products/travel-mug"
},
"request_id": "d7aa1c3a-38d2-4fb5-92c8-0f0cac3efa37",
"cache_metadata": {
"status": "miss",
"age_ms": 0
}
}
}
}
}
}
},
"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. Legacy deployments may return 401 USAGE_EXCEEDED for credit exhaustion.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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. An access policy can also block the website (`ACCESS_POLICY_DENIED`).",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"409": {
"description": "The browser profile is already in use. Wait for that request to finish.",
"headers": {
"X-Request-Id": {
"$ref": "#/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 browser profile is unavailable. Create a new profile or check the ID and 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"
}
}
}
},
"422": {
"description": "Authentication failed or a saved session or identity expired. Check error_code before retrying. PROFILE_SESSION_EXPIRED and PROFILE_REAUTHENTICATION_REQUIRED require a new profile.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
}
}
}
},
"/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/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",
"default": false,
"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"
}
}
}
}
}
}
},
"/news/search": {
"post": {
"summary": "Search news",
"description": "Find news about a company by name, domain, ticker, or ISIN, or search all news with a natural-language query. 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": {
"oneOf": [
{
"$ref": "#/components/schemas/NewsSearchByNaturalLanguage"
},
{
"$ref": "#/components/schemas/NewsSearchByEntity"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"natural_language": "#/components/schemas/NewsSearchByNaturalLanguage",
"entity": "#/components/schemas/NewsSearchByEntity"
}
},
"description": "What to search for: a specific company, or a natural-language query across all news."
},
"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",
"pk",
"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": [
"am",
"ar",
"az",
"be",
"bg",
"bn",
"ca",
"ceb",
"cs",
"cy",
"da",
"de",
"el",
"en",
"es",
"et",
"eu",
"fa",
"fi",
"fr",
"gu",
"ha",
"haw",
"he",
"hi",
"hr",
"hu",
"hy",
"id",
"is",
"it",
"ja",
"ka",
"kk",
"kn",
"ko",
"ku",
"ky",
"lo",
"lt",
"lv",
"mk",
"ml",
"mn",
"mr",
"ms",
"ne",
"nl",
"no",
"or",
"pa",
"pl",
"ps",
"pt",
"ro",
"ru",
"sk",
"sl",
"so",
"sq",
"sr",
"sv",
"sw",
"ta",
"te",
"th",
"tl",
"tr",
"uk",
"ur",
"uz",
"vi",
"yo",
"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."
}
},
"required": [
"type"
],
"additionalProperties": false,
"description": "Result ordering. Defaults to newest for entity searches. Natural-language searches are always ordered by relevance."
},
"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."
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
}
},
"required": [
"searchBy"
],
"additionalProperties": false
},
"examples": {
"entity": {
"summary": "Company news",
"value": {
"searchBy": {
"type": "entity",
"entity": {
"type": "domain",
"domain": "stripe.com"
}
}
}
},
"natural_language": {
"summary": "Natural-language query",
"value": {
"searchBy": {
"type": "natural_language",
"query": "chip export restrictions to China"
}
}
}
}
}
}
},
"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": "Article summary or excerpt. Natural-language search descriptions include matching passages and are capped at 2,000 characters."
},
"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",
"null"
],
"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. Null for natural-language searches."
}
},
"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"
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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": {
"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": {
"$ref": "#/components/schemas/AnswersResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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 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": "boolean",
"default": false,
"description": "Start each PDF page in the Markdown with a `` line, where N is the original 1-based page number."
},
"required": false,
"description": "Start each PDF page in the Markdown with a `` line, where N is the original 1-based page number.",
"name": "includeNumberedPages",
"in": "query"
},
{
"schema": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 1,
"description": "First 1-based PDF page to parse."
},
"end": {
"type": "integer",
"minimum": 1,
"description": "Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must be >= start."
}
},
"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",
"PDF_IMAGES_ONLY"
]
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"request_id"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"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"
]
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"request_id"
]
}
}
}
},
"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/scrape/bytes": {
"get": {
"x-hidden": true,
"deprecated": true,
"summary": "Scrape raw bytes",
"description": "Downloads a resource and returns its bytes as base64. Without waitForMs, returns the original HTTP response without image conversion, text extraction, or character-encoding changes. HTTP compression is decoded before base64 encoding. Supply waitForMs to render HTML with JavaScript in the browser and return the resulting HTML as UTF-8 bytes after the wait. Non-HTML resources, including images and PDFs, keep their original bytes and do not incur a browser wait. Follows public redirects and retries failed downloads through ISP and residential proxies, with a direct fallback. When country is specified, only a residential proxy in that country is used. Supply headers such as Referer for images that require a referring page. Cached results are reused according to maxAgeMs (default: 3 days; maximum: 1 year). Set maxAgeMs=0 to fetch fresh and refresh the cache. Cache identity includes the exact URL, country, waitForMs, and normalized outbound headers. Credential-bearing headers and zero data retention bypass cache reads and writes. cache_metadata reports hit, miss, or zdr and the cached result age in milliseconds. Maximum decoded resource size: 50 MiB (52428800 bytes), before base64 encoding. Successful requests cost 1 credit; errors are not billed.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Web Scraping"
],
"x-mint": {
"content": "1 Credit",
"title": "Scrape Bytes",
"sidebarTitle": "Scrape Bytes",
"description": "Download images, PDFs, pages, and other resources as base64"
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1,
"format": "uri",
"description": "Full HTTP(S) URL of the resource to download, such as an image, PDF, or page."
},
"required": true,
"description": "Full HTTP(S) URL of the resource to download, such as an image, PDF, or page.",
"name": "url",
"in": "query"
},
{
"schema": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 8192,
"pattern": "^[^\\r\\n]*$"
},
"description": "Headers for the target origin. Credentials are removed on cross-origin redirects and bypass caching."
},
"required": false,
"description": "Headers for the target origin. Credentials are removed on cross-origin redirects and bypass caching.",
"name": "headers",
"in": "query"
},
{
"schema": {
"$ref": "#/components/schemas/BrowserCountryCode"
},
"required": false,
"description": "Fetch from this country (ISO 3166-1 alpha-2).",
"name": "country",
"in": "query"
},
{
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 30000,
"description": "Optional browser wait time after initial page load, in milliseconds (0–30000; 0 uses 500). When supplied, HTML is rendered with JavaScript and returned as UTF-8 bytes. Other resources keep their original bytes without a browser wait. Omit to download the original HTTP response. When combined with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT."
},
"required": false,
"description": "Optional browser wait time after initial page load, in milliseconds (0–30000; 0 uses 500). When supplied, HTML is rendered with JavaScript and returned as UTF-8 bytes. Other resources keep their original bytes without a browser wait. Omit to download the original HTTP response. When combined with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT.",
"name": "waitForMs",
"in": "query"
},
{
"schema": {
"$ref": "#/components/schemas/LenientTimeout"
},
"required": false,
"description": "Request deadline and what to return when it passes.",
"style": "deepObject",
"explode": true,
"name": "timeoutOpts",
"in": "query"
},
{
"schema": {
"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."
},
"required": false,
"description": "Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 year (31536000000 ms). `0` fetches fresh.",
"name": "maxAgeMs",
"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": "Resource bytes and download 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"
]
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"url": {
"type": "string",
"format": "uri",
"description": "The requested resource URL."
},
"finalUrl": {
"type": "string",
"format": "uri",
"description": "The resource URL after redirects."
},
"bytes": {
"type": "string",
"format": "byte",
"description": "Base64-encoded resource bytes, without a data URI prefix. Decode this field to recover the downloaded file."
},
"encoding": {
"type": "string",
"enum": [
"base64"
]
},
"contentType": {
"type": "string",
"description": "The Content-Type returned by the origin, including any charset. Defaults to application/octet-stream when absent."
},
"contentLength": {
"type": "integer",
"minimum": 0,
"maximum": 52428800,
"description": "Number of decoded resource bytes, before base64 encoding."
},
"statusCode": {
"type": "integer",
"minimum": 200,
"maximum": 299,
"description": "HTTP status returned by the origin."
},
"cache_metadata": {
"$ref": "#/components/schemas/CacheMetadata"
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"success",
"url",
"finalUrl",
"bytes",
"encoding",
"contentType",
"contentLength",
"statusCode",
"cache_metadata",
"request_id"
]
}
}
}
},
"400": {
"description": "Bad request - Invalid URL or failed to scrape",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"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",
"TIMEOUT_TOO_SHORT_FOR_WAIT",
"WEBSITE_ACCESS_ERROR",
"WEBSITE_BLOCKED",
"WEBSITE_NOT_FOUND"
],
"description": "Machine-readable failure code, such as `WEBSITE_BLOCKED` or `TIMEOUT_TOO_SHORT_FOR_WAIT`."
},
"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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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": "Target page returned a 404",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"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 target page 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"
]
}
}
}
},
"413": {
"description": "Content too large - the target content exceeds the maximum supported download size, so it cannot be scraped",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"X-RateLimit-Mode": {
"$ref": "#/components/headers/RateLimitMode"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error message naming the URL and the maximum supported size"
},
"error_code": {
"type": "string",
"enum": [
"CONTENT_TOO_LARGE"
],
"description": "Error code indicating the target content exceeds the maximum supported size"
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"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/scrape/html": {
"get": {
"x-hidden": true,
"deprecated": true,
"summary": "Scrape HTML",
"description": "Scrapes the given URL and returns the HTML content of the page. Optional extractRules return deterministic structured data in extracted using CSS selectors, attributes, lists, and nested rules, without an LLM or additional credits. Rules run on the returned HTML after selector and main-content filtering. Send extractRules as a JSON-encoded query parameter. The base request costs 1 credit; requests with browser actions cost 2 credits. A request that hits its timeoutOpts.milliseconds deadline fails with 408 and is not billed, unless timeoutOpts.behavior=return-partial is set — then the page as rendered so far is returned with `finalDOMState: \"still-loading\"` and billed at the base cost of 1 credit.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Web Scraping"
],
"x-mint": {
"content": "1 CreditWith actions: 2 Credits",
"title": "Scrape HTML",
"sidebarTitle": "Scrape HTML",
"description": "Scrape the raw HTML from a URL"
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1,
"format": "uri",
"description": "Full URL to scrape (must include http:// or https:// protocol)"
},
"required": true,
"description": "Full URL to scrape (must include http:// or https:// protocol)",
"name": "url",
"in": "query"
},
{
"schema": {
"type": "object",
"properties": {
"shouldParse": {
"type": "boolean",
"default": true,
"description": "Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`."
},
"start": {
"type": "integer",
"minimum": 1,
"description": "First 1-based PDF page to parse."
},
"end": {
"type": "integer",
"minimum": 1,
"description": "Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must be >= start."
},
"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 handling. `start`/`end` limit parsing to an inclusive, 1-based page range."
},
"required": false,
"description": "PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range.",
"name": "pdf",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"description": "When true, iframes are rendered inline into the returned HTML."
},
"required": false,
"description": "When true, iframes are rendered inline into the returned HTML.",
"name": "includeFrames",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"description": "When true, return only the page's main content in the HTML response, excluding headers, footers, sidebars, and navigation when detectable."
},
"required": false,
"description": "When true, return only the page's main content in the HTML response, excluding headers, footers, sidebars, and navigation when detectable.",
"name": "useMainContentOnly",
"in": "query"
},
{
"schema": {
"type": "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": {
"anyOf": [
{
"type": "string",
"enum": [
"text",
"html"
]
},
{
"type": "string",
"pattern": "^@.*$"
},
{
"$ref": "#/components/schemas/HtmlExtractionRules"
}
],
"description": "Return text, HTML, an attribute such as `@href`, or nested field rules. Defaults to text."
}
},
"required": [
"selector"
],
"additionalProperties": false
}
]
},
"description": "CSS extraction rules, as a JSON object. Up to 100 fields and 5 nesting levels. XPath is unsupported."
},
"required": false,
"description": "CSS extraction rules, as a JSON object. Up to 100 fields and 5 nesting levels. XPath is unsupported.",
"name": "extractRules",
"in": "query"
},
{
"schema": {
"type": [
"array",
"null"
],
"items": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"maxItems": 50,
"description": "Keep only elements matching these CSS selectors."
},
"required": false,
"description": "Keep only elements matching these CSS selectors.",
"name": "includeSelectors",
"in": "query"
},
{
"schema": {
"type": [
"array",
"null"
],
"items": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"maxItems": 50,
"description": "CSS selectors to remove from the result. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\"."
},
"required": false,
"description": "CSS selectors to remove from the result. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\".",
"name": "excludeSelectors",
"in": "query"
},
{
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 31536000000,
"default": 259200000,
"description": "Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 year (31536000000 ms). `0` fetches fresh."
},
"required": false,
"description": "Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 year (31536000000 ms). `0` fetches fresh.",
"name": "maxAgeMs",
"in": "query"
},
{
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 30000,
"description": "Optional browser wait time in milliseconds after initial page load. Min: 0. Max: 30000 (30 seconds). When combined with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT."
},
"required": false,
"description": "Optional browser wait time in milliseconds after initial page load. Min: 0. Max: 30000 (30 seconds). When combined with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT.",
"name": "waitForMs",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"description": "When true, waits briefly for CSS and transition animations to settle before extracting HTML. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages."
},
"required": false,
"description": "When true, waits briefly for CSS and transition animations to settle before extracting HTML. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.",
"name": "settleAnimations",
"in": "query"
},
{
"schema": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/WebScrapeAction"
},
"maxItems": 5,
"description": "Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions."
},
"required": false,
"description": "Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.",
"name": "actions",
"in": "query"
},
{
"schema": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 8192,
"pattern": "^[^\\r\\n]*$"
},
"description": "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/BrowserCountryCode"
},
"required": false,
"description": "Fetch from this country (ISO 3166-1 alpha-2).",
"name": "country",
"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": [
"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": {
"success": {
"type": "boolean",
"enum": [
true
],
"description": "Indicates success"
},
"html": {
"type": "string",
"description": "The scraped content of the page. For normal pages this is the raw HTML. When the page is a sitemap or feed served behind an XSL stylesheet (which browsers render into HTML), this is the underlying XML instead — see the `type` field."
},
"extracted": {
"$ref": "#/components/schemas/HtmlExtractionResult"
},
"url": {
"type": "string",
"description": "The URL that was scraped"
},
"type": {
"type": "string",
"enum": [
"html",
"xml",
"json",
"text",
"csv",
"markdown",
"svg",
"pdf",
"docx",
"doc",
"xlsx",
"xls",
"pptx",
"ppt"
],
"description": "Detected content type of the returned `html` field. Sitemaps and feeds are surfaced as `xml`; ordinary pages are `html`. Excel workbooks are surfaced as `xlsx`/`xls` with the extracted sheets as HTML tables; PowerPoint presentations are surfaced as `pptx`/`ppt` with the extracted slides as HTML."
},
"metadata": {
"$ref": "#/components/schemas/PageMetadata"
},
"cache_metadata": {
"$ref": "#/components/schemas/CacheMetadata"
},
"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."
},
"actionsHtmlStale": {
"type": "boolean",
"description": "True when an action was applied but the returned content could not be refreshed afterward."
},
"finalDOMState": {
"type": "string",
"enum": [
"loaded",
"still-loading"
],
"description": "`loaded`, or `still-loading` when capture ended before the page finished loading."
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"success",
"html",
"url",
"type",
"metadata",
"cache_metadata",
"finalDOMState",
"request_id"
]
}
}
}
},
"400": {
"description": "Bad request - Invalid URL or failed to scrape",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"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",
"TIMEOUT_TOO_SHORT_FOR_WAIT",
"WEBSITE_ACCESS_ERROR",
"WEBSITE_BLOCKED",
"WEBSITE_NOT_FOUND"
],
"description": "Machine-readable failure code, such as `WEBSITE_BLOCKED` or `TIMEOUT_TOO_SHORT_FOR_WAIT`."
},
"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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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": "Target page returned a 404",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"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 target page 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"
]
}
}
}
},
"413": {
"description": "Content too large - the target content exceeds the maximum supported download size, so it cannot be scraped",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"X-RateLimit-Mode": {
"$ref": "#/components/headers/RateLimitMode"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error message naming the URL and the maximum supported size"
},
"error_code": {
"type": "string",
"enum": [
"CONTENT_TOO_LARGE"
],
"description": "Error code indicating the target content exceeds the maximum supported size"
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"message",
"error_code",
"request_id"
]
}
}
}
},
"415": {
"description": "Unsupported content type - the URL resolved to a content type that is not supported (e.g. an image, presentation, media, or archive). Supported types are HTML, XML, PDF, DOCX, DOC, XLSX, XLS, PPTX, PPT, and CSV.",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"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/scrape/markdown": {
"get": {
"x-hidden": true,
"deprecated": true,
"summary": "Scrape Markdown",
"description": "Scrapes the given URL into LLM usable Markdown. Inspect key_metadata on JSON responses from a recognized API key; use error_code to distinguish stable failure categories.\n\n### YouTube\n\nYouTube URLs return the video or channel itself rather than the surrounding player and navigation chrome. A URL addressing a single video (`/watch`, `youtu.be`, `/shorts`, `/embed`, `/live`) returns its title, channel, duration, view count, keywords, full description, and the transcript when the video has captions that can be retrieved; videos without captions return everything except the transcript. A channel URL (`/channel/UC…`, `/@handle`, `/c/…`, `/user/…`) returns its name, handle, subscriber count, video count, and full description. When `includeImages=true`, video responses also include the thumbnail and channel responses include the avatar. Costs the same as any other scrape.\n\n### Billing & errors\n\n| HTTP status | Billed? | Meaning |\n| --- | --- | --- |\n| 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing. A partial result (`finalDOMState: \"still-loading\"`, only with timeoutOpts.behavior=return-partial) is billed at the base 1 credit with no OCR or actions surcharge |\n| 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds. error_code NO_PUBLISHED_MARKDOWN means sourcePreference excludes html-conversion and the page publishes no Markdown version |\n| 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code |\n| 404 | Yes — 1 credit, or 2 credits with actions | Target page returned or fingerprinted as not found |\n| 408 | No | Request timed out. With timeoutOpts.behavior=return-partial this only happens when nothing usable had rendered by the deadline |\n| 413 | No | Target content exceeds the maximum supported size (50 MB) |\n| 415 | No | Unsupported content type |\n| 429 | No | Concurrency or per-minute rate limit exceeded; honor Retry-After |\n| 500 | No | Internal error |",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Web Scraping"
],
"x-mint": {
"content": "1 CreditWith actions: 2 Credits",
"title": "Scrape Markdown",
"sidebarTitle": "Scrape markdown",
"description": "Scrape the given URL into LLM usable Markdown"
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1,
"format": "uri",
"description": "Full URL to scrape into LLM usable Markdown (must include http:// or https:// protocol)"
},
"required": true,
"description": "Full URL to scrape into LLM usable Markdown (must include http:// or https:// protocol)",
"name": "url",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": true,
"description": "Preserve hyperlinks in Markdown output (`html-conversion` only)."
},
"required": false,
"description": "Preserve hyperlinks in Markdown output (`html-conversion` only).",
"name": "includeLinks",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"description": "Include image references in Markdown output (`html-conversion` only)."
},
"required": false,
"description": "Include image references in Markdown output (`html-conversion` only).",
"name": "includeImages",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": true,
"description": "Shorten base64-encoded image data in the Markdown output (`html-conversion` only)."
},
"required": false,
"description": "Shorten base64-encoded image data in the Markdown output (`html-conversion` only).",
"name": "shortenBase64Images",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"description": "Extract only the main content of the page, excluding headers, footers, sidebars, and navigation"
},
"required": false,
"description": "Extract only the main content of the page, excluding headers, footers, sidebars, and navigation",
"name": "useMainContentOnly",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"description": "When true, the response also includes an `html` field with the page HTML the Markdown was converted from — the same body the Scrape HTML endpoint returns for the equivalent request."
},
"required": false,
"description": "When true, the response also includes an `html` field with the page HTML the Markdown was converted from — the same body the Scrape HTML endpoint returns for the equivalent request.",
"name": "includeHTML",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"html-conversion",
"markdown-direct"
]
},
"minItems": 1,
"uniqueItems": true,
"default": [
"html-conversion",
"markdown-direct"
],
"description": "Markdown sources in order of preference: `html-conversion` converts the page HTML, `markdown-direct` uses Markdown the site publishes."
},
"required": false,
"description": "Markdown sources in order of preference: `html-conversion` converts the page HTML, `markdown-direct` uses Markdown the site publishes.",
"name": "sourcePreference",
"in": "query"
},
{
"schema": {
"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."
},
"end": {
"type": "integer",
"minimum": 1,
"description": "Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must be >= start."
},
"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 handling. `start`/`end` limit parsing to an inclusive, 1-based page range."
},
"required": false,
"description": "PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range.",
"name": "pdf",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"description": "When true, the contents of iframes are rendered to Markdown."
},
"required": false,
"description": "When true, the contents of iframes are rendered to Markdown.",
"name": "includeFrames",
"in": "query"
},
{
"schema": {
"type": [
"array",
"null"
],
"items": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"maxItems": 50,
"description": "Keep matching HTML subtrees before converting to Markdown."
},
"required": false,
"description": "Keep matching HTML subtrees before converting to Markdown.",
"name": "includeSelectors",
"in": "query"
},
{
"schema": {
"type": [
"array",
"null"
],
"items": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"maxItems": 50,
"description": "Remove matching elements after inclusions. Exclusions take precedence."
},
"required": false,
"description": "Remove matching elements after inclusions. Exclusions take precedence.",
"name": "excludeSelectors",
"in": "query"
},
{
"schema": {
"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."
},
"required": false,
"description": "Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 year (31536000000 ms). `0` fetches fresh.",
"name": "maxAgeMs",
"in": "query"
},
{
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 30000,
"description": "Optional browser wait time in milliseconds after initial page load before converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). When combined with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT."
},
"required": false,
"description": "Optional browser wait time in milliseconds after initial page load before converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). When combined with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT.",
"name": "waitForMs",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"description": "When true, waits briefly for CSS and transition animations to settle before converting to Markdown. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages."
},
"required": false,
"description": "When true, waits briefly for CSS and transition animations to settle before converting to Markdown. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.",
"name": "settleAnimations",
"in": "query"
},
{
"schema": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/WebScrapeAction"
},
"maxItems": 5,
"description": "Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions."
},
"required": false,
"description": "Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.",
"name": "actions",
"in": "query"
},
{
"schema": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 8192,
"pattern": "^[^\\r\\n]*$"
},
"description": "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/BrowserCountryCode"
},
"required": false,
"description": "Fetch from this country (ISO 3166-1 alpha-2).",
"name": "country",
"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": [
"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": {
"success": {
"type": "boolean",
"enum": [
true
],
"description": "Indicates success"
},
"markdown": {
"type": "string",
"description": "Page content converted to GitHub Flavored Markdown"
},
"html": {
"type": "string",
"description": "Only present when includeHTML=true: the page HTML the Markdown was converted from — the same body the Scrape HTML endpoint returns for the equivalent request."
},
"contentLength": {
"type": "integer",
"minimum": 0,
"description": "UTF-8 byte length of the returned Markdown. Use 0 to identify an empty result and compare small values against your workload's minimum useful-content threshold."
},
"url": {
"type": "string",
"description": "The URL that was scraped"
},
"metadata": {
"$ref": "#/components/schemas/PageMetadata"
},
"cache_metadata": {
"$ref": "#/components/schemas/CacheMetadata"
},
"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."
},
"actionsHtmlStale": {
"type": "boolean",
"description": "True when an action was applied but the returned content could not be refreshed afterward."
},
"finalDOMState": {
"type": "string",
"enum": [
"loaded",
"still-loading"
],
"description": "`loaded`, or `still-loading` when capture ended before the page finished loading."
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"success",
"markdown",
"contentLength",
"url",
"metadata",
"cache_metadata",
"finalDOMState",
"request_id"
]
}
}
}
},
"400": {
"description": "Bad request - Invalid URL or failed to scrape",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"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",
"TIMEOUT_TOO_SHORT_FOR_WAIT",
"WEBSITE_ACCESS_ERROR",
"WEBSITE_BLOCKED",
"WEBSITE_NOT_FOUND"
],
"description": "Machine-readable failure code, such as `WEBSITE_BLOCKED` or `TIMEOUT_TOO_SHORT_FOR_WAIT`."
},
"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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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": "Target page returned a 404",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"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 target page 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"
]
}
}
}
},
"413": {
"description": "Content too large - the target content exceeds the maximum supported download size, so it cannot be scraped",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"X-RateLimit-Mode": {
"$ref": "#/components/headers/RateLimitMode"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error message naming the URL and the maximum supported size"
},
"error_code": {
"type": "string",
"enum": [
"CONTENT_TOO_LARGE"
],
"description": "Error code indicating the target content exceeds the maximum supported size"
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"message",
"error_code",
"request_id"
]
}
}
}
},
"415": {
"description": "Unsupported content type - the URL resolved to a content type that is not supported (e.g. an image, presentation, media, or archive). Supported types are HTML, XML, PDF, DOCX, DOC, XLSX, XLS, PPTX, PPT, and CSV.",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"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/scrape/images": {
"get": {
"x-hidden": true,
"deprecated": true,
"summary": "Scrape Images",
"description": "Extract image assets from a web page, including standard URLs, inline SVGs, data URIs, responsive image sources, metadata, CSS backgrounds, video posters, and embeds. The base request costs 1 credit, or 2 credits with browser actions. When enrichment is enabled, the entire call costs 5 credits, including requests that also use actions.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Web Scraping"
],
"x-mint": {
"content": "1 CreditWith actions: 2 CreditsEnriched: 5 Credits",
"title": "Scrape Images",
"sidebarTitle": "Scrape images",
"description": "Extract image assets from a page."
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1,
"format": "uri",
"description": "Page URL to inspect. Must include http:// or https://."
},
"required": true,
"description": "Page URL to inspect. Must include http:// or https://.",
"name": "url",
"in": "query"
},
{
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 31536000000,
"default": 259200000,
"description": "Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 year (31536000000 ms). `0` fetches fresh."
},
"required": false,
"description": "Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 year (31536000000 ms). `0` fetches fresh.",
"name": "maxAgeMs",
"in": "query"
},
{
"schema": {
"type": [
"object",
"null"
],
"properties": {
"resolution": {
"type": "boolean",
"default": false,
"description": "Measure image width and height when possible."
},
"hostedUrl": {
"type": "boolean",
"default": false,
"description": "Host materializable images on the Context.dev CDN and return their URL and MIME type. Ignored when zero data retention is enabled."
},
"classification": {
"type": "boolean",
"default": false,
"description": "Classify each image by visual asset type."
},
"maxTimePerMs": {
"type": "integer",
"minimum": 1,
"maximum": 60000,
"default": 30000,
"description": "Per-image enrichment timeout in milliseconds. Default: 30000. Maximum: 60000."
}
},
"additionalProperties": false,
"description": "Optional per-image processing, sent as deep-object query params such as enrichment[resolution]=true."
},
"required": false,
"description": "Optional per-image processing, sent as deep-object query params such as enrichment[resolution]=true.",
"name": "enrichment",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"description": "Remove visual duplicates, keeping the highest-resolution copy. Undownloadable images remain."
},
"required": false,
"description": "Remove visual duplicates, keeping the highest-resolution copy. Undownloadable images remain.",
"name": "dedupe",
"in": "query"
},
{
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 30000,
"description": "Optional browser wait time in milliseconds after initial page load before collecting images. Min: 0. Max: 30000 (30 seconds). When combined with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT."
},
"required": false,
"description": "Optional browser wait time in milliseconds after initial page load before collecting images. Min: 0. Max: 30000 (30 seconds). When combined with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT.",
"name": "waitForMs",
"in": "query"
},
{
"schema": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/WebScrapeAction"
},
"maxItems": 5,
"description": "Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions."
},
"required": false,
"description": "Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.",
"name": "actions",
"in": "query"
},
{
"schema": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 8192,
"pattern": "^[^\\r\\n]*$"
},
"description": "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/BrowserCountryCode"
},
"required": false,
"description": "Fetch from this country (ISO 3166-1 alpha-2).",
"name": "country",
"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": [
"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 deadline interrupted rendering or image enrichment. Partial results are billed at the base request cost, without enrichment or actions surcharges."
},
"finalDOMState": {
"type": "string",
"enum": [
"loaded",
"still-loading"
],
"description": "`loaded`, or `still-loading` when capture ended before the page finished loading."
},
"success": {
"type": "boolean",
"enum": [
true
],
"description": "Always true on success."
},
"images": {
"type": "array",
"items": {
"type": "object",
"properties": {
"src": {
"type": "string",
"description": "Original image value: URL, inline SVG or HTML, or base64 data URI."
},
"element": {
"type": "string",
"enum": [
"img",
"svg",
"link",
"source",
"video",
"css",
"object",
"meta",
"background"
],
"description": "Where the image was found."
},
"type": {
"type": "string",
"enum": [
"url",
"html",
"base64"
],
"description": "Format of src."
},
"alt": {
"type": [
"string",
"null"
],
"description": "Image alt text, or null when unavailable."
},
"enrichment": {
"type": "object",
"properties": {
"width": {
"type": "integer",
"description": "Image width in pixels, when measured."
},
"height": {
"type": "integer",
"description": "Image height in pixels, when measured."
},
"mimetype": {
"type": "string",
"description": "Detected MIME type, when hosted."
},
"url": {
"type": "string",
"format": "uri",
"description": "Context.dev CDN URL, when hosted."
},
"type": {
"type": "string",
"enum": [
"photography",
"illustration",
"logo",
"wordmark",
"icon",
"pattern",
"graphic",
"other"
],
"description": "Visual asset category, when classified."
}
},
"description": "Requested metadata for images that could be processed."
}
},
"required": [
"src",
"element",
"type",
"alt"
]
},
"description": "Images found on the page."
},
"url": {
"type": "string",
"description": "Page URL that was scraped."
},
"cache_metadata": {
"$ref": "#/components/schemas/CacheMetadata"
},
"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."
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"success",
"images",
"url",
"cache_metadata",
"request_id"
]
}
}
}
},
"400": {
"description": "Invalid URL or scrape failed.",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"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",
"TIMEOUT_TOO_SHORT_FOR_WAIT",
"WEBSITE_ACCESS_ERROR"
],
"description": "Error code indicating the type of error. 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": "Missing, invalid, or disabled 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"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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/scrape/sitemap": {
"get": {
"x-hidden": true,
"deprecated": true,
"summary": "Crawl Sitemap",
"description": "Crawl an entire website's sitemap and return all discovered page URLs. Set `includeSubdomains=true` to also discover public pages and sitemaps on child hosts such as `docs.example.com` or `brand.example.com`. Pass `search` to have the discovered URLs filtered down to the pages about a phrase (for example `pricing and plans` or `api authentication docs`), most relevant first — a searched crawl scans the whole sitemap and costs 2 credits instead of 1.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Web Scraping"
],
"x-mint": {
"content": "1 Credit",
"title": "Crawl Sitemap",
"sidebarTitle": "Crawl sitemap",
"description": "Crawl a domain's sitemap, optionally including its subdomains, and return all discovered page URLs"
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 3,
"description": "Domain to 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": "Regex pattern. Only URLs matching this pattern are returned and counted against maxLinks.",
"example": "^https?://[^/]+/blog/"
},
"required": false,
"description": "Regex pattern. Only URLs matching this pattern are returned and counted against maxLinks.",
"name": "urlRegex",
"in": "query"
},
{
"schema": {
"type": "string",
"maxLength": 256,
"description": "Regex pattern. URLs matching this pattern are not returned, even when they match urlRegex.",
"example": "/tag/|/author/"
},
"required": false,
"description": "Regex pattern. URLs matching this pattern are not returned, even when they match urlRegex.",
"name": "excludeUrlRegex",
"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": "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."
},
"success": {
"type": "boolean",
"enum": [
true
],
"description": "Indicates success"
},
"domain": {
"type": "string",
"description": "The normalized domain that was crawled"
},
"urls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Discovered page URLs from the sitemap, up to `maxLinks`. When `search` is set these are only the matching pages, most relevant first."
},
"meta": {
"type": "object",
"properties": {
"sitemapsDiscovered": {
"type": "integer",
"description": "Total number of sitemap files discovered"
},
"sitemapsFetched": {
"type": "integer",
"description": "Number of sitemap files successfully fetched and parsed"
},
"sitemapsSkipped": {
"type": "integer",
"description": "Number of sitemap files skipped (due to errors, timeouts, or limits)"
},
"errors": {
"type": "integer",
"description": "Number of errors encountered during crawling"
}
},
"required": [
"sitemapsDiscovered",
"sitemapsFetched",
"sitemapsSkipped",
"errors"
],
"description": "Metadata about the sitemap crawl operation"
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"success",
"domain",
"urls",
"meta",
"request_id"
]
}
}
}
},
"400": {
"description": "Bad request - Invalid domain",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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/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": "Regex pattern. Only URLs matching this pattern are returned and counted against maxLinks.",
"example": "^https?://[^/]+/blog/"
},
"required": false,
"description": "Regex pattern. Only URLs matching this pattern are returned and counted against maxLinks.",
"name": "urlRegex",
"in": "query"
},
{
"schema": {
"type": "string",
"maxLength": 256,
"description": "Regex pattern. URLs matching this pattern are not returned, even when they match urlRegex.",
"example": "/tag/|/author/"
},
"required": false,
"description": "Regex pattern. URLs matching this pattern are not returned, even when they match urlRegex.",
"name": "excludeUrlRegex",
"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/AccessPolicies"
},
{
"$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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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. An access policy can also block the website (`ACCESS_POLICY_DENIED`).",
"headers": {
"X-Request-Id": {
"$ref": "#/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",
"minLength": 1,
"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",
"maxLength": 256,
"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/"
},
"excludeUrlRegex": {
"type": "string",
"maxLength": 256,
"description": "Regex pattern. URLs matching this pattern are never followed or scraped, even when they match urlRegex. The starting URL is always scraped.",
"example": "/tag/|/author/"
},
"includeLinks": {
"type": "boolean",
"default": true,
"description": "Preserve hyperlinks in the Markdown output (`html-conversion` only)."
},
"includeImages": {
"type": "boolean",
"default": false,
"description": "Include image references in the Markdown output (`html-conversion` only)."
},
"shortenBase64Images": {
"type": "boolean",
"default": true,
"description": "Truncate base64-encoded image data in the Markdown output (`html-conversion` only)."
},
"useMainContentOnly": {
"type": "boolean",
"default": false,
"description": "Extract only the main content, stripping headers, footers, sidebars, and navigation"
},
"sourcePreference": {
"type": "array",
"items": {
"type": "string",
"enum": [
"html-conversion",
"markdown-direct"
]
},
"minItems": 1,
"default": [
"html-conversion",
"markdown-direct"
],
"uniqueItems": true,
"description": "Markdown sources in order of preference: `html-conversion` converts the page HTML, `markdown-direct` uses Markdown the site publishes."
},
"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)."
},
"start": {
"type": "integer",
"minimum": 1,
"description": "First 1-based PDF page to parse."
},
"end": {
"type": "integer",
"minimum": 1,
"description": "Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must be >= start."
},
"ocr": {
"type": "boolean",
"default": false,
"description": "Read scanned PDF pages with OCR; preserve pages that already have text."
}
},
"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",
"null"
],
"items": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"maxItems": 50,
"description": "Keep matching HTML subtrees before converting each page to Markdown."
},
"excludeSelectors": {
"type": [
"array",
"null"
],
"items": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"maxItems": 50,
"description": "Remove matching elements after inclusions. Exclusions take precedence."
},
"maxAgeMs": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 2592000000,
"default": 86400000,
"description": "Maximum cache age in milliseconds. Defaults to 1 day; `0` fetches fresh."
},
"waitForMs": {
"type": [
"integer",
"null"
],
"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,
"default": 80000,
"maximum": 110000,
"description": "Soft crawl deadline in milliseconds. Returns pages collected before the next deadline check."
},
"timeoutOpts": {
"$ref": "#/components/schemas/PartialTimeout"
},
"country": {
"$ref": "#/components/schemas/BrowserCountryCode"
},
"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."
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
},
"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, URLs not matching urlRegex, or URLs matching excludeUrlRegex)"
}
},
"required": [
"numUrls",
"maxCrawlDepth",
"numSucceeded",
"numFailed",
"numSkipped"
]
},
"cache_metadata": {
"$ref": "#/components/schemas/CacheMetadata"
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"results",
"metadata",
"cache_metadata",
"request_id"
]
}
}
}
},
"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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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. An access policy can also block the website (`ACCESS_POLICY_DENIED`).",
"headers": {
"X-Request-Id": {
"$ref": "#/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",
"minLength": 1,
"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 PDF page to parse (1-based, inclusive). Defaults to the final page. Must be >= start."
}
},
"default": {
"shouldParse": true
},
"additionalProperties": false,
"description": "PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range."
},
"includeFrames": {
"type": "boolean",
"default": false,
"description": "When true, iframe contents are included in Markdown before extraction."
},
"maxAgeMs": {
"type": [
"integer",
"null"
],
"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",
"null"
],
"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",
"null"
],
"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,
"default": 80000,
"maximum": 110000,
"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."
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
},
"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"
]
},
"cache_metadata": {
"$ref": "#/components/schemas/CacheMetadata"
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"status",
"url",
"urls_analyzed",
"data",
"metadata",
"cache_metadata",
"request_id"
]
}
}
}
},
"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"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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. An access policy can also block the website (`ACCESS_POLICY_DENIED`).",
"headers": {
"X-Request-Id": {
"$ref": "#/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": 1,
"maximum": 100,
"default": 10,
"description": "Number of results to request and return (1–100). Defaults to 10."
},
"includeDomains": {
"type": "array",
"items": {
"type": "string",
"minLength": 3
},
"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",
"minLength": 3
},
"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\"."
},
"languages": {
"anyOf": [
{
"type": "string",
"enum": [
"all"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"am",
"ar",
"az",
"be",
"bg",
"bn",
"ca",
"ceb",
"cs",
"cy",
"da",
"de",
"el",
"en",
"es",
"et",
"eu",
"fa",
"fi",
"fr",
"gu",
"ha",
"haw",
"he",
"hi",
"hr",
"hu",
"hy",
"id",
"is",
"it",
"ja",
"ka",
"kk",
"kn",
"ko",
"ku",
"ky",
"lo",
"lt",
"lv",
"mk",
"ml",
"mn",
"mr",
"ms",
"ne",
"nl",
"no",
"or",
"pa",
"pl",
"ps",
"pt",
"ro",
"ru",
"sk",
"sl",
"so",
"sq",
"sr",
"sv",
"sw",
"ta",
"te",
"th",
"tl",
"tr",
"uk",
"ur",
"uz",
"vi",
"yo",
"zh"
]
},
"minItems": 1
}
],
"default": "all",
"description": "Languages to return results in, as BCP 47 language codes such as `en` or `de`, or \"all\" for any language. Defaults to \"all\". Example: [\"en\", \"de\"]."
},
"queryFanout": {
"type": "boolean",
"description": "Currently has no effect."
},
"markdownOptions": {
"type": [
"object",
"null"
],
"properties": {
"enabled": {
"type": "boolean",
"default": false,
"description": "Scrape each result to Markdown. Adds 1 credit per result with Markdown."
},
"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 1-based PDF page to parse."
},
"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. `start`/`end` limit parsing to an inclusive, 1-based page range."
},
"includeFrames": {
"type": "boolean",
"default": false,
"description": "Render iframe contents into the Markdown."
},
"maxAgeMs": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 31536000000,
"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",
"null"
],
"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",
"null"
],
"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."
},
"descriptionMaxCharacters": {
"type": [
"integer",
"null"
],
"minimum": 0,
"default": null,
"description": "Maximum length of each result's `description`, in characters."
},
"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."
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
},
"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",
"WEBSITE_BLOCKED",
"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",
"WEBSITE_BLOCKED",
"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)."
},
"cache_metadata": {
"$ref": "#/components/schemas/CacheMetadata"
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"results",
"query",
"cache_metadata",
"request_id"
]
}
}
}
},
"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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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/competitors": {
"get": {
"x-hidden": true,
"summary": "Find website competitors",
"description": "Analyze a company's landing page and web search evidence to return direct competitors for the same product or market.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Web Extraction"
],
"x-mint": {
"content": "10 Credits Private Alpha",
"title": "Find website competitors",
"sidebarTitle": "Find competitors",
"description": "Analyze a company's website and web search evidence to return direct competitors."
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 3,
"description": "Company domain to analyze, such as `stripe.com`. Full http(s) URLs are accepted and normalized to their domain."
},
"required": true,
"description": "Company domain to analyze, such as `stripe.com`. Full http(s) URLs are accepted and normalized to their domain.",
"name": "domain",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"default": 5,
"description": "Exact number of direct competitors to return. Defaults to 5."
},
"required": false,
"description": "Exact number of direct competitors to return. Defaults to 5.",
"name": "numCompetitors",
"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": "Competitor research succeeded.",
"headers": {
"X-Request-Id": {
"$ref": "#/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",
"enum": [
"ok"
],
"description": "Status of the response."
},
"domain": {
"type": "string",
"description": "Normalized input domain."
},
"target": {
"type": "object",
"properties": {
"companyName": {
"type": "string",
"description": "Company or product name inferred from the landing page."
},
"field": {
"type": "string",
"description": "Specific operating field, product category, or market."
},
"fieldDescription": {
"type": "string",
"description": "One-sentence description of what the target company sells and who it serves."
},
"websiteUrl": {
"type": "string",
"description": "Resolved URL used for the landing page analysis."
}
},
"required": [
"companyName",
"field",
"fieldDescription",
"websiteUrl"
],
"additionalProperties": false,
"description": "Target company profile inferred from the landing page."
},
"competitors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Competitor company or product name."
},
"domain": {
"type": "string",
"description": "Competitor's normalized official domain."
},
"url": {
"type": "string",
"description": "Competitor website URL."
},
"description": {
"type": "string",
"description": "Short description of the competitor."
},
"confidence": {
"type": "string",
"enum": [
"high",
"medium"
],
"description": "Confidence that this company is a direct competitor."
},
"sourceUrls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Search result URLs used as evidence for this competitor."
}
},
"required": [
"name",
"domain",
"url",
"description",
"confidence",
"sourceUrls"
],
"additionalProperties": false
},
"description": "Direct competitors ordered by relevance and confidence."
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"status",
"domain",
"target",
"competitors",
"request_id"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Bad request - Invalid parameters 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": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "object",
"properties": {}
}
}
],
"description": "Error message or validation details."
},
"error_code": {
"type": "string",
"enum": [
"INPUT_VALIDATION_ERROR",
"WEBSITE_ACCESS_ERROR"
],
"description": "Error code indicating the type of error."
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"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": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error message."
},
"error_code": {
"type": "string",
"enum": [
"UNAUTHORIZED"
],
"description": "Error code indicating unauthorized access."
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"message",
"error_code",
"request_id"
]
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error message."
},
"error_code": {
"type": "string",
"enum": [
"FORBIDDEN",
"INSUFFICIENT_PERMISSIONS"
],
"description": "Error code indicating forbidden access."
},
"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": [
"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": "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": [
"message",
"error_code",
"request_id"
]
}
}
}
}
}
}
},
"/people/enrich": {
"post": {
"summary": "Enrich a person",
"description": "Find a person from identity clues and return their profile with a match score. Available on all plans; free or disposable email addresses return 422.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"People"
],
"x-mint": {
"content": "20 credits per match All 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"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
}
}
}
},
"/people/retrieve": {
"post": {
"x-hidden": true,
"deprecated": true,
"summary": "Retrieve Person",
"description": "Retrieve and normalize a person profile from identifiers. Education and experience entries include LinkedIn-derived organization data (website, logo, employee counts, followers, headquarters, and Context.dev industry classification) when available.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"People"
],
"x-mint": {
"content": "50 Credits Private Alpha",
"title": "Retrieve Person",
"sidebarTitle": "Retrieve person",
"description": "Normalize a person profile from LinkedIn and personal website sources."
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PersonRetrieveRequest"
},
"example": {
"identifiers": {
"linkedinUrl": "https://www.linkedin.com/in/yahia-bakour/"
}
}
}
}
},
"responses": {
"200": {
"description": "Person retrieval succeeded.",
"headers": {
"X-Request-Id": {
"$ref": "#/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/PersonRetrieveResponse"
}
}
}
},
"400": {
"description": "Bad request - Invalid identifiers",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
}
}
}
},
"/brand/retrieve": {
"get": {
"x-hidden": true,
"deprecated": true,
"summary": "Retrieve brand data by domain",
"description": "Retrieve logos, backdrops, colors, industry, description, and more from any domain",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Brand Intelligence"
],
"x-mint": {
"content": "20 Credits All Paid Plans Beta Feature"
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 3,
"description": "Domain name to retrieve brand data for (e.g., 'example.com', 'google.com'). Cannot be used with name or ticker parameters."
},
"required": false,
"description": "Domain name to retrieve brand data for (e.g., 'example.com', 'google.com'). Cannot be used with name or ticker parameters.",
"name": "domain",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 3,
"maxLength": 30,
"description": "Company name to retrieve brand data for (e.g., 'Apple Inc'). Cannot be used with domain or ticker parameters."
},
"required": false,
"description": "Company name to retrieve brand data for (e.g., 'Apple Inc'). Cannot be used with domain or ticker parameters.",
"name": "name",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 15,
"pattern": "^[A-Za-z0-9.]+$",
"description": "Stock ticker symbol to retrieve brand data for (e.g., 'AAPL'). Cannot be used with domain or name parameters."
},
"required": false,
"description": "Stock ticker symbol to retrieve brand data for (e.g., 'AAPL'). Cannot be used with domain or name parameters.",
"name": "ticker",
"in": "query"
},
{
"schema": {
"$ref": "#/components/schemas/StockExchange"
},
"required": false,
"description": "Stock exchange code.",
"name": "ticker_exchange",
"in": "query"
},
{
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/SupportedLanguage"
},
{
"type": [
"string",
"null"
]
}
]
},
"required": false,
"description": "Language, e.g. `english`.",
"name": "force_language",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"description": "Skip slower enrichment steps for a faster, less detailed response."
},
"required": false,
"description": "Skip slower enrichment steps for a faster, less detailed response.",
"name": "maxSpeed",
"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/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"
],
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR."
},
"required": false,
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. 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 zdr=enabled suppressed logs and traces. Brand data and hosted assets may still be stored.",
"schema": {
"type": "string",
"enum": [
"true"
]
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrandResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
]
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
},
"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"
},
"X-Context-ZDR": {
"description": "Present with the value true when zdr=enabled suppressed logs and traces. Brand data and hosted assets may still be stored.",
"schema": {
"type": "string",
"enum": [
"true"
]
}
}
},
"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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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. An access policy can also block the website (`ACCESS_POLICY_DENIED`).",
"headers": {
"X-Request-Id": {
"$ref": "#/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/retrieve-by-name": {
"get": {
"x-hidden": true,
"deprecated": true,
"summary": "Retrieve brand data by company name",
"description": "Retrieve brand information using a company name.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Brand Intelligence"
],
"x-mint": {
"content": "10 Credits"
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 3,
"maxLength": 30,
"description": "Company name to retrieve brand data for (e.g., 'Apple Inc', 'Microsoft Corporation'). Must be 3-30 characters."
},
"required": true,
"description": "Company name to retrieve brand data for (e.g., 'Apple Inc', 'Microsoft Corporation'). Must be 3-30 characters.",
"name": "name",
"in": "query"
},
{
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/SupportedLanguage"
},
{
"type": [
"string",
"null"
]
}
]
},
"required": false,
"description": "Language, e.g. `english`.",
"name": "force_language",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"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."
},
"required": false,
"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.",
"name": "maxSpeed",
"in": "query"
},
{
"schema": {
"$ref": "#/components/schemas/CountryGL"
},
"required": false,
"description": "Two-letter ISO 3166-1 alpha-2 country code (GL parameter) used to localize search.",
"name": "country_gl",
"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/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"
],
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR."
},
"required": false,
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. 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 zdr=enabled suppressed logs and traces. Brand data and hosted assets may still be stored.",
"schema": {
"type": "string",
"enum": [
"true"
]
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrandResponse"
}
}
}
},
"400": {
"description": "Bad Request - Invalid company name or company not found",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"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"
}
}
}
}
}
}
},
"/brand/search": {
"get": {
"summary": "Auto-complete Brand",
"description": "Find up to 10 brands by name or domain, ordered by popularity. Optionally filter by country and primary language; both filters must match when provided together. Results include description, country, and language when available. 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. 'nike', 'nike.com', 'nik')."
},
"required": true,
"description": "Search term, matched against the fields selected by queryBy (e.g. 'nike', 'nike.com', 'nik').",
"name": "query",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"AD",
"AE",
"AF",
"AG",
"AI",
"AL",
"AM",
"AO",
"AQ",
"AR",
"AS",
"AT",
"AU",
"AW",
"AX",
"AZ",
"BA",
"BB",
"BD",
"BE",
"BF",
"BG",
"BH",
"BI",
"BJ",
"BL",
"BM",
"BN",
"BO",
"BQ",
"BR",
"BS",
"BT",
"BV",
"BW",
"BY",
"BZ",
"CA",
"CC",
"CD",
"CF",
"CG",
"CH",
"CI",
"CK",
"CL",
"CM",
"CN",
"CO",
"CR",
"CU",
"CV",
"CW",
"CX",
"CY",
"CZ",
"DE",
"DJ",
"DK",
"DM",
"DO",
"DZ",
"EC",
"EE",
"EG",
"EH",
"ER",
"ES",
"ET",
"FI",
"FJ",
"FK",
"FM",
"FO",
"FR",
"GA",
"GB",
"GD",
"GE",
"GF",
"GG",
"GH",
"GI",
"GL",
"GM",
"GN",
"GP",
"GQ",
"GR",
"GS",
"GT",
"GU",
"GW",
"GY",
"HK",
"HM",
"HN",
"HR",
"HT",
"HU",
"ID",
"IE",
"IL",
"IM",
"IN",
"IO",
"IQ",
"IR",
"IS",
"IT",
"JE",
"JM",
"JO",
"JP",
"KE",
"KG",
"KH",
"KI",
"KM",
"KN",
"KP",
"KR",
"KW",
"KY",
"KZ",
"LA",
"LB",
"LC",
"LI",
"LK",
"LR",
"LS",
"LT",
"LU",
"LV",
"LY",
"MA",
"MC",
"MD",
"ME",
"MF",
"MG",
"MH",
"MK",
"ML",
"MM",
"MN",
"MO",
"MP",
"MQ",
"MR",
"MS",
"MT",
"MU",
"MV",
"MW",
"MX",
"MY",
"MZ",
"NA",
"NC",
"NE",
"NF",
"NG",
"NI",
"NL",
"NO",
"NP",
"NR",
"NU",
"NZ",
"OM",
"PA",
"PE",
"PF",
"PG",
"PH",
"PK",
"PL",
"PM",
"PN",
"PR",
"PS",
"PT",
"PW",
"PY",
"QA",
"RE",
"RO",
"RS",
"RU",
"RW",
"SA",
"SB",
"SC",
"SD",
"SE",
"SG",
"SH",
"SI",
"SJ",
"SK",
"SL",
"SM",
"SN",
"SO",
"SR",
"SS",
"ST",
"SV",
"SX",
"SY",
"SZ",
"TC",
"TD",
"TF",
"TG",
"TH",
"TJ",
"TK",
"TL",
"TM",
"TN",
"TO",
"TR",
"TT",
"TV",
"TW",
"TZ",
"UA",
"UG",
"UM",
"US",
"UY",
"UZ",
"VA",
"VC",
"VE",
"VG",
"VI",
"VN",
"VU",
"WF",
"WS",
"YE",
"YT",
"ZA",
"ZM",
"ZW"
],
"description": "Only return brands in this country, as an uppercase ISO 3166-1 alpha-2 code such as US or GB.",
"example": "US"
},
"required": false,
"description": "Only return brands in this country, as an uppercase ISO 3166-1 alpha-2 code such as US or GB.",
"name": "country",
"in": "query"
},
{
"schema": {
"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": "Only return brands with this primary language, such as english or french."
},
"required": false,
"description": "Only return brands with this primary language, such as english or french.",
"name": "language",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": true,
"description": "Whether the search term matches by prefix, so partial words match as they are typed (e.g. 'nik' matches Nike). Set to false to match whole words only."
},
"required": false,
"description": "Whether the search term matches by prefix, so partial words match as they are typed (e.g. 'nik' matches Nike). Set to false to match whole words only.",
"name": "autocomplete",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"name",
"domain"
]
},
"minItems": 1,
"default": [
"name",
"domain"
],
"description": "Fields to match the search term against, as a comma-separated list or repeated parameter: 'name', 'domain', or both. Defaults to both."
},
"required": false,
"description": "Fields to match the search term against, as a comma-separated list or repeated parameter: 'name', 'domain', or both. Defaults to both.",
"name": "queryBy",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 2,
"default": 0,
"description": "Maximum number of typos tolerated when matching, from 0 to 2. Defaults to 0 (no typo tolerance)."
},
"required": false,
"description": "Maximum number of typos tolerated when matching, from 0 to 2. Defaults to 0 (no typo tolerance).",
"name": "typoTolerance",
"in": "query"
},
{
"$ref": "#/components/parameters/RequestTags"
}
],
"responses": {
"200": {
"description": "Successful response",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"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": "nike.com"
},
"name": {
"type": "string",
"description": "The brand's name. Empty string when unknown.",
"example": "Nike"
},
"description": {
"type": "string",
"description": "The brand's description, when available.",
"example": "Nike designs athletic footwear and apparel."
},
"country": {
"type": "string",
"enum": [
"AD",
"AE",
"AF",
"AG",
"AI",
"AL",
"AM",
"AO",
"AQ",
"AR",
"AS",
"AT",
"AU",
"AW",
"AX",
"AZ",
"BA",
"BB",
"BD",
"BE",
"BF",
"BG",
"BH",
"BI",
"BJ",
"BL",
"BM",
"BN",
"BO",
"BQ",
"BR",
"BS",
"BT",
"BV",
"BW",
"BY",
"BZ",
"CA",
"CC",
"CD",
"CF",
"CG",
"CH",
"CI",
"CK",
"CL",
"CM",
"CN",
"CO",
"CR",
"CU",
"CV",
"CW",
"CX",
"CY",
"CZ",
"DE",
"DJ",
"DK",
"DM",
"DO",
"DZ",
"EC",
"EE",
"EG",
"EH",
"ER",
"ES",
"ET",
"FI",
"FJ",
"FK",
"FM",
"FO",
"FR",
"GA",
"GB",
"GD",
"GE",
"GF",
"GG",
"GH",
"GI",
"GL",
"GM",
"GN",
"GP",
"GQ",
"GR",
"GS",
"GT",
"GU",
"GW",
"GY",
"HK",
"HM",
"HN",
"HR",
"HT",
"HU",
"ID",
"IE",
"IL",
"IM",
"IN",
"IO",
"IQ",
"IR",
"IS",
"IT",
"JE",
"JM",
"JO",
"JP",
"KE",
"KG",
"KH",
"KI",
"KM",
"KN",
"KP",
"KR",
"KW",
"KY",
"KZ",
"LA",
"LB",
"LC",
"LI",
"LK",
"LR",
"LS",
"LT",
"LU",
"LV",
"LY",
"MA",
"MC",
"MD",
"ME",
"MF",
"MG",
"MH",
"MK",
"ML",
"MM",
"MN",
"MO",
"MP",
"MQ",
"MR",
"MS",
"MT",
"MU",
"MV",
"MW",
"MX",
"MY",
"MZ",
"NA",
"NC",
"NE",
"NF",
"NG",
"NI",
"NL",
"NO",
"NP",
"NR",
"NU",
"NZ",
"OM",
"PA",
"PE",
"PF",
"PG",
"PH",
"PK",
"PL",
"PM",
"PN",
"PR",
"PS",
"PT",
"PW",
"PY",
"QA",
"RE",
"RO",
"RS",
"RU",
"RW",
"SA",
"SB",
"SC",
"SD",
"SE",
"SG",
"SH",
"SI",
"SJ",
"SK",
"SL",
"SM",
"SN",
"SO",
"SR",
"SS",
"ST",
"SV",
"SX",
"SY",
"SZ",
"TC",
"TD",
"TF",
"TG",
"TH",
"TJ",
"TK",
"TL",
"TM",
"TN",
"TO",
"TR",
"TT",
"TV",
"TW",
"TZ",
"UA",
"UG",
"UM",
"US",
"UY",
"UZ",
"VA",
"VC",
"VE",
"VG",
"VI",
"VN",
"VU",
"WF",
"WS",
"YE",
"YT",
"ZA",
"ZM",
"ZW"
],
"description": "The brand's country, when available, as an uppercase ISO 3166-1 alpha-2 code.",
"example": "US"
},
"language": {
"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": "The brand's primary language, when available.",
"example": "english"
},
"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=nike.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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
]
}
}
}
}
}
}
},
"/brand/retrieve-by-email": {
"get": {
"x-hidden": true,
"deprecated": true,
"summary": "Retrieve brand data by email address",
"description": "Retrieve brand information using an email address while detecting disposable and free email addresses. Disposable and free email addresses (like gmail.com, yahoo.com) will throw a 422 error.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Brand Intelligence"
],
"x-mint": {
"content": "10 Credits"
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1,
"format": "email",
"description": "Work email address. Free and disposable email providers are rejected."
},
"required": true,
"description": "Work email address. Free and disposable email providers are rejected.",
"name": "email",
"in": "query"
},
{
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/SupportedLanguage"
},
{
"type": [
"string",
"null"
]
}
]
},
"required": false,
"description": "Language, e.g. `english`.",
"name": "force_language",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"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."
},
"required": false,
"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.",
"name": "maxSpeed",
"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/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"
],
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR."
},
"required": false,
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. 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 zdr=enabled suppressed logs and traces. Brand data and hosted assets may still be stored.",
"schema": {
"type": "string",
"enum": [
"true"
]
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrandResponse"
}
}
}
},
"400": {
"description": "Bad Request - Invalid email or domain not found",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"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-by-ticker": {
"get": {
"x-hidden": true,
"deprecated": true,
"summary": "Retrieve brand data by stock ticker",
"description": "Retrieve brand information using a stock ticker symbol.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Brand Intelligence"
],
"x-mint": {
"content": "10 Credits"
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 15,
"pattern": "^[A-Za-z0-9.]+$",
"description": "Stock ticker symbol to retrieve brand data for (e.g., 'AAPL', 'GOOGL', 'BRK.A'). Must be 1-15 characters, letters/numbers/dots only."
},
"required": true,
"description": "Stock ticker symbol to retrieve brand data for (e.g., 'AAPL', 'GOOGL', 'BRK.A'). Must be 1-15 characters, letters/numbers/dots only.",
"name": "ticker",
"in": "query"
},
{
"schema": {
"$ref": "#/components/schemas/StockExchange"
},
"required": false,
"description": "Stock exchange code.",
"name": "ticker_exchange",
"in": "query"
},
{
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/SupportedLanguage"
},
{
"type": [
"string",
"null"
]
}
]
},
"required": false,
"description": "Language, e.g. `english`.",
"name": "force_language",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"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."
},
"required": false,
"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.",
"name": "maxSpeed",
"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/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"
],
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR."
},
"required": false,
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. 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 zdr=enabled suppressed logs and traces. Brand data and hosted assets may still be stored.",
"schema": {
"type": "string",
"enum": [
"true"
]
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrandResponse"
}
}
}
},
"400": {
"description": "Bad Request - Invalid ticker or ticker not found",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"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"
}
}
}
}
}
}
},
"/brand/retrieve-by-isin": {
"get": {
"x-hidden": true,
"deprecated": true,
"summary": "Retrieve brand data by ISIN",
"description": "Retrieve brand information using an ISIN (International Securities Identification Number). ",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Brand Intelligence"
],
"x-mint": {
"content": "10 Credits"
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 12,
"maxLength": 12,
"pattern": "^[A-Z]{2}[A-Z0-9]{9}[0-9]$",
"description": "Company ISIN: 12 characters, such as `US0378331005`."
},
"required": true,
"description": "Company ISIN: 12 characters, such as `US0378331005`.",
"name": "isin",
"in": "query"
},
{
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/SupportedLanguage"
},
{
"type": [
"string",
"null"
]
}
]
},
"required": false,
"description": "Language, e.g. `english`.",
"name": "force_language",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"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."
},
"required": false,
"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.",
"name": "maxSpeed",
"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/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"
],
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR."
},
"required": false,
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. 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 zdr=enabled suppressed logs and traces. Brand data and hosted assets may still be stored.",
"schema": {
"type": "string",
"enum": [
"true"
]
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrandResponse"
}
}
}
},
"400": {
"description": "Bad Request - Invalid ISIN or ISIN not found",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"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"
}
}
}
}
}
}
},
"/brand/retrieve-simplified": {
"get": {
"x-hidden": true,
"deprecated": true,
"summary": "Retrieve simplified brand data by domain",
"description": "Returns a simplified version of brand data containing only essential information: domain, title, colors, logos, and backdrops. Optimized for faster responses and reduced data transfer.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Brand Intelligence"
],
"x-mint": {
"content": "10 Credits"
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 3,
"description": "Domain name to retrieve simplified brand data for"
},
"required": true,
"description": "Domain name to retrieve simplified brand data for",
"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/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": [
"light",
"dark"
],
"description": "Optional theme preference used when selecting brand assets."
},
"required": false,
"description": "Optional theme preference used when selecting brand assets.",
"name": "theme",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"enabled",
"disabled"
],
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR."
},
"required": false,
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. 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 zdr=enabled suppressed logs and traces. Brand data and hosted assets may still be stored.",
"schema": {
"type": "string",
"enum": [
"true"
]
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimplifiedBrandResponse"
}
}
}
},
"400": {
"description": "Invalid input, or the website could not be found or 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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
]
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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."
},
"status": {
"type": "string",
"description": "Status of the response, e.g., 'error'"
},
"error_code": {
"type": "string",
"description": "Machine-readable error code."
},
"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` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR."
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Comma-separated access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
}
},
{
"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` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR."
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Comma-separated access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
}
}
],
"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"
],
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR."
},
"required": false,
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR.",
"name": "zdr",
"in": "query"
},
{
"$ref": "#/components/parameters/AccessPolicies"
},
{
"$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 zdr=enabled suppressed logs and traces. Brand data and hosted assets may still be stored.",
"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"
},
"X-Context-ZDR": {
"description": "Present with the value true when zdr=enabled suppressed logs and traces. Brand data and hosted assets may still be stored.",
"schema": {
"type": "string",
"enum": [
"true"
]
}
}
},
"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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
]
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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": "An access policy blocks this website (`ACCESS_POLICY_DENIED`).",
"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"
}
}
},
"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"
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Comma-separated access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
}
},
{
"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"
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Comma-separated access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
}
}
],
"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/AccessPolicies"
},
{
"$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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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. An access policy can also block the website (`ACCESS_POLICY_DENIED`).",
"headers": {
"X-Request-Id": {
"$ref": "#/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/scrape/screenshot": {
"get": {
"x-hidden": true,
"deprecated": true,
"summary": "Scrape Screenshot",
"description": "Capture the given HTTP or HTTPS URL with configurable viewport, full-page capture, wait time, popup handling, theme, scroll offset, cache age, country, and request timeout. Defaults to a 1920x1080 viewport, a 3-second wait, and a cache age of 3 days. With timeoutOpts.behavior=return-partial, a screenshot of the page rendered so far may be returned; inspect finalDOMState to identify an incomplete render. Successful requests cost 1 credit; errors are not billed.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Web Scraping"
],
"x-mint": {
"content": "1 Credit",
"title": "Scrape Screenshot",
"sidebarTitle": "Scrape Screenshot",
"description": "Capture a screenshot of a page from its URL."
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1,
"format": "uri"
},
"required": true,
"name": "url",
"in": "query"
},
{
"schema": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 8192,
"pattern": "^[^\\r\\n]*$"
},
"description": "Optional outbound HTTP headers, using the same JSON object or deep-object query format as other scrape endpoints (for example headers[Authorization]=Bearer token). Headers are scoped to the target origin during capture. For domain/page requests, discovery receives no custom headers and only pages on the resolved origin are eligible. Non-empty headers bypass screenshot caching and return an in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted headers."
},
"required": false,
"description": "Optional outbound HTTP headers, using the same JSON object or deep-object query format as other scrape endpoints (for example headers[Authorization]=Bearer token). Headers are scoped to the target origin during capture. For domain/page requests, discovery receives no custom headers and only pages on the resolved origin are eligible. Non-empty headers bypass screenshot caching and return an in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted headers.",
"style": "deepObject",
"explode": true,
"name": "headers",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"true",
"false"
],
"description": "Optional parameter to determine screenshot type. If 'true', takes a full page screenshot capturing all content. If 'false' or not provided, takes a viewport screenshot (standard browser view)."
},
"required": false,
"description": "Optional parameter to determine screenshot type. If 'true', takes a full page screenshot capturing all content. If 'false' or not provided, takes a viewport screenshot (standard browser view).",
"name": "fullScreenshot",
"in": "query"
},
{
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 30000,
"default": 3000,
"description": "Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. When combined with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT."
},
"required": false,
"description": "Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. When combined with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT.",
"name": "waitForMs",
"in": "query"
},
{
"schema": {
"type": "object",
"properties": {
"width": {
"type": "integer",
"minimum": 240,
"maximum": 7680,
"default": 1920,
"description": "Viewport width in pixels."
},
"height": {
"type": "integer",
"minimum": 240,
"maximum": 4320,
"default": 1080,
"description": "Viewport height in pixels."
}
},
"default": {
"width": 1920,
"height": 1080
},
"description": "Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080."
},
"required": false,
"description": "Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080.",
"name": "viewport",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"description": "Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step."
},
"required": false,
"description": "Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step.",
"name": "handleCookiePopup",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"description": "Optional parameter for comprehensive popup cleanup. If 'true', the browser dismisses detected cookie/consent UI and clears other detected obstructive popups and overlays before capture. If 'false' or not provided, this parameter requests no cleanup; handleCookiePopup can still request cookie/consent handling independently."
},
"required": false,
"description": "Optional parameter for comprehensive popup cleanup. If 'true', the browser dismisses detected cookie/consent UI and clears other detected obstructive popups and overlays before capture. If 'false' or not provided, this parameter requests no cleanup; handleCookiePopup can still request cookie/consent handling independently.",
"name": "clearPopups",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"light",
"dark"
],
"description": "Optional parameter to choose the site's visual theme in the screenshot. Use 'light' or 'dark' when the site offers both appearances."
},
"required": false,
"description": "Optional parameter to choose the site's visual theme in the screenshot. Use 'light' or 'dark' when the site offers both appearances.",
"name": "colorScheme",
"in": "query"
},
{
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 100000,
"description": "Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000."
},
"required": false,
"description": "Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000.",
"name": "scrollOffset",
"in": "query"
},
{
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 31536000000,
"default": 259200000,
"description": "Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 year (31536000000 ms). `0` fetches fresh."
},
"required": false,
"description": "Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 year (31536000000 ms). `0` fetches fresh.",
"name": "maxAgeMs",
"in": "query"
},
{
"schema": {
"$ref": "#/components/schemas/BrowserCountryCode"
},
"required": false,
"description": "Fetch from this country (ISO 3166-1 alpha-2).",
"name": "country",
"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": [
"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": "Screenshot captured or retrieved from cache",
"headers": {
"X-Request-Id": {
"$ref": "#/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": {
"screenshot": {
"type": "string",
"format": "uri",
"description": "Public image URL for standard requests, or an in-memory data URL when ZDR or non-empty custom headers are supplied."
},
"url": {
"type": "string",
"format": "uri",
"description": "The requested page URL."
},
"width": {
"type": "integer",
"description": "Width of the returned image in pixels."
},
"height": {
"type": "integer",
"description": "Height of the returned image in pixels."
},
"finalDOMState": {
"type": "string",
"enum": [
"loaded",
"still-loading"
],
"description": "`loaded`, or `still-loading` when capture ended before the page finished loading."
},
"cache_metadata": {
"$ref": "#/components/schemas/CacheMetadata"
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"screenshot",
"url",
"width",
"height",
"cache_metadata",
"request_id"
]
}
}
}
},
"400": {
"description": "Invalid screenshot URL or the page could not be captured.",
"headers": {
"X-Request-Id": {
"$ref": "#/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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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/screenshot": {
"get": {
"x-hidden": true,
"summary": "Scrape Screenshot",
"description": "Capture a screenshot of a website.",
"x-oneOf-query": [
{
"title": "By Domain",
"required": [
"domain"
],
"properties": {
"domain": {
"type": "string",
"description": "Domain name to take screenshot of (e.g., 'example.com', 'google.com')."
},
"fullScreenshot": {
"type": "string",
"enum": [
"true",
"false"
]
},
"handleCookiePopup": {
"type": "string",
"enum": [
"true",
"false"
],
"default": "false",
"description": "Optional parameter to control cookie/consent popup handling. If 'true', the browser service dismisses cookie consent before capture. If 'false' or omitted, captures without that step. "
},
"clearPopups": {
"type": "string",
"enum": [
"true",
"false"
],
"default": "false",
"description": "Optional parameter for comprehensive popup cleanup. If 'true', the browser dismisses detected cookie/consent UI and clears other detected obstructive popups and overlays before capture. If 'false' or omitted, this parameter requests no cleanup; handleCookiePopup can still request cookie/consent handling independently."
},
"colorScheme": {
"type": "string",
"enum": [
"light",
"dark"
],
"description": "Optional parameter to choose the site's visual theme in the screenshot. Use 'light' or 'dark' when the site offers both appearances."
},
"viewport": {
"type": "object",
"additionalProperties": false,
"default": {
"width": 1920,
"height": 1080
},
"properties": {
"width": {
"type": "integer",
"minimum": 240,
"maximum": 7680,
"default": 1920,
"description": "Viewport width in pixels."
},
"height": {
"type": "integer",
"minimum": 240,
"maximum": 4320,
"default": 1080,
"description": "Viewport height in pixels."
}
},
"description": "Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080."
},
"maxAgeMs": {
"type": "integer",
"minimum": 0,
"maximum": 2592000000,
"default": 86400000,
"description": "Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh."
},
"page": {
"type": "string",
"enum": [
"login",
"signup",
"blog",
"careers",
"pricing",
"terms",
"privacy",
"contact"
]
},
"waitForMs": {
"type": "integer",
"minimum": 0,
"maximum": 30000,
"default": 3000,
"description": "Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. When combined with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT."
},
"country": {
"$ref": "#/components/schemas/BrowserCountryCode"
},
"timeoutOpts": {
"$ref": "#/components/schemas/ScrapeTimeout"
}
}
},
{
"title": "By Direct URL",
"required": [
"directUrl"
],
"properties": {
"directUrl": {
"type": "string",
"format": "uri",
"description": "A specific URL to screenshot directly, bypassing domain resolution."
},
"fullScreenshot": {
"type": "string",
"enum": [
"true",
"false"
]
},
"handleCookiePopup": {
"type": "string",
"enum": [
"true",
"false"
],
"default": "false",
"description": "Optional parameter to control cookie/consent popup handling. If 'true', the browser service dismisses cookie consent before capture. If 'false' or omitted, captures without that step. "
},
"clearPopups": {
"type": "string",
"enum": [
"true",
"false"
],
"default": "false",
"description": "Optional parameter for comprehensive popup cleanup. If 'true', the browser dismisses detected cookie/consent UI and clears other detected obstructive popups and overlays before capture. If 'false' or omitted, this parameter requests no cleanup; handleCookiePopup can still request cookie/consent handling independently."
},
"colorScheme": {
"type": "string",
"enum": [
"light",
"dark"
],
"description": "Optional parameter to choose the site's visual theme in the screenshot. Use 'light' or 'dark' when the site offers both appearances."
},
"viewport": {
"type": "object",
"additionalProperties": false,
"default": {
"width": 1920,
"height": 1080
},
"properties": {
"width": {
"type": "integer",
"minimum": 240,
"maximum": 7680,
"default": 1920,
"description": "Viewport width in pixels."
},
"height": {
"type": "integer",
"minimum": 240,
"maximum": 4320,
"default": 1080,
"description": "Viewport height in pixels."
}
},
"description": "Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080."
},
"maxAgeMs": {
"type": "integer",
"minimum": 0,
"maximum": 2592000000,
"default": 86400000,
"description": "Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh."
},
"waitForMs": {
"type": "integer",
"minimum": 0,
"maximum": 30000,
"default": 3000,
"description": "Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. When combined with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT."
},
"country": {
"$ref": "#/components/schemas/BrowserCountryCode"
},
"timeoutOpts": {
"$ref": "#/components/schemas/ScrapeTimeout"
}
}
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Web Scraping"
],
"x-mint": {
"content": "1 Credit",
"title": "Scrape Screenshot",
"sidebarTitle": "Scrape screenshot",
"description": "Capture a screenshot of a website."
},
"parameters": [
{
"schema": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 8192,
"pattern": "^[^\\r\\n]*$"
},
"description": "Optional outbound HTTP headers, using the same JSON object or deep-object query format as other scrape endpoints (for example headers[Authorization]=Bearer token). Headers are scoped to the target origin during capture. For domain/page requests, discovery receives no custom headers and only pages on the resolved origin are eligible. Non-empty headers bypass screenshot caching and return an in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted headers."
},
"required": false,
"description": "Optional outbound HTTP headers, using the same JSON object or deep-object query format as other scrape endpoints (for example headers[Authorization]=Bearer token). Headers are scoped to the target origin during capture. For domain/page requests, discovery receives no custom headers and only pages on the resolved origin are eligible. Non-empty headers bypass screenshot caching and return an in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted headers.",
"style": "deepObject",
"explode": true,
"name": "headers",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 3,
"description": "Domain name to take screenshot of (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both."
},
"required": false,
"description": "Domain name to take screenshot of (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both.",
"name": "domain",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "uri",
"description": "A specific URL to screenshot directly, bypassing domain resolution (e.g., 'https://example.com/pricing'). When provided, the screenshot is taken of this exact URL. You must provide either 'domain' or 'directUrl', but not both."
},
"required": false,
"description": "A specific URL to screenshot directly, bypassing domain resolution (e.g., 'https://example.com/pricing'). When provided, the screenshot is taken of this exact URL. You must provide either 'domain' or 'directUrl', but not both.",
"name": "directUrl",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"true",
"false"
],
"description": "Optional parameter to determine screenshot type. If 'true', takes a full page screenshot capturing all content. If 'false' or not provided, takes a viewport screenshot (standard browser view)."
},
"required": false,
"description": "Optional parameter to determine screenshot type. If 'true', takes a full page screenshot capturing all content. If 'false' or not provided, takes a viewport screenshot (standard browser view).",
"name": "fullScreenshot",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"login",
"signup",
"blog",
"careers",
"pricing",
"terms",
"privacy",
"contact"
],
"description": "Optional parameter to specify which page type to screenshot. If provided, the system will scrape the domain's links and use heuristics to find the most appropriate URL for the specified page type (30 supported languages). If not provided, screenshots the main domain landing page. Only applicable when using 'domain', not 'directUrl'."
},
"required": false,
"description": "Optional parameter to specify which page type to screenshot. If provided, the system will scrape the domain's links and use heuristics to find the most appropriate URL for the specified page type (30 supported languages). If not provided, screenshots the main domain landing page. Only applicable when using 'domain', not 'directUrl'.",
"name": "page",
"in": "query"
},
{
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 30000,
"default": 3000,
"description": "Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. When combined with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT."
},
"required": false,
"description": "Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted. When combined with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT.",
"name": "waitForMs",
"in": "query"
},
{
"schema": {
"type": "object",
"properties": {
"width": {
"type": "integer",
"minimum": 240,
"maximum": 7680,
"default": 1920,
"description": "Viewport width in pixels."
},
"height": {
"type": "integer",
"minimum": 240,
"maximum": 4320,
"default": 1080,
"description": "Viewport height in pixels."
}
},
"default": {
"width": 1920,
"height": 1080
},
"description": "Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080."
},
"required": false,
"description": "Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080.",
"name": "viewport",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"description": "Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step."
},
"required": false,
"description": "Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step.",
"name": "handleCookiePopup",
"in": "query"
},
{
"schema": {
"type": "boolean",
"default": false,
"description": "Optional parameter for comprehensive popup cleanup. If 'true', the browser dismisses detected cookie/consent UI and clears other detected obstructive popups and overlays before capture. If 'false' or not provided, this parameter requests no cleanup; handleCookiePopup can still request cookie/consent handling independently."
},
"required": false,
"description": "Optional parameter for comprehensive popup cleanup. If 'true', the browser dismisses detected cookie/consent UI and clears other detected obstructive popups and overlays before capture. If 'false' or not provided, this parameter requests no cleanup; handleCookiePopup can still request cookie/consent handling independently.",
"name": "clearPopups",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"light",
"dark"
],
"description": "Optional parameter to choose the site's visual theme in the screenshot. Use 'light' or 'dark' when the site offers both appearances."
},
"required": false,
"description": "Optional parameter to choose the site's visual theme in the screenshot. Use 'light' or 'dark' when the site offers both appearances.",
"name": "colorScheme",
"in": "query"
},
{
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 100000,
"description": "Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000."
},
"required": false,
"description": "Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000.",
"name": "scrollOffset",
"in": "query"
},
{
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 2592000000,
"default": 86400000,
"description": "Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh."
},
"required": false,
"description": "Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh.",
"name": "maxAgeMs",
"in": "query"
},
{
"schema": {
"$ref": "#/components/schemas/BrowserCountryCode"
},
"required": false,
"description": "Fetch from this country (ISO 3166-1 alpha-2).",
"name": "country",
"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": [
"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"
},
"screenshot": {
"type": "string",
"description": "Public image URL for standard requests, or an in-memory data URL when ZDR or non-empty custom headers are supplied."
},
"screenshotType": {
"type": "string",
"enum": [
"viewport",
"fullPage"
],
"description": "Type of screenshot that was captured"
},
"width": {
"type": "integer",
"description": "Width in pixels of the returned screenshot image"
},
"height": {
"type": "integer",
"description": "Height in pixels of the returned screenshot image"
},
"code": {
"type": "integer",
"description": "HTTP status code"
},
"cache_metadata": {
"$ref": "#/components/schemas/CacheMetadata"
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"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",
"TIMEOUT_TOO_SHORT_FOR_WAIT",
"WEBSITE_ACCESS_ERROR",
"INPUT_VALIDATION_ERROR"
],
"description": "Error code indicating the type of error. TIMEOUT_TOO_SHORT_FOR_WAIT means timeoutOpts.milliseconds is shorter than waitForMs plus the page-load margin, so the screenshot could never complete before the deadline; raise timeoutOpts.milliseconds or lower waitForMs."
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"request_id"
]
}
}
}
},
"401": {
"description": "Missing or invalid 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": {
"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"
]
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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": {
"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": {
"x-hidden": true,
"deprecated": true,
"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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
]
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"/web/sic": {
"get": {
"x-hidden": true,
"deprecated": true,
"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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
]
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
}
}
}
},
"/brand/ai/product": {
"post": {
"x-hidden": true,
"deprecated": true,
"summary": "Extract a single product from a URL",
"description": "Given a single URL, determines if it is a product page and extracts the product information.",
"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 product page URL to extract product data from."
},
"maxAgeMs": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 2592000000,
"default": 604800000,
"description": "Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 7 days (604800000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh."
},
"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"
]
}
}
}
},
"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."
},
"is_product_page": {
"type": "boolean",
"description": "Whether the given URL is a product detail page"
},
"platform": {
"type": [
"string",
"null"
],
"enum": [
"amazon",
"tiktok_shop",
"etsy",
"generic",
null
],
"description": "The detected ecommerce platform, or null if not a product page"
},
"product": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the product"
},
"description": {
"type": "string",
"description": "Description of the product"
},
"price": {
"type": [
"number",
"null"
],
"description": "Price of the product"
},
"regular_price": {
"type": [
"number",
"null"
],
"description": "Original or regular price before a displayed discount"
},
"currency": {
"type": [
"string",
"null"
],
"description": "Currency code for the price (e.g., USD, EUR)"
},
"billing_frequency": {
"type": [
"string",
"null"
],
"enum": [
"monthly",
"yearly",
"one_time",
"usage_based",
null
],
"description": "Billing frequency for the product"
},
"pricing_model": {
"type": [
"string",
"null"
],
"enum": [
"per_seat",
"flat",
"tiered",
"freemium",
"custom",
null
],
"description": "Pricing model for the product"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to the product page"
},
"category": {
"type": [
"string",
"null"
],
"description": "Category of the product"
},
"availability": {
"type": [
"string",
"null"
],
"enum": [
"in_stock",
"out_of_stock",
"limited_availability",
"preorder",
"backorder",
"made_to_order",
"discontinued",
null
],
"description": "Normalized stock or ordering availability"
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Dimension statements shown for the product, preserving labels, values, and units"
},
"features": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of product features"
},
"target_audience": {
"type": "array",
"items": {
"type": "string"
},
"description": "Target audience for the product (array of strings)"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags associated with the product"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL to the product image"
},
"images": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs to product images on the page (up to 7)"
},
"variants": {
"$ref": "#/components/schemas/ProductVariants"
},
"sku": {
"type": [
"string",
"null"
],
"description": "Stock Keeping Unit (product identifier). Null if no identifier is found."
}
},
"required": [
"name",
"description",
"features",
"target_audience",
"tags",
"images",
"sku"
],
"description": "The extracted product data, or null if not a product page"
},
"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 - 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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
]
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
]
}
}
}
}
}
}
},
"/brand/ai/products": {
"post": {
"x-hidden": true,
"deprecated": true,
"summary": "Extract products from a brand's website",
"description": "Extract product information from a brand's website. We will analyze the website and return a list of products with details such as name, description, image, pricing, features, and more.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Web Extraction"
],
"x-mint": {
"content": "10 Credits Beta Feature"
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"minLength": 3,
"description": "The domain name to analyze."
},
"maxProducts": {
"type": "integer",
"minimum": 1,
"maximum": 12,
"description": "Maximum number of products to extract."
},
"maxAgeMs": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 2592000000,
"default": 604800000,
"description": "Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 7 days (604800000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh."
},
"timeoutOpts": {
"$ref": "#/components/schemas/PartialTimeout"
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
}
},
"required": [
"domain"
],
"title": "By Domain"
},
{
"type": "object",
"properties": {
"directUrl": {
"type": "string",
"format": "uri",
"description": "A specific URL to use directly as the starting point for extraction without domain resolution."
},
"maxProducts": {
"type": "integer",
"minimum": 1,
"maximum": 12,
"description": "Maximum number of products to extract."
},
"maxAgeMs": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 2592000000,
"default": 604800000,
"description": "Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 7 days (604800000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh."
},
"timeoutOpts": {
"$ref": "#/components/schemas/PartialTimeout"
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
}
},
"required": [
"directUrl"
],
"title": "By Direct URL"
}
]
}
}
}
},
"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": {
"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."
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the product"
},
"description": {
"type": "string",
"description": "Description of the product"
},
"price": {
"type": [
"number",
"null"
],
"description": "Price of the product"
},
"regular_price": {
"type": [
"number",
"null"
],
"description": "Original or regular price before a displayed discount"
},
"currency": {
"type": [
"string",
"null"
],
"description": "Currency code for the price (e.g., USD, EUR)"
},
"billing_frequency": {
"type": [
"string",
"null"
],
"enum": [
"monthly",
"yearly",
"one_time",
"usage_based",
null
],
"description": "Billing frequency for the product"
},
"pricing_model": {
"type": [
"string",
"null"
],
"enum": [
"per_seat",
"flat",
"tiered",
"freemium",
"custom",
null
],
"description": "Pricing model for the product"
},
"url": {
"type": [
"string",
"null"
],
"description": "URL to the product page"
},
"category": {
"type": [
"string",
"null"
],
"description": "Category of the product"
},
"availability": {
"type": [
"string",
"null"
],
"enum": [
"in_stock",
"out_of_stock",
"limited_availability",
"preorder",
"backorder",
"made_to_order",
"discontinued",
null
],
"description": "Normalized stock or ordering availability"
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Dimension statements shown for the product, preserving labels, values, and units"
},
"features": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of product features"
},
"target_audience": {
"type": "array",
"items": {
"type": "string"
},
"description": "Target audience for the product (array of strings)"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags associated with the product"
},
"image_url": {
"type": [
"string",
"null"
],
"description": "URL to the product image"
},
"images": {
"type": "array",
"items": {
"type": "string"
},
"description": "URLs to product images on the page (up to 7)"
},
"variants": {
"$ref": "#/components/schemas/ProductVariants"
},
"sku": {
"type": [
"string",
"null"
],
"description": "Stock Keeping Unit (product identifier). Null if no identifier is found."
}
},
"required": [
"name",
"description",
"features",
"target_audience",
"tags",
"images",
"sku"
]
},
"description": "Array of products extracted from the website"
},
"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 - 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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
]
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
]
}
}
}
}
}
}
},
"/brand/prefetch": {
"post": {
"x-hidden": true,
"deprecated": true,
"summary": "Prefetch brand data for a domain",
"description": "Signal that you may fetch brand data for a particular domain soon to improve latency.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Utility"
],
"x-mint": {
"content": "0 Credits Only for Subscribers"
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"domain": {
"type": "string",
"minLength": 3,
"description": "Domain name to prefetch brand data for"
},
"timeoutOpts": {
"$ref": "#/components/schemas/Timeout"
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
}
},
"required": [
"domain"
]
}
}
}
},
"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"
},
"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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
]
}
}
}
},
"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"
]
}
}
}
}
}
}
},
"/brand/prefetch-by-email": {
"post": {
"x-hidden": true,
"deprecated": true,
"summary": "Prefetch brand data by email",
"description": "Signal that you may fetch brand data for a particular domain soon to improve latency. This endpoint accepts an email address, extracts the domain from it, validates that it's not a disposable or free email provider, and queues the domain for prefetching.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Utility"
],
"x-mint": {
"content": "0 Credits Only for Subscribers"
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"minLength": 1,
"format": "email",
"description": "Email address to prefetch brand 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."
},
"timeoutOpts": {
"$ref": "#/components/schemas/Timeout"
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
}
},
"required": [
"email"
]
}
}
}
},
"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"
},
"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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
]
}
}
}
}
}
}
},
"/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"
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
},
"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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
]
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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": "Forbidden - Paid subscription required. An access policy can also block the website (`ACCESS_POLICY_DENIED`).",
"headers": {
"X-Request-Id": {
"$ref": "#/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, extract, and search targets can have instructions, and `url` matches a search target’s query.",
"example": "name,url"
},
"required": false,
"description": "Fields to search with `q`. Defaults to all fields; page, extract, and search targets can have instructions, and `url` matches a search target’s query.",
"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",
"search"
],
"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": {
"allOf": [
{
"$ref": "#/components/schemas/MonitorsRunStatus"
},
{
"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": {
"allOf": [
{
"$ref": "#/components/schemas/MonitorsRunStatus"
},
{
"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",
"search"
],
"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 100,000 URLs, or crawl a site, asynchronously using the same formats and scrape parameters as POST /web/scrape. Choose Markdown, HTML, screenshots, images, bytes, parsed fields, products, highlights, and JSON. Poll the batch ID or receive a webhook when it finishes.",
"operationId": "submitBatch",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Batches"
],
"x-mint": {
"content": "From 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": {
"scrapeAnything": {
"summary": "Scrape URLs as Markdown and HTML",
"value": {
"input": {
"mode": "scrape",
"data": {
"urls": [
{
"url": "https://example.com/products/anvil",
"itemId": "sku-1",
"meta": {
"category": "tools"
}
},
{
"url": "https://example.com/products/hammer",
"itemId": "sku-2"
}
],
"formats": {
"markdown": true,
"html": true
},
"sharedParams": {
"mainContentOnly": true
}
}
}
}
},
"scrapeScreenshots": {
"summary": "Capture screenshots and images",
"value": {
"input": {
"mode": "scrape",
"data": {
"urls": [
{
"url": "https://example.com"
},
{
"url": "https://example.com/pricing"
}
],
"formats": {
"screenshot": true,
"images": true
},
"screenshotParams": {
"area": "fullPage",
"format": "png"
}
}
}
}
},
"scrapeJson": {
"summary": "Extract structured JSON from each URL",
"value": {
"input": {
"mode": "scrape",
"data": {
"urls": [
{
"url": "https://example.com/products/anvil"
}
],
"formats": {
"json": true
},
"jsonParams": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"price": {
"type": [
"number",
"null"
]
}
},
"required": [
"name"
],
"additionalProperties": false
}
}
}
}
}
},
"crawlAnything": {
"summary": "Crawl a site with multiple output formats",
"value": {
"input": {
"mode": "crawl",
"data": {
"source": {
"type": "start_url",
"url": "https://example.com/docs",
"controls": {
"maxUrls": 500,
"maxDepth": 3
}
},
"formats": {
"markdown": true,
"html": true
},
"sharedParams": {
"mainContentOnly": true
}
}
}
}
},
"crawlSitemapAnything": {
"summary": "Scrape sitemap pages with selected formats",
"value": {
"input": {
"mode": "crawl",
"data": {
"source": {
"type": "sitemap",
"domain": "example.com",
"controls": {
"maxUrls": 250
}
},
"formats": {
"markdown": true,
"images": true
}
}
}
}
}
}
}
}
},
"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"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"request_id"
]
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"description": "Authentication failed.",
"headers": {
"X-Request-Id": {
"$ref": "#/components/headers/RequestId"
},
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
},
"X-RateLimit-Mode": {
"$ref": "#/components/headers/RateLimitMode"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.",
"headers": {
"X-Request-Id": {
"$ref": "#/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": "boolean",
"default": false,
"description": "Include batches submitted with Scrape Anything formats. Defaults to false."
},
"required": false,
"description": "Include batches submitted with Scrape Anything formats. Defaults to false.",
"name": "shouldIncludeUnified",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25,
"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": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Tags to filter by (matches batches having any of them). Pass repeated `tags` params or one comma-separated list, e.g. `tags=docs,competitor`.",
"example": "docs,competitor"
},
"required": false,
"description": "Tags to filter by (matches batches having any of them). Pass repeated `tags` params or one comma-separated list, e.g. `tags=docs,competitor`.",
"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"
},
{
"$ref": "#/components/schemas/BatchDetail"
},
{
"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"
},
"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. Each record contains result with the same outputs and per-format errors as POST /web/scrape. 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,
"default": 25,
"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",
"pattern": "^\\d+:\\d+$",
"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"
},
"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"
}
}
}
},
"/company/search": {
"post": {
"summary": "Search companies",
"description": "Find companies with a natural-language query.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"Company"
],
"x-mint": {
"content": "2 CreditsUltra: 10 Credits",
"title": "Search companies",
"sidebarTitle": "Search companies",
"description": "Search companies"
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 1,
"maxLength": 5000,
"description": "Describe the companies to find. Up to 500 characters in `fast` mode and 5000 in `ultra` mode.",
"example": "Solar startups in California that raised a Series B"
},
"mode": {
"type": "string",
"enum": [
"fast",
"ultra"
],
"default": "fast",
"description": "`fast` returns results in about two seconds; `ultra` searches more thoroughly and checks every result against each criterion in the query. `ultra` can take up to 20 seconds, so allow for that in your client timeout."
},
"filters": {
"$ref": "#/components/schemas/CompanySearchFilters"
},
"cursor": {
"type": "string",
"maxLength": 64,
"description": "Use next_cursor with the same query, mode and filters to fetch the next page."
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
}
},
"required": [
"query"
],
"additionalProperties": false,
"example": {
"query": "Solar startups in California that raised a Series B"
}
}
}
}
},
"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": {
"name": {
"type": "string",
"description": "Company name."
},
"domain": {
"type": "string",
"description": "The company's website domain."
},
"description": {
"type": [
"string",
"null"
],
"description": "What the company does."
},
"organization_type": {
"type": [
"string",
"null"
],
"description": "Company type, such as public_company or privately_held."
},
"operating_status": {
"type": [
"string",
"null"
],
"description": "Operating status, such as active, acquired or closed."
},
"stock_symbols": {
"type": "array",
"items": {
"type": "string"
},
"description": "Known stock listings and ticker symbols."
},
"revenue": {
"type": "object",
"properties": {
"min_usd": {
"type": [
"integer",
"null"
],
"description": "Lower estimate of annual revenue in US dollars."
},
"max_usd": {
"type": [
"integer",
"null"
],
"description": "Upper estimate of annual revenue in US dollars."
}
},
"description": "Estimated annual revenue in US dollars."
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Industries the company operates in."
},
"founded_year": {
"type": [
"integer",
"null"
],
"description": "Year the company was founded."
},
"headquarters": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2 country code."
},
"region": {
"type": [
"string",
"null"
],
"description": "State or region."
},
"city": {
"type": [
"string",
"null"
],
"description": "City."
},
"street_address": {
"type": [
"string",
"null"
],
"description": "Street address."
},
"postal_code": {
"type": [
"string",
"null"
],
"description": "Postal code."
}
},
"description": "Where the company is headquartered."
},
"employees": {
"type": "object",
"properties": {
"count": {
"type": [
"integer",
"null"
],
"description": "Employee count, when known."
},
"min": {
"type": [
"integer",
"null"
],
"description": "Lower bound of the headcount range."
},
"max": {
"type": [
"integer",
"null"
],
"description": "Upper headcount bound; null for open-ended ranges."
}
},
"description": "How many people the company employs."
},
"funding": {
"type": "object",
"properties": {
"total_usd": {
"type": [
"integer",
"null"
],
"description": "Total disclosed funding in US dollars."
},
"round_count": {
"type": "integer",
"description": "Number of known funding rounds."
},
"latest_round": {
"type": [
"object",
"null"
],
"properties": {
"type": {
"type": "string",
"description": "Round type, such as seed or series_b."
},
"date": {
"type": "string",
"description": "Announcement date (YYYY-MM-DD)."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "Round size in US dollars, when disclosed."
}
},
"required": [
"type",
"date"
],
"description": "The most recent known funding round; null when none is known."
},
"stage": {
"type": [
"string",
"null"
],
"description": "Current funding stage, when known."
},
"rounds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Round type, such as seed or series_b."
},
"date": {
"type": "string",
"description": "Announcement date (YYYY-MM-DD)."
},
"amount_usd": {
"type": [
"integer",
"null"
],
"description": "Round size in US dollars, when disclosed."
},
"phase": {
"type": [
"string",
"null"
],
"enum": [
"initial",
"extension",
null
],
"description": "Initial financing or an extension, when known."
}
},
"required": [
"type",
"date"
]
},
"description": "Known historical rounds; unavailable amounts are null."
}
},
"required": [
"round_count",
"rounds"
],
"description": "Known funding history."
}
},
"required": [
"name",
"domain",
"stock_symbols",
"revenue",
"industries",
"headquarters",
"employees",
"funding"
],
"example": {
"name": "Solstice",
"domain": "solstice.example",
"description": "Software for designing and managing solar installations.",
"organization_type": "privately_held",
"operating_status": "active",
"stock_symbols": [],
"revenue": {
"min_usd": null,
"max_usd": null
},
"industries": [
"Renewable Energy"
],
"founded_year": 2018,
"headquarters": {
"country_code": "US",
"region": "California",
"city": "San Francisco",
"street_address": null,
"postal_code": null
},
"employees": {
"count": null,
"min": 51,
"max": 200
},
"funding": {
"stage": "series_b",
"total_usd": 40000000,
"round_count": 3,
"latest_round": {
"type": "series_b",
"date": "2026-03-02",
"amount_usd": 25000000
},
"rounds": [
{
"type": "series_b",
"date": "2026-03-02",
"amount_usd": 25000000,
"phase": "initial"
}
]
}
}
},
"maxItems": 10,
"description": "Up to 10 matching companies, most relevant first by default."
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": "Pass as cursor to fetch the next page; null when there are no more results."
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"results",
"request_id"
]
},
"example": {
"results": [
{
"name": "Solstice",
"domain": "solstice.example",
"description": "Software for designing and managing solar installations.",
"organization_type": "privately_held",
"operating_status": "active",
"stock_symbols": [],
"revenue": {
"min_usd": null,
"max_usd": null
},
"industries": [
"Renewable Energy"
],
"founded_year": 2018,
"headquarters": {
"country_code": "US",
"region": "California",
"city": "San Francisco",
"street_address": null,
"postal_code": null
},
"employees": {
"count": null,
"min": 51,
"max": 200
},
"funding": {
"stage": "series_b",
"total_usd": 40000000,
"round_count": 3,
"latest_round": {
"type": "series_b",
"date": "2026-03-02",
"amount_usd": 25000000
},
"rounds": [
{
"type": "series_b",
"date": "2026-03-02",
"amount_usd": 25000000,
"phase": "initial"
}
]
}
}
],
"next_cursor": null,
"request_id": "3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91",
"key_metadata": {
"credits_consumed": 2,
"credits_remaining": 998
}
}
}
}
},
"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",
"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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
]
}
}
}
}
}
}
},
"/people/search": {
"post": {
"summary": "Search people",
"description": "Find people with a natural-language query.",
"security": [
{
"bearerAuth": []
}
],
"tags": [
"People"
],
"x-mint": {
"content": "10 CreditsUltra: 50 Credits",
"title": "Search people",
"sidebarTitle": "Search people",
"description": "Search People"
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 1,
"maxLength": 5000,
"description": "Describe the people to find. Up to 500 characters in `fast` mode and 5000 in `ultra` mode.",
"example": "VPs of sales at solar companies in California"
},
"mode": {
"type": "string",
"enum": [
"fast",
"ultra"
],
"default": "fast",
"description": "`fast` matches people on basic criteria (e.g. their role, location or background); `ultra` plans a deeper search, judges each candidate against every criterion in the query. Complex `ultra` searches can take up to 30 seconds to complete, so allow for that in your client timeout."
},
"filters": {
"$ref": "#/components/schemas/PeopleSearchFilters"
},
"cursor": {
"type": "string",
"maxLength": 65536,
"description": "Use next_cursor with the same query, mode and filters to fetch the next page."
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
}
},
"required": [
"query"
],
"additionalProperties": false,
"example": {
"query": "VPs of sales at solar companies in California"
}
}
}
}
},
"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": {
"name": {
"type": [
"string",
"null"
],
"description": "Full name."
},
"description": {
"type": [
"string",
"null"
],
"description": "What the person does."
},
"profiles": {
"type": "array",
"items": {
"type": "string"
},
"description": "Public professional profile URLs."
},
"location": {
"type": "object",
"properties": {
"country_code": {
"type": [
"string",
"null"
],
"description": "Country as a two-letter code, such as US or GB."
},
"region": {
"type": [
"string",
"null"
],
"description": "State or region."
},
"city": {
"type": [
"string",
"null"
],
"description": "City."
}
},
"required": [
"country_code",
"region",
"city"
],
"description": "Where the person lives."
},
"role": {
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "Job title."
},
"seniority": {
"type": [
"string",
"null"
],
"description": "Seniority level."
},
"functions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Areas of responsibility."
},
"started_on": {
"type": [
"string",
"null"
],
"description": "Role start date (YYYY-MM-DD)."
},
"company": {
"type": [
"object",
"null"
],
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "Company name."
},
"domain": {
"type": [
"string",
"null"
],
"description": "The company’s website domain."
}
},
"required": [
"name",
"domain"
],
"description": "Current employer, when known."
}
},
"required": [
"title",
"seniority",
"functions",
"started_on",
"company"
],
"description": "The person’s current role."
},
"years_of_experience": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Years of professional experience."
},
"is_founder": {
"type": [
"boolean",
"null"
],
"description": "Whether the person is currently a founder or co-founder."
},
"skills": {
"type": "array",
"items": {
"type": "string"
},
"description": "Professional skills."
},
"schools": {
"type": "array",
"items": {
"type": "string"
},
"description": "Schools attended."
},
"match": {
"$ref": "#/components/schemas/PeopleSearchMatch"
}
},
"required": [
"name",
"description",
"profiles",
"location",
"role",
"years_of_experience",
"is_founder",
"skills",
"schools"
],
"description": "A person matching your search; unavailable details are null or empty lists.",
"example": {
"name": "Alex Morgan",
"description": "Sales leader helping solar companies grow.",
"profiles": [
"https://alexmorgan.example"
],
"location": {
"country_code": "US",
"region": "California",
"city": "San Francisco"
},
"role": {
"title": "VP of Sales",
"seniority": "executive",
"functions": [
"sales"
],
"started_on": "2023-06-01",
"company": {
"name": "Solstice",
"domain": "solstice.example"
}
},
"years_of_experience": 12,
"is_founder": false,
"skills": [
"Enterprise Sales",
"Sales Leadership",
"Renewable Energy"
],
"schools": [
"University of California, Berkeley"
]
}
},
"maxItems": 10,
"description": "Up to 10 matching people, most relevant first."
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": "Pass as cursor to fetch the next page; null when there are no more results."
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"results",
"request_id"
]
},
"example": {
"results": [
{
"name": "Alex Morgan",
"description": "Sales leader helping solar companies grow.",
"profiles": [
"https://alexmorgan.example"
],
"location": {
"country_code": "US",
"region": "California",
"city": "San Francisco"
},
"role": {
"title": "VP of Sales",
"seniority": "executive",
"functions": [
"sales"
],
"started_on": "2023-06-01",
"company": {
"name": "Solstice",
"domain": "solstice.example"
}
},
"years_of_experience": 12,
"is_founder": false,
"skills": [
"Enterprise Sales",
"Sales Leadership",
"Renewable Energy"
],
"schools": [
"University of California, Berkeley"
]
}
],
"next_cursor": null,
"request_id": "3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91",
"key_metadata": {
"credits_consumed": 10,
"credits_remaining": 990
}
}
}
}
},
"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",
"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.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
]
}
}
}
}
}
}
}
},
"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"
},
"AccessPolicies": {
"name": "policies",
"in": "query",
"required": false,
"style": "form",
"explode": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Comma-separated access policy IDs to apply. A URL must pass every policy.",
"example": "pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
}
},
"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 these headers report concurrent requests. When a per-minute limit also applies, its rejections report per-minute headers without this header. New Free accounts have 2 concurrent requests; no plan has a per-minute limit by default. Existing and custom allowances can differ.",
"schema": {
"type": "string",
"enum": [
"concurrency"
]
}
}
},
"responses": {
"RateLimited": {
"description": "Rate limit exceeded. Organization concurrency rejections include structured error_data and subscription settings; follow Retry-After before retrying.",
"headers": {
"X-Request-Id": {
"$ref": "#/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"
},
"error_data": {
"$ref": "#/components/schemas/ConcurrencyErrorData"
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"message",
"error_code",
"request_id"
]
}
}
}
},
"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": {
"ScrapeResponse": {
"type": "object",
"additionalProperties": false,
"properties": {
"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."
},
"type": {
"type": "string",
"enum": [
"custom",
"google-maps",
"google-maps-reviews",
"google-play",
"google-play-reviews",
"app-store",
"app-store-reviews",
"g2-reviews",
"instagram-profile",
"instagram-post",
"instagram-feed",
"tiktok-profile",
"tiktok-video",
"tiktok-feed",
"tiktok-comments",
"tiktok-followers",
"tiktok-following",
"tiktok-user-search",
"reddit-post",
"reddit-search",
"reddit-subreddit",
"reddit-user",
"yelp-search",
"yelp-reviews",
"emails",
"phone-numbers",
"links"
],
"description": "The selected prebuilt parser name, or custom when type is omitted, custom rules are used, or parsing is not requested."
},
"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",
"type"
],
"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": "Custom rules return fields after content filters; unmatched fields are null ([] for lists). The google-maps parser returns business records in data.results, google-maps-reviews returns data.reviews, and the google-play parser returns one app record as data, google-play-reviews returns data.reviews, app-store and app-store-reviews do the same for the App Store, g2-reviews returns data.reviews for a G2 product, instagram-profile and instagram-post return one record as data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return one record as data, tiktok-feed returns data.videos, tiktok-comments returns data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return data.users, yelp-search returns up to 20 ranked organic businesses in data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews returns up to 20 latest public reviews in data.reviews, with business details and next_offset, from a Yelp business URL; emails, phone-numbers, and links return data.emails, data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, Instagram, and TikTok parsers read their data directly, independently of DOM filters and other outputs."
},
"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."
},
"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
},
"isTruncated": {
"type": "boolean",
"const": true,
"description": "True when the page was too long to read in full, so values found only in the unread parts may be missing."
}
},
"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."
},
"profile": {
"type": [
"object",
"null"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^prof_[a-f0-9]{32}$",
"description": "Save this ID after creating a profile, then reuse it as sharedParams.profile.profileId with type \"existing\"."
}
},
"required": [
"id"
],
"description": "Authenticated browser profile used for this scrape, or null when no profile was requested. New and existing profile requests both return the profile ID."
},
"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."
},
"metadata": {
"$ref": "#/components/schemas/ScrapeMetadata",
"description": "Page metadata. Fields are omitted when not found."
},
"cache_metadata": {
"$ref": "#/components/schemas/CacheMetadata"
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"url",
"html",
"markdown",
"screenshot",
"images",
"bytes",
"parsed",
"highlights",
"json",
"product",
"profile",
"metadata",
"cache_metadata",
"request_id"
],
"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."
}
}
},
"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"
]
},
"AccessPolicy": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Access policy ID. Pass it in `policies` on any request.",
"example": "pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
},
"name": {
"type": "string",
"minLength": 1,
"description": "A name to recognize this policy.",
"example": "Research sources"
},
"allowed_domains": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Only these domains and their subdomains can be accessed. Null for a blocklist.",
"example": [
"arxiv.org",
"*.gov"
]
},
"blocked_domains": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "These domains and their subdomains can't be accessed. Null for an allowlist.",
"example": null
},
"applies_to": {
"type": "string",
"enum": [
"request",
"api_keys",
"organization"
],
"description": "`request` applies when listed in `policies`. `api_keys` applies to every request made with `api_key_ids`. `organization` applies to every request."
},
"api_key_ids": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "API keys this policy applies to. Null unless `applies_to` is `api_keys`.",
"example": null
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When the policy was created.",
"example": "2026-10-27T18:00:00.000Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "When the policy was last changed.",
"example": "2026-10-27T18:00:00.000Z"
}
},
"required": [
"id",
"name",
"allowed_domains",
"blocked_domains",
"applies_to",
"api_key_ids",
"created_at",
"updated_at"
]
},
"CreateAccessPolicyRequest": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "A name to recognize this policy.",
"example": "Research sources"
},
"allowed_domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Only these domains and their subdomains can be accessed. Send this or `blocked_domains`.",
"example": [
"arxiv.org",
"*.gov"
]
},
"blocked_domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "These domains and their subdomains can't be accessed. Send this or `allowed_domains`.",
"example": [
"facebook.com",
"tiktok.com"
]
},
"applies_to": {
"type": "string",
"enum": [
"request",
"api_keys",
"organization"
],
"default": "request",
"description": "`request` applies when listed in `policies`. `api_keys` applies to every request made with `api_key_ids`. `organization` applies to every request."
},
"api_key_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "API key IDs to apply this policy to. Required when `applies_to` is `api_keys`.",
"example": [
"ctxt_keyid_4b7e2f9a1c8d4e6fa3b5c7d9e1f20a4b"
]
}
},
"required": [
"name"
]
},
"UpdateAccessPolicyRequest": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "A name to recognize this policy.",
"example": "Research sources"
},
"allowed_domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Only these domains and their subdomains can be accessed. Send this or `blocked_domains`.",
"example": [
"arxiv.org",
"*.gov"
]
},
"blocked_domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "These domains and their subdomains can't be accessed. Send this or `allowed_domains`.",
"example": [
"facebook.com",
"tiktok.com"
]
},
"applies_to": {
"type": "string",
"enum": [
"request",
"api_keys",
"organization"
],
"description": "`request` applies when listed in `policies`. `api_keys` applies to every request made with `api_key_ids`. `organization` applies to every request."
},
"api_key_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "API key IDs to apply this policy to. Required when `applies_to` is `api_keys`.",
"example": [
"ctxt_keyid_4b7e2f9a1c8d4e6fa3b5c7d9e1f20a4b"
]
}
}
},
"ListAccessPoliciesResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccessPolicy"
},
"description": "Access policies, newest first."
},
"has_more": {
"type": "boolean",
"description": "Whether a next page exists."
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to fetch the next page."
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"data",
"has_more",
"next_cursor",
"request_id"
]
},
"DeleteAccessPolicyResponse": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Access policy ID. Pass it in `policies` on any request.",
"example": "pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
},
"deleted": {
"type": "boolean",
"example": true
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"id",
"deleted",
"request_id"
]
},
"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"
]
},
"BrowserProfile": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Profile ID to pass as `sharedParams.profile.profileId` on `/web/scrape`.",
"example": "prof_8f14e45fceea167a5a36dedd4bea2543"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description supplied when the profile was created, or null.",
"example": "Acme billing portal admin"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When the profile was created.",
"example": "2026-10-15T14:03:11.000Z"
}
},
"required": [
"id",
"description",
"created_at"
]
},
"ListProfilesResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BrowserProfile"
},
"description": "Browser profiles, newest first."
},
"has_more": {
"type": "boolean",
"description": "Whether a next page exists."
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` to fetch the next page."
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"data",
"has_more",
"next_cursor",
"request_id"
]
},
"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)."
},
"CountryGL": {
"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 (GL parameter) used to localize search."
},
"StockExchange": {
"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 code."
},
"HtmlExtractionResult": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
},
{
"$ref": "#/components/schemas/HtmlExtractionResult"
},
{
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
},
{
"$ref": "#/components/schemas/HtmlExtractionResult"
}
]
}
}
]
},
"description": "Fields from your CSS rules. Missing items are `null`; unmatched lists are empty."
},
"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"
]
},
"BillingErrorData": {
"type": "object",
"properties": {
"is_authenticated": {
"type": "boolean",
"enum": [
true
]
},
"credits_remaining": {
"type": "number",
"minimum": 0
},
"credits_required": {
"type": "number",
"minimum": 0
},
"is_credits_required_estimated": {
"type": "boolean"
},
"credits_charged": {
"type": "number",
"minimum": 0
},
"should_retry": {
"type": "boolean",
"enum": [
false
]
},
"retry_condition": {
"type": "string",
"enum": [
"sufficient_credits"
]
},
"next_refill_at": {
"type": "string",
"format": "date-time"
},
"next_refill_credits": {
"type": "number",
"exclusiveMinimum": 0
},
"info_url": {
"type": "string",
"enum": [
"https://context.dev/dashboard/subscription"
]
}
},
"required": [
"is_authenticated",
"should_retry",
"retry_condition",
"info_url"
],
"description": "Credit admission or reservation failure details. credits_required is an admission estimate, not a final charge. should_retry is false for an unchanged request immediately; retry_condition requires sufficient account credits. Unknown balances, costs, and refill details are omitted. next_refill_at is an ISO 8601 UTC timestamp. Existing request_id and key_metadata remain on the error envelope."
},
"ConcurrencyErrorData": {
"type": "object",
"properties": {
"is_authenticated": {
"type": "boolean",
"enum": [
true
]
},
"limit_type": {
"type": "string",
"enum": [
"concurrency"
]
},
"limit": {
"type": "number",
"minimum": 0
},
"remaining": {
"type": "number",
"minimum": 0
},
"retry_after_seconds": {
"type": "number",
"minimum": 0
},
"credits_remaining": {
"type": "number",
"minimum": 0
},
"credits_charged": {
"type": "number",
"enum": [
0
]
},
"should_retry": {
"type": "boolean",
"enum": [
false
]
},
"retry_condition": {
"type": "string",
"enum": [
"available_concurrency"
]
},
"recovery_options": {
"type": "array",
"items": {
"type": "string",
"enum": [
"wait_for_in_flight_requests",
"increase_concurrency_limit"
]
}
},
"info_url": {
"type": "string",
"enum": [
"https://context.dev/dashboard/subscription"
]
}
},
"required": [
"is_authenticated",
"limit_type",
"limit",
"remaining",
"retry_after_seconds",
"credits_charged",
"should_retry",
"retry_condition",
"recovery_options",
"info_url"
],
"description": "Organization concurrency rejection details. Authentication is valid and no credits were charged. should_retry is false immediately; respect retry_after_seconds and wait for an in-flight request to finish or for the effective concurrency limit to increase. info_url opens subscription settings; no higher allowance is guaranteed for a particular account."
},
"AccessPolicyErrorData": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The URL that was blocked."
},
"denied_by": {
"type": "array",
"items": {
"type": "string"
},
"description": "IDs of the access policies that blocked it."
}
},
"required": [
"url",
"denied_by"
],
"description": "Sent with `ACCESS_POLICY_DENIED`."
},
"ErrorResponse": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Human-readable error message."
},
"error_code": {
"type": "string",
"enum": [
"PROFILE_NOT_FOUND",
"PROFILE_BUSY",
"PROFILE_SESSION_EXPIRED",
"PROFILE_REAUTHENTICATION_REQUIRED",
"PROFILE_INVALID_CREDENTIALS",
"PROFILE_MISSING_CREDENTIALS",
"PROFILE_INTERACTION_REQUIRED",
"PROFILE_AUTHENTICATION_UNKNOWN",
"PROFILE_ORIGIN_BLOCKED",
"PROFILE_INVALID_SESSION",
"PROFILE_SESSION_TOO_LARGE",
"INTERNAL_ERROR",
"VALID",
"NOT_FOUND",
"FORBIDDEN",
"ACCESS_POLICY_DENIED",
"ACCESS_POLICIES_NOT_ENABLED",
"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",
"NO_PUBLISHED_MARKDOWN",
"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."
},
"error_data": {
"anyOf": [
{
"$ref": "#/components/schemas/BillingErrorData"
},
{
"$ref": "#/components/schemas/ConcurrencyErrorData"
},
{
"$ref": "#/components/schemas/AccessPolicyErrorData"
}
]
},
"required_permission": {
"type": "string",
"enum": [
"logs:read",
"data:execute",
"monitors:read",
"monitors:write",
"batches:read",
"batches:write",
"access_policies:read",
"access_policies: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"
]
},
"SimplifiedBrandResponse": {
"type": "object",
"properties": {
"partial": {
"type": "boolean",
"description": "True when the timeout ended processing and only completed brand data is returned."
},
"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"
},
"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"
},
"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"
}
},
"description": "Simplified brand information"
},
"code": {
"type": "integer",
"description": "HTTP status code of the response"
},
"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"
]
},
"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."
},
"LenientTimeout": {
"type": "object",
"properties": {
"milliseconds": {
"type": "integer",
"minimum": 1,
"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."
},
"PersonDate": {
"type": "object",
"properties": {
"year": {
"type": "integer",
"description": "Year value."
},
"month": {
"type": "integer",
"minimum": 1,
"maximum": 12,
"description": "Month value, when known."
},
"day": {
"type": "integer",
"minimum": 1,
"maximum": 31,
"description": "Day value, when known."
}
},
"required": [
"year"
],
"additionalProperties": false
},
"PersonDateRange": {
"type": "object",
"properties": {
"startDate": {
"allOf": [
{
"$ref": "#/components/schemas/PersonDate"
}
],
"description": "Start date, when known."
},
"endDate": {
"allOf": [
{
"$ref": "#/components/schemas/PersonDate"
}
],
"description": "End date, when known."
},
"isCurrent": {
"type": "boolean",
"description": "Whether the entry is current."
}
},
"additionalProperties": false
},
"PersonOrganization": {
"type": "object",
"properties": {
"display": {
"type": "string",
"description": "Display name."
},
"normalized": {
"type": "string",
"description": "Standardized name, when available."
},
"linkedinUrl": {
"type": "string",
"format": "uri",
"description": "The organization's LinkedIn page URL."
},
"websiteUrl": {
"type": "string",
"format": "uri",
"description": "The organization's website URL."
},
"logoUrl": {
"type": "string",
"format": "uri",
"description": "The organization's logo, hosted on the Context.dev CDN."
},
"employeeCount": {
"type": "integer",
"description": "Employee count reported on the LinkedIn page."
},
"employeeCountRange": {
"type": "string",
"description": "Employee count range reported on the LinkedIn page (e.g. \"51-200\")."
},
"followerCount": {
"type": "integer",
"description": "Follower count reported on the LinkedIn page."
},
"headquarters": {
"type": "string",
"description": "Headquarters location (e.g. \"San Francisco, California, United States\")."
},
"industries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"industry": {
"$ref": "#/components/schemas/Industry"
},
"subindustry": {
"$ref": "#/components/schemas/Subindustry"
}
},
"required": [
"industry",
"subindustry"
],
"additionalProperties": false
},
"description": "Context.dev industry classification - array of industry and subindustry pairs."
}
},
"required": [
"display"
],
"additionalProperties": false
},
"PersonProfile": {
"type": "object",
"properties": {
"fullName": {
"type": "string",
"description": "Person's full name."
},
"headline": {
"type": "string",
"description": "Short professional headline."
},
"location": {
"type": "string",
"description": "Person's listed location."
},
"summary": {
"type": "string",
"description": "Brief profile summary."
},
"profilePictureUrl": {
"type": "string",
"format": "uri",
"description": "Profile image URL."
}
},
"additionalProperties": false
},
"PersonEducation": {
"type": "object",
"properties": {
"institution": {
"allOf": [
{
"$ref": "#/components/schemas/PersonOrganization"
}
],
"description": "School or institution, including LinkedIn-derived organization data when available."
},
"qualification": {
"type": "string",
"description": "Degree, certificate, or credential."
},
"fieldOfStudy": {
"type": "string",
"description": "Area of study."
},
"description": {
"type": "string",
"description": "Additional education details."
},
"dates": {
"allOf": [
{
"$ref": "#/components/schemas/PersonDateRange"
}
],
"description": "Education dates."
}
},
"additionalProperties": false,
"required": [
"institution"
]
},
"PersonExperience": {
"type": "object",
"properties": {
"company": {
"allOf": [
{
"$ref": "#/components/schemas/PersonOrganization"
}
],
"description": "Company or organization, including LinkedIn-derived organization data when available."
},
"title": {
"type": "string",
"description": "Role or job title."
},
"description": {
"type": "string",
"description": "Role description."
},
"dates": {
"allOf": [
{
"$ref": "#/components/schemas/PersonDateRange"
}
],
"description": "Role dates."
}
},
"required": [
"company",
"title"
],
"additionalProperties": false
},
"PersonSkill": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Skill name."
},
"normalized": {
"type": "string",
"description": "Standardized skill name, when available."
},
"proficiency": {
"type": "string",
"description": "Skill proficiency, when available."
}
},
"required": [
"name"
],
"additionalProperties": false
},
"Person": {
"type": "object",
"properties": {
"profile": {
"allOf": [
{
"$ref": "#/components/schemas/PersonProfile"
}
],
"description": "Core profile details."
},
"education": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PersonEducation"
},
"description": "Education history."
},
"experience": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PersonExperience"
},
"description": "Work history."
},
"skills": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PersonSkill"
},
"description": "Listed skills."
}
},
"required": [
"profile",
"education",
"experience",
"skills"
],
"additionalProperties": false
},
"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')."
},
"zdr": {
"type": "string",
"enum": [
"enabled",
"disabled"
],
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR."
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
},
"required": [
"type",
"domain"
],
"additionalProperties": false,
"title": "By domain",
"description": "Retrieve brand data by domain. Cannot be combined with name, email, or ticker."
},
"RequestTags": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 50
},
"maxItems": 20,
"description": "Labels for filtering usage in the dashboard.",
"example": [
"production",
"team-alpha"
]
},
"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": {
"allOf": [
{
"$ref": "#/components/schemas/CountryGL"
},
{
"description": "Optional country code hint (GL parameter) to specify the country when looking up by company name."
}
]
},
"zdr": {
"type": "string",
"enum": [
"enabled",
"disabled"
],
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR."
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
},
"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')."
},
"zdr": {
"type": "string",
"enum": [
"enabled",
"disabled"
],
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR."
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
},
"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": {
"allOf": [
{
"$ref": "#/components/schemas/StockExchange"
},
{
"description": "Optional stock exchange for the ticker. Defaults to NASDAQ if not specified."
}
]
},
"zdr": {
"type": "string",
"enum": [
"enabled",
"disabled"
],
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR."
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
},
"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"
},
"zdr": {
"type": "string",
"enum": [
"enabled",
"disabled"
],
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR."
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
},
"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": {
"allOf": [
{
"$ref": "#/components/schemas/CountryGL"
},
{
"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."
},
"zdr": {
"type": "string",
"enum": [
"enabled",
"disabled"
],
"description": "`enabled` disables request logs and traces and omits request and response content from usage logs. Brand data and hosted assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR."
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
},
"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}(?:\\.png)?$"
},
"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
},
"PersonRetrieveRequest": {
"type": "object",
"properties": {
"identifiers": {
"type": "object",
"properties": {
"linkedinUrl": {
"type": "string",
"format": "uri",
"description": "LinkedIn profile URL, e.g. https://www.linkedin.com/in/yahia-bakour/."
}
},
"additionalProperties": false,
"description": "Known identifiers for the person. At least one identifier is required."
},
"timeoutOpts": {
"$ref": "#/components/schemas/PartialTimeout"
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
}
},
"required": [
"identifiers"
],
"additionalProperties": false
},
"PersonRetrieveResponse": {
"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",
"enum": [
"ok"
],
"description": "Response status."
},
"code": {
"type": "integer",
"enum": [
200
],
"description": "HTTP status code."
},
"person": {
"allOf": [
{
"$ref": "#/components/schemas/Person"
}
],
"description": "Retrieved person profile."
},
"metadata": {
"type": "object",
"properties": {
"identifiers": {
"type": "object",
"properties": {
"linkedinUrl": {
"type": "string",
"format": "uri",
"description": "LinkedIn profile URL."
}
},
"additionalProperties": false,
"description": "Identifiers returned for the person."
},
"personalWebsiteUrl": {
"type": "string",
"format": "uri",
"description": "Personal website URL, when found."
},
"urlsAnalyzed": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "URLs reviewed for this profile."
},
"sourcesAttempted": {
"type": "array",
"items": {
"type": "string",
"enum": [
"linkedin",
"cv",
"manual",
"github",
"other"
]
},
"description": "Source categories checked."
},
"sourcesSucceeded": {
"type": "array",
"items": {
"type": "string",
"enum": [
"linkedin",
"cv",
"manual",
"github",
"other"
]
},
"description": "Source categories with data."
}
},
"required": [
"identifiers",
"urlsAnalyzed",
"sourcesAttempted",
"sourcesSucceeded"
],
"additionalProperties": false,
"description": "Additional response details."
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"status",
"code",
"person",
"metadata",
"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"
},
"MonitorsSearchTarget": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"search"
],
"description": "Use `search` to watch the whole web for new results about a topic."
},
"query": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Web search query to run on every check. Supports operators such as `site:`, `-site:`, and quoted phrases.",
"example": "Acme Corp acquisition"
},
"instructions": {
"type": "string",
"minLength": 1,
"maxLength": 2000,
"description": "Plain-language description of which new results matter. Defaults to the query.",
"example": "Alert me when Acme announces an acquisition or a new product. Ignore opinion pieces."
}
},
"required": [
"type",
"query"
],
"additionalProperties": false,
"description": "Search the web on every run and report results not seen before, listed in the change’s `matched_urls` and `evidence`. Semantic detection reports only results describing a new development that matches `instructions`; exact detection reports every new result.",
"title": "Search 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."
}
]
},
{
"$ref": "#/components/schemas/MonitorsSearchTarget"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"page": "#/components/schemas/MonitorsPageTarget",
"sitemap": "#/components/schemas/MonitorsSitemapTarget",
"extract": "#/components/schemas/MonitorsExtractTarget",
"search": "#/components/schemas/MonitorsSearchTarget"
}
},
"description": "What to watch: a page, a sitemap, data extracted from a site, or web search results."
},
"MonitorsExactChangeDetection": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"exact"
],
"description": "Use `exact` to compare visible text, sitemap URLs, or search results."
}
},
"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. For search targets, this means every new result.",
"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 and search 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"
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs to apply to every run.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
},
"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."
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs to apply to every run. Send an empty list to remove them.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
},
"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."
},
"MonitorsSearchBaseline": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string"
},
"description": {
"type": "string",
"description": "Result snippet."
},
"published_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When the result was published, when known."
}
},
"required": [
"url",
"title",
"description",
"published_at"
],
"additionalProperties": false
},
"description": "Search results as last observed."
},
"captured_at": {
"type": "string",
"format": "date-time",
"description": "When this baseline was last captured or replaced."
}
},
"required": [
"results",
"captured_at"
],
"additionalProperties": false,
"title": "Search baseline",
"description": "Current baseline of a `search` monitor: the search results as last observed."
},
"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"
},
{
"$ref": "#/components/schemas/MonitorsSearchBaseline"
},
{
"type": "null"
}
],
"description": "Comparison baseline, included on Retrieve. Null until capture completes or after target changes."
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs applied to every run.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
},
"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/search) 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"
},
{
"$ref": "#/components/schemas/MonitorsSearchBaseline"
},
{
"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"
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs applied to every run.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"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"
},
{
"$ref": "#/components/schemas/MonitorsSearchBaseline"
},
{
"type": "null"
}
],
"description": "Comparison baseline, included on Retrieve. Null until capture completes or after target changes."
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs applied to every run.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"mode",
"id",
"name",
"target",
"change_detection",
"status",
"created_at",
"updated_at",
"request_id"
],
"additionalProperties": false
},
"MonitorsTargetType": {
"type": "string",
"enum": [
"page",
"sitemap",
"extract",
"search"
]
},
"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",
"description": "The monitored URL. For search targets, the first newly reported result."
},
"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."
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"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",
"description": "The monitored URL. For search targets, the first newly reported result."
},
"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"
]
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"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"
]
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"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"
]
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"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"
]
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"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
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"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
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"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."
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"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."
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"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": 100000,
"description": "Pages to scrape. Maximum 100000."
},
"options": {
"type": "object",
"properties": {
"includeLinks": {
"type": "boolean",
"default": true,
"description": "Include links in the Markdown (`html-conversion` only)."
},
"includeImages": {
"type": "boolean",
"default": false,
"description": "Include image references in the Markdown (`html-conversion` only)."
},
"shortenBase64Images": {
"type": "boolean",
"default": true,
"description": "Shorten inline base64 image data (`html-conversion` only)."
},
"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`."
},
"sourcePreference": {
"type": "array",
"items": {
"type": "string",
"enum": [
"html-conversion",
"markdown-direct"
]
},
"minItems": 1,
"default": [
"html-conversion",
"markdown-direct"
],
"uniqueItems": true,
"description": "Markdown sources in order of preference: `html-conversion` converts the page HTML, `markdown-direct` uses Markdown the site publishes."
},
"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."
},
"end": {
"type": "integer",
"minimum": 1,
"description": "Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must be >= start."
},
"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 handling. `start`/`end` limit parsing 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."
}
},
"additionalProperties": false,
"description": "Options for Markdown output."
}
},
"required": [
"format",
"urls"
],
"additionalProperties": false,
"description": "Scrape the listed pages as Markdown.",
"title": "Markdown",
"deprecated": true,
"x-stainless-skip": [
"php"
]
},
{
"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": 100000,
"description": "Pages to scrape. Maximum 100000."
},
"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."
},
"end": {
"type": "integer",
"minimum": 1,
"description": "Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must be >= start."
},
"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 handling. `start`/`end` limit parsing 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",
"deprecated": true,
"x-stainless-skip": [
"php"
]
},
{
"$ref": "#/components/schemas/BatchUnifiedScrapeData"
}
],
"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 100,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": 100000,
"default": 100,
"description": "Maximum pages to fetch. Unused reserved credits are refunded. Maximum 100000."
},
"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": "Regex pattern for URLs to include. The `start_url` itself is always included.",
"example": "^https://example\\.com/docs/"
},
"excludeRegex": {
"type": "string",
"maxLength": 256,
"description": "Regex pattern for URLs to exclude, even when they match `regex`. The `start_url` itself is always included.",
"example": "/tag/|/author/"
},
"languages": {
"anyOf": [
{
"type": "string",
"enum": [
"same_as_start_url"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"am",
"ar",
"az",
"be",
"bg",
"bn",
"ca",
"ceb",
"cs",
"cy",
"da",
"de",
"el",
"en",
"es",
"et",
"eu",
"fa",
"fi",
"fr",
"gu",
"ha",
"haw",
"he",
"hi",
"hr",
"hu",
"hy",
"id",
"is",
"it",
"ja",
"ka",
"kk",
"kn",
"ko",
"ku",
"ky",
"lo",
"lt",
"lv",
"mk",
"ml",
"mn",
"mr",
"ms",
"ne",
"nl",
"no",
"or",
"pa",
"pl",
"ps",
"pt",
"ro",
"ru",
"sk",
"sl",
"so",
"sq",
"sr",
"sv",
"sw",
"ta",
"te",
"th",
"tl",
"tr",
"uk",
"ur",
"uz",
"vi",
"yo",
"zh"
]
},
"minItems": 1
}
],
"description": "Only follow pages in these languages, or `same_as_start_url`; all languages when omitted.",
"example": "same_as_start_url"
}
},
"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": 100000,
"default": 100,
"description": "Maximum pages to fetch. Unused reserved credits are refunded. Maximum 100000."
},
"regex": {
"type": "string",
"maxLength": 256,
"description": "Regex pattern; only sitemap URLs matching it are scraped.",
"example": "^https://example\\.com/docs/"
},
"excludeRegex": {
"type": "string",
"maxLength": 256,
"description": "Regex pattern; sitemap URLs matching it are not scraped, even when they match `regex`.",
"example": "/tag/|/author/"
}
},
"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 (`html-conversion` only)."
},
"includeImages": {
"type": "boolean",
"default": false,
"description": "Include image references in the Markdown (`html-conversion` only)."
},
"shortenBase64Images": {
"type": "boolean",
"default": true,
"description": "Shorten inline base64 image data (`html-conversion` only)."
},
"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`."
},
"sourcePreference": {
"type": "array",
"items": {
"type": "string",
"enum": [
"html-conversion",
"markdown-direct"
]
},
"minItems": 1,
"default": [
"html-conversion",
"markdown-direct"
],
"uniqueItems": true,
"description": "Markdown sources in order of preference: `html-conversion` converts the page HTML, `markdown-direct` uses Markdown the site publishes."
},
"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."
},
"end": {
"type": "integer",
"minimum": 1,
"description": "Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must be >= start."
},
"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 handling. `start`/`end` limit parsing 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."
}
},
"additionalProperties": false,
"description": "Options for Markdown output."
}
},
"required": [
"format",
"source"
],
"additionalProperties": false,
"title": "Markdown",
"description": "Crawl pages and return Markdown.",
"deprecated": true,
"x-stainless-skip": [
"php"
]
},
{
"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": 100000,
"default": 100,
"description": "Maximum pages to fetch. Unused reserved credits are refunded. Maximum 100000."
},
"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": "Regex pattern for URLs to include. The `start_url` itself is always included.",
"example": "^https://example\\.com/docs/"
},
"excludeRegex": {
"type": "string",
"maxLength": 256,
"description": "Regex pattern for URLs to exclude, even when they match `regex`. The `start_url` itself is always included.",
"example": "/tag/|/author/"
},
"languages": {
"anyOf": [
{
"type": "string",
"enum": [
"same_as_start_url"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"am",
"ar",
"az",
"be",
"bg",
"bn",
"ca",
"ceb",
"cs",
"cy",
"da",
"de",
"el",
"en",
"es",
"et",
"eu",
"fa",
"fi",
"fr",
"gu",
"ha",
"haw",
"he",
"hi",
"hr",
"hu",
"hy",
"id",
"is",
"it",
"ja",
"ka",
"kk",
"kn",
"ko",
"ku",
"ky",
"lo",
"lt",
"lv",
"mk",
"ml",
"mn",
"mr",
"ms",
"ne",
"nl",
"no",
"or",
"pa",
"pl",
"ps",
"pt",
"ro",
"ru",
"sk",
"sl",
"so",
"sq",
"sr",
"sv",
"sw",
"ta",
"te",
"th",
"tl",
"tr",
"uk",
"ur",
"uz",
"vi",
"yo",
"zh"
]
},
"minItems": 1
}
],
"description": "Only follow pages in these languages, or `same_as_start_url`; all languages when omitted.",
"example": "same_as_start_url"
}
},
"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": 100000,
"default": 100,
"description": "Maximum pages to fetch. Unused reserved credits are refunded. Maximum 100000."
},
"regex": {
"type": "string",
"maxLength": 256,
"description": "Regex pattern; only sitemap URLs matching it are scraped.",
"example": "^https://example\\.com/docs/"
},
"excludeRegex": {
"type": "string",
"maxLength": 256,
"description": "Regex pattern; sitemap URLs matching it are not scraped, even when they match `regex`.",
"example": "/tag/|/author/"
}
},
"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."
},
"end": {
"type": "integer",
"minimum": 1,
"description": "Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must be >= start."
},
"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 handling. `start`/`end` limit parsing 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.",
"deprecated": true,
"x-stainless-skip": [
"php"
]
},
{
"$ref": "#/components/schemas/BatchUnifiedCrawlData"
}
],
"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",
"format": "uri",
"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"
]
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs to apply to every page. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
},
"required": [
"input"
],
"additionalProperties": false,
"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": "Regex pattern URLs had to match to be crawled. Null when the crawl set none."
},
"exclude_url_pattern": {
"type": [
"string",
"null"
],
"example": "/tag/|/author/",
"description": "Regex pattern URLs must not match to be crawled. Null when the crawl set none."
},
"languages": {
"anyOf": [
{
"type": "string",
"enum": [
"same_as_start_url"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"am",
"ar",
"az",
"be",
"bg",
"bn",
"ca",
"ceb",
"cs",
"cy",
"da",
"de",
"el",
"en",
"es",
"et",
"eu",
"fa",
"fi",
"fr",
"gu",
"ha",
"haw",
"he",
"hi",
"hr",
"hu",
"hy",
"id",
"is",
"it",
"ja",
"ka",
"kk",
"kn",
"ko",
"ku",
"ky",
"lo",
"lt",
"lv",
"mk",
"ml",
"mn",
"mr",
"ms",
"ne",
"nl",
"no",
"or",
"pa",
"pl",
"ps",
"pt",
"ro",
"ru",
"sk",
"sl",
"so",
"sq",
"sr",
"sv",
"sw",
"ta",
"te",
"th",
"tl",
"tr",
"uk",
"ur",
"uz",
"vi",
"yo",
"zh"
]
},
"minItems": 1
},
{
"type": "null"
}
],
"example": "same_as_start_url",
"description": "Languages whose pages were followed; null when all languages were."
}
},
"required": [
"source",
"max_pages",
"max_depth",
"follow_subdomains",
"url_pattern",
"exclude_url_pattern",
"languages"
],
"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`."
},
"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."
},
"formats": {
"$ref": "#/components/schemas/ScrapeFormats",
"example": {
"html": true,
"markdown": true
},
"description": "Outputs requested for each page. Matches input.data.formats on submission."
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs applied to every page.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
},
"required": [
"id",
"status",
"mode",
"tags",
"crawl",
"input",
"progress",
"credits",
"timing",
"page_errors",
"failure",
"results",
"formats"
],
"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."
},
"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."
},
"formats": {
"$ref": "#/components/schemas/ScrapeFormats",
"example": {
"html": true,
"markdown": true
},
"description": "Outputs requested for each page. Matches input.data.formats on submission."
}
},
"required": [
"id",
"status",
"mode",
"tags",
"crawl",
"input",
"progress",
"credits",
"timing",
"page_errors",
"formats"
],
"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."
},
"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."
},
"formats": {
"$ref": "#/components/schemas/ScrapeFormats",
"example": {
"html": true,
"markdown": true
},
"description": "Outputs requested for each page. Matches input.data.formats on submission."
}
},
"required": [
"id",
"status",
"mode",
"tags",
"crawl",
"input",
"credits",
"created_at",
"invalid_urls",
"cache_metadata",
"formats"
],
"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": {
"title": "Batch result record",
"description": "One scrape outcome. result uses the single Scrape Anything response schema; itemId and meta identify your input.",
"discriminator": {
"propertyName": "status"
},
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"title": "Scraped page",
"description": "At least one requested output succeeded. Check result.isPartial and each output success for incomplete results.",
"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"
]
},
"result": {
"$ref": "#/components/schemas/BatchScrapeResponse"
},
"credits_used": {
"type": "integer",
"minimum": 0,
"description": "Credits charged for this page, including OCR. Cached outputs use the same pricing as POST /web/scrape."
},
"ocr_pages": {
"type": "integer",
"minimum": 0,
"description": "PDF pages recovered by OCR. Omitted when OCR did not run."
}
},
"required": [
"url",
"status",
"result",
"credits_used"
]
},
{
"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."
},
"result": {
"$ref": "#/components/schemas/BatchScrapeResponse",
"description": "Per-format failures when scraping returned a structured response. Omitted for errors that prevent scraping."
},
"credits_used": {
"type": "integer",
"minimum": 0,
"description": "Credits charged for this page, including OCR. Cached outputs use the same pricing as POST /web/scrape."
},
"ocr_pages": {
"type": "integer",
"minimum": 0,
"description": "PDF pages recovered by OCR. Omitted when OCR did not run."
}
},
"required": [
"url",
"status",
"error_code",
"message"
],
"title": "Failed page",
"description": "A page the batch could not fetch."
}
]
},
"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"
}
},
"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."
},
"ScrapeRequest": {
"type": "object",
"properties": {
"url": {
"type": "string",
"minLength": 1,
"format": "uri",
"pattern": "^[Hh][Tt][Tt][Pp][Ss]?://",
"description": "Public HTTP or HTTPS URL to scrape."
},
"formats": {
"$ref": "#/components/schemas/ScrapeFormats"
},
"sharedParams": {
"$ref": "#/components/schemas/ScrapeSharedParams"
},
"markdownParams": {
"$ref": "#/components/schemas/ScrapeMarkdownParams"
},
"screenshotParams": {
"$ref": "#/components/schemas/ScrapeScreenshotParams"
},
"imageParams": {
"$ref": "#/components/schemas/ScrapeImageParams"
},
"parseParams": {
"$ref": "#/components/schemas/ScrapeParseParams"
},
"productParams": {
"$ref": "#/components/schemas/ScrapeProductParams"
},
"highlightsParams": {
"$ref": "#/components/schemas/ScrapeHighlightsParams"
},
"jsonParams": {
"$ref": "#/components/schemas/ScrapeJsonParams"
},
"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"
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
},
"required": [
"url",
"formats"
],
"additionalProperties": false,
"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": [
"productParams"
]
},
"then": {
"properties": {
"formats": {
"required": [
"product"
],
"properties": {
"product": {
"const": true
}
}
}
}
}
},
{
"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"
]
}
}
]
},
"ScrapeFormats": {
"type": "object",
"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 custom rules or a prebuilt parser, returned as `parsed`."
},
"product": {
"type": "boolean",
"default": false,
"description": "Product details such as name, price, and availability."
},
"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."
}
},
"additionalProperties": false,
"description": "Outputs to return. Set at least one to `true`.",
"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": [
"product"
],
"properties": {
"product": {
"const": true
}
}
}
},
{
"not": {
"required": [
"highlights"
],
"properties": {
"highlights": {
"const": true
}
}
}
},
{
"not": {
"required": [
"json"
],
"properties": {
"json": {
"const": true
}
}
}
}
]
}
},
"ScrapeSharedParams": {
"type": "object",
"properties": {
"profile": {
"$ref": "#/components/schemas/ScrapeProfile"
},
"country": {
"type": "string",
"description": "Proxy country as a two-letter code, such as `US`. Case-insensitive.",
"pattern": "^[A-Za-z]{2}$",
"examples": [
"US"
]
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 8192,
"pattern": "^[^\\r\\n]*$"
},
"examples": [
{
"Accept-Language": "en-US"
}
],
"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]|[Tt][Rr][Aa][Nn][Ss][Ff][Ee][Rr]-[Ee][Nn][Cc][Oo][Dd][Ii][Nn][Gg]|[Uu][Pp][Gg][Rr][Aa][Dd][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]|[Ee][Xx][Pp][Ee][Cc][Tt])$"
}
},
"description": "HTTP headers to send to the target site. Requests with headers skip the cache."
},
"viewport": {
"type": "object",
"properties": {
"width": {
"type": "integer",
"minimum": 240,
"maximum": 7680,
"default": 1440,
"description": "Browser viewport width in pixels."
},
"height": {
"type": "integer",
"minimum": 240,
"maximum": 4320,
"default": 900,
"description": "Browser viewport height in pixels."
}
},
"additionalProperties": false,
"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",
"items": {
"$ref": "#/components/schemas/ScrapeAction"
},
"minItems": 1,
"maxItems": 5,
"description": "Browser steps run in order before capture. Requires a paid plan. Skips the cache."
},
"waitFor": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 30000
},
{
"type": "string",
"minLength": 1,
"maxLength": 2048,
"pattern": "\\S"
}
],
"description": "Milliseconds, or a CSS selector to wait for, after actions. Defaults to 500 (2000 with frames or XML).",
"examples": [
500,
"#content"
]
},
"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",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"pattern": "\\S"
},
"minItems": 1,
"maxItems": 50,
"uniqueItems": true,
"description": "Keep only elements matching these CSS selectors."
},
"excludeSelectors": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"pattern": "\\S"
},
"minItems": 1,
"maxItems": 50,
"uniqueItems": true,
"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",
"properties": {
"pdf": {
"$ref": "#/components/schemas/ScrapePdfOptions"
}
},
"additionalProperties": false,
"description": "Document parsing options."
}
},
"additionalProperties": false,
"description": "Browser and content settings shared by all outputs."
},
"ScrapeProfile": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"existing"
],
"const": "existing",
"description": "Reuse a saved browser profile."
},
"profileId": {
"type": "string",
"pattern": "^prof_[a-f0-9]{32}$",
"description": "The ID returned in profile.id by an earlier scrape."
}
},
"required": [
"type",
"profileId"
],
"additionalProperties": false,
"x-stainless-variantName": "Existing"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"new"
],
"const": "new",
"description": "Sign in and create a browser profile."
},
"identifier": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"description": "Username or email for the target website."
},
"password": {
"type": "string",
"minLength": 1,
"maxLength": 4096,
"description": "Password used to sign in. It is never stored in the profile.",
"writeOnly": true
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Optional label shown when listing profiles with `GET /org/browser/profiles`."
}
},
"required": [
"type",
"identifier",
"password"
],
"additionalProperties": false,
"x-stainless-variantName": "New"
}
],
"discriminator": {
"propertyName": "type"
},
"description": "Create or reuse an authenticated browser profile. Requires a paid plan and an HTTPS target. Profiles persist session state, bypass shared caches, and cannot be combined with ZDR, custom headers, raw bytes, or prebuilt parsers."
},
"ScrapeAction": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"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.",
"examples": [
"Click the product details tab"
]
}
},
"required": [
"type",
"action"
],
"additionalProperties": false,
"x-stainless-variantName": "Perform"
},
{
"type": "object",
"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": {
"anyOf": [
{
"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",
"minLength": 1,
"maxLength": 2000,
"pattern": "\\S",
"description": "Scroll this container. Omit to scroll the page."
},
"maxScrolls": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 1,
"description": "Maximum number of scroll steps for this action."
}
},
"required": [
"type"
],
"additionalProperties": false,
"x-stainless-variantName": "Scroll"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"wait"
],
"description": "Use `wait` to pause for a fixed duration."
},
"milliseconds": {
"type": "integer",
"minimum": 0,
"maximum": 30000,
"description": "Time to pause in milliseconds before the next action."
}
},
"required": [
"type",
"milliseconds"
],
"additionalProperties": false,
"x-stainless-variantName": "Wait"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"waitFor"
],
"description": "Use `waitFor` to wait for a matching element."
},
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"pattern": "\\S",
"description": "CSS selector to wait for before continuing."
}
},
"required": [
"type",
"selector"
],
"additionalProperties": false,
"x-stainless-variantName": "WaitFor"
}
],
"discriminator": {
"propertyName": "type"
},
"title": "Browser action"
},
"ScrapePdfOptions": {
"type": "object",
"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."
},
"includeNumberedPages": {
"type": "boolean",
"default": false,
"description": "Start each page in the Markdown with a `` line using its original 1-based page number; these responses are never served from cache."
}
},
"additionalProperties": false,
"description": "PDF page range and OCR."
},
"ScrapeMarkdownParams": {
"type": "object",
"properties": {
"includeLinks": {
"type": "boolean",
"default": true,
"description": "Keep link URLs in the Markdown (`html-conversion` only)."
},
"includeImages": {
"type": "boolean",
"default": false,
"description": "Include images in the Markdown (`html-conversion` only)."
},
"inlineImages": {
"type": "string",
"enum": [
"placeholder",
"preserve"
],
"default": "placeholder",
"description": "How base64 images appear when `includeImages` is set (`html-conversion` only)."
},
"sourcePreference": {
"type": "array",
"items": {
"type": "string",
"enum": [
"html-conversion",
"markdown-direct"
]
},
"minItems": 1,
"default": [
"html-conversion",
"markdown-direct"
],
"uniqueItems": true,
"description": "Markdown sources in order of preference: `html-conversion` converts the page HTML, `markdown-direct` uses Markdown the site publishes."
}
},
"additionalProperties": false,
"description": "Markdown options. Requires `formats.markdown`."
},
"ScrapeScreenshotParams": {
"type": "object",
"properties": {
"area": {
"anyOf": [
{
"type": "string",
"enum": [
"viewport",
"fullPage"
],
"x-stainless-variantName": "Page"
},
{
"type": "object",
"properties": {
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"pattern": "\\S",
"description": "CSS selector matching exactly one visible element."
}
},
"required": [
"selector"
],
"additionalProperties": false,
"x-stainless-variantName": "Element"
},
{
"type": "object",
"properties": {
"x": {
"type": "integer",
"minimum": 0,
"maximum": 100000,
"description": "Left edge of the capture, in pixels from the document origin."
},
"y": {
"type": "integer",
"minimum": 0,
"maximum": 100000,
"description": "Top edge of the capture, in pixels from the document origin."
},
"width": {
"type": "integer",
"minimum": 1,
"maximum": 7680,
"description": "Width of the capture in pixels."
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 100000,
"description": "Height of the capture in pixels."
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false,
"x-stainless-variantName": "Rectangle",
"description": "Pixels from the document origin."
}
],
"default": "viewport",
"description": "What to capture: `viewport`, `fullPage`, one element, or a rectangle. Max 40 megapixels."
},
"format": {
"type": "string",
"enum": [
"png",
"jpeg",
"webp"
],
"default": "png",
"description": "Image format for the screenshot."
}
},
"additionalProperties": false,
"description": "Screenshot options. Requires formats.screenshot: true."
},
"ScrapeImageParams": {
"type": "object",
"properties": {
"enrich": {
"type": "array",
"items": {
"type": "string",
"enum": [
"dimensions",
"classification",
"file"
]
},
"maxItems": 3,
"uniqueItems": true,
"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."
}
},
"additionalProperties": false,
"description": "Image options. Requires formats.images: true."
},
"ScrapeParseParams": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"custom"
],
"default": "custom",
"const": "custom",
"description": "Extract fields using custom CSS rules. This is the default when type is omitted."
},
"rules": {
"$ref": "#/components/schemas/ScrapeParseRules"
}
},
"required": [
"rules"
],
"additionalProperties": false,
"x-stainless-variantName": "CustomParser"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"prebuilt"
],
"const": "prebuilt",
"description": "Use a prebuilt parser instead of custom rules."
},
"parser": {
"type": "string",
"enum": [
"google-maps",
"google-maps-reviews",
"google-play",
"google-play-reviews",
"app-store",
"app-store-reviews",
"g2-reviews",
"instagram-profile",
"instagram-post",
"instagram-feed",
"tiktok-profile",
"tiktok-video",
"tiktok-feed",
"tiktok-comments",
"tiktok-followers",
"tiktok-following",
"tiktok-user-search",
"reddit-post",
"reddit-search",
"reddit-subreddit",
"reddit-user",
"yelp-search",
"yelp-reviews",
"emails",
"phone-numbers",
"links"
],
"description": "google-maps parses Google Maps business data into data.results. Accepts Maps place, search, and internal data URLs. Uses a US exit and English labels regardless of hl or Accept-Language. google-maps-reviews returns the reviews of a place in data.reviews, in the same shape as the Serper reviews API (rating, date, isoDate, snippet, translatedSnippet, likes, user, media, response, link, id), plus language, guided ratings in details, and user.isLocalGuide; data also carries the place featureId, cid, and sort. sort and limit pick the order and count, and oldest is exact. It accepts Maps place, search, and ?cid= URLs, plus search.google.com/local/reviews URLs, so the google_maps_url and google_reviews_url fields of google-maps results work as input. An unknown place returns no reviews. google-play parses a Play Store app into data: details, developer contact, ratings, price, permissions, and data safety. google-play-reviews returns the 200 newest reviews of the app, with developer replies, in data.reviews. Both Play parsers accept app details URLs (play.google.com/store/apps/details?id=…); hl and gl set the language and storefront, defaulting to en and us. app-store parses an App Store app into data: details, developer, ratings, price, version, and screenshots. app-store-reviews returns up to the 500 newest reviews in data.reviews. Both App Store parsers accept app URLs (apps.apple.com/us/app/…/id…); the country in the path sets the storefront, defaulting to us. g2-reviews returns the 25 most recently published reviews of a G2 product in data.reviews (rating, title, likes, dislikes, problems_solved, reviewer role, company size, and industry), plus data.product. It accepts G2 product URLs (g2.com/products/…), follows renamed products, and keeps star-rating filters from the URL (filters[nps_score][]=1 to 5); other filters, sort orders, and pages are ignored. instagram-profile parses a public profile (instagram.com/{username}) into data: bio, links, follower and post counts, category, business address, similar_accounts, and latest_posts (up to the 12 posts at the top of the profile, newest first). Instagram lists pinned posts there ahead of newer ones, so posts with is_pinned true can be older; when Instagram shows only a rounded post count (32K), post_count is that rounded number and is_post_count_rounded is true. instagram-post parses a post or reel (/p/…, /reel/…) into data: caption, hashtags, mentions, like, comment, and view counts (like_count and view_count are null when the owner hides them), media URLs, tagged users, collaborators, location, and the top ~14 comments in data.comments. instagram-feed returns the top posts for a hashtag or keyword (/explore/tags/…, /popular/…) or the recent posts at a location (/explore/locations/{id}/…) in data.posts; keyword posts carry only the shortcode, owner, thumbnail, and views, plus the caption when Instagram shows it. All three Instagram parsers read public data without logging in, so private accounts return no posts and follower lists are unavailable. tiktok-profile parses a public profile (tiktok.com/@{username}) into data: nickname, bio, bio link, follower, following, like, and video counts, verified, private, and business flags, and business category; it does not list videos. tiktok-video parses a video or photo post (/@{username}/video/{id} or /@{username}/photo/{id}) into data: caption, hashtags, mentions, author, view, like, comment, share, save, and repost counts, duration, thumbnail, a video_url that downloads without cookies, image_urls for photo posts, music, location, and ad, paid-partnership, and AI-generated flags. tiktok-feed returns videos in the tiktok-video shape as data.videos: the latest 15 from a profile URL, the top 30 from a hashtag URL (/tag/{name}), or the top 12 from a search URL (/search?q={query}). tiktok-comments returns the first 20 comments of a video or photo post as data.comments: text, posted_at, like and reply counts, whether the author liked it, and the commenter. tiktok-followers and tiktok-following return up to 30 accounts of a profile as data.users, in the tiktok-profile shape. tiktok-user-search returns the top 10 accounts for a user search URL (/search/user?q={query}) as data.users: id, username, nickname, biography, avatar_url, sec_uid, follower_count, like_count, and is_verified. The TikTok parsers accept tiktok.com, www.tiktok.com, and m.tiktok.com URLs but not short links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). reddit-post parses a post (reddit.com/r/{subreddit}/comments/{id}, reddit.com/comments/{id}, or redd.it/{id}) into data.post: title, body as Markdown, type (text, link, image, gallery, or video), link_url, subreddit, author, flairs, score, upvote_ratio, comment and crosspost counts, NSFW, spoiler, locked, stickied, and archived flags, images (every gallery image in order), and video (an MP4 url plus an hls_url that carries the audio). data.comments holds the comment tree, each comment with id, author, body as Markdown, score, posted_at, depth, parent_id, url, is_submitter, is_deleted, and its replies; limit caps the total number of comments (default 100), filled shallowest first so whole conversations are kept, and data.has_more_comments says whether the thread has more. The sort query of the URL (best, top, new, controversial, old, qa) orders the comments. reddit-search returns search results for a search URL (reddit.com/search?q={query}, or reddit.com/r/{subreddit}/search?q={query} to search one subreddit). With type=link or no type it returns posts in the reddit-post shape as data.posts, ordered by the sort (relevance, hot, top, new, comments) and limited to the t time range (hour, day, week, month, year, all) of the URL; type=sr returns communities as data.communities (name, title, description, sidebar, subscriber_count, created_at, type, NSFW and quarantine flags, language, category, icon and banner URLs, and allowed post types); type=user returns accounts as data.users (username, display_name, bio, created_at, post and comment karma, avatar and banner URLs, and verified, employee, moderator, premium, and NSFW flags). limit caps the number of results (default 100), in the order Reddit returns them, and data.has_more says whether Reddit has more. reddit-subreddit reads a subreddit URL (reddit.com/r/{subreddit}, optionally followed by /hot, /new, /top, /rising, or /controversial, with t setting the time range of top and controversial, default day) into data.subreddit in the community shape of reddit-search, data.rules (name, description, applies_to, violation_reason, created_at), and data.posts in the reddit-post shape, ordered like the tab (default hot) and with stickied posts flagged; r/all and r/popular return posts with a null subreddit and rules. limit caps the posts (default 100) and data.has_more says whether Reddit has more. Private and quarantined subreddits return WEBSITE_ACCESS_ERROR. reddit-user reads a profile URL (reddit.com/user/{username} or reddit.com/u/{username}, optionally followed by /overview, /submitted, or /comments, with sort set to new, hot, top, or controversial and t setting the time range of top and controversial, default all) into data.user (id, username, display_name, bio, created_at, total, post, comment, awardee, and awarder karma, avatar and banner URLs, and verified, suspended, employee, moderator, premium, and NSFW flags), data.trophies (name, description, icon_url, granted_at, url), data.moderated_communities (name, title, url, subscriber_count, icon_url, is_nsfw), data.posts in the reddit-post shape, and data.comments, each with id, author, body as Markdown, score, posted_at, edited_at, url, subreddit, parent_id (null for a top-level comment), is_submitter, is_stickied, distinguished, award_count, and the post it was left on (id, title, url, author, is_nsfw). The overview tab returns both posts and comments; submitted returns null comments and comments returns null posts. limit caps the posts and comments together (default 100) and data.has_more says whether Reddit has more. Users who hide their activity return empty lists, and suspended accounts return their profile with null posts and comments. yelp-search accepts Yelp search URLs with find_desc and find_loc, reads start as the result offset, and returns up to 20 ranked organic businesses in data.businesses with total and pagination. yelp-reviews accepts a Yelp business URL (yelp.com/biz/{alias}), uses optional start for the offset, and always sorts newest first; unsupported sort and review filters are rejected, while tracking params are ignored. It returns up to 20 latest public reviews in data.reviews with business details and pagination.next_offset. Each review has rating, full text, updated_at, and author; owner replies and photos are not included. emails accepts any page and returns its email addresses as data.emails ([{ email }]), read from mailto links, Cloudflare-protected addresses, and visible text. phone-numbers accepts any page and returns its valid phone numbers in E.164 as data.phone_numbers ([{ phone }]), read from tel links and visible text; numbers without a country code are read for the country of the site TLD, defaulting to US. links accepts any page and returns its unique http(s) links as data.links ([{ url, text }]), with absolute URLs; text falls back to aria-label or image alt and is null when a link has none. The emails parser reads the rendered page and respects content filters; the other prebuilt parsers read their data independently of DOM filters."
},
"sort": {
"type": "string",
"enum": [
"newest",
"oldest",
"relevant",
"highest",
"lowest"
],
"default": "newest",
"description": "google-maps-reviews only. Order of data.reviews. newest, relevant, highest, and lowest follow Google; oldest returns the earliest reviews first, which Google itself does not offer."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 100,
"description": "google-maps-reviews and reddit parsers only. Maximum number of reviews (google-maps-reviews, default 100), comments (reddit-post, default 100), or results (reddit-search, reddit-subreddit, and reddit-user, default 100) to return; maximum 1000."
}
},
"required": [
"type",
"parser"
],
"additionalProperties": false,
"x-stainless-variantName": "PrebuiltParser"
}
],
"description": "Requires `formats.parse: true`; required when it is set."
},
"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
}
]
},
"description": "Field names mapped to CSS selectors (`h1`, `a@href`) or rule objects. Max 100 fields, 5 levels.",
"minProperties": 1,
"examples": [
{
"title": "h1",
"links": {
"selector": "a",
"type": "list",
"output": "@href"
}
}
]
},
"HtmlExtractionRules": {
"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": {
"anyOf": [
{
"type": "string",
"enum": [
"text",
"html"
]
},
{
"type": "string",
"pattern": "^@.*$"
},
{
"$ref": "#/components/schemas/HtmlExtractionRules"
}
],
"description": "Return text, HTML, an attribute such as `@href`, or nested field rules. Defaults to text."
}
},
"required": [
"selector"
],
"additionalProperties": false
}
]
}
},
"ScrapeProductParams": {
"type": "object",
"properties": {
"dedupeImages": {
"type": "boolean",
"default": false,
"description": "Drop visually duplicate product images, keeping the largest copy."
},
"useAIFallback": {
"type": "boolean",
"deprecated": true,
"description": "Ignored. The AI fallback runs automatically."
}
},
"additionalProperties": false,
"description": "Product options. Requires formats.product: true."
},
"ScrapeHighlightsParams": {
"type": "object",
"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"
],
"additionalProperties": false,
"description": "Requires `formats.highlights: true`; required when it is set."
},
"ScrapeJsonParams": {
"type": "object",
"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"
],
"additionalProperties": false,
"description": "Requires `formats.json: true`; required when it is set."
},
"NewsSearchByNaturalLanguage": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"natural_language"
],
"description": "Use `natural_language` to search all news with a plain-language query."
},
"query": {
"type": "string",
"minLength": 2,
"maxLength": 1000,
"description": "What to search for, in plain language, such as \"chip export restrictions to China\"."
}
},
"required": [
"type",
"query"
],
"additionalProperties": false,
"description": "Search all news with a plain-language query. Returns up to 100 matches, ordered by relevance.",
"title": "By Natural Language"
},
"NewsSearchByEntity": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"entity"
],
"description": "Use `entity` to find news about a specific company."
},
"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": "Find news about a specific company.",
"title": "By Entity"
},
"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"
},
"AnswersResponse": {
"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": "URLs of the pages and company/profile records read for the answer, followed by URLs cited in json_content."
},
"key_metadata": {
"$ref": "#/components/schemas/KeyMetadata"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
}
},
"required": [
"json_content",
"sources",
"request_id"
]
},
"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."
},
"policies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access policy IDs to apply. A URL must pass every policy.",
"example": [
"pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e"
]
}
},
"required": [
"task"
],
"additionalProperties": false
},
"CompanySearchFilters": {
"type": "object",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"description": "Headquarters countries as two-letter codes, such as US or GB."
},
"employees_min": {
"type": "integer",
"minimum": 0,
"description": "Minimum headcount; includes overlapping employee ranges."
},
"employees_max": {
"type": "integer",
"minimum": 0,
"description": "Maximum headcount; includes overlapping employee ranges."
}
},
"additionalProperties": false,
"description": "Additional constraints every result must match."
},
"PeopleSearchMatch": {
"type": "object",
"properties": {
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "How well the person matches the query, from 0 to 1."
}
},
"required": [
"confidence"
],
"description": "How well the person matches the query. Only returned in `ultra` mode."
},
"PeopleSearchFilters": {
"type": "object",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"description": "Countries people live in as two-letter codes, such as US or GB."
},
"years_of_experience_min": {
"type": "integer",
"minimum": 0,
"description": "Minimum years of professional experience."
},
"years_of_experience_max": {
"type": "integer",
"minimum": 0,
"description": "Maximum years of professional experience."
}
},
"additionalProperties": false,
"description": "Additional constraints every result must match."
},
"BatchUnifiedScrapeData": {
"type": "object",
"properties": {
"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": 100000,
"description": "Pages to scrape. Maximum 100000."
},
"formats": {
"$ref": "#/components/schemas/ScrapeFormats"
},
"sharedParams": {
"$ref": "#/components/schemas/ScrapeSharedParams"
},
"markdownParams": {
"$ref": "#/components/schemas/ScrapeMarkdownParams"
},
"screenshotParams": {
"$ref": "#/components/schemas/ScrapeScreenshotParams"
},
"imageParams": {
"$ref": "#/components/schemas/ScrapeImageParams"
},
"parseParams": {
"$ref": "#/components/schemas/ScrapeParseParams"
},
"productParams": {
"$ref": "#/components/schemas/ScrapeProductParams"
},
"highlightsParams": {
"$ref": "#/components/schemas/ScrapeHighlightsParams"
},
"jsonParams": {
"$ref": "#/components/schemas/ScrapeJsonParams"
},
"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": [
"disabled"
],
"default": "disabled",
"description": "Batches persist their results. Only disabled is supported; enabled returns ZDR_NOT_SUPPORTED."
},
"timeoutOpts": {
"$ref": "#/components/schemas/ScrapeTimeout",
"description": "Deadline for each page, using the same behavior and defaults as POST /web/scrape."
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
}
},
"required": [
"urls",
"formats"
],
"additionalProperties": false,
"title": "Scrape Anything",
"description": "Use the same formats and parameters as POST /web/scrape, replacing url with urls. Options apply to every page."
},
"BatchUnifiedCrawlData": {
"type": "object",
"properties": {
"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": 100000,
"default": 100,
"description": "Maximum pages to fetch. Unused reserved credits are refunded. Maximum 100000."
},
"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": "Regex pattern for URLs to include. The `start_url` itself is always included.",
"example": "^https://example\\.com/docs/"
},
"excludeRegex": {
"type": "string",
"maxLength": 256,
"description": "Regex pattern for URLs to exclude, even when they match `regex`. The `start_url` itself is always included.",
"example": "/tag/|/author/"
},
"languages": {
"anyOf": [
{
"type": "string",
"enum": [
"same_as_start_url"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"am",
"ar",
"az",
"be",
"bg",
"bn",
"ca",
"ceb",
"cs",
"cy",
"da",
"de",
"el",
"en",
"es",
"et",
"eu",
"fa",
"fi",
"fr",
"gu",
"ha",
"haw",
"he",
"hi",
"hr",
"hu",
"hy",
"id",
"is",
"it",
"ja",
"ka",
"kk",
"kn",
"ko",
"ku",
"ky",
"lo",
"lt",
"lv",
"mk",
"ml",
"mn",
"mr",
"ms",
"ne",
"nl",
"no",
"or",
"pa",
"pl",
"ps",
"pt",
"ro",
"ru",
"sk",
"sl",
"so",
"sq",
"sr",
"sv",
"sw",
"ta",
"te",
"th",
"tl",
"tr",
"uk",
"ur",
"uz",
"vi",
"yo",
"zh"
]
},
"minItems": 1
}
],
"description": "Only follow pages in these languages, or `same_as_start_url`; all languages when omitted.",
"example": "same_as_start_url"
}
},
"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": 100000,
"default": 100,
"description": "Maximum pages to fetch. Unused reserved credits are refunded. Maximum 100000."
},
"regex": {
"type": "string",
"maxLength": 256,
"description": "Regex pattern; only sitemap URLs matching it are scraped.",
"example": "^https://example\\.com/docs/"
},
"excludeRegex": {
"type": "string",
"maxLength": 256,
"description": "Regex pattern; sitemap URLs matching it are not scraped, even when they match `regex`.",
"example": "/tag/|/author/"
}
},
"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."
},
"formats": {
"$ref": "#/components/schemas/ScrapeFormats"
},
"sharedParams": {
"$ref": "#/components/schemas/ScrapeSharedParams"
},
"markdownParams": {
"$ref": "#/components/schemas/ScrapeMarkdownParams"
},
"screenshotParams": {
"$ref": "#/components/schemas/ScrapeScreenshotParams"
},
"imageParams": {
"$ref": "#/components/schemas/ScrapeImageParams"
},
"parseParams": {
"$ref": "#/components/schemas/ScrapeParseParams"
},
"productParams": {
"$ref": "#/components/schemas/ScrapeProductParams"
},
"highlightsParams": {
"$ref": "#/components/schemas/ScrapeHighlightsParams"
},
"jsonParams": {
"$ref": "#/components/schemas/ScrapeJsonParams"
},
"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": [
"disabled"
],
"default": "disabled",
"description": "Batches persist their results. Only disabled is supported; enabled returns ZDR_NOT_SUPPORTED."
},
"timeoutOpts": {
"$ref": "#/components/schemas/ScrapeTimeout",
"description": "Deadline for each page, using the same behavior and defaults as POST /web/scrape."
},
"tags": {
"$ref": "#/components/schemas/RequestTags"
}
},
"required": [
"source",
"formats"
],
"additionalProperties": false,
"title": "Crawl with Scrape Anything",
"description": "Use the same formats and parameters as POST /web/scrape, replacing url with source. Options apply to every page."
},
"BatchScrapeResponse": {
"$ref": "#/components/schemas/ScrapeResponse",
"title": "Scrape result",
"description": "The same response as POST /web/scrape, including per-format success, failure, and partial results."
}
}
}
}