{ "openapi": "3.1.0", "info": { "title": "XDive API", "version": "1.0.0", "summary": "Scrape, crawl, map, search and research the web as clean Markdown and structured data.", "description": "Public REST API of XDive. Guides and examples: https://xdive.dev/docs. A plain-text index for language models: https://xdive.dev/llms.txt.\n\nAuthenticate with an organization API key (`ck_live_…`) in `X-API-Key` or `Authorization: Bearer`. Organization-management endpoints (API keys, usage, history, schedules, monitors, crawl export) require a dashboard session token instead.\n\nEvery error is JSON with a stable `code`, a `retryable` flag and an `error` message (see the `Error` schema). Work-creating POST requests accept an `Idempotency-Key` header and report the per-minute budget in `RateLimit-*` headers.", "contact": { "url": "https://xdive.dev/docs" } }, "externalDocs": { "description": "XDive documentation", "url": "https://xdive.dev/docs" }, "servers": [ { "url": "https://xdive.dev/api" } ], "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ], "tags": [ { "name": "Scrape", "description": "Single pages and uploaded documents." }, { "name": "Crawl", "description": "Crawls, batch scrapes, map and crawl results." }, { "name": "Extract", "description": "Structured extraction and llms.txt." }, { "name": "Search", "description": "Web search and research." }, { "name": "Browser", "description": "Interactive browser sessions and profiles." }, { "name": "Schedules", "description": "Recurring crawls and change monitoring (session token)." }, { "name": "Account", "description": "Identity, API keys and usage." } ], "paths": { "/orgs/{id}/api-keys": { "parameters": [ { "$ref": "#/components/parameters/OrgId" } ], "get": { "operationId": "listApiKeys", "summary": "List API keys", "tags": [ "Account" ], "description": "The organization's API keys, without secrets. Requires a dashboard session token (`Authorization: Bearer `) of a member of the organization; API keys are rejected on organization-management endpoints.", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionToken": [] } ] }, "post": { "operationId": "createApiKey", "summary": "Create an API key", "tags": [ "Account" ], "description": "Issue a key. The response is the only one that includes `secret`. Scopes outside crawl, scrape, search, browser and connectors are rejected with 400. Requires a dashboard session token (`Authorization: Bearer `) of a member of the organization; API keys are rejected on organization-management endpoints.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionToken": [] } ] } }, "/orgs/{id}/api-keys/{keyId}": { "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/KeyId" } ], "delete": { "operationId": "revokeApiKey", "summary": "Revoke an API key", "tags": [ "Account" ], "description": "Revoke a key; it stops working immediately. Requires a dashboard session token (`Authorization: Bearer `) of a member of the organization; API keys are rejected on organization-management endpoints.", "responses": { "204": { "description": "Revoked." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionToken": [] } ] }, "patch": { "operationId": "updateApiKeyLimits", "summary": "Update an API key's monthly budgets", "tags": [ "Account" ], "description": "Change a key's per-key monthly page and search budgets. Returns the updated key (without secret). Requires a dashboard session token (`Authorization: Bearer `) of a member of the organization; API keys are rejected on organization-management endpoints.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyLimitsRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionToken": [] } ] } }, "/orgs/{id}/batch/scrape": { "parameters": [ { "$ref": "#/components/parameters/OrgId" } ], "post": { "operationId": "batchScrape", "summary": "Batch scrape up to 100 URLs", "tags": [ "Crawl" ], "description": "Queue an asynchronous job that scrapes up to 100 known URLs without following links. Returns 202 with a crawl id; follow it with the crawl endpoints. Scope: `scrape` or `crawl`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchScrapeRequest" } } } }, "responses": { "202": { "description": "Queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExceeded" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } }, "/orgs/{id}/browser/profiles": { "parameters": [ { "$ref": "#/components/parameters/OrgId" } ], "get": { "operationId": "listBrowserProfiles", "summary": "List saved browser profiles", "tags": [ "Browser" ], "description": "Saved browser profiles (cookies and storage) of the organization. Scope: `browser`.", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BrowserProfile" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "$ref": "#/components/responses/NotImplemented" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } }, "/orgs/{id}/browser/profiles/{name}": { "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/ProfileName" } ], "delete": { "operationId": "deleteBrowserProfile", "summary": "Delete a browser profile", "tags": [ "Browser" ], "description": "Delete a saved browser profile. Scope: `browser`.", "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "$ref": "#/components/responses/NotImplemented" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } }, "/orgs/{id}/browser/sessions": { "parameters": [ { "$ref": "#/components/parameters/OrgId" } ], "get": { "operationId": "listBrowserSessions", "summary": "List browser sessions", "tags": [ "Browser" ], "description": "The organization's live interactive browser sessions. Scope: `browser`.", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BrowserSession" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "$ref": "#/components/responses/NotImplemented" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] }, "post": { "operationId": "createBrowserSession", "summary": "Create a browser session", "tags": [ "Browser" ], "description": "Start an interactive browser session, optionally loading a saved profile. 409 when no session is free or the profile is in use. Scope: `browser`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBrowserSessionRequest" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSession" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExceeded" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "$ref": "#/components/responses/NotImplemented" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } }, "/orgs/{id}/browser/sessions/{sessionId}": { "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/SessionId" } ], "delete": { "operationId": "closeBrowserSession", "summary": "Close a browser session", "tags": [ "Browser" ], "description": "Close a session (saving its profile when `save_profile` was set). Scope: `browser`.", "responses": { "204": { "description": "Closed." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "$ref": "#/components/responses/NotImplemented" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } }, "/orgs/{id}/browser/sessions/{sessionId}/actions": { "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/SessionId" } ], "post": { "operationId": "runBrowserActions", "summary": "Run browser actions", "tags": [ "Browser" ], "description": "Run actions in a session in order; `extract` actions return rendered artifacts. Metered as browser seconds (rounded up, at least 1). 410 when the session has expired. Scope: `browser`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserActionsRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserActionsResponse" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExceeded" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" }, "410": { "description": "The browser session has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "$ref": "#/components/responses/NotImplemented" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } }, "/orgs/{id}/crawl": { "parameters": [ { "$ref": "#/components/parameters/OrgId" } ], "post": { "operationId": "startCrawl", "summary": "Start a crawl", "tags": [ "Crawl" ], "description": "Queue an asynchronous crawl from a seed URL following links. Returns 202 with a crawl id; poll `GET /orgs/{id}/crawls/{crawlId}` or receive a webhook. Scope: `crawl`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlRequest" } } } }, "responses": { "202": { "description": "Queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAccepted" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExceeded" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } }, "/orgs/{id}/crawls/{crawlId}": { "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/CrawlId" } ], "get": { "operationId": "getCrawl", "summary": "Get a crawl or batch scrape", "tags": [ "Crawl" ], "description": "Status of a crawl or batch scrape, and its pages once finished. Supports `If-None-Match` (304 when unchanged); while queued or running the response carries `Retry-After: 2`. Scope: `crawl` or `scrape`. Not rate limited.", "parameters": [ { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Crawl" } } }, "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "304": { "description": "Not modified since the ETag in `If-None-Match`.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] }, "delete": { "operationId": "cancelCrawl", "summary": "Cancel a crawl or batch scrape", "tags": [ "Crawl" ], "description": "Cancel a queued or running crawl or batch scrape. Pages fetched so far are kept. Scope: `crawl` or `scrape`.", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "const": "cancelled" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } }, "/orgs/{id}/crawls/{crawlId}/errors": { "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/CrawlId" } ], "get": { "operationId": "getCrawlErrors", "summary": "List a crawl's failed pages", "tags": [ "Crawl" ], "description": "Only the pages that failed, with pages refused by robots.txt listed separately. Scope: `crawl` or `scrape`.", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlErrors" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } }, "/orgs/{id}/crawls/{crawlId}/export": { "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/CrawlId" } ], "get": { "operationId": "exportCrawl", "summary": "Export a finished crawl", "tags": [ "Crawl" ], "description": "Download a finished crawl as JSON or CSV rows: the pages' structured `records` when any page has them, otherwise page metadata (url, title, description, lang, word_count, status_code, depth). Sent as an attachment. 409 when the crawl has not finished. Requires a dashboard session token (`Authorization: Bearer `) of a member of the organization; API keys are rejected on organization-management endpoints.", "parameters": [ { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } } ], "responses": { "200": { "description": "Export rows.", "headers": { "Content-Disposition": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } } }, "text/csv": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionToken": [] } ] } }, "/orgs/{id}/extract": { "parameters": [ { "$ref": "#/components/parameters/OrgId" } ], "post": { "operationId": "extract", "summary": "Extract structured data from up to 10 URLs", "tags": [ "Extract" ], "description": "Scrape up to 10 URLs and have the organization's LLM answer a prompt or fill a JSON Schema from all of them. Synchronous (90 seconds). Scope: `scrape` or `crawl`. 502 bodies include `sources` when no page could be read.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractResponse" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExceeded" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } }, "/orgs/{id}/history": { "parameters": [ { "$ref": "#/components/parameters/OrgId" } ], "get": { "operationId": "listHistory", "summary": "List recent crawls", "tags": [ "Crawl" ], "description": "The organization's 100 most recent crawls and batch scrapes (without results). Requires a dashboard session token (`Authorization: Bearer `) of a member of the organization; API keys are rejected on organization-management endpoints.", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CrawlRecord" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionToken": [] } ] } }, "/orgs/{id}/llmstxt": { "parameters": [ { "$ref": "#/components/parameters/OrgId" } ], "post": { "operationId": "generateLlmsTxt", "summary": "Generate llms.txt for a site", "tags": [ "Extract" ], "description": "Build an llms.txt index (and optionally llms-full.txt) from a site's most important pages. Synchronous (2 minutes). Scope: `crawl` or `scrape`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmsTxtRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmsTxtResponse" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExceeded" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } }, "/orgs/{id}/map": { "parameters": [ { "$ref": "#/components/parameters/OrgId" } ], "post": { "operationId": "map", "summary": "Map a site's URLs", "tags": [ "Crawl" ], "description": "List a site's URLs from its sitemaps and a links-only crawl, without converting content. Synchronous (45 seconds). Scope: `crawl`. Not metered, but refused with 402 once the page quota is used up.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapResponse" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExceeded" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } }, "/orgs/{id}/monitors": { "parameters": [ { "$ref": "#/components/parameters/OrgId" } ], "get": { "operationId": "listMonitorRuns", "summary": "List monitor runs", "tags": [ "Schedules" ], "description": "The 100 most recent change-monitoring runs across the organization's schedules. Requires a dashboard session token (`Authorization: Bearer `) of a member of the organization; API keys are rejected on organization-management endpoints.", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorRun" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionToken": [] } ] } }, "/orgs/{id}/monitors/{scheduleId}/runs": { "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/ScheduleId" } ], "get": { "operationId": "listScheduleMonitorRuns", "summary": "List a schedule's monitor runs", "tags": [ "Schedules" ], "description": "The 100 most recent change-monitoring runs of one schedule. Requires a dashboard session token (`Authorization: Bearer `) of a member of the organization; API keys are rejected on organization-management endpoints.", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorRun" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionToken": [] } ] } }, "/orgs/{id}/parse": { "parameters": [ { "$ref": "#/components/parameters/OrgId" } ], "post": { "operationId": "parse", "summary": "Parse an uploaded document", "tags": [ "Scrape" ], "description": "Convert one uploaded document (PDF, DOCX, XLSX, HTML, Markdown, text) without storing it. Must be `multipart/form-data` (415 otherwise). Scope: `scrape`. Counts one page.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ParseRequest" }, "encoding": { "options": { "contentType": "application/json" } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseResponse" } } }, "headers": { "X-Data-Retention": { "$ref": "#/components/headers/X-Data-Retention" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExceeded" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" }, "415": { "description": "The request was not `multipart/form-data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } }, "/orgs/{id}/research": { "parameters": [ { "$ref": "#/components/parameters/OrgId" } ], "post": { "operationId": "research", "summary": "Research a question", "tags": [ "Search" ], "description": "Search, read and answer a question with citations verified in code. Synchronous: 45 seconds (quick) or 150 seconds (deep). Scope: `search`; needs an LLM. 404 `NO_SOURCES`, 504 `RESEARCH_TIMEOUT`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchResponse" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExceeded" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "description": "`RESEARCH_TIMEOUT`: the run did not finish in time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } }, "/orgs/{id}/schedules": { "parameters": [ { "$ref": "#/components/parameters/OrgId" } ], "get": { "operationId": "listSchedules", "summary": "List schedules", "tags": [ "Schedules" ], "description": "Recurring crawls of the organization. Requires a dashboard session token (`Authorization: Bearer `) of a member of the organization; API keys are rejected on organization-management endpoints.", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Schedule" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionToken": [] } ] }, "post": { "operationId": "createSchedule", "summary": "Create a schedule", "tags": [ "Schedules" ], "description": "Create a recurring crawl, optionally with change monitoring. 402 when the plan's schedule cap is reached. Requires a dashboard session token (`Authorization: Bearer `) of a member of the organization; API keys are rejected on organization-management endpoints.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleRequest" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExceeded" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionToken": [] } ] } }, "/orgs/{id}/schedules/{scheduleId}": { "parameters": [ { "$ref": "#/components/parameters/OrgId" }, { "$ref": "#/components/parameters/ScheduleId" } ], "patch": { "operationId": "updateSchedule", "summary": "Update a schedule", "tags": [ "Schedules" ], "description": "Enable or disable a schedule and change its monitoring options. Requires a dashboard session token (`Authorization: Bearer `) of a member of the organization; API keys are rejected on organization-management endpoints.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduleRequest" } } } }, "responses": { "204": { "description": "Updated." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionToken": [] } ] }, "delete": { "operationId": "deleteSchedule", "summary": "Delete a schedule", "tags": [ "Schedules" ], "description": "Delete a schedule. Requires a dashboard session token (`Authorization: Bearer `) of a member of the organization; API keys are rejected on organization-management endpoints.", "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionToken": [] } ] } }, "/orgs/{id}/scrape": { "parameters": [ { "$ref": "#/components/parameters/OrgId" } ], "post": { "operationId": "scrape", "summary": "Scrape one URL", "tags": [ "Scrape" ], "description": "Fetch one URL synchronously and return it as Markdown, HTML, text, links, images, a screenshot or structured data. Scope: `scrape`. Times out after 30 seconds (3 minutes for `audio`; 45 seconds per browser step). `actions`, `wait_for` and `screenshot` run in an ephemeral browser and are metered as browser seconds.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeResponse" } } }, "headers": { "X-Data-Retention": { "$ref": "#/components/headers/X-Data-Retention" }, "X-Network-Policy": { "$ref": "#/components/headers/X-Network-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExceeded" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] }, "get": { "operationId": "scrapeGet", "summary": "Scrape one URL as Markdown", "tags": [ "Scrape" ], "description": "Legacy GET: returns the page's Markdown as `text/markdown`. Accepts only `url`, `respect_robots`, `zero_data_retention` and `lockdown`; formats, actions, headers and `max_age` need POST. Scope: `scrape`.", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "respect_robots", "in": "query", "schema": { "type": "boolean", "default": true } }, { "name": "zero_data_retention", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "lockdown", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The page as Markdown.", "headers": { "X-Data-Retention": { "$ref": "#/components/headers/X-Data-Retention" }, "X-Network-Policy": { "$ref": "#/components/headers/X-Network-Policy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } }, "content": { "text/markdown": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExceeded" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } }, "/orgs/{id}/search": { "parameters": [ { "$ref": "#/components/parameters/OrgId" } ], "post": { "operationId": "search", "summary": "Search the web", "tags": [ "Search" ], "description": "Search the web, news or images; optionally read or scrape the top results and write a short cited answer. Synchronous. Scope: `search`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExceeded" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyInProgress" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } }, "/orgs/{id}/usage": { "parameters": [ { "$ref": "#/components/parameters/OrgId" } ], "get": { "operationId": "getUsage", "summary": "Get usage and limits", "tags": [ "Account" ], "description": "Current-period usage, plan limits and residential proxy entitlement. Requires a dashboard session token (`Authorization: Bearer `) of a member of the organization; API keys are rejected on organization-management endpoints.", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionToken": [] } ] } }, "/whoami": { "get": { "operationId": "whoami", "summary": "Identify the caller", "tags": [ "Account" ], "description": "Identify the caller. Accepts an API key or a session token; the SDKs use it to discover the organization id of a key. Not metered.", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoAmI" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ] } } }, "components": { "securitySchemes": { "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Organization API key: `ck_live_` followed by 32 lowercase letters and digits. Limited to the key's scopes (`crawl`, `scrape`, `search`, `browser`, `connectors`)." }, "bearerAuth": { "type": "http", "scheme": "bearer", "description": "`Authorization: Bearer `. A value starting with `ck_` is treated as an API key; anything else as a dashboard session token (JWT, 7 days), which acts as the user with no scope limits. If both headers are sent, `X-API-Key` wins." }, "sessionToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Dashboard session token from `POST /auth/login`, sent as `Authorization: Bearer `. Required for organization-management endpoints; API keys are not accepted there." } }, "parameters": { "OrgId": { "name": "id", "in": "path", "required": true, "description": "Organization id (`org_…`). Find it with `GET /whoami`.", "schema": { "type": "string" } }, "CrawlId": { "name": "crawlId", "in": "path", "required": true, "description": "Crawl or batch scrape id (`crl_…`).", "schema": { "type": "string" } }, "ScheduleId": { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string" } }, "KeyId": { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } }, "SessionId": { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, "ProfileName": { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "1 to 255 printable ASCII characters (a UUID is a good choice). A retry with the same key and the same body within 24 hours returns the stored response with `Idempotent-Replayed: true` instead of running the work again. The same key with a different body returns 422 `IDEMPOTENCY_KEY_REUSED`; a retry while the first request is still running returns 409 `IDEMPOTENCY_KEY_IN_PROGRESS`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimit-Limit": { "description": "Requests allowed in the organization's current per-minute window (work-creating requests only).", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Legacy name of `RateLimit-Limit`.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Legacy name of `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Legacy name of `RateLimit-Reset`.", "schema": { "type": "integer" } }, "Idempotent-Replayed": { "description": "`true` when this response is a stored replay of an earlier request with the same `Idempotency-Key`.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-Request-ID": { "description": "Request identifier (`req_…`); include it when reporting a problem.", "schema": { "type": "string" } }, "ETag": { "description": "Changes only when the crawl's status, page count or duration does.", "schema": { "type": "string" } }, "X-Data-Retention": { "description": "`none` with zero data retention, otherwise `standard`.", "schema": { "type": "string", "enum": [ "none", "standard" ] } }, "X-Network-Policy": { "description": "`cache_only` under lockdown, otherwise `live`.", "schema": { "type": "string", "enum": [ "live", "cache_only" ] } } }, "responses": { "BadRequest": { "description": "The request is malformed or a parameter is invalid. Codes: `SIGNED_WEBHOOK_REQUIRED`, `WEBHOOK_TARGET_DENIED`, `INVALID_IDEMPOTENCY_KEY`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "Unauthorized": { "description": "Missing or invalid credentials (`invalid API key` / `unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "QuotaExceeded": { "description": "The organization's monthly quota for this kind of work is used up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "Forbidden": { "description": "Authenticated but not allowed: missing scope, not a member, organization suspended, account pending/rejected, or the target is refused (robots.txt, `SITE_RESTRICTED`, `PROXY_NOT_ENABLED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "NotFound": { "description": "The resource does not exist (or `NO_SOURCES`, `SCRAPE_LOCKDOWN_CACHE_MISS`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "Conflict": { "description": "Conflict with the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "IdempotencyInProgress": { "description": "`IDEMPOTENCY_KEY_IN_PROGRESS`: a request with the same Idempotency-Key is still running; retry after `Retry-After`. Endpoint-specific conflicts also use 409.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "Unprocessable": { "description": "The content could not be processed, or `IDEMPOTENCY_KEY_REUSED`: the Idempotency-Key was already used with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "TooManyRequests": { "description": "Rate limited (`RATE_LIMITED`) or over the plan's concurrency limit (`CONCURRENCY_LIMIT`). Wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "NotImplemented": { "description": "The feature is not configured on this server (LLM, browser automation, search engine).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "BadGateway": { "description": "A dependency failed: the target site, the search engine or the language model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } }, "ServiceUnavailable": { "description": "The server is at capacity (`SERVER_BUSY`) or a dependency is unavailable. Wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "ServerError": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/X-Request-ID" } } } }, "schemas": { "Error": { "type": "object", "description": "Error body. Every error has a stable `code`, a human-readable `error` message that may change, `retryable` and `docs_url`. Branch on the HTTP status and `code`; retry only when `retryable` is true, after `Retry-After` seconds when present.", "required": [ "success", "code", "error", "retryable" ], "properties": { "error": { "type": "string", "description": "Human-readable message." }, "code": { "$ref": "#/components/schemas/ErrorCode" }, "success": { "type": "boolean", "const": false }, "invalid_urls": { "type": "array", "items": { "type": "string" }, "description": "Batch scrape 400 only: entries that are not valid URLs." }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractSource" }, "description": "Extract 502 only: each URL and why it could not be read." }, "retryable": { "type": "boolean", "description": "True when the same request may succeed later (rate limits, overload, timeouts, upstream failures)." }, "docs_url": { "type": "string", "format": "uri", "description": "The errors documentation page." } }, "additionalProperties": true }, "ErrorCode": { "type": "string", "description": "Machine-readable error code. `SITE_RESTRICTED` and `PROXY_NOT_ENABLED` also appear as a failed page's `error_code` in crawl and batch results.", "enum": [ "RATE_LIMITED", "CONCURRENCY_LIMIT", "SERVER_BUSY", "PROXY_NOT_ENABLED", "SITE_RESTRICTED", "SCRAPE_LOCKDOWN_CACHE_MISS", "NO_SOURCES", "RESEARCH_TIMEOUT", "SIGNED_WEBHOOK_REQUIRED", "WEBHOOK_TARGET_DENIED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_KEY_REUSED", "IDEMPOTENCY_KEY_IN_PROGRESS", "ACCOUNT_PENDING_APPROVAL", "ACCOUNT_REJECTED", "EMAIL_NOT_VERIFIED", "CORS_ORIGIN_DENIED", "INVALID_REQUEST", "UNAUTHORIZED", "QUOTA_EXCEEDED", "FORBIDDEN", "NOT_FOUND", "METHOD_NOT_ALLOWED", "CONFLICT", "GONE", "REQUEST_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "UNPROCESSABLE", "NOT_CONFIGURED", "UPSTREAM_FAILED", "UNAVAILABLE", "TIMEOUT", "INTERNAL_ERROR", "ERROR" ] }, "FormatName": { "type": "string", "description": "Output format. Case-insensitive; aliases `md`, `txt`, `raw_html`, `clean_html`, `summarize`, `answer`, `screenshots`, `mp3` are accepted and normalized.", "examples": [ "markdown", "text", "html", "rawHtml", "links", "images", "json", "summary", "question", "highlights", "branding", "audio", "screenshot", "product", "menu" ] }, "FormatOptions": { "type": "object", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/FormatName" }, "prompt": { "type": "string", "description": "Instructions for `json`, `summary`, `question`, `highlights`." }, "schema": { "type": "object", "description": "JSON Schema for `json`." }, "question": { "type": "string", "description": "For `question`." }, "query": { "type": "string", "description": "For `highlights`." }, "max_results": { "type": "integer", "minimum": 0, "maximum": 50, "description": "For `highlights` (default 5)." } } }, "FormatRequest": { "oneOf": [ { "$ref": "#/components/schemas/FormatName" }, { "$ref": "#/components/schemas/FormatOptions" } ] }, "Formats": { "type": "array", "items": { "$ref": "#/components/schemas/FormatRequest" }, "description": "Representations to return; each format at most once. Default `[\"markdown\"]`." }, "Headers": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2048 }, "maxProperties": 10, "description": "Extra request headers for the page fetch (at most 10). Hop-by-hop, Host, Proxy-Authorization and X-Forwarded-* headers are rejected." }, "WebhookEvents": { "type": "array", "items": { "type": "string", "enum": [ "started", "page", "completed", "failed" ] }, "description": "Default `[\"completed\", \"failed\"]`." }, "Quality": { "type": "object", "properties": { "passed": { "type": "boolean" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "warnings": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "Artifact": { "type": "object", "description": "One rendered format. Carries the field for its format: `content`, `json`, `links`, `images`, `highlights`, `branding` or `url`.", "properties": { "media_type": { "type": "string" }, "bytes": { "type": "integer" }, "quality": { "$ref": "#/components/schemas/Quality" }, "content": { "type": "string" }, "json": {}, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "text": { "type": "string" } } } }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "alt": { "type": "string" }, "title": { "type": "string" } } } }, "highlights": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "score": { "type": "number" } } } }, "branding": { "type": "object", "additionalProperties": true }, "url": { "type": "string", "description": "Signed link (audio)." }, "estimated_tokens": { "type": "integer", "description": "Approximate model tokens to read content (about four characters per token). Set on markdown." }, "total_chars": { "type": "integer", "description": "Full length of the content when the response is one part of it (max_chars/offset)." }, "next_offset": { "type": "integer", "description": "Offset of the next part; absent when this part ends the content." } }, "additionalProperties": true }, "Artifacts": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Artifact" }, "description": "Artifacts keyed by canonical format name." }, "Page": { "type": "object", "description": "A fetched page (scrape `data`, crawl and batch `results`).", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "canonical": { "type": "string" }, "lang": { "type": "string" }, "image": { "type": "string" }, "site_name": { "type": "string" }, "depth": { "type": "integer" }, "status_code": { "type": "integer" }, "word_count": { "type": "integer" }, "fetched_at": { "type": "string", "format": "date-time" }, "fetch_route": { "type": "string", "enum": [ "cache", "http", "impersonate", "browser", "proxy" ] }, "fetch_attempts": { "type": "integer" }, "fetch_cost_units": { "type": "integer" }, "fetch_reason": { "type": "string" }, "policy_refusal": { "type": "boolean", "description": "true when robots.txt disallowed the page." }, "markdown": { "type": "string", "description": "Crawl/batch without `formats`." }, "artifacts": { "$ref": "#/components/schemas/Artifacts" }, "links": { "type": "array", "items": { "type": "string" } }, "records": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, "error": { "type": "string", "description": "Why this page failed (crawl/batch)." }, "error_code": { "type": "string", "enum": [ "PROXY_NOT_ENABLED", "SITE_RESTRICTED" ] }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Present when the content may be incomplete, for example a client-rendered page that could not be rendered in a browser. The page still succeeded." } }, "additionalProperties": true }, "SecurityPolicy": { "type": "object", "properties": { "zero_data_retention": { "type": "boolean" }, "network_policy": { "type": "string", "enum": [ "live", "cache_only" ] }, "cache_state": { "type": "string", "enum": [ "eligible", "write_disabled", "hit" ] }, "outbound_permitted": { "type": "boolean" } } }, "BrowserAction": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "goto", "click", "fill", "press", "scroll", "wait", "extract", "screenshot" ], "description": "On scrape, only click, fill, press, scroll and wait are accepted." }, "url": { "type": "string", "description": "goto." }, "selector": { "type": "string", "maxLength": 1000, "description": "click, fill, wait." }, "value": { "type": "string", "maxLength": 10000, "description": "fill." }, "key": { "type": "string", "enum": [ "Enter", "Tab", "Escape", "Backspace", "Delete", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Space" ], "description": "press." }, "x": { "type": "integer", "minimum": -100000, "maximum": 100000, "description": "scroll." }, "y": { "type": "integer", "minimum": -100000, "maximum": 100000, "description": "scroll." }, "milliseconds": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "wait." }, "full_page": { "type": "boolean", "description": "screenshot." }, "formats": { "type": "array", "items": { "$ref": "#/components/schemas/FormatName" }, "description": "extract (default markdown)." } } }, "ScrapeRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Absolute http(s) URL." }, "formats": { "$ref": "#/components/schemas/Formats" }, "extract": { "type": "boolean", "default": true, "description": "Main-content extraction." }, "respect_robots": { "type": "boolean", "default": true }, "max_age": { "type": "integer", "minimum": 0, "default": 0, "description": "Cache freshness window in ms; 0 = server default." }, "max_chars": { "type": "integer", "minimum": 0, "default": 0, "description": "Return at most this many characters of Markdown, cut at a paragraph break (0 = no limit, otherwise at least 500). The markdown artifact then carries total_chars and next_offset." }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Continue a long page from a previous response's next_offset. Reuses a cached copy up to 10 minutes old." }, "store_in_cache": { "type": "boolean", "default": true }, "headers": { "$ref": "#/components/schemas/Headers" }, "actions": { "type": "array", "maxItems": 15, "items": { "$ref": "#/components/schemas/BrowserAction" } }, "wait_for": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 }, "full_page_screenshot": { "type": "boolean", "default": false }, "redact_pii": { "type": "boolean", "default": false }, "zero_data_retention": { "type": "boolean", "default": false }, "lockdown": { "type": "boolean", "default": false, "description": "Serve only a cached copy; no outbound fetch." } } }, "ScrapeResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Page" }, "security": { "$ref": "#/components/schemas/SecurityPolicy" } } }, "CrawlRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "max_depth": { "type": "integer", "minimum": 0, "default": 2 }, "max_pages": { "type": "integer", "minimum": 0, "maximum": 500, "default": 100, "description": "0 or >500 means 500." }, "same_domain": { "type": "boolean", "default": true }, "include_paths": { "type": "array", "items": { "type": "string" }, "description": "RE2 patterns on the URL path." }, "exclude_paths": { "type": "array", "items": { "type": "string" } }, "impersonate": { "type": "boolean", "default": false }, "render": { "type": "boolean", "default": false }, "extract_schema": { "type": "object", "properties": { "container": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "required": [ "name", "selector" ], "properties": { "name": { "type": "string" }, "selector": { "type": "string" }, "attr": { "type": "string" } } } } } }, "llm_extract": { "type": "object", "properties": { "prompt": { "type": "string" }, "multiple": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean" ] } } } } } }, "extract": { "type": "boolean", "default": true }, "respect_robots": { "type": "boolean", "default": true }, "adaptive_fetch": { "type": "boolean", "default": true }, "bypass_cache": { "type": "boolean", "default": false }, "max_age": { "type": "integer", "minimum": 0, "default": 0 }, "headers": { "$ref": "#/components/schemas/Headers" }, "redact_pii": { "type": "boolean", "default": false }, "webhook_url": { "type": "string", "format": "uri" }, "webhook_secret": { "type": "string", "description": "HMAC-SHA256 key; required with webhook_url unless the server's signed-webhook policy is off." }, "webhook_events": { "$ref": "#/components/schemas/WebhookEvents" }, "formats": { "allOf": [ { "$ref": "#/components/schemas/Formats" } ], "description": "As on scrape; `screenshot` and `audio` are not allowed." } } }, "BatchScrapeRequest": { "type": "object", "required": [ "urls" ], "properties": { "urls": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } }, "ignore_invalid_urls": { "type": "boolean", "default": false }, "extract": { "type": "boolean", "default": true }, "respect_robots": { "type": "boolean", "default": true }, "adaptive_fetch": { "type": "boolean", "default": true }, "bypass_cache": { "type": "boolean", "default": false }, "max_age": { "type": "integer", "minimum": 0, "default": 0 }, "headers": { "$ref": "#/components/schemas/Headers" }, "redact_pii": { "type": "boolean", "default": false }, "webhook_url": { "type": "string", "format": "uri" }, "webhook_secret": { "type": "string", "description": "HMAC-SHA256 key; required with webhook_url unless the server's signed-webhook policy is off." }, "webhook_events": { "$ref": "#/components/schemas/WebhookEvents" }, "formats": { "allOf": [ { "$ref": "#/components/schemas/Formats" } ], "description": "As on scrape; `screenshot` and `audio` are not allowed." } } }, "JobAccepted": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "examples": [ "crl_7d1e4b9a2c6f3e8d0a5b7c9e1f3a5c7d" ] }, "status": { "type": "string", "const": "queued" }, "urls": { "type": "integer", "description": "Batch only: URLs that will be scraped." }, "invalid_urls": { "type": "array", "items": { "type": "string" }, "description": "Batch only: skipped entries." } } }, "CrawlStatus": { "type": "string", "enum": [ "queued", "running", "success", "error", "cancelled" ] }, "Crawl": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "description": "Seed URL, or `batch:` for a batch scrape." }, "status": { "$ref": "#/components/schemas/CrawlStatus" }, "pages": { "type": "integer" }, "maxDepth": { "type": "integer" }, "durationMs": { "type": "integer" }, "httpPages": { "type": "integer" }, "cachePages": { "type": "integer" }, "impersonatedPages": { "type": "integer" }, "browserPages": { "type": "integer" }, "fetchAttempts": { "type": "integer" }, "fetchCostUnits": { "type": "integer" }, "error": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "results": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Page" }, "description": "null until the crawl has finished." } }, "additionalProperties": true }, "CrawlRecord": { "type": "object", "description": "A crawl in the history list (no results).", "properties": { "id": { "type": "string" }, "orgId": { "type": "string" }, "userId": { "type": "string" }, "scheduleId": { "type": "string" }, "url": { "type": "string" }, "maxDepth": { "type": "integer" }, "pages": { "type": "integer" }, "status": { "$ref": "#/components/schemas/CrawlStatus" }, "durationMs": { "type": "integer" }, "httpPages": { "type": "integer" }, "cachePages": { "type": "integer" }, "impersonatedPages": { "type": "integer" }, "browserPages": { "type": "integer" }, "fetchAttempts": { "type": "integer" }, "fetchCostUnits": { "type": "integer" }, "error": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "CrawlErrors": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/CrawlStatus" }, "error": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "error": { "type": "string" } } } }, "robots_blocked": { "type": "array", "items": { "type": "string" } } } }, "MapRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "search": { "type": "string", "description": "Case-insensitive substring filter." }, "limit": { "type": "integer", "minimum": 0, "maximum": 5000, "default": 5000 }, "max_depth": { "type": "integer", "minimum": 0, "default": 2 } } }, "MapResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "urls": { "type": "array", "items": { "type": "string" } } } }, "Passage": { "type": "object", "properties": { "text": { "type": "string" }, "score": { "type": "number" }, "start": { "type": "integer" } } }, "Citation": { "type": "object", "properties": { "number": { "type": "integer" }, "url": { "type": "string" }, "title": { "type": "string" }, "quote": { "type": "string" } } }, "Confidence": { "type": "string", "enum": [ "high", "medium", "low", "none" ] }, "SearchRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "maxLength": 400 }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "web", "news", "images" ] }, "default": [ "web" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "country": { "type": "string", "description": "Two-letter country code." }, "search_language": { "type": "string" }, "freshness": { "type": "string", "description": "`pd`, `pw`, `pm`, `py`, or `YYYY-MM-DDtoYYYY-MM-DD`.", "pattern": "^(pd|pw|pm|py|\\d{4}-\\d{2}-\\d{2}to\\d{4}-\\d{2}-\\d{2})$" }, "safe_search": { "type": "string", "enum": [ "off", "moderate", "strict" ], "default": "moderate" }, "include_domains": { "type": "array", "maxItems": 20, "items": { "type": "string" }, "description": "Host names; subdomains match." }, "exclude_domains": { "type": "array", "maxItems": 20, "items": { "type": "string" }, "description": "Host names; subdomains match." }, "search_depth": { "type": "string", "enum": [ "basic", "advanced" ], "default": "basic" }, "auto_parameters": { "type": "boolean", "default": false }, "scrape": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 0, "maximum": 5, "default": 3 }, "formats": { "type": "array", "items": { "$ref": "#/components/schemas/FormatName" }, "default": [ "markdown" ] }, "respect_robots": { "type": "boolean", "default": true }, "main_content_only": { "type": "boolean", "default": true } } }, "include_answer": { "type": "boolean", "default": false, "description": "Requires an LLM." } } }, "SearchResult": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string", "enum": [ "web", "news", "images" ] }, "rank": { "type": "integer" }, "title": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "published_at": { "type": "string" }, "image": { "type": "object", "properties": { "url": { "type": "string" }, "thumbnail": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } } }, "page": { "$ref": "#/components/schemas/Page" }, "passages": { "type": "array", "items": { "$ref": "#/components/schemas/Passage" } }, "relevance_score": { "type": "number" }, "scrape_error": { "type": "string" } }, "additionalProperties": true }, "SearchResponse": { "type": "object", "properties": { "query": { "type": "string" }, "provider": { "type": "string" }, "search_depth": { "type": "string" }, "parameters": { "type": "object", "additionalProperties": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "answer": { "type": "object", "properties": { "text": { "type": "string" }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/Citation" } }, "confidence": { "$ref": "#/components/schemas/Confidence" }, "error": { "type": "string" } } } }, "additionalProperties": true }, "ResearchRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "maxLength": 500 }, "depth": { "type": "string", "enum": [ "quick", "deep" ], "default": "quick" }, "output": { "type": "string", "enum": [ "answer", "report" ], "description": "Default `answer` for quick, `report` for deep." }, "schema": { "type": "object", "description": "JSON Schema; the result is returned as `data`." }, "max_sources": { "type": "integer", "minimum": 1, "description": "Default 6 (quick) / 15 (deep)." }, "include_domains": { "type": "array", "maxItems": 20, "items": { "type": "string" }, "description": "Host names; subdomains match." }, "exclude_domains": { "type": "array", "maxItems": 20, "items": { "type": "string" }, "description": "Host names; subdomains match." }, "freshness": { "type": "string", "description": "`pd`, `pw`, `pm`, `py`, or `YYYY-MM-DDtoYYYY-MM-DD`.", "pattern": "^(pd|pw|pm|py|\\d{4}-\\d{2}-\\d{2}to\\d{4}-\\d{2}-\\d{2})$" }, "country": { "type": "string" }, "no_cache": { "type": "boolean", "default": false } } }, "ResearchResponse": { "type": "object", "properties": { "query": { "type": "string" }, "answer": { "type": "string" }, "data": { "description": "Filled schema, when `schema` was passed." }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/Citation" } }, "sources": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer" }, "url": { "type": "string" }, "title": { "type": "string" }, "passages": { "type": "array", "items": { "$ref": "#/components/schemas/Passage" } }, "score": { "type": "number" }, "snippet": { "type": "boolean" } }, "additionalProperties": true } }, "queries": { "type": "array", "items": { "type": "string" } }, "confidence": { "$ref": "#/components/schemas/Confidence" }, "usage": { "type": "object", "properties": { "searches": { "type": "integer" }, "pages_read": { "type": "integer" }, "rounds": { "type": "integer" }, "hops": { "type": "integer" }, "plan": { "type": "string", "enum": [ "single", "multi_hop", "unavailable" ] }, "duration_ms": { "type": "integer" }, "search_ms": { "type": "integer" }, "read_ms": { "type": "integer" }, "model_ms": { "type": "integer" } }, "additionalProperties": true }, "cached": { "type": "boolean" } }, "additionalProperties": true }, "ExtractRequest": { "type": "object", "required": [ "urls" ], "description": "At least one of `prompt` and `schema` is required.", "properties": { "urls": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "uri" } }, "prompt": { "type": "string" }, "schema": { "type": "object" }, "main_content_only": { "type": "boolean", "default": true }, "respect_robots": { "type": "boolean", "default": true }, "show_sources": { "type": "boolean", "default": false } } }, "ExtractSource": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "error": { "type": "string" } } }, "ExtractResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "description": "JSON produced by the model." }, "sources_scraped": { "type": "integer" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractSource" } } } }, "LlmsTxtRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "max_urls": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 }, "full_text": { "type": "boolean", "default": false } } }, "LlmsTxtResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "llms_txt": { "type": "string" }, "pages": { "type": "integer" }, "llms_full_txt": { "type": "string" } } }, "ParseRequest": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "description": "Exactly one document: PDF, DOCX, XLSX, HTML, Markdown or plain text." }, "options": { "type": "string", "contentMediaType": "application/json", "description": "JSON-encoded options: `formats` (as on scrape; `audio` not allowed), `ocr` (`auto`, `never`, `force`), `ocr_language`, `max_pages`." } } }, "ParseResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "filename": { "type": "string" }, "media_type": { "type": "string" }, "title": { "type": "string" }, "artifacts": { "$ref": "#/components/schemas/Artifacts" } } } } }, "PlanLimits": { "type": "object", "description": "`-1` means unlimited.", "properties": { "monthlyPages": { "type": "integer" }, "monthlySearches": { "type": "integer" }, "monthlyBrowserSeconds": { "type": "integer" }, "maxBrowserSessions": { "type": "integer" }, "maxSchedules": { "type": "integer" }, "requestsPerMinute": { "type": "integer" }, "maxConcurrentRequests": { "type": "integer" }, "maxConcurrentCrawls": { "type": "integer" }, "name": { "type": "string" } }, "additionalProperties": true }, "Usage": { "type": "object", "properties": { "period": { "type": "string", "description": "UTC month, `YYYY-MM`." }, "plan": { "type": "string", "enum": [ "free", "pro", "enterprise" ] }, "limits": { "$ref": "#/components/schemas/PlanLimits" }, "pagesUsed": { "type": "integer" }, "searchesUsed": { "type": "integer" }, "browserSecondsUsed": { "type": "integer" }, "crawlsUsed": { "type": "integer" }, "schedules": { "type": "integer" }, "proxy": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "monthlyPages": { "type": "integer" }, "pagesUsed": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "Organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "plan": { "type": "string" }, "role": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "WhoAmI": { "type": "object", "required": [ "auth" ], "description": "With an API key: `auth: api_key`, `keyId`, `orgId`, `scopes`, `plan`, `suspended`. With a session token: `auth: user`, `userId`, `orgs`.", "properties": { "auth": { "type": "string", "enum": [ "api_key", "user" ] }, "keyId": { "type": "string" }, "orgId": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } }, "plan": { "type": "string", "enum": [ "free", "pro", "enterprise" ] }, "suspended": { "type": "boolean" }, "userId": { "type": "string" }, "orgs": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" } } } }, "Scope": { "type": "string", "enum": [ "crawl", "scrape", "search", "browser", "connectors" ] }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "orgId": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string", "description": "First 12 characters, e.g. `ck_live_7hq2`." }, "secret": { "type": "string", "description": "Full key (`ck_live_` + 32 characters). Returned only on creation." }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "ipAllowlist": { "type": "array", "items": { "type": "string" } }, "monthlyPageLimit": { "type": "integer", "description": "Per-key monthly page budget; 0 = only the plan quota applies." }, "monthlySearchLimit": { "type": "integer", "description": "Per-key monthly search budget; 0 = only the plan quota applies." }, "pagesUsed": { "type": "integer", "description": "Pages counted for this key this period (listings)." }, "searchesUsed": { "type": "integer", "description": "Searches counted for this key this period (listings)." } }, "additionalProperties": true }, "CreateApiKeyRequest": { "type": "object", "properties": { "name": { "type": "string", "default": "Untitled key" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" }, "default": [ "crawl", "scrape" ] }, "expires_in_days": { "type": "integer", "minimum": 0, "maximum": 3650, "default": 0, "description": "0 = never expires." }, "ip_allowlist": { "type": "array", "maxItems": 32, "items": { "type": "string" }, "description": "IP addresses or CIDRs." }, "monthly_page_limit": { "type": "integer", "minimum": 0, "maximum": 100000000, "default": 0, "description": "Monthly budget for this key alone; 0 = no per-key limit." }, "monthly_search_limit": { "type": "integer", "minimum": 0, "maximum": 100000000, "default": 0, "description": "Monthly budget for this key alone; 0 = no per-key limit." } } }, "UpdateApiKeyLimitsRequest": { "type": "object", "description": "Omitted fields keep their current value; 0 removes the per-key limit.", "properties": { "monthly_page_limit": { "type": "integer", "minimum": 0, "maximum": 100000000, "default": 0, "description": "Monthly budget for this key alone; 0 = no per-key limit." }, "monthly_search_limit": { "type": "integer", "minimum": 0, "maximum": 100000000, "default": 0, "description": "Monthly budget for this key alone; 0 = no per-key limit." } } }, "CreateScheduleRequest": { "type": "object", "required": [ "url", "interval_sec" ], "properties": { "url": { "type": "string", "format": "uri" }, "max_depth": { "type": "integer", "minimum": 0 }, "max_pages": { "type": "integer", "minimum": 0 }, "render": { "type": "boolean" }, "interval_sec": { "type": "integer", "minimum": 60 }, "webhook_url": { "type": "string", "format": "uri" }, "webhook_secret": { "type": "string" }, "monitor_changes": { "type": "boolean" }, "notify_on_change_only": { "type": "boolean", "description": "Requires monitor_changes." }, "monitor_goal": { "type": "string" }, "monitor_ignore_patterns": { "type": "array", "items": { "type": "string" } }, "monitor_ignore_dynamic": { "type": "boolean" }, "monitor_min_change_percent": { "type": "number" }, "monitor_judge": { "type": "boolean", "description": "Requires monitor_changes." }, "adaptive_fetch": { "type": "boolean" } } }, "UpdateScheduleRequest": { "type": "object", "description": "Fields to change; omitted fields are left as they are.", "properties": { "enabled": { "type": "boolean" }, "monitor_changes": { "type": "boolean" }, "notify_on_change_only": { "type": "boolean", "description": "Requires monitor_changes." }, "monitor_goal": { "type": "string" }, "monitor_ignore_patterns": { "type": "array", "items": { "type": "string" } }, "monitor_ignore_dynamic": { "type": "boolean" }, "monitor_min_change_percent": { "type": "number" }, "monitor_judge": { "type": "boolean", "description": "Requires monitor_changes." }, "adaptive_fetch": { "type": "boolean" } } }, "Schedule": { "type": "object", "properties": { "id": { "type": "string" }, "orgId": { "type": "string" }, "userId": { "type": "string" }, "url": { "type": "string" }, "maxDepth": { "type": "integer" }, "maxPages": { "type": "integer" }, "render": { "type": "boolean" }, "adaptiveFetch": { "type": "boolean" }, "intervalSec": { "type": "integer" }, "webhookUrl": { "type": "string" }, "monitorChanges": { "type": "boolean" }, "notifyOnChangeOnly": { "type": "boolean" }, "monitorGoal": { "type": "string" }, "monitorIgnorePatterns": { "type": "array", "items": { "type": "string" } }, "monitorIgnoreDynamic": { "type": "boolean" }, "monitorMinChangePercent": { "type": "number" }, "monitorJudge": { "type": "boolean" }, "enabled": { "type": "boolean" }, "nextRunAt": { "type": "string", "format": "date-time" }, "lastRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "MonitorRun": { "type": "object", "properties": { "id": { "type": "string" }, "orgId": { "type": "string" }, "scheduleId": { "type": "string" }, "crawlId": { "type": "string" }, "previousCrawlId": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string" }, "error": { "type": "string" }, "baseline": { "type": "boolean" }, "hasChanges": { "type": "boolean" }, "detectedChanges": { "type": "boolean" }, "suppressedChanges": { "type": "integer" }, "judged": { "type": "boolean" }, "relevanceScore": { "type": "integer" }, "judgmentReason": { "type": "string" }, "addedPages": { "type": "integer" }, "changedPages": { "type": "integer" }, "removedPages": { "type": "integer" }, "totalPages": { "type": "integer" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "added", "changed", "removed" ] }, "addedLines": { "type": "array", "items": { "type": "string" } }, "removedLines": { "type": "array", "items": { "type": "string" } } } } }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "BrowserSession": { "type": "object", "properties": { "id": { "type": "string" }, "profile_name": { "type": "string" }, "save_profile": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "last_active_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } }, "CreateBrowserSessionRequest": { "type": "object", "properties": { "ttl_seconds": { "type": "integer", "minimum": 0, "description": "Default 15 minutes, at most 1 hour (server defaults)." }, "profile_name": { "type": "string", "description": "Load (and with save_profile, save) a named browser profile." }, "save_profile": { "type": "boolean" } } }, "BrowserActionsRequest": { "type": "object", "required": [ "actions" ], "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/BrowserAction" }, "description": "At most 20 per call (server default)." } } }, "BrowserActionsResponse": { "type": "object", "properties": { "session_id": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "duration_ms": { "type": "integer" }, "url": { "type": "string" }, "text": { "type": "string" }, "screenshot": { "type": "string" }, "artifacts": { "$ref": "#/components/schemas/Artifacts" } }, "additionalProperties": true } } } }, "BrowserProfile": { "type": "object", "properties": { "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }