{ "openapi": "3.1.0", "info": { "title": "Nimble SDK", "version": "1.0.0", "description": "The AI-Native SDK for Real-Time Web Data at scale" }, "paths": { "/v1/realtime/serp": { "post": { "servers": [ { "url": "https://api.us.webit.live/api", "description": "Production" } ], "summary": "Fast Google SERP", "tags": [ "Fast SERP" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/FastSerpPayload" } ], "examples": [ { "search_engine": "google_search", "query": "NBA Allstar 2026", "country": "US", "locale": "en" } ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SerpResponse" } ], "examples": [ { "url": "https://www.google.com/search?hl=en&gl=us&q=NBA+Allstar+2026", "task_id": "bd46cd9c-50f7-4736-9c4a-660a32e4dc87", "status": "success", "query_time": "2026-03-05T13:47:16.435Z", "html_content": "...", "status_code": 200, "parsing": { "entities": { "AnswerBox": [ { "entity_type": "AnswerBox", "snippet": "NBANBA", "snippet_highlighted": [ "NBANBA" ], "display_link": "" } ], "InlineImages": [ { "entity_type": "InlineImages", "title": "#NBAAllStar 2026: Day of Service with Habitat for Humanity & Baby2Baby", "url": "https://www.youtube.com/watch?v=CG98tKo" } ], "OrganicResult": [ { "position": 1, "title": "2026 All-Star | Schedule", "url": "https://www.nba.com/allstar/2026/schedule", "snippet": "The 2026 NBA All-Star Game will take place on Sunday, Feb. 15, 2026 in Los Angeles, California at the Intuit Dome, the home of the LA Clippers.", "cleaned_domain": "nba", "displayed_url": "https://www.nba.com › allstar › 2026 › schedule", "entity_type": "OrganicResult" }, { "position": 2, "title": "2026 All-Star | Roster", "url": "https://www.nba.com/allstar/2026/roster", "snippet": "2026 All-Star · Latest · Events. Feb. 13: Ruffles All-Star Celebrity Game ...", "cleaned_domain": "nba", "displayed_url": "https://www.nba.com › allstar › 2026 › roster", "entity_type": "OrganicResult" }, { "...": "more results" } ], "TopStory": [ { "entity_type": "TopStory", "url": "https://www.youtube.com/watch?v=0omGCG98tKo" }, { "...": "more results" } ], "Pagination": [ { "current_page": 1, "entity_type": "Pagination", "next_page_url": "https://www.google.com/search?q=NBA+All+Star+2026&start=10", "other_page_urls": { "3": "https://www.google.com/search?q=NBA+All+Star+2026&start=20", "...": "more pages" } } ], "RelatedQuestion": [ { "entity_type": "RelatedQuestion", "question": "Who are the NBA All-Star 2026?" }, { "...": "more questions" } ], "RelatedSearch": [ { "entity_type": "RelatedSearch", "position": "7", "query": "NBA All-Star 2026 tickets", "url": "/search?q=NBA+All-Star+2026+tickets" }, { "...": "more searches" } ] }, "total_entities_count": 32, "entities_count": { "AnswerBox": 1, "InlineImages": 1, "OrganicResult": 8, "Pagination": 1, "RelatedQuestion": 4, "RelatedSearch": 14, "TopStory": 3 }, "metrics": {} }, "nimble_pagination": { "next_page_url": "https://api.us.webit.live/api/v1/realtime/serp?search_engine=google_search&query=NBA+Allstar+2026&country=US&locale=en&parse=true&page_params=...", "other_pages": [ "..." ] }, "nimble_payload": { "next_page": { "search_engine": "google_search", "query": "NBA Allstar 2026", "country": "US", "locale": "en", "parse": "true", "page_params": "q=NBA+All+Star+2026&start=10&..." } }, "driver": "vx6" } ] } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" } } } }, "400": { "description": "Unprocessable Entity - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error500" } } } } } } }, "/v2/extract/templates/run": { "post": { "description": "Execute Extract Template Realtime Endpoint", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractionTemplateBody" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "browser_actions": { "additionalProperties": false, "description": "Browser actions execution results. Present only when browser_actions were specified in the request.", "properties": { "results": { "items": { "additionalProperties": false, "properties": { "duration": { "minimum": 0, "type": "number" }, "error": { "type": "string" }, "name": { "enum": [ "goto", "wait", "wait_for_element", "wait_for_navigation", "click", "fill", "press", "scroll", "auto_scroll", "screenshot", "get_cookies", "eval", "fetch" ], "type": "string" }, "result": {}, "status": { "enum": [ "no-run", "in-progress", "done", "error", "skipped" ], "type": "string" } }, "required": [ "name", "status", "duration" ], "type": "object" }, "readOnly": true, "type": "array" }, "success": { "type": "boolean" }, "total_duration": { "minimum": 0, "type": "number" } }, "required": [ "success", "results", "total_duration" ], "type": "object" }, "cookies": { "description": "The cookies collected from browser actions during the task.", "items": {}, "type": "array" }, "eval": { "description": "The evaluation results from browser actions during the task.", "items": {}, "type": "array" }, "fetch": { "description": "The http requests from browser actions made during the task.", "items": {}, "type": "array" }, "headers": { "additionalProperties": { "type": "string" }, "description": "The headers received during the task.", "propertyNames": { "type": "string" }, "type": "object" }, "html": { "description": "The HTML content of the page.", "type": "string" }, "links": { "description": "List of all unique URLs found on the page.", "items": { "type": "string" }, "type": "array" }, "markdown": { "description": "The Markdown version of the HTML content.", "type": "string" }, "network_capture": { "description": "The network capture data collected during the task.", "items": { "additionalProperties": false, "properties": { "errorMessage": { "type": "string" }, "filter": { "additionalProperties": false, "properties": { "method": { "enum": [ "GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH" ], "type": "string" }, "resource_type": { "anyOf": [ { "description": "Resource type for network capture filtering", "enum": [ "document", "stylesheet", "image", "media", "font", "script", "texttrack", "xhr", "fetch", "prefetch", "eventsource", "websocket", "manifest", "signedexchange", "ping", "cspviolationreport", "preflight", "other", "fedcm" ], "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, { "items": { "description": "Resource type for network capture filtering", "enum": [ "document", "stylesheet", "image", "media", "font", "script", "texttrack", "xhr", "fetch", "prefetch", "eventsource", "websocket", "manifest", "signedexchange", "ping", "cspviolationreport", "preflight", "other", "fedcm" ], "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, "minItems": 1, "type": "array" } ] }, "status_code": { "anyOf": [ { "maximum": 599, "minimum": 100, "type": "number" }, { "items": { "maximum": 599, "minimum": 100, "type": "number" }, "minItems": 1, "type": "array" } ] }, "url": { "additionalProperties": false, "properties": { "type": { "default": "exact", "enum": [ "exact", "contains" ], "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "validation": { "default": false, "type": "boolean" }, "wait_for_requests_count": { "default": 0, "minimum": 0, "type": "number" }, "wait_for_requests_count_timeout": { "exclusiveMinimum": 0, "maximum": 300000, "type": "number" } }, "required": [ "validation", "wait_for_requests_count" ], "type": "object" }, "results": { "items": { "additionalProperties": false, "properties": { "request": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "headers": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "method": { "type": "string" }, "resource_type": { "description": "Resource type for network capture filtering", "enum": [ "document", "stylesheet", "image", "media", "font", "script", "texttrack", "xhr", "fetch", "prefetch", "eventsource", "websocket", "manifest", "signedexchange", "ping", "cspviolationreport", "preflight", "other", "fedcm" ], "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "resource_type", "method", "url", "headers" ], "type": "object" }, "response": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "headers": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "serialization": { "enum": [ "none", "base64" ], "type": "string" }, "status": { "type": "number" }, "status_text": { "type": "string" } }, "required": [ "status", "status_text", "headers", "serialization", "body" ], "type": "object" } }, "required": [ "request", "response" ], "type": "object" }, "type": "array" } }, "required": [ "filter", "results" ], "type": "object" }, "readOnly": true, "type": "array" }, "pages_html": { "description": "Individual HTML content of each pagination page, before merging.", "items": { "type": "string" }, "type": "array" }, "parsing": { "anyOf": [ { "$ref": "#/components/schemas/ParsingSuccessResult" }, { "$ref": "#/components/schemas/ParsingErrorResult" }, { "additionalProperties": {}, "propertyNames": { "type": "string" }, "type": "object" } ], "description": "The parsing results extracted from the HTML & network content." }, "redirects": { "description": "The list of redirects that occurred during the task.", "items": { "additionalProperties": false, "properties": { "status_code": { "maximum": 599, "minimum": 100, "type": "number" }, "url": { "type": "string" } }, "required": [ "status_code", "url" ], "type": "object" }, "type": "array" }, "screenshots": { "description": "Screenshots taken during the task, from browser actions, or the screenshot format.", "items": {}, "type": "array" } }, "type": "object" }, "debug": { "additionalProperties": false, "properties": { "performance_metrics": { "additionalProperties": { "type": "number" }, "description": "Performance metrics collected during the task.", "propertyNames": { "type": "string" }, "type": "object" }, "proxy_total_bytes_usage": { "description": "Total bytes used by the proxy during the task.", "minimum": 0, "type": "number" }, "transformed_output": { "description": "The transformed output after applying any transformations." }, "userbrowser": { "description": "The userbrowser instance using during the task." } }, "type": "object" }, "metadata": { "additionalProperties": false, "properties": { "agent": { "description": "The name of the agent used for the query.", "type": "string" }, "driver": { "description": "The driver used for the task.", "type": "string" }, "localization_id": { "description": "The localization identifier for the query.", "type": "string" }, "query_duration": { "description": "The duration in milliseconds of the query processing.", "type": "number" }, "query_time": { "description": "The time when the query was received.", "type": "string" }, "response_parameters": { "description": "Additional response parameters." }, "tag": { "description": "A tag associated with the query.", "type": "string" } }, "type": "object" }, "pagination": { "anyOf": [ { "additionalProperties": false, "properties": { "next_page_params": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "next_page_params" ], "type": "object" }, { "items": { "additionalProperties": false, "properties": { "next_page_params": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "next_page_params" ], "type": "object" }, "type": "array" } ], "description": "Pagination information if applicable." }, "status": { "description": "The status of the task.", "enum": [ "success", "skipped", "fatal", "error", "postponed", "ignored", "rejected", "blocked" ], "type": "string" }, "status_code": { "description": "The HTTP status code of the task.", "type": "number" }, "task_id": { "description": "Unique identifier for the task.", "type": "string" }, "url": { "description": "The final URL.", "type": "string" }, "warnings": { "description": "List of warnings generated during the task.", "items": { "type": "string" }, "type": "array" } }, "required": [ "task_id", "url", "status", "data", "metadata" ], "type": "object" } } }, "description": "Successful Response" }, "404": { "content": { "application/json": { "schema": { "additionalProperties": {}, "properties": { "msg": { "examples": [ "Template not found" ], "type": "string" }, "status": { "const": "failed", "type": "string" } }, "required": [ "status", "msg" ], "type": "object" } } }, "description": "Template Not Found" } }, "security": [ { "BearerAuth": [] } ], "tags": [ "Extract Templates API" ], "summary": "Run Extract Template", "operationId": "runExtractTemplate" } }, "/v2/extract/templates/async": { "post": { "description": "Execute Extract Template Async Endpoint", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ExtractionTemplateBody" }, { "properties": { "callback_url": { "description": "URL to call back when async operation completes", "examples": [ "https://example.com/webhook/callback" ], "type": "string" }, "storage_compress": { "description": "Whether to compress stored data", "examples": [ true ], "type": "boolean" }, "storage_object_name": { "description": "Custom name for the stored object", "examples": [ "result-2024-01-15.json" ], "type": "string" }, "storage_type": { "description": "Type of storage to use for results", "examples": [ "s3" ], "type": "string" }, "storage_url": { "description": "URL for storage location", "examples": [ "s3://bucket-name/path/to/object" ], "type": "string" } }, "type": "object" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "status": { "const": "success", "type": "string" }, "task": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "status", "task" ], "type": "object" } } }, "description": "Async Task Created" } }, "security": [ { "BearerAuth": [] } ], "tags": [ "Extract Templates API" ], "summary": "Run Extract Template (Async)", "operationId": "runExtractTemplateAsync" } }, "/v2/extract/templates/batch": { "post": { "description": "Execute Extract Template Batch Endpoint", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractionTemplateBatchBody" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractBatchResponse" } } }, "description": "Batch Created" } }, "security": [ { "BearerAuth": [] } ], "tags": [ "Extract Templates API" ], "summary": "Run Extract Template (Batch)", "operationId": "runExtractTemplateBatch" } }, "/v2/extract/templates": { "get": { "operationId": "listExtractTemplates", "parameters": [ { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_ExtractTemplateResponsePublicV2_" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List Extract Templates", "tags": [ "Extract Templates API" ] } }, "/v2/extract/templates/{extract_template_name}": { "delete": { "operationId": "deleteExtractTemplate", "parameters": [ { "in": "path", "name": "extract_template_name", "required": true, "schema": { "title": "Extract Template Name", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Delete Extract Template", "tags": [ "Extract Templates API" ] }, "get": { "operationId": "getExtractTemplate", "parameters": [ { "in": "path", "name": "extract_template_name", "required": true, "schema": { "title": "Extract Template Name", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractTemplateResponsePublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Extract Template", "tags": [ "Extract Templates API" ] }, "patch": { "operationId": "updateExtractTemplate", "parameters": [ { "in": "path", "name": "extract_template_name", "required": true, "schema": { "title": "Extract Template Name", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonPatchDocument" } }, "application/json-patch+json": { "schema": { "$ref": "#/components/schemas/JsonPatchDocument" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractTemplateResponsePublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update Extract Template", "tags": [ "Extract Templates API" ] } }, "/v2/extract/templates/{extract_template_name}/versions": { "get": { "operationId": "listExtractTemplateVersions", "parameters": [ { "in": "path", "name": "extract_template_name", "required": true, "schema": { "title": "Extract Template Name", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_ExtractTemplateVersionResponsePublicV2_" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List Extract Template Versions", "tags": [ "Extract Templates API" ] } }, "/v2/extract/templates/{extract_template_name}/versions/{version_id}": { "get": { "operationId": "getExtractTemplateVersion", "parameters": [ { "in": "path", "name": "extract_template_name", "required": true, "schema": { "title": "Extract Template Name", "type": "string" } }, { "in": "path", "name": "version_id", "required": true, "schema": { "format": "uuid", "title": "Version Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractTemplateVersionResponsePublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Extract Template Version", "tags": [ "Extract Templates API" ] } }, "/v2/extract/templates/generations": { "post": { "operationId": "generateExtractTemplate", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CreateExtractTemplateGenerationRequestPublicV2" }, { "$ref": "#/components/schemas/CreateExtractTemplateRefinementRequestPublicV2" } ], "title": "Request" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractTemplateGenerationResponsePublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create Extract Template Generation", "tags": [ "Extract Templates API" ] } }, "/v2/extract/templates/generations/{generation_id}": { "get": { "operationId": "getExtractTemplateGeneration", "parameters": [ { "in": "path", "name": "generation_id", "required": true, "schema": { "format": "uuid", "title": "Generation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractTemplateGenerationResponsePublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Extract Template Generation", "tags": [ "Extract Templates API" ] } }, "/v2/tasks": { "get": { "description": "Retrieve a paginated list of tasks for the authenticated account.", "parameters": [ { "description": "Cursor for pagination. Use the next_cursor from the previous response.", "in": "query", "name": "cursor", "schema": { "description": "Cursor for pagination. Use the next_cursor from the previous response.", "format": "uuid", "type": "string" } }, { "description": "Number of tasks to return per page.", "in": "query", "name": "limit", "schema": { "default": 100, "description": "Number of tasks to return per page.", "examples": [ 10 ], "maximum": 9007199254740991, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskListResponse" } } }, "description": "List of tasks returned successfully." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskErrorResponse" } } }, "description": "Invalid query parameters." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskErrorResponse" } } }, "description": "Internal server error while retrieving tasks." } }, "security": [ { "BearerAuth": [] } ], "summary": "List tasks", "tags": [ "Tasks" ] } }, "/v2/tasks/{task_id}": { "get": { "description": "Retrieve the details of a specific task by its ID.", "parameters": [ { "description": "The unique identifier of the task.", "in": "path", "name": "task_id", "required": true, "schema": { "description": "The unique identifier of the task.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponseSchema" } } }, "description": "Task found and returned successfully." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskNotFoundErrorResponse" } } }, "description": "Task not found." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskErrorResponse" } } }, "description": "Internal server error while retrieving task." } }, "security": [ { "BearerAuth": [] } ], "summary": "Task Status", "tags": [ "Tasks" ] } }, "/v2/tasks/{task_id}/results": { "get": { "description": "Retrieve the results of a completed task.", "parameters": [ { "description": "The unique identifier of the task.", "in": "path", "name": "task_id", "required": true, "schema": { "description": "The unique identifier of the task.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": {}, "description": "The results of the completed task.", "propertyNames": { "type": "string" }, "type": "object" } } }, "description": "Task results" }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskPendingResponse" } } }, "description": "Task is still pending and results are not yet available." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskErrorResponse" } } }, "description": "Task not found or results are no longer available." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskFailedResponse" } } }, "description": "Task failed or error retrieving results." } }, "security": [ { "BearerAuth": [] } ], "summary": "Task Result", "tags": [ "Tasks" ] } }, "/v2/batches": { "get": { "description": "Retrieve a paginated list of batches for the authenticated account.", "responses": { "200": { "description": "List of batches returned successfully." } }, "security": [ { "BearerAuth": [] } ], "summary": "List batches", "tags": [ "Tasks" ] } }, "/v2/batches/{batch_id}": { "get": { "description": "Retrieve the details of a batch including all its tasks and completion status.", "parameters": [ { "description": "The unique identifier of the batch.", "in": "path", "name": "batch_id", "required": true, "schema": { "description": "The unique identifier of the batch.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchGetResponse" } } }, "description": "Batch found and returned successfully." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskErrorResponse" } } }, "description": "Batch not found." } }, "security": [ { "BearerAuth": [] } ], "summary": "Get batch details", "tags": [ "Tasks" ] } }, "/v2/batches/{batch_id}/progress": { "get": { "description": "Retrieve lightweight progress information for a batch without fetching all task details.", "parameters": [ { "description": "The unique identifier of the batch.", "in": "path", "name": "batch_id", "required": true, "schema": { "description": "The unique identifier of the batch.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchProgressResponse" } } }, "description": "Batch progress returned successfully." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskErrorResponse" } } }, "description": "Batch not found." } }, "security": [ { "BearerAuth": [] } ], "summary": "Get batch progress", "tags": [ "Tasks" ] } }, "/v2/agents": { "get": { "operationId": "list_agents_public_v2_api_v2_public_web_search_agents_get", "parameters": [ { "in": "query", "name": "workspace_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Workspace Id" }, "description": "Only return agents belonging to this workspace. Defaults to the workspace resolved from your token." }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" }, "description": "Number of items to skip before this page." }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" }, "description": "Maximum number of items to return (1-200)." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_WebSearchAgentResponsePublicV2_" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "List Agents", "tags": [ "Public API" ], "description": "List the active Web Search Agents in your account. Results are scoped to the workspace resolved from your token (or the optional `workspace_id` query parameter) and paginated with `offset`/`limit`." }, "post": { "operationId": "create_agent_public_v2_api_v2_public_web_search_agents_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchAgentCreateRequestPublicV2" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchAgentResponsePublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Create Agent", "tags": [ "Public API" ], "description": "Create a Web Search Agent. Either pass `template` to materialize a pre-built template (its fields, goals, sources, and suggested questions are copied), or define the agent from scratch with `display_name`, `goals`, `sources`, and an optional `output_schema` for structured results.", "security": [ { "BearerAuth": [] } ] } }, "/v2/agents/runs": { "post": { "description": "Creates a minimal persistent Web Search Agent and starts a run for it. The response includes `web_search_agent_id` for later agent and run queries.", "operationId": "create_run_with_generated_agent_public_v2_api_v2_public_web_search_agents_runs_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchAgentRunCreateRequestPublicV2" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRunResponsePublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "APIKeyCookie": [] } ], "summary": "Create Run", "tags": [ "Public API" ] } }, "/v2/agents/templates": { "get": { "operationId": "list_templates_public_v2_api_v2_public_web_search_agents_templates_get", "parameters": [ { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" }, "description": "Number of items to skip before this page." }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" }, "description": "Maximum number of items to return (1-200)." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_WebSearchAgentTemplateResponsePublicV2_" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "List Agent Templates", "tags": [ "Public API" ], "description": "List the pre-built agent templates available to your account. Use a template's `template_name` with `POST /v2/agents` to create an agent instance from it." } }, "/v2/agents/templates/{template_name}": { "get": { "operationId": "get_template_public_v2_api_v2_public_web_search_agents_templates__template_name__get", "parameters": [ { "in": "path", "name": "template_name", "required": true, "schema": { "title": "Template Name", "type": "string" }, "description": "Stable template name, e.g. `linkedin_company_profiles`." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchAgentTemplateResponsePublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "404": { "description": "Template not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "title": "Detail" } }, "title": "ErrorDetail" }, "example": { "detail": "Template 'linkedin_company_profiles' not found" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Get Agent Template", "tags": [ "Public API" ], "description": "Retrieve a single agent template by its stable `template_name`." } }, "/v2/agents/{agent_id}": { "delete": { "operationId": "deactivate_agent_public_v2_api_v2_public_web_search_agents__agent_id__delete", "parameters": [ { "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "title": "Agent Id", "type": "string" }, "description": "Web Search Agent ID, format `wsa_`." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "404": { "description": "Agent not found (or not owned by your account).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "title": "Detail" } }, "title": "ErrorDetail" }, "example": { "detail": "Web Search Agent wsa_2af5b0e2-58b8-4b60-a1a4-9e57e4d33f00 not found" } } } } }, "summary": "Deactivate Agent", "tags": [ "Public API" ], "description": "Deactivate an agent. This is a soft delete: the agent can no longer start new runs, but its existing runs and their results remain retrievable.", "security": [ { "BearerAuth": [] } ] }, "get": { "operationId": "get_agent_public_v2_api_v2_public_web_search_agents__agent_id__get", "parameters": [ { "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "title": "Agent Id", "type": "string" }, "description": "Web Search Agent ID, format `wsa_`." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchAgentResponsePublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "404": { "description": "Agent not found (or not owned by your account).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "title": "Detail" } }, "title": "ErrorDetail" }, "example": { "detail": "Web Search Agent wsa_2af5b0e2-58b8-4b60-a1a4-9e57e4d33f00 not found" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Get Agent", "tags": [ "Public API" ], "description": "Retrieve a single Web Search Agent by ID." }, "patch": { "operationId": "update_agent_public_v2_api_v2_public_web_search_agents__agent_id__patch", "parameters": [ { "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "title": "Agent Id", "type": "string" }, "description": "Web Search Agent ID, format `wsa_`." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonPatchDocument" } }, "application/json-patch+json": { "schema": { "$ref": "#/components/schemas/JsonPatchDocument" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchAgentResponsePublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "404": { "description": "Agent not found (or not owned by your account).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "title": "Detail" } }, "title": "ErrorDetail" }, "example": { "detail": "Web Search Agent wsa_2af5b0e2-58b8-4b60-a1a4-9e57e4d33f00 not found" } } } } }, "summary": "Update Agent", "tags": [ "Public API" ], "description": "Update an agent with a [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) document — an array of `{op, path, value}` operations applied to the agent, e.g. `[{\"op\": \"replace\", \"path\": \"/display_name\", \"value\": \"My agent\"}]`. Returns the updated agent.", "security": [ { "BearerAuth": [] } ] } }, "/v2/agents/{agent_id}/runs": { "get": { "operationId": "list_runs_public_v2_api_v2_public_web_search_agents__agent_id__runs_get", "parameters": [ { "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "title": "Agent Id", "type": "string" }, "description": "Web Search Agent ID, format `wsa_`." }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" }, "description": "Number of items to skip before this page." }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" }, "description": "Maximum number of items to return (1-200)." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_TaskRunResponsePublicV2_" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "404": { "description": "Agent not found (or not owned by your account).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "title": "Detail" } }, "title": "ErrorDetail" }, "example": { "detail": "Web Search Agent wsa_2af5b0e2-58b8-4b60-a1a4-9e57e4d33f00 not found" } } } } }, "summary": "List Agent Runs", "tags": [ "Public API" ], "description": "List the runs of an agent, newest first, paginated with `offset`/`limit`.", "security": [ { "BearerAuth": [] } ] }, "post": { "operationId": "create_run_public_v2_api_v2_public_web_search_agents__agent_id__runs_post", "parameters": [ { "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "title": "Agent Id", "type": "string" }, "description": "Web Search Agent ID, format `wsa_`." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchAgentRunCreateRequestPublicV2" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRunResponsePublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "404": { "description": "Agent not found, not owned by your account, or deactivated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "title": "Detail" } }, "title": "ErrorDetail" }, "example": { "detail": "Web Search Agent wsa_2af5b0e2-58b8-4b60-a1a4-9e57e4d33f00 is not active" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Create Agent Run", "tags": [ "Public API" ], "description": "Start an agent run. The run executes asynchronously: the response returns immediately with status `queued`, then poll `GET .../runs/{run_id}` until `completed` and fetch the output from `GET .../runs/{run_id}/result` — or set `enable_events: true` and follow `GET .../runs/{run_id}/events` for live progress.\n\nTo enrich existing records instead of researching from scratch, pass them in `input_data`; this requires an `output_schema` (on the request or the agent)." } }, "/v2/agents/{agent_id}/runs/{run_id}": { "get": { "operationId": "get_run_public_v2_api_v2_public_web_search_agents__agent_id__runs__run_id__get", "parameters": [ { "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "title": "Agent Id", "type": "string" }, "description": "Web Search Agent ID, format `wsa_`." }, { "in": "path", "name": "run_id", "required": true, "schema": { "title": "Run Id", "type": "string" }, "description": "Run ID, format `task_run_`." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRunResponsePublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "404": { "description": "Run not found for this agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "title": "Detail" } }, "title": "ErrorDetail" }, "example": { "detail": "Run 'task_run_c0ffee00-0000-4000-8000-000000000000' not found for agent wsa_2af5b0e2-58b8-4b60-a1a4-9e57e4d33f00" } } } } }, "summary": "Get Agent Run", "tags": [ "Public API" ], "description": "Retrieve a run's current state. Poll this endpoint after creating a run: the run is finished once `status` is `completed`, `failed`, or `cancelled`.", "security": [ { "BearerAuth": [] } ] } }, "/v2/agents/{agent_id}/runs/{run_id}/events": { "get": { "operationId": "stream_run_events_public_v2_api_v2_public_web_search_agents__agent_id__runs__run_id__events_get", "parameters": [ { "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "title": "Agent Id", "type": "string" }, "description": "Web Search Agent ID, format `wsa_`." }, { "in": "path", "name": "run_id", "required": true, "schema": { "title": "Run Id", "type": "string" }, "description": "Run ID, format `task_run_`." } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string", "title": "Event stream" }, "example": "data: {\"type\": \"progress\", \"message\": \"Searching linkedin.com\"}\n\n" } }, "description": "Server-sent event stream of run activity." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "404": { "description": "Run not found for this agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "title": "Detail" } }, "title": "ErrorDetail" }, "example": { "detail": "Run 'task_run_c0ffee00-0000-4000-8000-000000000000' not found for agent wsa_2af5b0e2-58b8-4b60-a1a4-9e57e4d33f00" } } } } }, "summary": "Stream Agent Run Events", "tags": [ "Public API" ], "description": "Stream a run's progress as [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) (`text/event-stream`). Create the run with `enable_events: true` to have events published. A keep-alive comment is sent every 15 seconds.", "security": [ { "BearerAuth": [] } ] } }, "/v2/agents/{agent_id}/runs/{run_id}/result": { "get": { "operationId": "get_run_result_public_v2_api_v2_public_web_search_agents__agent_id__runs__run_id__result_get", "parameters": [ { "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "title": "Agent Id", "type": "string" }, "description": "Web Search Agent ID, format `wsa_`." }, { "in": "path", "name": "run_id", "required": true, "schema": { "title": "Run Id", "type": "string" }, "description": "Run ID, format `task_run_`." } ], "responses": { "200": { "description": "Run completed; the output is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRunResultPublicV2" } } } }, "422": { "description": "The run failed or was cancelled. `detail` carries the run and its error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "$ref": "#/components/schemas/TaskRunFailedResultPublicV2" } }, "title": "FailedRunDetail" } } } }, "404": { "description": "Run not found for this agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "title": "Detail" } }, "title": "ErrorDetail" }, "example": { "detail": "Run 'task_run_c0ffee00-0000-4000-8000-000000000000' not found for agent wsa_2af5b0e2-58b8-4b60-a1a4-9e57e4d33f00" } } } }, "409": { "description": "Run is still queued or running. Poll `GET .../runs/{run_id}` until `status` is `completed`, then retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "title": "Detail" } }, "title": "ErrorDetail" }, "example": { "detail": "Run still active; poll the run status endpoint (GET .../runs/task_run_c0ffee00-0000-4000-8000-000000000000) until completed" } } } } }, "summary": "Get Agent Run Result", "tags": [ "Public API" ], "description": "Fetch the output of a completed run. The `output` is `type: \"text\"` (a prose answer) or `type: \"json\"` (structured data matching the output schema), plus `trust` metadata with per-claim citations for the answer.\n\nWhile the run is still `queued` or `running` this endpoint returns `409`; if the run `failed` or was `cancelled` it returns `422` with the run and error details.", "security": [ { "BearerAuth": [] } ] } }, "/v2/jobs": { "get": { "operationId": "list_jobs_public_v2_api_v2_public_jobs_get", "parameters": [ { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_JobPublicV2_" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "List Jobs", "tags": [ "Jobs" ] }, "post": { "operationId": "create_job_public_v2_api_v2_public_jobs_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobRequestPublicV2" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create Job", "tags": [ "Jobs" ] } }, "/v2/jobs/runs/{run_id}": { "get": { "operationId": "get_run_public_v2_api_v2_public_jobs_runs__run_id__get", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "title": "Run Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRunDetailPublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get Run", "tags": [ "Jobs" ] } }, "/v2/jobs/runs/{run_id}/artifacts": { "get": { "operationId": "list_run_artifacts_public_v2_api_v2_public_jobs_runs__run_id__artifacts_get", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "title": "Run Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactListPublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "List Run Artifacts", "tags": [ "Jobs" ] } }, "/v2/jobs/runs/{run_id}/artifacts/{artifact_id}": { "get": { "operationId": "get_run_artifact_public_v2_api_v2_public_jobs_runs__run_id__artifacts__artifact_id__get", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "title": "Run Id", "type": "string" } }, { "in": "path", "name": "artifact_id", "required": true, "schema": { "title": "Artifact Id", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactPublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get Run Artifact", "tags": [ "Jobs" ] } }, "/v2/jobs/runs/{run_id}/artifacts/{artifact_id}/download-url": { "get": { "operationId": "get_run_artifact_download_url_public_v2_api_v2_public_jobs_runs__run_id__artifacts__artifact_id__download_url_get", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "title": "Run Id", "type": "string" } }, { "in": "path", "name": "artifact_id", "required": true, "schema": { "title": "Artifact Id", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactDownloadUrlPublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get Run Artifact Download URL", "tags": [ "Jobs" ] } }, "/v2/jobs/runs/{run_id}/artifacts/{artifact_id}/preview": { "get": { "operationId": "preview_run_artifact_public_v2_api_v2_public_jobs_runs__run_id__artifacts__artifact_id__preview_get", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "title": "Run Id", "type": "string" } }, { "in": "path", "name": "artifact_id", "required": true, "schema": { "title": "Artifact Id", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactPreviewPublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Preview Run Artifact", "tags": [ "Jobs" ] } }, "/v2/jobs/runs/{run_id}/cancel": { "post": { "operationId": "cancel_run_public_v2_api_v2_public_jobs_runs__run_id__cancel_post", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "title": "Run Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRunCancelResponsePublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Cancel Run", "tags": [ "Jobs" ] } }, "/v2/jobs/{job_id}": { "delete": { "operationId": "delete_job_public_v2_api_v2_public_jobs__job_id__delete", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete Job", "tags": [ "Jobs" ] }, "get": { "operationId": "get_job_public_v2_api_v2_public_jobs__job_id__get", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get Job", "tags": [ "Jobs" ] }, "patch": { "operationId": "update_job_public_v2_api_v2_public_jobs__job_id__patch", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJobRequestPublicV2" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update Job", "tags": [ "Jobs" ] } }, "/v2/jobs/{job_id}/runs": { "get": { "operationId": "list_job_runs_public_v2_api_v2_public_jobs__job_id__runs_get", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_JobRunPublicV2_" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "List Runs for Job", "tags": [ "Jobs" ] }, "post": { "operationId": "trigger_job_run_public_v2_api_v2_public_jobs__job_id__runs_post", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRunPublicV2" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Trigger Run", "tags": [ "Jobs" ] } }, "/v2/crawl": { "get": { "parameters": [ { "description": "Filter crawls by their status.", "in": "query", "name": "status", "schema": { "default": "all", "description": "Filter crawls by their status.", "enum": [ "queued", "running", "succeeded", "failed", "canceled", "all" ], "examples": [ "queued" ], "type": "string" } }, { "description": "Cursor for pagination.", "in": "query", "name": "cursor", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Cursor for pagination." } }, { "description": "Number of crawls to return per page.", "in": "query", "name": "limit", "schema": { "default": 100, "description": "Number of crawls to return per page.", "examples": [ 10 ], "maximum": 9007199254740991, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlByFiltersResponse" } } }, "description": "Successful Response - List of Crawl Tasks" } }, "security": [ { "BearerAuth": [] } ], "summary": "List Crawls", "tags": [ "Crawl" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlPayload" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlApiResponse" } } }, "description": "Successful Response - Crawl Task Created" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create Crawl", "tags": [ "Crawl" ] } }, "/v2/crawl/{id}": { "delete": { "parameters": [ { "description": "The unique identifier of the crawl task.", "in": "path", "name": "id", "required": true, "schema": { "description": "The unique identifier of the crawl task.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "status": { "enum": [ "canceled" ], "type": "string" } }, "required": [ "status" ], "type": "object" } } }, "description": "Successful Response" }, "404": { "description": "Crawl Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Cancel Crawl", "tags": [ "Crawl" ] }, "get": { "parameters": [ { "description": "The unique identifier of the crawl task.", "in": "path", "name": "id", "required": true, "schema": { "description": "The unique identifier of the crawl task.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlApiResponse" } } }, "description": "Successful Response" } }, "security": [ { "BearerAuth": [] } ], "summary": "Crawl by ID", "tags": [ "Crawl" ] } }, "/v2/domain-knowledge/driver": { "get": { "description": "Resolves the suggested driver for a given URL or agent name. Exactly one of `url` or `agent` must be provided.", "parameters": [ { "description": "Target domain to resolve driver for (e.g. amazon.com).", "in": "query", "name": "url", "schema": { "description": "Target domain to resolve driver for (e.g. amazon.com).", "examples": [ "amazon.com" ], "type": "string" } }, { "description": "Agent name to resolve driver for (e.g. nimble-ecommerce).", "in": "query", "name": "agent", "schema": { "description": "Agent name to resolve driver for (e.g. nimble-ecommerce).", "examples": [ "nimble-ecommerce" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriverResolutionResponse" } } }, "description": "Driver resolution result" }, "400": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "msg": { "type": "string" }, "status": { "const": "failed", "type": "string" } }, "required": [ "status", "msg" ], "type": "object" } } }, "description": "Bad Request — both or neither url/agent provided" }, "404": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "msg": { "type": "string" }, "status": { "const": "failed", "type": "string" } }, "required": [ "status", "msg" ], "type": "object" } } }, "description": "Agent not found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get Driver", "tags": [ "Domain Knowledge" ] } }, "/v2/extract": { "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractPayload" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "browser_actions": { "additionalProperties": false, "description": "Browser actions execution results. Present only when browser_actions were specified in the request.", "properties": { "results": { "items": { "additionalProperties": false, "properties": { "duration": { "minimum": 0, "type": "number" }, "error": { "type": "string" }, "name": { "enum": [ "goto", "wait", "wait_for_element", "wait_for_navigation", "click", "fill", "press", "scroll", "auto_scroll", "screenshot", "get_cookies", "eval", "fetch" ], "type": "string" }, "result": {}, "status": { "enum": [ "no-run", "in-progress", "done", "error", "skipped" ], "type": "string" } }, "required": [ "name", "status", "duration" ], "type": "object" }, "readOnly": true, "type": "array" }, "success": { "type": "boolean" }, "total_duration": { "minimum": 0, "type": "number" } }, "required": [ "success", "results", "total_duration" ], "type": "object" }, "cookies": { "description": "The cookies collected from browser actions during the task.", "items": {}, "type": "array" }, "eval": { "description": "The evaluation results from browser actions during the task.", "items": {}, "type": "array" }, "fetch": { "description": "The http requests from browser actions made during the task.", "items": {}, "type": "array" }, "headers": { "additionalProperties": { "type": "string" }, "description": "The headers received during the task.", "propertyNames": { "type": "string" }, "type": "object" }, "html": { "description": "The HTML content of the page.", "type": "string" }, "links": { "description": "List of all unique URLs found on the page.", "items": { "type": "string" }, "type": "array" }, "markdown": { "description": "The Markdown version of the HTML content.", "type": "string" }, "network_capture": { "description": "The network capture data collected during the task.", "items": { "additionalProperties": false, "properties": { "errorMessage": { "type": "string" }, "filter": { "additionalProperties": false, "properties": { "method": { "enum": [ "GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH" ], "type": "string" }, "resource_type": { "anyOf": [ { "description": "Resource type for network capture filtering", "enum": [ "document", "stylesheet", "image", "media", "font", "script", "texttrack", "xhr", "fetch", "prefetch", "eventsource", "websocket", "manifest", "signedexchange", "ping", "cspviolationreport", "preflight", "other", "fedcm" ], "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, { "items": { "description": "Resource type for network capture filtering", "enum": [ "document", "stylesheet", "image", "media", "font", "script", "texttrack", "xhr", "fetch", "prefetch", "eventsource", "websocket", "manifest", "signedexchange", "ping", "cspviolationreport", "preflight", "other", "fedcm" ], "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, "minItems": 1, "type": "array" } ] }, "status_code": { "anyOf": [ { "maximum": 599, "minimum": 100, "type": "number" }, { "items": { "maximum": 599, "minimum": 100, "type": "number" }, "minItems": 1, "type": "array" } ] }, "url": { "additionalProperties": false, "properties": { "type": { "default": "exact", "enum": [ "exact", "contains" ], "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "validation": { "default": false, "type": "boolean" }, "wait_for_requests_count": { "default": 0, "minimum": 0, "type": "number" }, "wait_for_requests_count_timeout": { "exclusiveMinimum": 0, "maximum": 300000, "type": "number" } }, "required": [ "validation", "wait_for_requests_count" ], "type": "object" }, "results": { "items": { "additionalProperties": false, "properties": { "request": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "headers": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "method": { "type": "string" }, "resource_type": { "description": "Resource type for network capture filtering", "enum": [ "document", "stylesheet", "image", "media", "font", "script", "texttrack", "xhr", "fetch", "prefetch", "eventsource", "websocket", "manifest", "signedexchange", "ping", "cspviolationreport", "preflight", "other", "fedcm" ], "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "resource_type", "method", "url", "headers" ], "type": "object" }, "response": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "headers": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "serialization": { "enum": [ "none", "base64" ], "type": "string" }, "status": { "type": "number" }, "status_text": { "type": "string" } }, "required": [ "status", "status_text", "headers", "serialization", "body" ], "type": "object" } }, "required": [ "request", "response" ], "type": "object" }, "type": "array" } }, "required": [ "filter", "results" ], "type": "object" }, "readOnly": true, "type": "array" }, "pages_html": { "description": "Individual HTML content of each pagination page, before merging.", "items": { "type": "string" }, "type": "array" }, "parsing": { "anyOf": [ { "$ref": "#/components/schemas/ParsingSuccessResult" }, { "$ref": "#/components/schemas/ParsingErrorResult" }, { "additionalProperties": {}, "propertyNames": { "type": "string" }, "type": "object" } ], "description": "The parsing results extracted from the HTML & network content." }, "redirects": { "description": "The list of redirects that occurred during the task.", "items": { "additionalProperties": false, "properties": { "status_code": { "maximum": 599, "minimum": 100, "type": "number" }, "url": { "type": "string" } }, "required": [ "status_code", "url" ], "type": "object" }, "type": "array" }, "screenshots": { "description": "Screenshots taken during the task, from browser actions, or the screenshot format.", "items": {}, "type": "array" } }, "type": "object" }, "debug": { "additionalProperties": false, "properties": { "performance_metrics": { "additionalProperties": { "type": "number" }, "description": "Performance metrics collected during the task.", "propertyNames": { "type": "string" }, "type": "object" }, "proxy_total_bytes_usage": { "description": "Total bytes used by the proxy during the task.", "minimum": 0, "type": "number" }, "transformed_output": { "description": "The transformed output after applying any transformations." }, "userbrowser": { "description": "The userbrowser instance using during the task." } }, "type": "object" }, "metadata": { "additionalProperties": false, "properties": { "agent": { "description": "The name of the agent used for the query.", "type": "string" }, "driver": { "description": "The driver used for the task.", "type": "string" }, "localization_id": { "description": "The localization identifier for the query.", "type": "string" }, "query_duration": { "description": "The duration in milliseconds of the query processing.", "type": "number" }, "query_time": { "description": "The time when the query was received.", "type": "string" }, "response_parameters": { "description": "Additional response parameters." }, "tag": { "description": "A tag associated with the query.", "type": "string" } }, "type": "object" }, "pagination": { "anyOf": [ { "additionalProperties": false, "properties": { "next_page_params": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "next_page_params" ], "type": "object" }, { "items": { "additionalProperties": false, "properties": { "next_page_params": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "next_page_params" ], "type": "object" }, "type": "array" } ], "description": "Pagination information if applicable." }, "status": { "description": "The status of the task.", "enum": [ "success", "skipped", "fatal", "error", "postponed", "ignored", "rejected", "blocked" ], "type": "string" }, "status_code": { "description": "The HTTP status code of the task.", "type": "number" }, "task_id": { "description": "Unique identifier for the task.", "type": "string" }, "url": { "description": "The final URL.", "type": "string" }, "warnings": { "description": "List of warnings generated during the task.", "items": { "type": "string" }, "type": "array" } }, "required": [ "task_id", "url", "status", "data", "metadata" ], "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "BearerAuth": [] } ], "summary": "Extract", "tags": [ "Extract" ] } }, "/v2/extract/async": { "post": { "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ExtractPayload" }, { "properties": { "callback_url": { "description": "URL to call back when async operation completes", "examples": [ "https://example.com/webhook/callback" ], "type": "string" }, "storage_compress": { "description": "Whether to compress stored data", "examples": [ true ], "type": "boolean" }, "storage_object_name": { "description": "Custom name for the stored object", "examples": [ "result-2024-01-15.json" ], "type": "string" }, "storage_type": { "description": "Type of storage to use for results", "examples": [ "s3" ], "type": "string" }, "storage_url": { "description": "URL for storage location", "examples": [ "s3://bucket-name/path/to/object" ], "type": "string" } }, "type": "object" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractAsyncResponse" } } }, "description": "Task created successfully" } }, "security": [ { "BearerAuth": [] } ], "summary": "Extract Async", "tags": [ "Extract" ] } }, "/v2/extract/batch": { "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractBatchPayload" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractBatchResponse" } } }, "description": "Batch created successfully" } }, "security": [ { "BearerAuth": [] } ], "summary": "Extract Batch", "tags": [ "Extract" ] } }, "/v2/map": { "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapPayload" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapResponse" } } }, "description": "Successful Response" } }, "security": [ { "BearerAuth": [] } ], "summary": "Map", "tags": [ "Map" ] } }, "/v2/media": { "post": { "description": "Download media from a URL. Waits for the result before responding.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaPayload" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "browser_actions": { "additionalProperties": false, "description": "Browser actions execution results. Present only when browser_actions were specified in the request.", "properties": { "results": { "items": { "additionalProperties": false, "properties": { "duration": { "minimum": 0, "type": "number" }, "error": { "type": "string" }, "name": { "enum": [ "goto", "wait", "wait_for_element", "wait_for_navigation", "click", "fill", "press", "scroll", "auto_scroll", "screenshot", "get_cookies", "eval", "fetch" ], "type": "string" }, "result": {}, "status": { "enum": [ "no-run", "in-progress", "done", "error", "skipped" ], "type": "string" } }, "required": [ "name", "status", "duration" ], "type": "object" }, "readOnly": true, "type": "array" }, "success": { "type": "boolean" }, "total_duration": { "minimum": 0, "type": "number" } }, "required": [ "success", "results", "total_duration" ], "type": "object" }, "cookies": { "description": "The cookies collected from browser actions during the task.", "items": {}, "type": "array" }, "eval": { "description": "The evaluation results from browser actions during the task.", "items": {}, "type": "array" }, "fetch": { "description": "The http requests from browser actions made during the task.", "items": {}, "type": "array" }, "headers": { "additionalProperties": { "type": "string" }, "description": "The headers received during the task.", "propertyNames": { "type": "string" }, "type": "object" }, "html": { "description": "The HTML content of the page.", "type": "string" }, "links": { "description": "List of all unique URLs found on the page.", "items": { "type": "string" }, "type": "array" }, "markdown": { "description": "The Markdown version of the HTML content.", "type": "string" }, "network_capture": { "description": "The network capture data collected during the task.", "items": { "additionalProperties": false, "properties": { "errorMessage": { "type": "string" }, "filter": { "additionalProperties": false, "properties": { "method": { "enum": [ "GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH" ], "type": "string" }, "resource_type": { "anyOf": [ { "description": "Resource type for network capture filtering", "enum": [ "document", "stylesheet", "image", "media", "font", "script", "texttrack", "xhr", "fetch", "prefetch", "eventsource", "websocket", "manifest", "signedexchange", "ping", "cspviolationreport", "preflight", "other", "fedcm" ], "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, { "items": { "description": "Resource type for network capture filtering", "enum": [ "document", "stylesheet", "image", "media", "font", "script", "texttrack", "xhr", "fetch", "prefetch", "eventsource", "websocket", "manifest", "signedexchange", "ping", "cspviolationreport", "preflight", "other", "fedcm" ], "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, "minItems": 1, "type": "array" } ] }, "status_code": { "anyOf": [ { "maximum": 599, "minimum": 100, "type": "number" }, { "items": { "maximum": 599, "minimum": 100, "type": "number" }, "minItems": 1, "type": "array" } ] }, "url": { "additionalProperties": false, "properties": { "type": { "default": "exact", "enum": [ "exact", "contains" ], "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "validation": { "default": false, "type": "boolean" }, "wait_for_requests_count": { "default": 0, "minimum": 0, "type": "number" }, "wait_for_requests_count_timeout": { "exclusiveMinimum": 0, "maximum": 300000, "type": "number" } }, "required": [ "validation", "wait_for_requests_count" ], "type": "object" }, "results": { "items": { "additionalProperties": false, "properties": { "request": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "headers": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "method": { "type": "string" }, "resource_type": { "description": "Resource type for network capture filtering", "enum": [ "document", "stylesheet", "image", "media", "font", "script", "texttrack", "xhr", "fetch", "prefetch", "eventsource", "websocket", "manifest", "signedexchange", "ping", "cspviolationreport", "preflight", "other", "fedcm" ], "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "resource_type", "method", "url", "headers" ], "type": "object" }, "response": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "headers": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "serialization": { "enum": [ "none", "base64" ], "type": "string" }, "status": { "type": "number" }, "status_text": { "type": "string" } }, "required": [ "status", "status_text", "headers", "serialization", "body" ], "type": "object" } }, "required": [ "request", "response" ], "type": "object" }, "type": "array" } }, "required": [ "filter", "results" ], "type": "object" }, "readOnly": true, "type": "array" }, "pages_html": { "description": "Individual HTML content of each pagination page, before merging.", "items": { "type": "string" }, "type": "array" }, "parsing": { "anyOf": [ { "$ref": "#/components/schemas/ParsingSuccessResult" }, { "$ref": "#/components/schemas/ParsingErrorResult" }, { "additionalProperties": {}, "propertyNames": { "type": "string" }, "type": "object" } ], "description": "The parsing results extracted from the HTML & network content." }, "redirects": { "description": "The list of redirects that occurred during the task.", "items": { "additionalProperties": false, "properties": { "status_code": { "maximum": 599, "minimum": 100, "type": "number" }, "url": { "type": "string" } }, "required": [ "status_code", "url" ], "type": "object" }, "type": "array" }, "screenshots": { "description": "Screenshots taken during the task, from browser actions, or the screenshot format.", "items": {}, "type": "array" } }, "type": "object" }, "debug": { "additionalProperties": false, "properties": { "performance_metrics": { "additionalProperties": { "type": "number" }, "description": "Performance metrics collected during the task.", "propertyNames": { "type": "string" }, "type": "object" }, "proxy_total_bytes_usage": { "description": "Total bytes used by the proxy during the task.", "minimum": 0, "type": "number" }, "transformed_output": { "description": "The transformed output after applying any transformations." }, "userbrowser": { "description": "The userbrowser instance using during the task." } }, "type": "object" }, "metadata": { "additionalProperties": false, "properties": { "agent": { "description": "The name of the agent used for the query.", "type": "string" }, "driver": { "description": "The driver used for the task.", "type": "string" }, "localization_id": { "description": "The localization identifier for the query.", "type": "string" }, "query_duration": { "description": "The duration in milliseconds of the query processing.", "type": "number" }, "query_time": { "description": "The time when the query was received.", "type": "string" }, "response_parameters": { "description": "Additional response parameters." }, "tag": { "description": "A tag associated with the query.", "type": "string" } }, "type": "object" }, "pagination": { "anyOf": [ { "additionalProperties": false, "properties": { "next_page_params": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "next_page_params" ], "type": "object" }, { "items": { "additionalProperties": false, "properties": { "next_page_params": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "next_page_params" ], "type": "object" }, "type": "array" } ], "description": "Pagination information if applicable." }, "status": { "description": "The status of the task.", "enum": [ "success", "skipped", "fatal", "error", "postponed", "ignored", "rejected", "blocked" ], "type": "string" }, "status_code": { "description": "The HTTP status code of the task.", "type": "number" }, "task_id": { "description": "Unique identifier for the task.", "type": "string" }, "url": { "description": "The final URL.", "type": "string" }, "warnings": { "description": "List of warnings generated during the task.", "items": { "type": "string" }, "type": "array" } }, "required": [ "task_id", "url", "status", "data", "metadata" ], "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "BearerAuth": [] } ], "summary": "Media Download", "tags": [ "Media" ] } }, "/v2/media/async": { "post": { "description": "Download media from a URL asynchronously. Returns a task ID immediately.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaAsyncPayload" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaAsyncResponse" } } }, "description": "Task created successfully" } }, "security": [ { "BearerAuth": [] } ], "summary": "Media Download Async", "tags": [ "Media" ] } }, "/v2/search": { "post": { "operationId": "search_search_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }, "description": "Successful Response" } }, "security": [ { "BearerAuth": [] } ], "summary": "Search", "tags": [ "Search" ] } }, "/v2/serp": { "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerpPayload" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "browser_actions": { "additionalProperties": false, "description": "Browser actions execution results. Present only when browser_actions were specified in the request.", "properties": { "results": { "items": { "additionalProperties": false, "properties": { "duration": { "minimum": 0, "type": "number" }, "error": { "type": "string" }, "name": { "enum": [ "goto", "wait", "wait_for_element", "wait_for_navigation", "click", "fill", "press", "scroll", "auto_scroll", "screenshot", "get_cookies", "eval", "fetch" ], "type": "string" }, "result": {}, "status": { "enum": [ "no-run", "in-progress", "done", "error", "skipped" ], "type": "string" } }, "required": [ "name", "status", "duration" ], "type": "object" }, "readOnly": true, "type": "array" }, "success": { "type": "boolean" }, "total_duration": { "minimum": 0, "type": "number" } }, "required": [ "success", "results", "total_duration" ], "type": "object" }, "cookies": { "description": "The cookies collected from browser actions during the task.", "items": {}, "type": "array" }, "eval": { "description": "The evaluation results from browser actions during the task.", "items": {}, "type": "array" }, "fetch": { "description": "The http requests from browser actions made during the task.", "items": {}, "type": "array" }, "headers": { "additionalProperties": { "type": "string" }, "description": "The headers received during the task.", "propertyNames": { "type": "string" }, "type": "object" }, "html": { "description": "The HTML content of the page.", "type": "string" }, "links": { "description": "List of all unique URLs found on the page.", "items": { "type": "string" }, "type": "array" }, "markdown": { "description": "The Markdown version of the HTML content.", "type": "string" }, "network_capture": { "description": "The network capture data collected during the task.", "items": { "additionalProperties": false, "properties": { "errorMessage": { "type": "string" }, "filter": { "additionalProperties": false, "properties": { "method": { "enum": [ "GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH" ], "type": "string" }, "resource_type": { "anyOf": [ { "description": "Resource type for network capture filtering", "enum": [ "document", "stylesheet", "image", "media", "font", "script", "texttrack", "xhr", "fetch", "prefetch", "eventsource", "websocket", "manifest", "signedexchange", "ping", "cspviolationreport", "preflight", "other", "fedcm" ], "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, { "items": { "description": "Resource type for network capture filtering", "enum": [ "document", "stylesheet", "image", "media", "font", "script", "texttrack", "xhr", "fetch", "prefetch", "eventsource", "websocket", "manifest", "signedexchange", "ping", "cspviolationreport", "preflight", "other", "fedcm" ], "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, "minItems": 1, "type": "array" } ] }, "status_code": { "anyOf": [ { "maximum": 599, "minimum": 100, "type": "number" }, { "items": { "maximum": 599, "minimum": 100, "type": "number" }, "minItems": 1, "type": "array" } ] }, "url": { "additionalProperties": false, "properties": { "type": { "default": "exact", "enum": [ "exact", "contains" ], "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "validation": { "default": false, "type": "boolean" }, "wait_for_requests_count": { "default": 0, "minimum": 0, "type": "number" }, "wait_for_requests_count_timeout": { "exclusiveMinimum": 0, "maximum": 300000, "type": "number" } }, "required": [ "validation", "wait_for_requests_count" ], "type": "object" }, "results": { "items": { "additionalProperties": false, "properties": { "request": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "headers": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "method": { "type": "string" }, "resource_type": { "description": "Resource type for network capture filtering", "enum": [ "document", "stylesheet", "image", "media", "font", "script", "texttrack", "xhr", "fetch", "prefetch", "eventsource", "websocket", "manifest", "signedexchange", "ping", "cspviolationreport", "preflight", "other", "fedcm" ], "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "resource_type", "method", "url", "headers" ], "type": "object" }, "response": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "headers": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "serialization": { "enum": [ "none", "base64" ], "type": "string" }, "status": { "type": "number" }, "status_text": { "type": "string" } }, "required": [ "status", "status_text", "headers", "serialization", "body" ], "type": "object" } }, "required": [ "request", "response" ], "type": "object" }, "type": "array" } }, "required": [ "filter", "results" ], "type": "object" }, "readOnly": true, "type": "array" }, "pages_html": { "description": "Individual HTML content of each pagination page, before merging.", "items": { "type": "string" }, "type": "array" }, "parsing": { "anyOf": [ { "$ref": "#/components/schemas/ParsingSuccessResult" }, { "$ref": "#/components/schemas/ParsingErrorResult" }, { "additionalProperties": {}, "propertyNames": { "type": "string" }, "type": "object" } ], "description": "The parsing results extracted from the HTML & network content." }, "redirects": { "description": "The list of redirects that occurred during the task.", "items": { "additionalProperties": false, "properties": { "status_code": { "maximum": 599, "minimum": 100, "type": "number" }, "url": { "type": "string" } }, "required": [ "status_code", "url" ], "type": "object" }, "type": "array" }, "screenshots": { "description": "Screenshots taken during the task, from browser actions, or the screenshot format.", "items": {}, "type": "array" } }, "type": "object" }, "debug": { "additionalProperties": false, "properties": { "performance_metrics": { "additionalProperties": { "type": "number" }, "description": "Performance metrics collected during the task.", "propertyNames": { "type": "string" }, "type": "object" }, "proxy_total_bytes_usage": { "description": "Total bytes used by the proxy during the task.", "minimum": 0, "type": "number" }, "transformed_output": { "description": "The transformed output after applying any transformations." }, "userbrowser": { "description": "The userbrowser instance using during the task." } }, "type": "object" }, "metadata": { "additionalProperties": false, "properties": { "agent": { "description": "The name of the agent used for the query.", "type": "string" }, "driver": { "description": "The driver used for the task.", "type": "string" }, "localization_id": { "description": "The localization identifier for the query.", "type": "string" }, "query_duration": { "description": "The duration in milliseconds of the query processing.", "type": "number" }, "query_time": { "description": "The time when the query was received.", "type": "string" }, "response_parameters": { "description": "Additional response parameters." }, "tag": { "description": "A tag associated with the query.", "type": "string" } }, "type": "object" }, "pagination": { "anyOf": [ { "additionalProperties": false, "properties": { "next_page_params": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "next_page_params" ], "type": "object" }, { "items": { "additionalProperties": false, "properties": { "next_page_params": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "next_page_params" ], "type": "object" }, "type": "array" } ], "description": "Pagination information if applicable." }, "status": { "description": "The status of the task.", "enum": [ "success", "skipped", "fatal", "error", "postponed", "ignored", "rejected", "blocked" ], "type": "string" }, "status_code": { "description": "The HTTP status code of the task.", "type": "number" }, "task_id": { "description": "Unique identifier for the task.", "type": "string" }, "url": { "description": "The final URL.", "type": "string" }, "warnings": { "description": "List of warnings generated during the task.", "items": { "type": "string" }, "type": "array" } }, "required": [ "task_id", "url", "status", "data", "metadata" ], "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "BearerAuth": [] } ], "summary": "SERP", "tags": [ "SERP" ] } }, "/v2/serp/async": { "post": { "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SerpPayload" }, { "properties": { "callback_url": { "description": "URL to call back when async operation completes", "examples": [ "https://example.com/webhook/callback" ], "type": "string" }, "storage_compress": { "description": "Whether to compress stored data", "examples": [ true ], "type": "boolean" }, "storage_object_name": { "description": "Custom name for the stored object", "examples": [ "result-2024-01-15.json" ], "type": "string" }, "storage_type": { "description": "Type of storage to use for results", "examples": [ "s3" ], "type": "string" }, "storage_url": { "description": "URL for storage location", "examples": [ "s3://bucket-name/path/to/object" ], "type": "string" } }, "type": "object" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerpAsyncResponse" } } }, "description": "Task created successfully" } }, "security": [ { "BearerAuth": [] } ], "summary": "SERP Async", "tags": [ "SERP" ] } }, "/v2/serp/batch": { "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerpBatchPayload" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerpBatchResponse" } } }, "description": "Batch created successfully" } }, "security": [ { "BearerAuth": [] } ], "summary": "SERP Batch", "tags": [ "SERP" ] } }, "/v1/domain-health/check": { "post": { "operationId": "check_domain_health", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainHealthCheckPayload" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainHealthCheckResponse" } } }, "description": "Successful Response" } }, "security": [ { "BearerAuth": [] } ], "summary": "Check Domain Health", "description": "Check whether Nimble is seeing healthy traffic to one or more domains right now, sourced from real request outcomes across Search, SERP, ecommerce, and Extract traffic.", "tags": [ "Domain Health" ] } } }, "components": { "schemas": { "DomainHealthCheckPayload": { "description": "Request body model for the domain health check endpoint", "properties": { "domains": { "description": "Domains to check, 1-100 per request. Pass the bare domain (e.g. \"walmart.com\"), not a full URL.", "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "title": "Domains", "type": "array" } }, "required": [ "domains" ], "title": "DomainHealthCheckPayload", "type": "object" }, "DomainHealthCheckResponse": { "description": "Response model for the domain health check endpoint", "properties": { "domains": { "description": "One entry per requested domain, in the order requested.", "items": { "$ref": "#/components/schemas/DomainHealthEntry" }, "title": "Domains", "type": "array" } }, "required": [ "domains" ], "title": "DomainHealthCheckResponse", "type": "object" }, "DomainHealthEntry": { "description": "Live status and trailing 6-hour trend for a single domain.", "properties": { "domain": { "description": "The domain checked.", "title": "Domain", "type": "string" }, "status": { "description": "Live status: 'up' (healthy), 'degraded' (1-2 consecutive bad windows), 'down' (3+ consecutive bad windows), or 'unknown' (fewer than 10 samples in the lookback window).", "enum": [ "up", "degraded", "down", "unknown" ], "title": "Status", "type": "string" }, "success_rate": { "description": "Success rate over the live detection window.", "title": "Success Rate", "type": "number" }, "consecutive_bad_windows": { "description": "Consecutive 10-minute windows below the success threshold.", "title": "Consecutive Bad Windows", "type": "integer" }, "history": { "description": "6 hourly buckets, most recent completed hour first.", "items": { "$ref": "#/components/schemas/DomainHealthHistoryBucket" }, "title": "History", "type": "array" } }, "required": [ "domain", "status", "success_rate", "consecutive_bad_windows", "history" ], "title": "DomainHealthEntry", "type": "object" }, "DomainHealthHistoryBucket": { "description": "One hourly bucket in a domain's trailing 6-hour trend.", "properties": { "hours_ago": { "description": "0 is the latest completed UTC hour, not the in-progress current hour.", "title": "Hours Ago", "type": "integer" }, "window_start": { "title": "Window Start", "type": "string" }, "window_end": { "title": "Window End", "type": "string" }, "status": { "description": "'up' or 'down' for this hour's own traffic, using the same threshold as live status. No consecutive-window logic at this granularity.", "enum": [ "up", "down" ], "title": "Status", "type": "string" }, "success_rate": { "title": "Success Rate", "type": "number" } }, "required": [ "hours_ago", "window_start", "window_end", "status", "success_rate" ], "title": "DomainHealthHistoryBucket", "type": "object" }, "BrowserAction": { "description": "A browser automation action. Exactly one action key must be present.", "oneOf": [ { "$ref": "#/components/schemas/AutoScrollAction" }, { "$ref": "#/components/schemas/ClickAction" }, { "$ref": "#/components/schemas/EvalAction" }, { "$ref": "#/components/schemas/FetchAction" }, { "$ref": "#/components/schemas/FillAction" }, { "$ref": "#/components/schemas/GetCookiesAction" }, { "$ref": "#/components/schemas/GotoAction" }, { "$ref": "#/components/schemas/PressAction" }, { "$ref": "#/components/schemas/ScreenshotAction" }, { "$ref": "#/components/schemas/ScrollAction" }, { "$ref": "#/components/schemas/WaitAction" }, { "$ref": "#/components/schemas/WaitForElementAction" }, { "$ref": "#/components/schemas/WaitForNavigationAction" } ] }, "TaskListResponse": { "additionalProperties": false, "description": "Paginated list of tasks response.", "properties": { "data": { "description": "Array of task objects.", "items": { "additionalProperties": false, "properties": { "_query": {}, "account_name": { "description": "Account name that owns the task.", "type": "string" }, "api_type": { "enum": [ "web", "serp", "ecommerce", "social", "media", "agent", "extract", "fast-serp", "labs" ], "type": "string" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Batch ID if this task is part of a batch.", "examples": [ "4b0a90bf-c951-42e4-95b3-a95a65ba69fc" ] }, "created_at": { "description": "Timestamp when the task was created.", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "download_url": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ], "description": "URL for downloading the task results.", "examples": [ "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000/results" ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if the task failed.", "examples": [ "Connection timeout" ] }, "error_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Classification of the error type.", "examples": [ "timeout_error" ] }, "id": { "description": "Unique task identifier.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "minLength": 1, "type": "string" }, "input": { "description": "Original input data for the task." }, "modified_at": { "description": "Timestamp when the task was last modified.", "examples": [ "2024-01-15T10:35:00Z" ], "type": "string" }, "output_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Storage location of the output data." }, "queue": { "description": "Queue name the task was submitted to.", "type": "string" }, "state": { "description": "Current state of the task.", "enum": [ "pending", "queued", "in_progress", "success", "error" ], "examples": [ "pending" ], "type": "string" }, "status_code": { "description": "HTTP status code from the task execution.", "examples": [ 200 ], "type": "number" }, "status_url": { "description": "URL for checking the task status.", "examples": [ "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000" ], "format": "uri", "type": "string" } }, "required": [ "id", "state", "status_url", "created_at", "input", "_query" ], "type": "object" }, "type": "array" }, "pagination": { "additionalProperties": false, "properties": { "has_next": { "description": "Whether there are more tasks available.", "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor to use for fetching the next page." }, "total": { "description": "Total number of tasks.", "type": "number" } }, "required": [ "has_next", "next_cursor", "total" ], "type": "object" } }, "required": [ "data", "pagination" ], "type": "object" }, "BatchGetResponse": { "additionalProperties": false, "description": "Response containing batch details with all tasks.", "properties": { "completed": { "description": "Whether all tasks in the batch have finished.", "type": "boolean" }, "completed_at": { "description": "ISO timestamp when the batch completed.", "type": "string" }, "completed_count": { "description": "Number of tasks that have completed so far.", "type": "number" }, "created_at": { "description": "ISO timestamp when the batch was created.", "type": "string" }, "id": { "description": "Unique identifier for the batch.", "type": "string" }, "progress": { "description": "Completion ratio between 0 and 1.", "type": "number" }, "status": { "const": "success", "type": "string" }, "tasks": { "description": "List of tasks in the batch.", "items": { "anyOf": [ { "additionalProperties": false, "properties": { "_query": {}, "account_name": { "description": "Account name that owns the task.", "type": "string" }, "api_type": { "enum": [ "web", "serp", "ecommerce", "social", "media", "agent", "extract", "fast-serp", "labs" ], "type": "string" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Batch ID if this task is part of a batch.", "examples": [ "4b0a90bf-c951-42e4-95b3-a95a65ba69fc" ] }, "created_at": { "description": "Timestamp when the task was created.", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "download_url": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ], "description": "URL for downloading the task results.", "examples": [ "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000/results" ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if the task failed.", "examples": [ "Connection timeout" ] }, "error_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Classification of the error type.", "examples": [ "timeout_error" ] }, "id": { "description": "Unique task identifier.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "minLength": 1, "type": "string" }, "input": { "description": "Original input data for the task." }, "modified_at": { "description": "Timestamp when the task was last modified.", "examples": [ "2024-01-15T10:35:00Z" ], "type": "string" }, "output_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Storage location of the output data." }, "queue": { "description": "Queue name the task was submitted to.", "type": "string" }, "state": { "description": "Current state of the task.", "enum": [ "pending", "queued", "in_progress", "success", "error" ], "examples": [ "pending" ], "type": "string" }, "status_code": { "description": "HTTP status code from the task execution.", "examples": [ 200 ], "type": "number" }, "status_url": { "description": "URL for checking the task status.", "examples": [ "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000" ], "format": "uri", "type": "string" } }, "required": [ "id", "state", "status_url", "created_at", "input", "_query" ], "type": "object" }, { "type": "null" } ] }, "type": "array" } }, "required": [ "status", "id", "completed", "completed_count", "progress", "created_at", "tasks" ], "type": "object" }, "BatchProgressResponse": { "additionalProperties": false, "description": "Lightweight batch progress without task details.", "properties": { "completed": { "description": "Whether all tasks in the batch have finished.", "type": "boolean" }, "completed_at": { "description": "ISO timestamp when the batch completed.", "type": "string" }, "completed_count": { "description": "Number of tasks that have completed so far.", "type": "number" }, "id": { "description": "Unique identifier for the batch.", "type": "string" }, "progress": { "description": "Completion ratio between 0 and 1.", "type": "number" }, "status": { "const": "success", "type": "string" } }, "required": [ "status", "id", "completed", "completed_count", "progress" ], "type": "object" }, "ExtractPayload": { "properties": { "auto_driver_configuration": { "additionalProperties": { "maximum": 10, "minimum": 0, "type": "integer" }, "description": "Custom flow for the optimization engine: maps candidate names to the number of attempts to spend on each candidate before advancing (0 skips it). Key order defines the flow order. Providing it opts the request into 'auto' driver selection.", "examples": [ { "vx10": 2, "vx10-pro": 0, "vx6-fast": 1, "vx6-stealth": 1, "vx8": 5, "vx8-pro": 5 } ], "propertyNames": { "type": "string" }, "type": "object" }, "body": { "description": "Request body for POST, PUT, PATCH methods", "examples": [ { "key": "value" } ] }, "browser": { "anyOf": [ { "description": "Browser type to emulate", "enum": [ "chrome", "firefox" ], "examples": [ "chrome" ], "type": "string" }, { "properties": { "name": { "enum": [ "chrome", "firefox" ], "type": "string" }, "version": { "description": "Specific browser version to emulate", "examples": [ "120.0.0" ], "type": "string" } }, "required": [ "name" ], "type": "object" } ] }, "browser_actions": { "$ref": "#/components/schemas/BrowserActions" }, "city": { "description": "City for geolocation", "examples": [ "Los Angeles" ], "type": "string" }, "consent_header": { "description": "Whether to automatically handle cookie consent headers", "type": "boolean" }, "cookies": { "anyOf": [ { "description": "Browser cookies as array of cookie objects", "items": { "additionalProperties": {}, "properties": { "creation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires": { "anyOf": [ { "type": "string" }, { "const": "Infinity", "type": "string" } ] }, "extensions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] }, "hostOnly": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "httpOnly": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "lastAccessed": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxAge": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "const": "Infinity", "type": "string" }, { "const": "-Infinity", "type": "string" } ] }, { "type": "null" } ] }, "name": { "type": "string" }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pathIsDefault": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "sameSite": { "enum": [ "strict", "lax", "none" ], "type": "string" }, "secure": { "type": "boolean" }, "value": { "type": "string" } }, "type": "object" }, "type": "array" }, { "description": "Browser cookies as string", "examples": [ "sessionId=abc123; userId=user456" ], "type": "string" } ] }, "country": { "anyOf": [ { "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", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "type": "string" }, { "const": "ALL", "type": "string" } ], "default": "ALL", "description": "Country code for geolocation and proxy selection", "examples": [ "US" ] }, "device": { "default": "desktop", "description": "Device type for browser emulation", "enum": [ "desktop", "mobile", "tablet" ], "examples": [ "desktop" ], "type": "string" }, "driver": { "description": "Browser driver to use", "enum": [ "auto", "vx6", "vx8", "vx8-pro", "vx10", "vx10-pro", "vx12", "vx12-pro", "media-vx6", "fast-vx6" ], "examples": [ "vx8" ], "type": "string" }, "expected_status_codes": { "description": "Expected HTTP status codes for successful requests", "examples": [ [ 200, 201 ] ], "items": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "type": "array" }, "formats": { "description": "List of acceptable response formats in order of preference", "examples": [ [ "html" ] ], "items": { "enum": [ "html", "markdown", "screenshot", "headers", "links" ], "type": "string" }, "minItems": 1, "type": "array" }, "headers": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" }, { "items": { "type": "string" }, "type": "array" } ] }, "default": {}, "description": "Custom HTTP headers to include in the request", "examples": [ { "Accept-Language": "en-US", "User-Agent": "CustomBot/1.0" } ], "propertyNames": { "type": "string" }, "type": "object" }, "http2": { "default": false, "description": "Whether to use HTTP/2 protocol", "examples": [ true ], "type": "boolean" }, "is_xhr": { "default": false, "description": "Whether to emulate XMLHttpRequest behavior", "examples": [ true ], "type": "boolean" }, "locale": { "anyOf": [ { "enum": [ "aa-DJ", "aa-ER", "aa-ET", "af", "af-NA", "af-ZA", "ak", "ak-GH", "am", "am-ET", "an-ES", "ar", "ar-AE", "ar-BH", "ar-DZ", "ar-EG", "ar-IN", "ar-IQ", "ar-JO", "ar-KW", "ar-LB", "ar-LY", "ar-MA", "ar-OM", "ar-QA", "ar-SA", "ar-SD", "ar-SY", "ar-TN", "ar-YE", "as", "as-IN", "asa", "asa-TZ", "ast-ES", "az", "az-AZ", "az-Cyrl", "az-Cyrl-AZ", "az-Latn", "az-Latn-AZ", "be", "be-BY", "bem", "bem-ZM", "ber-DZ", "ber-MA", "bez", "bez-TZ", "bg", "bg-BG", "bho-IN", "bm", "bm-ML", "bn", "bn-BD", "bn-IN", "bo", "bo-CN", "bo-IN", "br-FR", "brx-IN", "bs", "bs-BA", "byn-ER", "ca", "ca-AD", "ca-ES", "ca-FR", "ca-IT", "cgg", "cgg-UG", "chr", "chr-US", "crh-UA", "cs", "cs-CZ", "csb-PL", "cv-RU", "cy", "cy-GB", "da", "da-DK", "dav", "dav-KE", "de", "de-AT", "de-BE", "de-CH", "de-DE", "de-LI", "de-LU", "dv-MV", "dz-BT", "ebu", "ebu-KE", "ee", "ee-GH", "ee-TG", "el", "el-CY", "el-GR", "en", "en-AG", "en-AS", "en-AU", "en-BE", "en-BW", "en-BZ", "en-CA", "en-DK", "en-GB", "en-GU", "en-HK", "en-IE", "en-IN", "en-JM", "en-MH", "en-MP", "en-MT", "en-MU", "en-NA", "en-NG", "en-NZ", "en-PH", "en-PK", "en-SG", "en-TT", "en-UM", "en-US", "en-VI", "en-ZA", "en-ZM", "en-ZW", "eo", "es", "es-419", "es-AR", "es-BO", "es-CL", "es-CO", "es-CR", "es-CU", "es-DO", "es-EC", "es-ES", "es-GQ", "es-GT", "es-HN", "es-MX", "es-NI", "es-PA", "es-PE", "es-PR", "es-PY", "es-SV", "es-US", "es-UY", "es-VE", "et", "et-EE", "eu", "eu-ES", "fa", "fa-AF", "fa-IR", "ff", "ff-SN", "fi", "fi-FI", "fil", "fil-PH", "fo", "fo-FO", "fr", "fr-BE", "fr-BF", "fr-BI", "fr-BJ", "fr-BL", "fr-CA", "fr-CD", "fr-CF", "fr-CG", "fr-CH", "fr-CI", "fr-CM", "fr-DJ", "fr-FR", "fr-GA", "fr-GN", "fr-GP", "fr-GQ", "fr-KM", "fr-LU", "fr-MC", "fr-MF", "fr-MG", "fr-ML", "fr-MQ", "fr-NE", "fr-RE", "fr-RW", "fr-SN", "fr-TD", "fr-TG", "fur-IT", "fy-DE", "fy-NL", "ga", "ga-IE", "gd-GB", "gez-ER", "gez-ET", "gl", "gl-ES", "gsw", "gsw-CH", "gu", "gu-IN", "guz", "guz-KE", "gv", "gv-GB", "ha", "ha-Latn", "ha-Latn-GH", "ha-Latn-NE", "ha-Latn-NG", "ha-NG", "haw", "haw-US", "he", "he-IL", "hi", "hi-IN", "hne-IN", "hr", "hr-HR", "hsb-DE", "ht-HT", "hu", "hu-HU", "hy", "hy-AM", "id", "id-ID", "ig", "ig-NG", "ii", "ii-CN", "ik-CA", "is", "is-IS", "it", "it-CH", "it-IT", "iu-CA", "iw-IL", "ja", "ja-JP", "jmc", "jmc-TZ", "ka", "ka-GE", "kab", "kab-DZ", "kam", "kam-KE", "kde", "kde-TZ", "kea", "kea-CV", "khq", "khq-ML", "ki", "ki-KE", "kk", "kk-Cyrl", "kk-Cyrl-KZ", "kk-KZ", "kl", "kl-GL", "kln", "kln-KE", "km", "km-KH", "kn", "kn-IN", "ko", "ko-KR", "kok", "kok-IN", "ks-IN", "ku-TR", "kw", "kw-GB", "ky-KG", "lag", "lag-TZ", "lb-LU", "lg", "lg-UG", "li-BE", "li-NL", "lij-IT", "lo-LA", "lt", "lt-LT", "luo", "luo-KE", "luy", "luy-KE", "lv", "lv-LV", "mag-IN", "mai-IN", "mas", "mas-KE", "mas-TZ", "mer", "mer-KE", "mfe", "mfe-MU", "mg", "mg-MG", "mhr-RU", "mi-NZ", "mk", "mk-MK", "ml", "ml-IN", "mn-MN", "mr", "mr-IN", "ms", "ms-BN", "ms-MY", "mt", "mt-MT", "my", "my-MM", "nan-TW", "naq", "naq-NA", "nb", "nb-NO", "nd", "nd-ZW", "nds-DE", "nds-NL", "ne", "ne-IN", "ne-NP", "nl", "nl-AW", "nl-BE", "nl-NL", "nn", "nn-NO", "nr-ZA", "nso-ZA", "nyn", "nyn-UG", "oc-FR", "om", "om-ET", "om-KE", "or", "or-IN", "os-RU", "pa", "pa-Arab", "pa-Arab-PK", "pa-Guru", "pa-Guru-IN", "pa-IN", "pa-PK", "pap-AN", "pl", "pl-PL", "ps", "ps-AF", "pt", "pt-BR", "pt-GW", "pt-MZ", "pt-PT", "rm", "rm-CH", "ro", "ro-MD", "ro-RO", "rof", "rof-TZ", "ru", "ru-MD", "ru-RU", "ru-UA", "rw", "rw-RW", "rwk", "rwk-TZ", "sa-IN", "saq", "saq-KE", "sc-IT", "sd-IN", "se-NO", "seh", "seh-MZ", "ses", "ses-ML", "sg", "sg-CF", "shi", "shi-Latn", "shi-Latn-MA", "shi-Tfng", "shi-Tfng-MA", "shs-CA", "si", "si-LK", "sid-ET", "sk", "sk-SK", "sl", "sl-SI", "sn", "sn-ZW", "so", "so-DJ", "so-ET", "so-KE", "so-SO", "sq", "sq-AL", "sq-MK", "sr", "sr-Cyrl", "sr-Cyrl-BA", "sr-Cyrl-ME", "sr-Cyrl-RS", "sr-Latn", "sr-Latn-BA", "sr-Latn-ME", "sr-Latn-RS", "sr-ME", "sr-RS", "ss-ZA", "st-ZA", "sv", "sv-FI", "sv-SE", "sw", "sw-KE", "sw-TZ", "ta", "ta-IN", "ta-LK", "te", "te-IN", "teo", "teo-KE", "teo-UG", "tg-TJ", "th", "th-TH", "ti", "ti-ER", "ti-ET", "tig-ER", "tk-TM", "tl-PH", "tn-ZA", "to", "to-TO", "tr", "tr-CY", "tr-TR", "ts-ZA", "tt-RU", "tzm", "tzm-Latn", "tzm-Latn-MA", "ug-CN", "uk", "uk-UA", "unm-US", "ur", "ur-IN", "ur-PK", "uz", "uz-Arab", "uz-Arab-AF", "uz-Cyrl", "uz-Cyrl-UZ", "uz-Latn", "uz-Latn-UZ", "uz-UZ", "ve-ZA", "vi", "vi-VN", "vun", "vun-TZ", "wa-BE", "wae-CH", "wal-ET", "wo-SN", "xh-ZA", "xog", "xog-UG", "yi-US", "yo", "yo-NG", "yue-HK", "zh", "zh-CN", "zh-HK", "zh-Hans", "zh-Hans-CN", "zh-Hans-HK", "zh-Hans-MO", "zh-Hans-SG", "zh-Hant", "zh-Hant-HK", "zh-Hant-MO", "zh-Hant-TW", "zh-SG", "zh-TW", "zu", "zu-ZA" ], "type": "string" }, { "const": "auto", "type": "string" } ], "default": "en", "description": "Locale for browser language and region settings", "examples": [ "en-US" ] }, "markdown_backend": { "default": "full_page", "description": "Selects which markdown conversion strategy to use. \"full_page\" converts the entire HTML page. \"main_content\" uses Mozilla Readability to extract the main article content before converting.", "enum": [ "full_page", "main_content" ], "examples": [ "full_page" ], "type": "string" }, "method": { "default": "GET", "description": "HTTP method for the request", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "examples": [ "GET" ], "type": "string" }, "network_capture": { "description": "Filters for capturing network traffic", "items": { "properties": { "method": { "enum": [ "GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH" ], "type": "string" }, "resource_type": { "anyOf": [ { "description": "Resource type for network capture filtering", "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, { "items": { "description": "Resource type for network capture filtering", "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, "minItems": 1, "type": "array" } ] }, "status_code": { "anyOf": [ { "maximum": 599, "minimum": 100, "type": "number" }, { "items": { "maximum": 599, "minimum": 100, "type": "number" }, "minItems": 1, "type": "array" } ] }, "url": { "properties": { "type": { "default": "exact", "enum": [ "exact", "contains" ], "type": "string" }, "value": { "type": "string" } }, "required": [ "value" ], "type": "object" }, "validation": { "default": false, "type": "boolean" }, "wait_for_requests_count": { "default": 0, "minimum": 0, "type": "number" }, "wait_for_requests_count_timeout": { "exclusiveMinimum": 0, "maximum": 300000, "type": "number" } }, "type": "object" }, "type": "array" }, "os": { "description": "Operating system to emulate", "enum": [ "windows", "mac os", "linux", "android", "ios" ], "examples": [ "windows" ], "type": "string" }, "parse": { "default": false, "description": "Whether to parse the response content", "examples": [ true ], "type": "boolean" }, "parser": { "anyOf": [ { "additionalProperties": {}, "propertyNames": { "type": "string" }, "type": "object" }, { "type": "string" } ], "description": "Custom parser configuration as a key-value map", "examples": [ { "myParser": { "option1": "value1" } } ] }, "referrer_type": { "anyOf": [ { "enum": [ "random", "no-referer", "same-origin" ], "type": "string" }, { "enum": [ "google", "bing", "facebook", "twitter", "instagram" ], "type": "string" } ], "description": "Referrer policy for the request", "examples": [ "no-referrer" ] }, "render": { "anyOf": [ { "type": "boolean" }, { "const": "auto", "type": "string" } ], "description": "Whether to render JavaScript content using a browser", "examples": [ true ] }, "request_timeout": { "description": "Request timeout in milliseconds", "examples": [ 30000 ], "minimum": 1, "type": "number" }, "session": { "properties": { "id": { "type": "string" }, "prefetch_userbrowser": { "default": false, "type": "boolean" }, "renew_on_blocked": { "default": false, "type": "boolean" }, "retry": { "default": false, "type": "boolean" }, "timeout": { "exclusiveMinimum": 0, "type": "number" } }, "type": "object" }, "skill": { "anyOf": [ { "description": "Skills or capabilities required for the request", "examples": [ "dynamic-content" ], "private": true, "type": "string", "x-private": true }, { "description": "Skills or capabilities required for the request", "examples": [ [ "javascript", "dynamic-content" ] ], "items": { "type": "string" }, "private": true, "type": "array", "x-private": true } ] }, "state": { "description": "US state for geolocation (only valid when country is US)", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "VI", "WA", "WV", "WI", "WY" ], "examples": [ "CA" ], "type": "string" }, "tag": { "description": "User-defined tag for request identification", "examples": [ "campaign-2024-q1" ], "type": "string" }, "url": { "description": "Target URL to scrape", "type": "string" } }, "required": [ "url" ], "type": "object" }, "SerpPayload": { "description": "Request body model for the /serp endpoint", "properties": { "country": { "description": "ISO Alpha-2 country code used to access the target search engine (e.g. US, DE, GB).", "examples": [ "US" ], "type": "string" }, "device": { "description": "Device type used for the search request.", "enum": [ "desktop", "mobile" ], "examples": [ "desktop" ], "type": "string" }, "domain": { "default": "com", "description": "Top-level domain for the search engine (e.g. \"com\", \"co.uk\", \"de\").", "examples": [ "com" ], "type": "string" }, "locale": { "description": "Locale used for the search request.", "examples": [ "en" ], "type": "string" }, "location": { "description": "Geo-location for the search (canonical Google location name).", "examples": [ "New York, New York, United States" ], "type": "string" }, "num_results": { "description": "Number of results to return (1–100).", "examples": [ 10 ], "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "The result page number for pagination.", "examples": [ 1 ], "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "parse": { "default": true, "description": "When true, the SERP response is parsed into structured JSON.", "examples": [ true ], "type": "boolean" }, "query": { "description": "The search keyword or phrase to query.", "examples": [ "nimble web data" ], "type": "string" }, "render": { "default": false, "description": "Whether to render the page in a browser before extracting.", "examples": [ false ], "type": "boolean" }, "resolve_url": { "default": false, "description": "Resolves redirect or broken URLs to their real destination. Adds a small increase in latency. If an individual result can't be resolved, that result falls back to the raw URL instead of failing the whole request.", "examples": [ false ], "type": "boolean" }, "search_engine": { "description": "The search engine to query.", "enum": [ "google_search", "google_sge", "google_aio", "google_maps_search", "google_maps_reviews", "google_maps_place", "google_news", "google_images", "bing_search", "yandex_search" ], "examples": [ "google_search" ], "type": "string" }, "show_hidden_results": { "description": "When true, disables Google result filtering (filter=0) so omitted/duplicate and highly similar pages are also returned. Applies to Google search engines.", "examples": [ false ], "type": "boolean" } }, "required": [ "search_engine" ], "type": "object" }, "FastSerpPayload": { "type": "object", "title": "FastSerpPayload", "properties": { "search_engine": { "type": "string", "description": "The search engine to query", "examples": [ "google_search" ], "enum": [ "google_search", "google_news", "google_images", "google_maps_search", "google_maps_place", "google_maps_reviews" ] }, "query": { "type": "string", "description": "The search query string. Required for google_search, google_news, google_images, and google_maps_search", "examples": [ "NBA Allstars 2026" ] }, "place_id": { "type": "string", "description": "Google Maps place identifier. Required for google_maps_place and google_maps_reviews", "examples": [ "ChIJtRq8oUjLw4kR_tN2GQKUOXs" ] }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "string", "description": "Google Maps place identifier. Required for google_maps_place and google_maps_reviews", "examples": [ "40.7123695" ] }, "longitude": { "type": "string", "examples": [ "-74.0357317" ] } }, "examples": [ { "latitude": "40.7123695", "longitude": "-74.0357317" } ] }, "time": { "type": "string", "description": "Filter results by time range. Only supported for google_search, google_news, and google_images", "examples": [ "hour", "day", "week", "month", "year" ] }, "country": { "type": "string", "default": "US", "description": "Run the search as if from a specific country. Returns geo-localized results (optimized for US)", "examples": [ "US" ] }, "locale": { "type": "string", "description": "Language preference for the search results. Use LCID standard", "examples": [ "en" ] }, "location": { "type": "string", "description": "Location context for the search. Accepted for google_search, google_news, and google_images — not supported for Maps engines. Pass a location string (e.g. \"United States\", \"New York, NY\") or a raw Google UULE value.", "examples": [ "United States", "New York, NY" ] }, "no_html": { "type": "boolean", "default": false, "description": "When set to true, removes the html_content field from the response", "examples": [ true ] }, "resolve_url": { "type": "boolean", "default": false, "description": "Resolves redirect or broken URLs to their real destination. Adds a small increase in latency. If an individual result can't be resolved, that result falls back to the raw URL instead of failing the whole request.", "examples": [ false ] } }, "required": [ "search_engine" ], "description": "Request body model for the fast serp endpoint" }, "SerpResponse": { "type": "object", "title": "SerpResponse", "description": "Response from the Fast SERP realtime API. All engines share the same top-level envelope; entity types under parsing.entities vary by search_engine.", "properties": { "task_id": { "type": "string", "description": "Unique identifier for this request", "examples": [ "bd46cd9c-50f7-4736-9c4a-660a32e4dc87" ] }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Request status", "examples": [ "success" ] }, "query_time": { "type": "string", "format": "date-time", "description": "ISO timestamp of when the query ran", "examples": [ "2026-03-05T13:47:16.435Z" ] }, "status_code": { "type": "integer", "description": "HTTP status code from the upstream source", "examples": [ 200 ] }, "url": { "type": "string", "description": "The upstream URL that was queried", "examples": [ "https://www.google.com/search?hl=en&gl=us&q=NBA+Allstar+2026" ] }, "input_url": { "type": "string", "description": "The original input URL before any redirects", "examples": [ "https://www.google.com/search?hl=en&gl=us&q=NBA+Allstar+2026" ] }, "html_content": { "type": "string", "nullable": true, "description": "Raw HTML of the response page. Omitted when no_html is true.", "examples": [ "..." ] }, "driver": { "type": "string", "description": "Internal routing driver used for this request", "examples": [ "vx6" ] }, "parsing": { "type": "object", "description": "Structured parsing output. Entity types under entities vary by search_engine." }, "nimble_links": { "type": "object", "nullable": true, "description": "Pagination links as ready-to-use Nimble API URLs (Maps engines)", "properties": { "next_page": { "type": "string", "description": "URL to fetch the next page of results" } } }, "nimble_payload": { "type": "object", "nullable": true, "description": "Next-page parameters as a structured object (web search engines)" } }, "required": [ "task_id", "status", "status_code", "parsing" ] }, "CrawlPayload": { "description": "Request body model for the /crawl endpoint", "properties": { "allow_external_links": { "default": false, "description": "Allows the crawler to follow links to external websites.", "examples": [ false ], "type": "boolean" }, "allow_subdomains": { "default": false, "description": "Allows the crawler to follow links to subdomains of the main domain.", "examples": [ false ], "type": "boolean" }, "callback": { "anyOf": [ { "anyOf": [ { "properties": { "events": { "items": { "enum": [ "started", "page", "completed", "failed" ], "type": "string" }, "type": "array" }, "headers": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "metadata": { "additionalProperties": {}, "propertyNames": { "type": "string" }, "type": "object" }, "url": { "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" }, { "format": "uri", "type": "string" } ] }, { "format": "uri", "type": "string" } ], "description": "Webhook configuration for receiving crawl results." }, "crawl_entire_domain": { "default": false, "description": "Allows the crawler to follow internal links to sibling or parent URLs, not just child paths.", "examples": [ false ], "type": "boolean" }, "exclude_paths": { "description": "URL pathname regex patterns that exclude matching URLs from the crawl.", "examples": [ [ "/exclude-this-path", "/and-this-path" ] ], "items": { "type": "string" }, "type": "array" }, "extract_options": { "properties": { "auto_driver_configuration": { "additionalProperties": { "maximum": 10, "minimum": 0, "type": "integer" }, "description": "Custom flow for the optimization engine: maps candidate names to the number of attempts to spend on each candidate before advancing (0 skips it). Key order defines the flow order. Providing it opts the request into 'auto' driver selection.", "examples": [ { "vx10": 2, "vx10-pro": 0, "vx6-fast": 1, "vx6-stealth": 1, "vx8": 5, "vx8-pro": 5 } ], "propertyNames": { "type": "string" }, "type": "object" }, "body": { "description": "Request body for POST, PUT, PATCH methods", "examples": [ { "key": "value" } ] }, "browser": { "anyOf": [ { "description": "Browser type to emulate", "enum": [ "chrome", "firefox" ], "examples": [ "chrome" ], "type": "string" }, { "properties": { "name": { "enum": [ "chrome", "firefox" ], "type": "string" }, "version": { "description": "Specific browser version to emulate", "examples": [ "120.0.0" ], "type": "string" } }, "required": [ "name" ], "type": "object" } ] }, "browser_actions": { "$ref": "#/components/schemas/BrowserActions" }, "city": { "description": "City for geolocation", "examples": [ "Los Angeles" ], "type": "string" }, "consent_header": { "description": "Whether to automatically handle cookie consent headers", "type": "boolean" }, "cookies": { "anyOf": [ { "description": "Browser cookies as array of cookie objects", "items": { "additionalProperties": {}, "properties": { "creation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires": { "anyOf": [ { "type": "string" }, { "const": "Infinity", "type": "string" } ] }, "extensions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] }, "hostOnly": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "httpOnly": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "lastAccessed": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxAge": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "const": "Infinity", "type": "string" }, { "const": "-Infinity", "type": "string" } ] }, { "type": "null" } ] }, "name": { "type": "string" }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pathIsDefault": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "sameSite": { "enum": [ "strict", "lax", "none" ], "type": "string" }, "secure": { "type": "boolean" }, "value": { "type": "string" } }, "type": "object" }, "type": "array" }, { "description": "Browser cookies as string", "examples": [ "sessionId=abc123; userId=user456" ], "type": "string" } ] }, "country": { "anyOf": [ { "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", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "type": "string" }, { "const": "ALL", "type": "string" } ], "default": "ALL", "description": "Country code for geolocation and proxy selection", "examples": [ "US" ] }, "device": { "default": "desktop", "description": "Device type for browser emulation", "enum": [ "desktop", "mobile", "tablet" ], "examples": [ "desktop" ], "type": "string" }, "driver": { "description": "Browser driver to use", "enum": [ "auto", "vx6", "vx8", "vx8-pro", "vx10", "vx10-pro", "vx12", "vx12-pro", "media-vx6", "fast-vx6" ], "examples": [ "vx8" ], "type": "string" }, "expected_status_codes": { "description": "Expected HTTP status codes for successful requests", "examples": [ [ 200, 201 ] ], "items": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "type": "array" }, "formats": { "description": "List of acceptable response formats in order of preference", "examples": [ [ "html" ] ], "items": { "enum": [ "html", "markdown", "screenshot", "headers", "links" ], "type": "string" }, "minItems": 1, "type": "array" }, "headers": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" }, { "items": { "type": "string" }, "type": "array" } ] }, "default": {}, "description": "Custom HTTP headers to include in the request", "examples": [ { "Accept-Language": "en-US", "User-Agent": "CustomBot/1.0" } ], "propertyNames": { "type": "string" }, "type": "object" }, "http2": { "default": false, "description": "Whether to use HTTP/2 protocol", "examples": [ true ], "type": "boolean" }, "is_xhr": { "default": false, "description": "Whether to emulate XMLHttpRequest behavior", "examples": [ true ], "type": "boolean" }, "locale": { "anyOf": [ { "enum": [ "aa-DJ", "aa-ER", "aa-ET", "af", "af-NA", "af-ZA", "ak", "ak-GH", "am", "am-ET", "an-ES", "ar", "ar-AE", "ar-BH", "ar-DZ", "ar-EG", "ar-IN", "ar-IQ", "ar-JO", "ar-KW", "ar-LB", "ar-LY", "ar-MA", "ar-OM", "ar-QA", "ar-SA", "ar-SD", "ar-SY", "ar-TN", "ar-YE", "as", "as-IN", "asa", "asa-TZ", "ast-ES", "az", "az-AZ", "az-Cyrl", "az-Cyrl-AZ", "az-Latn", "az-Latn-AZ", "be", "be-BY", "bem", "bem-ZM", "ber-DZ", "ber-MA", "bez", "bez-TZ", "bg", "bg-BG", "bho-IN", "bm", "bm-ML", "bn", "bn-BD", "bn-IN", "bo", "bo-CN", "bo-IN", "br-FR", "brx-IN", "bs", "bs-BA", "byn-ER", "ca", "ca-AD", "ca-ES", "ca-FR", "ca-IT", "cgg", "cgg-UG", "chr", "chr-US", "crh-UA", "cs", "cs-CZ", "csb-PL", "cv-RU", "cy", "cy-GB", "da", "da-DK", "dav", "dav-KE", "de", "de-AT", "de-BE", "de-CH", "de-DE", "de-LI", "de-LU", "dv-MV", "dz-BT", "ebu", "ebu-KE", "ee", "ee-GH", "ee-TG", "el", "el-CY", "el-GR", "en", "en-AG", "en-AS", "en-AU", "en-BE", "en-BW", "en-BZ", "en-CA", "en-DK", "en-GB", "en-GU", "en-HK", "en-IE", "en-IN", "en-JM", "en-MH", "en-MP", "en-MT", "en-MU", "en-NA", "en-NG", "en-NZ", "en-PH", "en-PK", "en-SG", "en-TT", "en-UM", "en-US", "en-VI", "en-ZA", "en-ZM", "en-ZW", "eo", "es", "es-419", "es-AR", "es-BO", "es-CL", "es-CO", "es-CR", "es-CU", "es-DO", "es-EC", "es-ES", "es-GQ", "es-GT", "es-HN", "es-MX", "es-NI", "es-PA", "es-PE", "es-PR", "es-PY", "es-SV", "es-US", "es-UY", "es-VE", "et", "et-EE", "eu", "eu-ES", "fa", "fa-AF", "fa-IR", "ff", "ff-SN", "fi", "fi-FI", "fil", "fil-PH", "fo", "fo-FO", "fr", "fr-BE", "fr-BF", "fr-BI", "fr-BJ", "fr-BL", "fr-CA", "fr-CD", "fr-CF", "fr-CG", "fr-CH", "fr-CI", "fr-CM", "fr-DJ", "fr-FR", "fr-GA", "fr-GN", "fr-GP", "fr-GQ", "fr-KM", "fr-LU", "fr-MC", "fr-MF", "fr-MG", "fr-ML", "fr-MQ", "fr-NE", "fr-RE", "fr-RW", "fr-SN", "fr-TD", "fr-TG", "fur-IT", "fy-DE", "fy-NL", "ga", "ga-IE", "gd-GB", "gez-ER", "gez-ET", "gl", "gl-ES", "gsw", "gsw-CH", "gu", "gu-IN", "guz", "guz-KE", "gv", "gv-GB", "ha", "ha-Latn", "ha-Latn-GH", "ha-Latn-NE", "ha-Latn-NG", "ha-NG", "haw", "haw-US", "he", "he-IL", "hi", "hi-IN", "hne-IN", "hr", "hr-HR", "hsb-DE", "ht-HT", "hu", "hu-HU", "hy", "hy-AM", "id", "id-ID", "ig", "ig-NG", "ii", "ii-CN", "ik-CA", "is", "is-IS", "it", "it-CH", "it-IT", "iu-CA", "iw-IL", "ja", "ja-JP", "jmc", "jmc-TZ", "ka", "ka-GE", "kab", "kab-DZ", "kam", "kam-KE", "kde", "kde-TZ", "kea", "kea-CV", "khq", "khq-ML", "ki", "ki-KE", "kk", "kk-Cyrl", "kk-Cyrl-KZ", "kk-KZ", "kl", "kl-GL", "kln", "kln-KE", "km", "km-KH", "kn", "kn-IN", "ko", "ko-KR", "kok", "kok-IN", "ks-IN", "ku-TR", "kw", "kw-GB", "ky-KG", "lag", "lag-TZ", "lb-LU", "lg", "lg-UG", "li-BE", "li-NL", "lij-IT", "lo-LA", "lt", "lt-LT", "luo", "luo-KE", "luy", "luy-KE", "lv", "lv-LV", "mag-IN", "mai-IN", "mas", "mas-KE", "mas-TZ", "mer", "mer-KE", "mfe", "mfe-MU", "mg", "mg-MG", "mhr-RU", "mi-NZ", "mk", "mk-MK", "ml", "ml-IN", "mn-MN", "mr", "mr-IN", "ms", "ms-BN", "ms-MY", "mt", "mt-MT", "my", "my-MM", "nan-TW", "naq", "naq-NA", "nb", "nb-NO", "nd", "nd-ZW", "nds-DE", "nds-NL", "ne", "ne-IN", "ne-NP", "nl", "nl-AW", "nl-BE", "nl-NL", "nn", "nn-NO", "nr-ZA", "nso-ZA", "nyn", "nyn-UG", "oc-FR", "om", "om-ET", "om-KE", "or", "or-IN", "os-RU", "pa", "pa-Arab", "pa-Arab-PK", "pa-Guru", "pa-Guru-IN", "pa-IN", "pa-PK", "pap-AN", "pl", "pl-PL", "ps", "ps-AF", "pt", "pt-BR", "pt-GW", "pt-MZ", "pt-PT", "rm", "rm-CH", "ro", "ro-MD", "ro-RO", "rof", "rof-TZ", "ru", "ru-MD", "ru-RU", "ru-UA", "rw", "rw-RW", "rwk", "rwk-TZ", "sa-IN", "saq", "saq-KE", "sc-IT", "sd-IN", "se-NO", "seh", "seh-MZ", "ses", "ses-ML", "sg", "sg-CF", "shi", "shi-Latn", "shi-Latn-MA", "shi-Tfng", "shi-Tfng-MA", "shs-CA", "si", "si-LK", "sid-ET", "sk", "sk-SK", "sl", "sl-SI", "sn", "sn-ZW", "so", "so-DJ", "so-ET", "so-KE", "so-SO", "sq", "sq-AL", "sq-MK", "sr", "sr-Cyrl", "sr-Cyrl-BA", "sr-Cyrl-ME", "sr-Cyrl-RS", "sr-Latn", "sr-Latn-BA", "sr-Latn-ME", "sr-Latn-RS", "sr-ME", "sr-RS", "ss-ZA", "st-ZA", "sv", "sv-FI", "sv-SE", "sw", "sw-KE", "sw-TZ", "ta", "ta-IN", "ta-LK", "te", "te-IN", "teo", "teo-KE", "teo-UG", "tg-TJ", "th", "th-TH", "ti", "ti-ER", "ti-ET", "tig-ER", "tk-TM", "tl-PH", "tn-ZA", "to", "to-TO", "tr", "tr-CY", "tr-TR", "ts-ZA", "tt-RU", "tzm", "tzm-Latn", "tzm-Latn-MA", "ug-CN", "uk", "uk-UA", "unm-US", "ur", "ur-IN", "ur-PK", "uz", "uz-Arab", "uz-Arab-AF", "uz-Cyrl", "uz-Cyrl-UZ", "uz-Latn", "uz-Latn-UZ", "uz-UZ", "ve-ZA", "vi", "vi-VN", "vun", "vun-TZ", "wa-BE", "wae-CH", "wal-ET", "wo-SN", "xh-ZA", "xog", "xog-UG", "yi-US", "yo", "yo-NG", "yue-HK", "zh", "zh-CN", "zh-HK", "zh-Hans", "zh-Hans-CN", "zh-Hans-HK", "zh-Hans-MO", "zh-Hans-SG", "zh-Hant", "zh-Hant-HK", "zh-Hant-MO", "zh-Hant-TW", "zh-SG", "zh-TW", "zu", "zu-ZA" ], "type": "string" }, { "const": "auto", "type": "string" } ], "default": "en", "description": "Locale for browser language and region settings", "examples": [ "en-US" ] }, "markdown_backend": { "default": "full_page", "description": "Selects which markdown conversion strategy to use. \"full_page\" converts the entire HTML page. \"main_content\" uses Mozilla Readability to extract the main article content before converting.", "enum": [ "full_page", "main_content" ], "examples": [ "full_page" ], "type": "string" }, "method": { "default": "GET", "description": "HTTP method for the request", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "examples": [ "GET" ], "type": "string" }, "network_capture": { "description": "Filters for capturing network traffic", "items": { "properties": { "method": { "enum": [ "GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH" ], "type": "string" }, "resource_type": { "anyOf": [ { "description": "Resource type for network capture filtering", "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, { "items": { "description": "Resource type for network capture filtering", "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, "minItems": 1, "type": "array" } ] }, "status_code": { "anyOf": [ { "maximum": 599, "minimum": 100, "type": "number" }, { "items": { "maximum": 599, "minimum": 100, "type": "number" }, "minItems": 1, "type": "array" } ] }, "url": { "properties": { "type": { "default": "exact", "enum": [ "exact", "contains" ], "type": "string" }, "value": { "type": "string" } }, "required": [ "value" ], "type": "object" }, "validation": { "default": false, "type": "boolean" }, "wait_for_requests_count": { "default": 0, "minimum": 0, "type": "number" }, "wait_for_requests_count_timeout": { "exclusiveMinimum": 0, "maximum": 300000, "type": "number" } }, "type": "object" }, "type": "array" }, "os": { "description": "Operating system to emulate", "enum": [ "windows", "mac os", "linux", "android", "ios" ], "examples": [ "windows" ], "type": "string" }, "parse": { "default": false, "description": "Whether to parse the response content", "examples": [ true ], "type": "boolean" }, "parser": { "anyOf": [ { "additionalProperties": {}, "propertyNames": { "type": "string" }, "type": "object" }, { "type": "string" } ], "description": "Custom parser configuration as a key-value map", "examples": [ { "myParser": { "option1": "value1" } } ] }, "referrer_type": { "anyOf": [ { "enum": [ "random", "no-referer", "same-origin" ], "type": "string" }, { "enum": [ "google", "bing", "facebook", "twitter", "instagram" ], "type": "string" } ], "description": "Referrer policy for the request", "examples": [ "no-referrer" ] }, "render": { "anyOf": [ { "type": "boolean" }, { "const": "auto", "type": "string" } ], "description": "Whether to render JavaScript content using a browser", "examples": [ true ] }, "request_timeout": { "description": "Request timeout in milliseconds", "examples": [ 30000 ], "minimum": 1, "type": "number" }, "session": { "properties": { "id": { "type": "string" }, "prefetch_userbrowser": { "default": false, "type": "boolean" }, "renew_on_blocked": { "default": false, "type": "boolean" }, "retry": { "default": false, "type": "boolean" }, "timeout": { "exclusiveMinimum": 0, "type": "number" } }, "type": "object" }, "skill": { "anyOf": [ { "description": "Skills or capabilities required for the request", "examples": [ "dynamic-content" ], "private": true, "type": "string", "x-private": true }, { "description": "Skills or capabilities required for the request", "examples": [ [ "javascript", "dynamic-content" ] ], "items": { "type": "string" }, "private": true, "type": "array", "x-private": true } ] }, "state": { "description": "US state for geolocation (only valid when country is US)", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "VI", "WA", "WV", "WI", "WY" ], "examples": [ "CA" ], "type": "string" }, "tag": { "description": "User-defined tag for request identification", "examples": [ "campaign-2024-q1" ], "type": "string" }, "url": { "description": "Target URL to scrape", "type": "string" } }, "type": "object" }, "ignore_query_parameters": { "default": false, "description": "Do not re-scrape the same path with different (or none) query parameters.", "examples": [ false ], "type": "boolean" }, "include_paths": { "description": "URL pathname regex patterns that include matching URLs in the crawl.", "examples": [ [ "/include-this-path", "/and-this-path" ] ], "items": { "type": "string" }, "type": "array" }, "limit": { "default": 5000, "description": "Maximum number of pages to crawl.", "examples": [ 100 ], "maximum": 10000, "minimum": 1, "type": "integer" }, "max_discovery_depth": { "default": 5, "description": "Maximum depth to crawl based on discovery order.", "examples": [ 3 ], "maximum": 20, "minimum": 1, "type": "integer" }, "name": { "description": "Name of the crawl.", "examples": [ "The best crawl ever" ], "type": "string" }, "sitemap": { "default": "include", "description": "Sitemap and other methods will be used together to find URLs.", "enum": [ "skip", "include", "only" ], "examples": [ "include" ], "type": "string" }, "url": { "description": "Url to crawl.", "type": "string" } }, "required": [ "url" ], "type": "object" }, "MapPayload": { "description": "Request body model for the /map endpoint", "properties": { "country": { "description": "Country code for geolocation and proxy selection", "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", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "examples": [ "US" ], "type": "string" }, "domain_filter": { "default": "all", "description": "Includes subdomains of the main domain in the mapping process.", "enum": [ "domain", "subdomain", "all" ], "examples": [ "all" ], "type": "string" }, "limit": { "default": 5000, "description": "Maximum number of links to return.", "examples": [ 1000 ], "maximum": 100000, "minimum": 1, "type": "integer" }, "locale": { "anyOf": [ { "enum": [ "aa-DJ", "aa-ER", "aa-ET", "af", "af-NA", "af-ZA", "ak", "ak-GH", "am", "am-ET", "an-ES", "ar", "ar-AE", "ar-BH", "ar-DZ", "ar-EG", "ar-IN", "ar-IQ", "ar-JO", "ar-KW", "ar-LB", "ar-LY", "ar-MA", "ar-OM", "ar-QA", "ar-SA", "ar-SD", "ar-SY", "ar-TN", "ar-YE", "as", "as-IN", "asa", "asa-TZ", "ast-ES", "az", "az-AZ", "az-Cyrl", "az-Cyrl-AZ", "az-Latn", "az-Latn-AZ", "be", "be-BY", "bem", "bem-ZM", "ber-DZ", "ber-MA", "bez", "bez-TZ", "bg", "bg-BG", "bho-IN", "bm", "bm-ML", "bn", "bn-BD", "bn-IN", "bo", "bo-CN", "bo-IN", "br-FR", "brx-IN", "bs", "bs-BA", "byn-ER", "ca", "ca-AD", "ca-ES", "ca-FR", "ca-IT", "cgg", "cgg-UG", "chr", "chr-US", "crh-UA", "cs", "cs-CZ", "csb-PL", "cv-RU", "cy", "cy-GB", "da", "da-DK", "dav", "dav-KE", "de", "de-AT", "de-BE", "de-CH", "de-DE", "de-LI", "de-LU", "dv-MV", "dz-BT", "ebu", "ebu-KE", "ee", "ee-GH", "ee-TG", "el", "el-CY", "el-GR", "en", "en-AG", "en-AS", "en-AU", "en-BE", "en-BW", "en-BZ", "en-CA", "en-DK", "en-GB", "en-GU", "en-HK", "en-IE", "en-IN", "en-JM", "en-MH", "en-MP", "en-MT", "en-MU", "en-NA", "en-NG", "en-NZ", "en-PH", "en-PK", "en-SG", "en-TT", "en-UM", "en-US", "en-VI", "en-ZA", "en-ZM", "en-ZW", "eo", "es", "es-419", "es-AR", "es-BO", "es-CL", "es-CO", "es-CR", "es-CU", "es-DO", "es-EC", "es-ES", "es-GQ", "es-GT", "es-HN", "es-MX", "es-NI", "es-PA", "es-PE", "es-PR", "es-PY", "es-SV", "es-US", "es-UY", "es-VE", "et", "et-EE", "eu", "eu-ES", "fa", "fa-AF", "fa-IR", "ff", "ff-SN", "fi", "fi-FI", "fil", "fil-PH", "fo", "fo-FO", "fr", "fr-BE", "fr-BF", "fr-BI", "fr-BJ", "fr-BL", "fr-CA", "fr-CD", "fr-CF", "fr-CG", "fr-CH", "fr-CI", "fr-CM", "fr-DJ", "fr-FR", "fr-GA", "fr-GN", "fr-GP", "fr-GQ", "fr-KM", "fr-LU", "fr-MC", "fr-MF", "fr-MG", "fr-ML", "fr-MQ", "fr-NE", "fr-RE", "fr-RW", "fr-SN", "fr-TD", "fr-TG", "fur-IT", "fy-DE", "fy-NL", "ga", "ga-IE", "gd-GB", "gez-ER", "gez-ET", "gl", "gl-ES", "gsw", "gsw-CH", "gu", "gu-IN", "guz", "guz-KE", "gv", "gv-GB", "ha", "ha-Latn", "ha-Latn-GH", "ha-Latn-NE", "ha-Latn-NG", "ha-NG", "haw", "haw-US", "he", "he-IL", "hi", "hi-IN", "hne-IN", "hr", "hr-HR", "hsb-DE", "ht-HT", "hu", "hu-HU", "hy", "hy-AM", "id", "id-ID", "ig", "ig-NG", "ii", "ii-CN", "ik-CA", "is", "is-IS", "it", "it-CH", "it-IT", "iu-CA", "iw-IL", "ja", "ja-JP", "jmc", "jmc-TZ", "ka", "ka-GE", "kab", "kab-DZ", "kam", "kam-KE", "kde", "kde-TZ", "kea", "kea-CV", "khq", "khq-ML", "ki", "ki-KE", "kk", "kk-Cyrl", "kk-Cyrl-KZ", "kk-KZ", "kl", "kl-GL", "kln", "kln-KE", "km", "km-KH", "kn", "kn-IN", "ko", "ko-KR", "kok", "kok-IN", "ks-IN", "ku-TR", "kw", "kw-GB", "ky-KG", "lag", "lag-TZ", "lb-LU", "lg", "lg-UG", "li-BE", "li-NL", "lij-IT", "lo-LA", "lt", "lt-LT", "luo", "luo-KE", "luy", "luy-KE", "lv", "lv-LV", "mag-IN", "mai-IN", "mas", "mas-KE", "mas-TZ", "mer", "mer-KE", "mfe", "mfe-MU", "mg", "mg-MG", "mhr-RU", "mi-NZ", "mk", "mk-MK", "ml", "ml-IN", "mn-MN", "mr", "mr-IN", "ms", "ms-BN", "ms-MY", "mt", "mt-MT", "my", "my-MM", "nan-TW", "naq", "naq-NA", "nb", "nb-NO", "nd", "nd-ZW", "nds-DE", "nds-NL", "ne", "ne-IN", "ne-NP", "nl", "nl-AW", "nl-BE", "nl-NL", "nn", "nn-NO", "nr-ZA", "nso-ZA", "nyn", "nyn-UG", "oc-FR", "om", "om-ET", "om-KE", "or", "or-IN", "os-RU", "pa", "pa-Arab", "pa-Arab-PK", "pa-Guru", "pa-Guru-IN", "pa-IN", "pa-PK", "pap-AN", "pl", "pl-PL", "ps", "ps-AF", "pt", "pt-BR", "pt-GW", "pt-MZ", "pt-PT", "rm", "rm-CH", "ro", "ro-MD", "ro-RO", "rof", "rof-TZ", "ru", "ru-MD", "ru-RU", "ru-UA", "rw", "rw-RW", "rwk", "rwk-TZ", "sa-IN", "saq", "saq-KE", "sc-IT", "sd-IN", "se-NO", "seh", "seh-MZ", "ses", "ses-ML", "sg", "sg-CF", "shi", "shi-Latn", "shi-Latn-MA", "shi-Tfng", "shi-Tfng-MA", "shs-CA", "si", "si-LK", "sid-ET", "sk", "sk-SK", "sl", "sl-SI", "sn", "sn-ZW", "so", "so-DJ", "so-ET", "so-KE", "so-SO", "sq", "sq-AL", "sq-MK", "sr", "sr-Cyrl", "sr-Cyrl-BA", "sr-Cyrl-ME", "sr-Cyrl-RS", "sr-Latn", "sr-Latn-BA", "sr-Latn-ME", "sr-Latn-RS", "sr-ME", "sr-RS", "ss-ZA", "st-ZA", "sv", "sv-FI", "sv-SE", "sw", "sw-KE", "sw-TZ", "ta", "ta-IN", "ta-LK", "te", "te-IN", "teo", "teo-KE", "teo-UG", "tg-TJ", "th", "th-TH", "ti", "ti-ER", "ti-ET", "tig-ER", "tk-TM", "tl-PH", "tn-ZA", "to", "to-TO", "tr", "tr-CY", "tr-TR", "ts-ZA", "tt-RU", "tzm", "tzm-Latn", "tzm-Latn-MA", "ug-CN", "uk", "uk-UA", "unm-US", "ur", "ur-IN", "ur-PK", "uz", "uz-Arab", "uz-Arab-AF", "uz-Cyrl", "uz-Cyrl-UZ", "uz-Latn", "uz-Latn-UZ", "uz-UZ", "ve-ZA", "vi", "vi-VN", "vun", "vun-TZ", "wa-BE", "wae-CH", "wal-ET", "wo-SN", "xh-ZA", "xog", "xog-UG", "yi-US", "yo", "yo-NG", "yue-HK", "zh", "zh-CN", "zh-HK", "zh-Hans", "zh-Hans-CN", "zh-Hans-HK", "zh-Hans-MO", "zh-Hans-SG", "zh-Hant", "zh-Hant-HK", "zh-Hant-MO", "zh-Hant-TW", "zh-SG", "zh-TW", "zu", "zu-ZA" ], "type": "string" }, { "const": "auto", "type": "string" } ], "description": "Locale for browser language and region settings", "examples": [ "en-US" ] }, "sitemap": { "default": "include", "description": "Sitemap and other methods will be used together to find URLs.", "enum": [ "skip", "include", "only" ], "examples": [ "include" ], "type": "string" }, "url": { "description": "Url to map.", "type": "string" } }, "required": [ "url" ], "type": "object" }, "MediaPayload": { "properties": { "country": { "type": "string" }, "expected_mime_types": { "items": { "type": "string" }, "type": "array" }, "locale": { "type": "string" }, "storage": { "properties": { "object_name": { "type": "string" }, "type": { "default": "s3", "enum": [ "s3", "gcs", "do", "oci" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "url": { "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" }, "ExtractBatchPayload": { "properties": { "inputs": { "description": "Array of extraction requests. Each object can include extraction parameters and async/storage settings.", "items": { "allOf": [ { "properties": { "auto_driver_configuration": { "additionalProperties": { "maximum": 10, "minimum": 0, "type": "integer" }, "description": "Custom flow for the optimization engine: maps candidate names to the number of attempts to spend on each candidate before advancing (0 skips it). Key order defines the flow order. Providing it opts the request into 'auto' driver selection.", "examples": [ { "vx10": 2, "vx10-pro": 0, "vx6-fast": 1, "vx6-stealth": 1, "vx8": 5, "vx8-pro": 5 } ], "propertyNames": { "type": "string" }, "type": "object" }, "body": { "description": "Request body for POST, PUT, PATCH methods", "examples": [ { "key": "value" } ] }, "browser": { "anyOf": [ { "description": "Browser type to emulate", "enum": [ "chrome", "firefox" ], "examples": [ "chrome" ], "type": "string" }, { "properties": { "name": { "enum": [ "chrome", "firefox" ], "type": "string" }, "version": { "description": "Specific browser version to emulate", "examples": [ "120.0.0" ], "type": "string" } }, "required": [ "name" ], "type": "object" } ] }, "browser_actions": { "$ref": "#/components/schemas/BrowserActions" }, "city": { "description": "City for geolocation", "examples": [ "Los Angeles" ], "type": "string" }, "consent_header": { "description": "Whether to automatically handle cookie consent headers", "type": "boolean" }, "cookies": { "anyOf": [ { "description": "Browser cookies as array of cookie objects", "items": { "additionalProperties": {}, "properties": { "creation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires": { "anyOf": [ { "type": "string" }, { "const": "Infinity", "type": "string" } ] }, "extensions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] }, "hostOnly": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "httpOnly": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "lastAccessed": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxAge": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "const": "Infinity", "type": "string" }, { "const": "-Infinity", "type": "string" } ] }, { "type": "null" } ] }, "name": { "type": "string" }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pathIsDefault": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "sameSite": { "enum": [ "strict", "lax", "none" ], "type": "string" }, "secure": { "type": "boolean" }, "value": { "type": "string" } }, "type": "object" }, "type": "array" }, { "description": "Browser cookies as string", "examples": [ "sessionId=abc123; userId=user456" ], "type": "string" } ] }, "country": { "anyOf": [ { "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", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "type": "string" }, { "const": "ALL", "type": "string" } ], "default": "ALL", "description": "Country code for geolocation and proxy selection", "examples": [ "US" ] }, "device": { "default": "desktop", "description": "Device type for browser emulation", "enum": [ "desktop", "mobile", "tablet" ], "examples": [ "desktop" ], "type": "string" }, "driver": { "description": "Browser driver to use. Use 'auto' to let the engine select the candidate config per domain.", "enum": [ "auto", "vx6", "vx8", "vx8-pro", "vx10", "vx10-pro", "vx12", "vx12-pro", "media-vx6", "fast-vx6" ], "examples": [ "vx8" ], "type": "string" }, "expected_status_codes": { "description": "Expected HTTP status codes for successful requests", "examples": [ [ 200, 201 ] ], "items": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "type": "array" }, "formats": { "description": "List of acceptable response formats in order of preference", "examples": [ [ "html" ] ], "items": { "enum": [ "html", "markdown", "screenshot", "headers", "links" ], "type": "string" }, "minItems": 1, "type": "array" }, "headers": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" }, { "items": { "type": "string" }, "type": "array" } ] }, "default": {}, "description": "Custom HTTP headers to include in the request", "examples": [ { "Accept-Language": "en-US", "User-Agent": "CustomBot/1.0" } ], "propertyNames": { "type": "string" }, "type": "object" }, "http2": { "default": false, "description": "Whether to use HTTP/2 protocol", "examples": [ true ], "type": "boolean" }, "is_xhr": { "default": false, "description": "Whether to emulate XMLHttpRequest behavior", "examples": [ true ], "type": "boolean" }, "locale": { "anyOf": [ { "enum": [ "aa-DJ", "aa-ER", "aa-ET", "af", "af-NA", "af-ZA", "ak", "ak-GH", "am", "am-ET", "an-ES", "ar", "ar-AE", "ar-BH", "ar-DZ", "ar-EG", "ar-IN", "ar-IQ", "ar-JO", "ar-KW", "ar-LB", "ar-LY", "ar-MA", "ar-OM", "ar-QA", "ar-SA", "ar-SD", "ar-SY", "ar-TN", "ar-YE", "as", "as-IN", "asa", "asa-TZ", "ast-ES", "az", "az-AZ", "az-Cyrl", "az-Cyrl-AZ", "az-Latn", "az-Latn-AZ", "be", "be-BY", "bem", "bem-ZM", "ber-DZ", "ber-MA", "bez", "bez-TZ", "bg", "bg-BG", "bho-IN", "bm", "bm-ML", "bn", "bn-BD", "bn-IN", "bo", "bo-CN", "bo-IN", "br-FR", "brx-IN", "bs", "bs-BA", "byn-ER", "ca", "ca-AD", "ca-ES", "ca-FR", "ca-IT", "cgg", "cgg-UG", "chr", "chr-US", "crh-UA", "cs", "cs-CZ", "csb-PL", "cv-RU", "cy", "cy-GB", "da", "da-DK", "dav", "dav-KE", "de", "de-AT", "de-BE", "de-CH", "de-DE", "de-LI", "de-LU", "dv-MV", "dz-BT", "ebu", "ebu-KE", "ee", "ee-GH", "ee-TG", "el", "el-CY", "el-GR", "en", "en-AG", "en-AS", "en-AU", "en-BE", "en-BW", "en-BZ", "en-CA", "en-DK", "en-GB", "en-GU", "en-HK", "en-IE", "en-IN", "en-JM", "en-MH", "en-MP", "en-MT", "en-MU", "en-NA", "en-NG", "en-NZ", "en-PH", "en-PK", "en-SG", "en-TT", "en-UM", "en-US", "en-VI", "en-ZA", "en-ZM", "en-ZW", "eo", "es", "es-419", "es-AR", "es-BO", "es-CL", "es-CO", "es-CR", "es-CU", "es-DO", "es-EC", "es-ES", "es-GQ", "es-GT", "es-HN", "es-MX", "es-NI", "es-PA", "es-PE", "es-PR", "es-PY", "es-SV", "es-US", "es-UY", "es-VE", "et", "et-EE", "eu", "eu-ES", "fa", "fa-AF", "fa-IR", "ff", "ff-SN", "fi", "fi-FI", "fil", "fil-PH", "fo", "fo-FO", "fr", "fr-BE", "fr-BF", "fr-BI", "fr-BJ", "fr-BL", "fr-CA", "fr-CD", "fr-CF", "fr-CG", "fr-CH", "fr-CI", "fr-CM", "fr-DJ", "fr-FR", "fr-GA", "fr-GN", "fr-GP", "fr-GQ", "fr-KM", "fr-LU", "fr-MC", "fr-MF", "fr-MG", "fr-ML", "fr-MQ", "fr-NE", "fr-RE", "fr-RW", "fr-SN", "fr-TD", "fr-TG", "fur-IT", "fy-DE", "fy-NL", "ga", "ga-IE", "gd-GB", "gez-ER", "gez-ET", "gl", "gl-ES", "gsw", "gsw-CH", "gu", "gu-IN", "guz", "guz-KE", "gv", "gv-GB", "ha", "ha-Latn", "ha-Latn-GH", "ha-Latn-NE", "ha-Latn-NG", "ha-NG", "haw", "haw-US", "he", "he-IL", "hi", "hi-IN", "hne-IN", "hr", "hr-HR", "hsb-DE", "ht-HT", "hu", "hu-HU", "hy", "hy-AM", "id", "id-ID", "ig", "ig-NG", "ii", "ii-CN", "ik-CA", "is", "is-IS", "it", "it-CH", "it-IT", "iu-CA", "iw-IL", "ja", "ja-JP", "jmc", "jmc-TZ", "ka", "ka-GE", "kab", "kab-DZ", "kam", "kam-KE", "kde", "kde-TZ", "kea", "kea-CV", "khq", "khq-ML", "ki", "ki-KE", "kk", "kk-Cyrl", "kk-Cyrl-KZ", "kk-KZ", "kl", "kl-GL", "kln", "kln-KE", "km", "km-KH", "kn", "kn-IN", "ko", "ko-KR", "kok", "kok-IN", "ks-IN", "ku-TR", "kw", "kw-GB", "ky-KG", "lag", "lag-TZ", "lb-LU", "lg", "lg-UG", "li-BE", "li-NL", "lij-IT", "lo-LA", "lt", "lt-LT", "luo", "luo-KE", "luy", "luy-KE", "lv", "lv-LV", "mag-IN", "mai-IN", "mas", "mas-KE", "mas-TZ", "mer", "mer-KE", "mfe", "mfe-MU", "mg", "mg-MG", "mhr-RU", "mi-NZ", "mk", "mk-MK", "ml", "ml-IN", "mn-MN", "mr", "mr-IN", "ms", "ms-BN", "ms-MY", "mt", "mt-MT", "my", "my-MM", "nan-TW", "naq", "naq-NA", "nb", "nb-NO", "nd", "nd-ZW", "nds-DE", "nds-NL", "ne", "ne-IN", "ne-NP", "nl", "nl-AW", "nl-BE", "nl-NL", "nn", "nn-NO", "nr-ZA", "nso-ZA", "nyn", "nyn-UG", "oc-FR", "om", "om-ET", "om-KE", "or", "or-IN", "os-RU", "pa", "pa-Arab", "pa-Arab-PK", "pa-Guru", "pa-Guru-IN", "pa-IN", "pa-PK", "pap-AN", "pl", "pl-PL", "ps", "ps-AF", "pt", "pt-BR", "pt-GW", "pt-MZ", "pt-PT", "rm", "rm-CH", "ro", "ro-MD", "ro-RO", "rof", "rof-TZ", "ru", "ru-MD", "ru-RU", "ru-UA", "rw", "rw-RW", "rwk", "rwk-TZ", "sa-IN", "saq", "saq-KE", "sc-IT", "sd-IN", "se-NO", "seh", "seh-MZ", "ses", "ses-ML", "sg", "sg-CF", "shi", "shi-Latn", "shi-Latn-MA", "shi-Tfng", "shi-Tfng-MA", "shs-CA", "si", "si-LK", "sid-ET", "sk", "sk-SK", "sl", "sl-SI", "sn", "sn-ZW", "so", "so-DJ", "so-ET", "so-KE", "so-SO", "sq", "sq-AL", "sq-MK", "sr", "sr-Cyrl", "sr-Cyrl-BA", "sr-Cyrl-ME", "sr-Cyrl-RS", "sr-Latn", "sr-Latn-BA", "sr-Latn-ME", "sr-Latn-RS", "sr-ME", "sr-RS", "ss-ZA", "st-ZA", "sv", "sv-FI", "sv-SE", "sw", "sw-KE", "sw-TZ", "ta", "ta-IN", "ta-LK", "te", "te-IN", "teo", "teo-KE", "teo-UG", "tg-TJ", "th", "th-TH", "ti", "ti-ER", "ti-ET", "tig-ER", "tk-TM", "tl-PH", "tn-ZA", "to", "to-TO", "tr", "tr-CY", "tr-TR", "ts-ZA", "tt-RU", "tzm", "tzm-Latn", "tzm-Latn-MA", "ug-CN", "uk", "uk-UA", "unm-US", "ur", "ur-IN", "ur-PK", "uz", "uz-Arab", "uz-Arab-AF", "uz-Cyrl", "uz-Cyrl-UZ", "uz-Latn", "uz-Latn-UZ", "uz-UZ", "ve-ZA", "vi", "vi-VN", "vun", "vun-TZ", "wa-BE", "wae-CH", "wal-ET", "wo-SN", "xh-ZA", "xog", "xog-UG", "yi-US", "yo", "yo-NG", "yue-HK", "zh", "zh-CN", "zh-HK", "zh-Hans", "zh-Hans-CN", "zh-Hans-HK", "zh-Hans-MO", "zh-Hans-SG", "zh-Hant", "zh-Hant-HK", "zh-Hant-MO", "zh-Hant-TW", "zh-SG", "zh-TW", "zu", "zu-ZA" ], "type": "string" }, { "const": "auto", "type": "string" } ], "default": "en", "description": "Locale for browser language and region settings", "examples": [ "en-US" ] }, "markdown_backend": { "default": "full_page", "description": "Selects which markdown conversion strategy to use. \"full_page\" converts the entire HTML page. \"main_content\" uses Mozilla Readability to extract the main article content before converting.", "enum": [ "full_page", "main_content" ], "examples": [ "full_page" ], "type": "string" }, "method": { "default": "GET", "description": "HTTP method for the request", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "examples": [ "GET" ], "type": "string" }, "network_capture": { "description": "Filters for capturing network traffic", "items": { "properties": { "method": { "enum": [ "GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH" ], "type": "string" }, "resource_type": { "anyOf": [ { "description": "Resource type for network capture filtering", "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, { "items": { "description": "Resource type for network capture filtering", "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, "minItems": 1, "type": "array" } ] }, "status_code": { "anyOf": [ { "maximum": 599, "minimum": 100, "type": "number" }, { "items": { "maximum": 599, "minimum": 100, "type": "number" }, "minItems": 1, "type": "array" } ] }, "url": { "properties": { "type": { "default": "exact", "enum": [ "exact", "contains" ], "type": "string" }, "value": { "type": "string" } }, "required": [ "value" ], "type": "object" }, "validation": { "default": false, "type": "boolean" }, "wait_for_requests_count": { "default": 0, "minimum": 0, "type": "number" }, "wait_for_requests_count_timeout": { "exclusiveMinimum": 0, "maximum": 300000, "type": "number" } }, "type": "object" }, "type": "array" }, "os": { "description": "Operating system to emulate", "enum": [ "windows", "mac os", "linux", "android", "ios" ], "examples": [ "windows" ], "type": "string" }, "parse": { "default": false, "description": "Whether to parse the response content", "examples": [ true ], "type": "boolean" }, "parser": { "anyOf": [ { "additionalProperties": {}, "propertyNames": { "type": "string" }, "type": "object" }, { "type": "string" } ], "description": "Custom parser configuration as a key-value map", "examples": [ { "myParser": { "option1": "value1" } } ] }, "referrer_type": { "anyOf": [ { "enum": [ "random", "no-referer", "same-origin" ], "type": "string" }, { "enum": [ "google", "bing", "facebook", "twitter", "instagram" ], "type": "string" } ], "description": "Referrer policy for the request", "examples": [ "no-referrer" ] }, "render": { "anyOf": [ { "type": "boolean" }, { "const": "auto", "type": "string" } ], "description": "Whether to render JavaScript content using a browser. Use 'auto' to let the engine select the candidate config per domain.", "examples": [ false, true, "auto" ] }, "request_timeout": { "description": "Request timeout in milliseconds", "examples": [ 30000 ], "minimum": 1, "type": "number" }, "session": { "properties": { "id": { "type": "string" }, "prefetch_userbrowser": { "default": false, "type": "boolean" }, "renew_on_blocked": { "default": false, "type": "boolean" }, "retry": { "default": false, "type": "boolean" }, "timeout": { "exclusiveMinimum": 0, "type": "number" } }, "type": "object" }, "skill": { "anyOf": [ { "description": "Skills or capabilities required for the request", "examples": [ "dynamic-content" ], "private": true, "type": "string", "x-private": true }, { "description": "Skills or capabilities required for the request", "examples": [ [ "javascript", "dynamic-content" ] ], "items": { "type": "string" }, "private": true, "type": "array", "x-private": true } ] }, "state": { "description": "US state for geolocation (only valid when country is US)", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "VI", "WA", "WV", "WI", "WY" ], "examples": [ "CA" ], "type": "string" }, "tag": { "description": "User-defined tag for request identification", "examples": [ "campaign-2024-q1" ], "type": "string" }, "url": { "description": "Target URL to scrape", "type": "string" } }, "type": "object" }, { "properties": { "callback_url": { "description": "URL to call back when async operation completes", "examples": [ "https://example.com/webhook/callback" ], "type": "string" }, "storage_compress": { "description": "Whether to compress stored data", "examples": [ true ], "type": "boolean" }, "storage_object_name": { "description": "Custom name for the stored object", "examples": [ "result-2024-01-15.json" ], "type": "string" }, "storage_type": { "description": "Type of storage to use for results", "examples": [ "s3" ], "type": "string" }, "storage_url": { "description": "URL for storage location", "examples": [ "s3://bucket-name/path/to/object" ], "type": "string" } }, "type": "object" } ] }, "minItems": 1, "type": "array" }, "shared_inputs": { "allOf": [ { "properties": { "auto_driver_configuration": { "additionalProperties": { "maximum": 10, "minimum": 0, "type": "integer" }, "description": "Custom flow for the optimization engine: maps candidate names to the number of attempts to spend on each candidate before advancing (0 skips it). Key order defines the flow order. Providing it opts the request into 'auto' driver selection.", "examples": [ { "vx10": 2, "vx10-pro": 0, "vx6-fast": 1, "vx6-stealth": 1, "vx8": 5, "vx8-pro": 5 } ], "propertyNames": { "type": "string" }, "type": "object" }, "body": { "description": "Request body for POST, PUT, PATCH methods", "examples": [ { "key": "value" } ] }, "browser": { "anyOf": [ { "description": "Browser type to emulate", "enum": [ "chrome", "firefox" ], "examples": [ "chrome" ], "type": "string" }, { "properties": { "name": { "enum": [ "chrome", "firefox" ], "type": "string" }, "version": { "description": "Specific browser version to emulate", "examples": [ "120.0.0" ], "type": "string" } }, "required": [ "name" ], "type": "object" } ] }, "browser_actions": { "$ref": "#/components/schemas/BrowserActions" }, "city": { "description": "City for geolocation", "examples": [ "Los Angeles" ], "type": "string" }, "consent_header": { "description": "Whether to automatically handle cookie consent headers", "type": "boolean" }, "cookies": { "anyOf": [ { "description": "Browser cookies as array of cookie objects", "items": { "additionalProperties": {}, "properties": { "creation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires": { "anyOf": [ { "type": "string" }, { "const": "Infinity", "type": "string" } ] }, "extensions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] }, "hostOnly": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "httpOnly": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "lastAccessed": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxAge": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "const": "Infinity", "type": "string" }, { "const": "-Infinity", "type": "string" } ] }, { "type": "null" } ] }, "name": { "type": "string" }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pathIsDefault": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "sameSite": { "enum": [ "strict", "lax", "none" ], "type": "string" }, "secure": { "type": "boolean" }, "value": { "type": "string" } }, "type": "object" }, "type": "array" }, { "description": "Browser cookies as string", "examples": [ "sessionId=abc123; userId=user456" ], "type": "string" } ] }, "country": { "anyOf": [ { "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", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "type": "string" }, { "const": "ALL", "type": "string" } ], "default": "ALL", "description": "Country code for geolocation and proxy selection", "examples": [ "US" ] }, "device": { "default": "desktop", "description": "Device type for browser emulation", "enum": [ "desktop", "mobile", "tablet" ], "examples": [ "desktop" ], "type": "string" }, "driver": { "description": "Browser driver to use. Use 'auto' to let the engine select the candidate config per domain.", "enum": [ "auto", "vx6", "vx8", "vx8-pro", "vx10", "vx10-pro", "vx12", "vx12-pro", "media-vx6", "fast-vx6" ], "examples": [ "vx8" ], "type": "string" }, "expected_status_codes": { "description": "Expected HTTP status codes for successful requests", "examples": [ [ 200, 201 ] ], "items": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "type": "array" }, "formats": { "description": "List of acceptable response formats in order of preference", "examples": [ [ "html" ] ], "items": { "enum": [ "html", "markdown", "screenshot", "headers", "links" ], "type": "string" }, "minItems": 1, "type": "array" }, "headers": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" }, { "items": { "type": "string" }, "type": "array" } ] }, "default": {}, "description": "Custom HTTP headers to include in the request", "examples": [ { "Accept-Language": "en-US", "User-Agent": "CustomBot/1.0" } ], "propertyNames": { "type": "string" }, "type": "object" }, "http2": { "default": false, "description": "Whether to use HTTP/2 protocol", "examples": [ true ], "type": "boolean" }, "is_xhr": { "default": false, "description": "Whether to emulate XMLHttpRequest behavior", "examples": [ true ], "type": "boolean" }, "locale": { "anyOf": [ { "enum": [ "aa-DJ", "aa-ER", "aa-ET", "af", "af-NA", "af-ZA", "ak", "ak-GH", "am", "am-ET", "an-ES", "ar", "ar-AE", "ar-BH", "ar-DZ", "ar-EG", "ar-IN", "ar-IQ", "ar-JO", "ar-KW", "ar-LB", "ar-LY", "ar-MA", "ar-OM", "ar-QA", "ar-SA", "ar-SD", "ar-SY", "ar-TN", "ar-YE", "as", "as-IN", "asa", "asa-TZ", "ast-ES", "az", "az-AZ", "az-Cyrl", "az-Cyrl-AZ", "az-Latn", "az-Latn-AZ", "be", "be-BY", "bem", "bem-ZM", "ber-DZ", "ber-MA", "bez", "bez-TZ", "bg", "bg-BG", "bho-IN", "bm", "bm-ML", "bn", "bn-BD", "bn-IN", "bo", "bo-CN", "bo-IN", "br-FR", "brx-IN", "bs", "bs-BA", "byn-ER", "ca", "ca-AD", "ca-ES", "ca-FR", "ca-IT", "cgg", "cgg-UG", "chr", "chr-US", "crh-UA", "cs", "cs-CZ", "csb-PL", "cv-RU", "cy", "cy-GB", "da", "da-DK", "dav", "dav-KE", "de", "de-AT", "de-BE", "de-CH", "de-DE", "de-LI", "de-LU", "dv-MV", "dz-BT", "ebu", "ebu-KE", "ee", "ee-GH", "ee-TG", "el", "el-CY", "el-GR", "en", "en-AG", "en-AS", "en-AU", "en-BE", "en-BW", "en-BZ", "en-CA", "en-DK", "en-GB", "en-GU", "en-HK", "en-IE", "en-IN", "en-JM", "en-MH", "en-MP", "en-MT", "en-MU", "en-NA", "en-NG", "en-NZ", "en-PH", "en-PK", "en-SG", "en-TT", "en-UM", "en-US", "en-VI", "en-ZA", "en-ZM", "en-ZW", "eo", "es", "es-419", "es-AR", "es-BO", "es-CL", "es-CO", "es-CR", "es-CU", "es-DO", "es-EC", "es-ES", "es-GQ", "es-GT", "es-HN", "es-MX", "es-NI", "es-PA", "es-PE", "es-PR", "es-PY", "es-SV", "es-US", "es-UY", "es-VE", "et", "et-EE", "eu", "eu-ES", "fa", "fa-AF", "fa-IR", "ff", "ff-SN", "fi", "fi-FI", "fil", "fil-PH", "fo", "fo-FO", "fr", "fr-BE", "fr-BF", "fr-BI", "fr-BJ", "fr-BL", "fr-CA", "fr-CD", "fr-CF", "fr-CG", "fr-CH", "fr-CI", "fr-CM", "fr-DJ", "fr-FR", "fr-GA", "fr-GN", "fr-GP", "fr-GQ", "fr-KM", "fr-LU", "fr-MC", "fr-MF", "fr-MG", "fr-ML", "fr-MQ", "fr-NE", "fr-RE", "fr-RW", "fr-SN", "fr-TD", "fr-TG", "fur-IT", "fy-DE", "fy-NL", "ga", "ga-IE", "gd-GB", "gez-ER", "gez-ET", "gl", "gl-ES", "gsw", "gsw-CH", "gu", "gu-IN", "guz", "guz-KE", "gv", "gv-GB", "ha", "ha-Latn", "ha-Latn-GH", "ha-Latn-NE", "ha-Latn-NG", "ha-NG", "haw", "haw-US", "he", "he-IL", "hi", "hi-IN", "hne-IN", "hr", "hr-HR", "hsb-DE", "ht-HT", "hu", "hu-HU", "hy", "hy-AM", "id", "id-ID", "ig", "ig-NG", "ii", "ii-CN", "ik-CA", "is", "is-IS", "it", "it-CH", "it-IT", "iu-CA", "iw-IL", "ja", "ja-JP", "jmc", "jmc-TZ", "ka", "ka-GE", "kab", "kab-DZ", "kam", "kam-KE", "kde", "kde-TZ", "kea", "kea-CV", "khq", "khq-ML", "ki", "ki-KE", "kk", "kk-Cyrl", "kk-Cyrl-KZ", "kk-KZ", "kl", "kl-GL", "kln", "kln-KE", "km", "km-KH", "kn", "kn-IN", "ko", "ko-KR", "kok", "kok-IN", "ks-IN", "ku-TR", "kw", "kw-GB", "ky-KG", "lag", "lag-TZ", "lb-LU", "lg", "lg-UG", "li-BE", "li-NL", "lij-IT", "lo-LA", "lt", "lt-LT", "luo", "luo-KE", "luy", "luy-KE", "lv", "lv-LV", "mag-IN", "mai-IN", "mas", "mas-KE", "mas-TZ", "mer", "mer-KE", "mfe", "mfe-MU", "mg", "mg-MG", "mhr-RU", "mi-NZ", "mk", "mk-MK", "ml", "ml-IN", "mn-MN", "mr", "mr-IN", "ms", "ms-BN", "ms-MY", "mt", "mt-MT", "my", "my-MM", "nan-TW", "naq", "naq-NA", "nb", "nb-NO", "nd", "nd-ZW", "nds-DE", "nds-NL", "ne", "ne-IN", "ne-NP", "nl", "nl-AW", "nl-BE", "nl-NL", "nn", "nn-NO", "nr-ZA", "nso-ZA", "nyn", "nyn-UG", "oc-FR", "om", "om-ET", "om-KE", "or", "or-IN", "os-RU", "pa", "pa-Arab", "pa-Arab-PK", "pa-Guru", "pa-Guru-IN", "pa-IN", "pa-PK", "pap-AN", "pl", "pl-PL", "ps", "ps-AF", "pt", "pt-BR", "pt-GW", "pt-MZ", "pt-PT", "rm", "rm-CH", "ro", "ro-MD", "ro-RO", "rof", "rof-TZ", "ru", "ru-MD", "ru-RU", "ru-UA", "rw", "rw-RW", "rwk", "rwk-TZ", "sa-IN", "saq", "saq-KE", "sc-IT", "sd-IN", "se-NO", "seh", "seh-MZ", "ses", "ses-ML", "sg", "sg-CF", "shi", "shi-Latn", "shi-Latn-MA", "shi-Tfng", "shi-Tfng-MA", "shs-CA", "si", "si-LK", "sid-ET", "sk", "sk-SK", "sl", "sl-SI", "sn", "sn-ZW", "so", "so-DJ", "so-ET", "so-KE", "so-SO", "sq", "sq-AL", "sq-MK", "sr", "sr-Cyrl", "sr-Cyrl-BA", "sr-Cyrl-ME", "sr-Cyrl-RS", "sr-Latn", "sr-Latn-BA", "sr-Latn-ME", "sr-Latn-RS", "sr-ME", "sr-RS", "ss-ZA", "st-ZA", "sv", "sv-FI", "sv-SE", "sw", "sw-KE", "sw-TZ", "ta", "ta-IN", "ta-LK", "te", "te-IN", "teo", "teo-KE", "teo-UG", "tg-TJ", "th", "th-TH", "ti", "ti-ER", "ti-ET", "tig-ER", "tk-TM", "tl-PH", "tn-ZA", "to", "to-TO", "tr", "tr-CY", "tr-TR", "ts-ZA", "tt-RU", "tzm", "tzm-Latn", "tzm-Latn-MA", "ug-CN", "uk", "uk-UA", "unm-US", "ur", "ur-IN", "ur-PK", "uz", "uz-Arab", "uz-Arab-AF", "uz-Cyrl", "uz-Cyrl-UZ", "uz-Latn", "uz-Latn-UZ", "uz-UZ", "ve-ZA", "vi", "vi-VN", "vun", "vun-TZ", "wa-BE", "wae-CH", "wal-ET", "wo-SN", "xh-ZA", "xog", "xog-UG", "yi-US", "yo", "yo-NG", "yue-HK", "zh", "zh-CN", "zh-HK", "zh-Hans", "zh-Hans-CN", "zh-Hans-HK", "zh-Hans-MO", "zh-Hans-SG", "zh-Hant", "zh-Hant-HK", "zh-Hant-MO", "zh-Hant-TW", "zh-SG", "zh-TW", "zu", "zu-ZA" ], "type": "string" }, { "const": "auto", "type": "string" } ], "default": "en", "description": "Locale for browser language and region settings", "examples": [ "en-US" ] }, "markdown_backend": { "default": "full_page", "description": "Selects which markdown conversion strategy to use. \"full_page\" converts the entire HTML page. \"main_content\" uses Mozilla Readability to extract the main article content before converting.", "enum": [ "full_page", "main_content" ], "examples": [ "full_page" ], "type": "string" }, "method": { "default": "GET", "description": "HTTP method for the request", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "examples": [ "GET" ], "type": "string" }, "network_capture": { "description": "Filters for capturing network traffic", "items": { "properties": { "method": { "enum": [ "GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH" ], "type": "string" }, "resource_type": { "anyOf": [ { "description": "Resource type for network capture filtering", "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, { "items": { "description": "Resource type for network capture filtering", "examples": [ "document", "script", "xhr", "fetch" ], "type": "string" }, "minItems": 1, "type": "array" } ] }, "status_code": { "anyOf": [ { "maximum": 599, "minimum": 100, "type": "number" }, { "items": { "maximum": 599, "minimum": 100, "type": "number" }, "minItems": 1, "type": "array" } ] }, "url": { "properties": { "type": { "default": "exact", "enum": [ "exact", "contains" ], "type": "string" }, "value": { "type": "string" } }, "required": [ "value" ], "type": "object" }, "validation": { "default": false, "type": "boolean" }, "wait_for_requests_count": { "default": 0, "minimum": 0, "type": "number" }, "wait_for_requests_count_timeout": { "exclusiveMinimum": 0, "maximum": 300000, "type": "number" } }, "type": "object" }, "type": "array" }, "os": { "description": "Operating system to emulate", "enum": [ "windows", "mac os", "linux", "android", "ios" ], "examples": [ "windows" ], "type": "string" }, "parse": { "default": false, "description": "Whether to parse the response content", "examples": [ true ], "type": "boolean" }, "parser": { "anyOf": [ { "additionalProperties": {}, "propertyNames": { "type": "string" }, "type": "object" }, { "type": "string" } ], "description": "Custom parser configuration as a key-value map", "examples": [ { "myParser": { "option1": "value1" } } ] }, "referrer_type": { "anyOf": [ { "enum": [ "random", "no-referer", "same-origin" ], "type": "string" }, { "enum": [ "google", "bing", "facebook", "twitter", "instagram" ], "type": "string" } ], "description": "Referrer policy for the request", "examples": [ "no-referrer" ] }, "render": { "anyOf": [ { "type": "boolean" }, { "const": "auto", "type": "string" } ], "description": "Whether to render JavaScript content using a browser. Use 'auto' to let the engine select the candidate config per domain.", "examples": [ false, true, "auto" ] }, "request_timeout": { "description": "Request timeout in milliseconds", "examples": [ 30000 ], "minimum": 1, "type": "number" }, "session": { "properties": { "id": { "type": "string" }, "prefetch_userbrowser": { "default": false, "type": "boolean" }, "renew_on_blocked": { "default": false, "type": "boolean" }, "retry": { "default": false, "type": "boolean" }, "timeout": { "exclusiveMinimum": 0, "type": "number" } }, "type": "object" }, "skill": { "anyOf": [ { "description": "Skills or capabilities required for the request", "examples": [ "dynamic-content" ], "private": true, "type": "string", "x-private": true }, { "description": "Skills or capabilities required for the request", "examples": [ [ "javascript", "dynamic-content" ] ], "items": { "type": "string" }, "private": true, "type": "array", "x-private": true } ] }, "state": { "description": "US state for geolocation (only valid when country is US)", "enum": [ "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "VI", "WA", "WV", "WI", "WY" ], "examples": [ "CA" ], "type": "string" }, "tag": { "description": "User-defined tag for request identification", "examples": [ "campaign-2024-q1" ], "type": "string" }, "url": { "description": "Target URL to scrape", "type": "string" } }, "type": "object" }, { "properties": { "callback_url": { "description": "URL to call back when async operation completes", "examples": [ "https://example.com/webhook/callback" ], "type": "string" }, "storage_compress": { "description": "Whether to compress stored data", "examples": [ true ], "type": "boolean" }, "storage_object_name": { "description": "Custom name for the stored object", "examples": [ "result-2024-01-15.json" ], "type": "string" }, "storage_type": { "description": "Type of storage to use for results", "examples": [ "s3" ], "type": "string" }, "storage_url": { "description": "URL for storage location", "examples": [ "s3://bucket-name/path/to/object" ], "type": "string" } }, "type": "object" } ], "description": "Shared parameters applied to the entire batch. Can include extraction parameters and async/storage settings." } }, "required": [ "inputs" ], "type": "object" }, "SerpBatchPayload": { "properties": { "inputs": { "description": "Array of SERP requests. Each object can include search parameters and async/storage settings.", "items": { "allOf": [ { "properties": { "country": { "description": "ISO Alpha-2 country code used to access the target search engine (e.g. US, DE, GB).", "examples": [ "US" ], "type": "string" }, "device": { "description": "Device type used for the search request.", "enum": [ "desktop", "mobile" ], "examples": [ "desktop" ], "type": "string" }, "domain": { "default": "com", "description": "Top-level domain for the search engine (e.g. \"com\", \"co.uk\", \"de\").", "examples": [ "com" ], "type": "string" }, "locale": { "description": "Locale used for the search request.", "examples": [ "en" ], "type": "string" }, "location": { "description": "Geo-location for the search (canonical Google location name).", "examples": [ "New York, New York, United States" ], "type": "string" }, "num_results": { "description": "Number of results to return (1–100).", "examples": [ 10 ], "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "The result page number for pagination.", "examples": [ 1 ], "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "parse": { "default": true, "description": "When true, the SERP response is parsed into structured JSON.", "examples": [ true ], "type": "boolean" }, "query": { "description": "The search keyword or phrase to query.", "examples": [ "nimble web data" ], "type": "string" }, "render": { "default": false, "description": "Whether to render the page in a browser before extracting.", "examples": [ false ], "type": "boolean" }, "search_engine": { "description": "The search engine to query.", "enum": [ "google_search", "google_sge", "google_aio", "google_maps_search", "google_maps_reviews", "google_maps_place", "google_news", "google_images", "bing_search", "yandex_search" ], "examples": [ "google_search" ], "type": "string" }, "show_hidden_results": { "description": "When true, disables Google result filtering (filter=0) so omitted/duplicate and highly similar pages are also returned. Applies to Google search engines.", "examples": [ false ], "type": "boolean" } }, "type": "object" }, { "properties": { "callback_url": { "description": "URL to call back when async operation completes", "examples": [ "https://example.com/webhook/callback" ], "type": "string" }, "storage_compress": { "description": "Whether to compress stored data", "examples": [ true ], "type": "boolean" }, "storage_object_name": { "description": "Custom name for the stored object", "examples": [ "result-2024-01-15.json" ], "type": "string" }, "storage_type": { "description": "Type of storage to use for results", "examples": [ "s3" ], "type": "string" }, "storage_url": { "description": "URL for storage location", "examples": [ "s3://bucket-name/path/to/object" ], "type": "string" } }, "type": "object" } ] }, "minItems": 1, "type": "array" }, "shared_inputs": { "allOf": [ { "properties": { "country": { "description": "ISO Alpha-2 country code used to access the target search engine (e.g. US, DE, GB).", "examples": [ "US" ], "type": "string" }, "device": { "description": "Device type used for the search request.", "enum": [ "desktop", "mobile" ], "examples": [ "desktop" ], "type": "string" }, "domain": { "default": "com", "description": "Top-level domain for the search engine (e.g. \"com\", \"co.uk\", \"de\").", "examples": [ "com" ], "type": "string" }, "locale": { "description": "Locale used for the search request.", "examples": [ "en" ], "type": "string" }, "location": { "description": "Geo-location for the search (canonical Google location name).", "examples": [ "New York, New York, United States" ], "type": "string" }, "num_results": { "description": "Number of results to return (1–100).", "examples": [ 10 ], "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "The result page number for pagination.", "examples": [ 1 ], "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "parse": { "default": true, "description": "When true, the SERP response is parsed into structured JSON.", "examples": [ true ], "type": "boolean" }, "query": { "description": "The search keyword or phrase to query.", "examples": [ "nimble web data" ], "type": "string" }, "render": { "default": false, "description": "Whether to render the page in a browser before extracting.", "examples": [ false ], "type": "boolean" }, "search_engine": { "description": "The search engine to query.", "enum": [ "google_search", "google_sge", "google_aio", "google_maps_search", "google_maps_reviews", "google_maps_place", "google_news", "google_images", "bing_search", "yandex_search" ], "examples": [ "google_search" ], "type": "string" }, "show_hidden_results": { "description": "When true, disables Google result filtering (filter=0) so omitted/duplicate and highly similar pages are also returned. Applies to Google search engines.", "examples": [ false ], "type": "boolean" } }, "type": "object" }, { "properties": { "callback_url": { "description": "URL to call back when async operation completes", "examples": [ "https://example.com/webhook/callback" ], "type": "string" }, "storage_compress": { "description": "Whether to compress stored data", "examples": [ true ], "type": "boolean" }, "storage_object_name": { "description": "Custom name for the stored object", "examples": [ "result-2024-01-15.json" ], "type": "string" }, "storage_type": { "description": "Type of storage to use for results", "examples": [ "s3" ], "type": "string" }, "storage_url": { "description": "URL for storage location", "examples": [ "s3://bucket-name/path/to/object" ], "type": "string" } }, "type": "object" } ], "description": "Shared parameters applied to the entire batch. Can include search parameters and async/storage settings." } }, "required": [ "inputs" ], "type": "object" }, "DriverResolutionResponse": { "additionalProperties": false, "properties": { "agent": { "description": "The input agent name (present when agent query param was used)", "type": "string" }, "antibots": { "description": "List of detected antibots for the domain", "examples": [ [ "cloudflare", "datadome" ] ], "items": { "type": "string" }, "type": "array" }, "description": { "description": "Description of the driver", "type": "string" }, "driver": { "description": "Resolved driver name", "examples": [ "vx10-pro" ], "type": "string" }, "need_to_render": { "description": "Whether the page needs to be rendered to be properly resolved.", "type": "boolean" }, "url": { "description": "The input URL (present when url query param was used)", "type": "string" } }, "required": [ "driver", "antibots", "description" ], "type": "object" }, "SearchResponse": { "description": "Response model from SearchService with results.\n\nNote: request_id is always a valid UUID generated internally by the middleware,\nso no validation is needed.", "properties": { "request_id": { "description": "Unique identifier for this request (UUID)", "title": "Request Id", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/ResultModel" }, "title": "Results", "type": "array" }, "total_results": { "description": "Number of results returned", "title": "Total Results", "type": "integer" } }, "required": [ "total_results", "results", "request_id" ], "title": "SearchResponse", "type": "object" }, "MapResponse": { "additionalProperties": false, "description": "Response schema for map requests.", "properties": { "links": { "description": "Array of mapped links with optional titles and descriptions.", "examples": [ [ { "description": "This is an example description for page 1.", "title": "Example Page 1", "url": "https://example.com/page1" }, { "url": "https://example.com/page2" } ] ], "items": { "additionalProperties": false, "properties": { "description": { "type": "string" }, "title": { "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" }, "type": "array" }, "success": { "description": "Indicates if the map request was successful.", "examples": [ true ], "type": "boolean" }, "task_id": { "description": "Unique identifier for the map task.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" } }, "required": [ "task_id", "success", "links" ], "type": "object" }, "Error402": { "type": "object", "title": "Error402", "properties": { "status": { "type": "string", "example": "failed", "examples": [ "failed" ] }, "msg": { "type": "string", "description": "Error message indicating the payment issue", "example": "trial expired", "enum": [ "no budget", "limit reached", "trial expired", "trial quota finished" ] } }, "required": [ "status", "msg" ], "example": { "status": "failed", "msg": "trial expired" } }, "Error400": { "type": "object", "title": "Error400", "properties": { "status": { "type": "string", "example": "failed", "examples": [ "failed" ] }, "msg": { "type": "string", "description": "Validation error message describing what went wrong", "example": "Invalid request parameters", "examples": [ "Invalid request parameters" ] }, "error": { "type": "string", "description": "The validation error type", "example": "PARAMETERS_FAILED_JSON_SCHEMA_VALIDATION_ERROR", "examples": [ "PARAMETERS_FAILED_JSON_SCHEMA_VALIDATION_ERROR" ] }, "details": { "type": "object", "description": "Detailed validation error information", "example": { "schema_validation_errors": [ { "instancePath": "", "schemaPath": "#/required", "keyword": "required", "params": { "missingProperty": "search_engine" }, "message": "must have required property 'search_engine'" } ] } } }, "required": [ "status", "msg" ], "example": { "status": "failed", "msg": "Invalid request parameters", "error": "PARAMETERS_FAILED_JSON_SCHEMA_VALIDATION_ERROR", "details": { "schema_validation_errors": [ { "instancePath": "", "schemaPath": "#/required", "keyword": "required", "params": { "missingProperty": "search_engine" }, "message": "must have required property 'search_engine'" } ] } } }, "Error429": { "type": "object", "title": "Error429", "properties": { "status": { "type": "string", "example": "failed", "examples": [ "failed" ] }, "msg": { "type": "string", "example": "Rate limit exceeded", "examples": [ "Rate limit exceeded" ] } }, "required": [ "status", "msg" ], "example": { "status": "failed", "msg": "Rate limit exceeded" } }, "Error500": { "type": "object", "title": "Error500", "properties": { "success": { "type": "string", "example": "false", "examples": [ "false" ] }, "task_id": { "type": "string", "example": "1ed1dbeb-8f34-4fd1-bb2d-a72bacae2ef3", "examples": [ "1ed1dbeb-8f34-4fd1-bb2d-a72bacae2ef3" ] }, "message": { "type": "string", "example": "can't download the query response - please try again", "examples": [ "can't download the query response - please try again" ] } }, "required": [ "success", "task_id", "message" ], "example": { "success": "false", "task_id": "1ed1dbeb-8f34-4fd1-bb2d-a72bacae2ef3", "message": "can't download the query response - please try again" } }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "title": "Detail", "type": "array" } }, "title": "HTTPValidationError", "type": "object" }, "ValidationError": { "properties": { "ctx": { "title": "Context", "type": "object" }, "input": { "title": "Input" }, "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "title": "Location", "type": "array" }, "msg": { "title": "Message", "type": "string" }, "type": { "title": "Error Type", "type": "string" } }, "required": [ "loc", "msg", "type" ], "title": "ValidationError", "type": "object" }, "CreateExtractTemplateGenerationRequestPublicV2": { "additionalProperties": false, "properties": { "input_schema": { "additionalProperties": true, "description": "Optional JSON schema describing expected input parameters.", "title": "Input Schema", "type": "object" }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/CreateExtractTemplateMetadataPublicV2" }, { "type": "null" } ], "description": "Metadata to attach to the generated extract template." }, "name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "pattern": "^[a-z0-9_]+$", "type": "string" }, { "type": "null" } ], "description": "Optional stable name for the generated extract template.", "title": "Name" }, "output_schema": { "additionalProperties": true, "description": "Optional JSON schema describing desired extracted output.", "title": "Output Schema", "type": "object" }, "prompt": { "description": "Instructions for generating the extract template.", "title": "Prompt", "type": "string" }, "url": { "description": "Example URL used to generate the extract template.", "title": "Url", "type": "string" } }, "required": [ "prompt", "url" ], "title": "CreateExtractTemplateGenerationRequestPublicV2", "type": "object" }, "CreateExtractTemplateMetadataPublicV2": { "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description for the generated template.", "title": "Description" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-friendly display name for the generated template.", "title": "Display Name" }, "tags": { "description": "Tags to associate with the generated template.", "items": { "type": "string" }, "title": "Tags", "type": "array" } }, "title": "CreateExtractTemplateMetadataPublicV2", "type": "object" }, "CreateExtractTemplateRefinementRequestPublicV2": { "additionalProperties": false, "properties": { "from_extract_template": { "description": "Name of the source extract template to refine.", "title": "From Extract Template", "type": "string" }, "prompt": { "description": "Instructions for refining the extract template.", "title": "Prompt", "type": "string" } }, "required": [ "prompt", "from_extract_template" ], "title": "CreateExtractTemplateRefinementRequestPublicV2", "type": "object" }, "ExtractBatchResponse": { "additionalProperties": false, "description": "Response when a batch of extract tasks is created successfully.", "properties": { "batch_id": { "description": "Unique identifier for the batch.", "type": "string" }, "batch_size": { "description": "Number of tasks in the batch.", "type": "number" }, "tasks": { "description": "List of created tasks.", "items": { "additionalProperties": false, "properties": { "_query": {}, "account_name": { "description": "Account name that owns the task.", "type": "string" }, "api_type": { "enum": [ "web", "serp", "ecommerce", "social", "media", "agent", "extract", "fast-serp", "labs" ], "type": "string" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Batch ID if this task is part of a batch.", "examples": [ "4b0a90bf-c951-42e4-95b3-a95a65ba69fc" ] }, "created_at": { "description": "Timestamp when the task was created.", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "download_url": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ], "description": "URL for downloading the task results.", "examples": [ "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000/results" ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if the task failed.", "examples": [ "Connection timeout" ] }, "error_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Classification of the error type.", "examples": [ "timeout_error" ] }, "id": { "description": "Unique task identifier.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "minLength": 1, "type": "string" }, "input": { "description": "Original input data for the task." }, "modified_at": { "description": "Timestamp when the task was last modified.", "examples": [ "2024-01-15T10:35:00Z" ], "type": "string" }, "output_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Storage location of the output data." }, "queue": { "description": "Queue name the task was submitted to.", "type": "string" }, "state": { "description": "Current state of the task.", "enum": [ "pending", "queued", "in_progress", "success", "error" ], "examples": [ "pending" ], "type": "string" }, "status_code": { "description": "HTTP status code from the task execution.", "examples": [ 200 ], "type": "number" }, "status_url": { "description": "URL for checking the task status.", "examples": [ "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000" ], "format": "uri", "type": "string" } }, "required": [ "id", "state", "status_url", "created_at", "input", "_query" ], "type": "object" }, "type": "array" } }, "required": [ "batch_id", "batch_size", "tasks" ], "type": "object" }, "ExtractTemplateGenerationResponsePublicV2": { "properties": { "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the generation completed.", "title": "Completed At" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the generation was created.", "title": "Created At" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message when generation failed.", "title": "Error" }, "generated_version": { "anyOf": [ { "$ref": "#/components/schemas/ExtractTemplateVersionResponsePublicV2" }, { "type": "null" } ], "description": "Generated version details, when available." }, "generated_version_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Identifier of the generated version.", "title": "Generated Version Id" }, "id": { "description": "Unique extract template generation identifier.", "format": "uuid", "title": "Id", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Extract template name associated with the generation.", "title": "Name" }, "source_version_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Identifier of the version being refined.", "title": "Source Version Id" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the generation started executing.", "title": "Started At" }, "status": { "description": "Current generation status.", "title": "Status", "type": "string" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Summary of the generation result.", "title": "Summary" } }, "required": [ "id", "status" ], "title": "ExtractTemplateGenerationResponsePublicV2", "type": "object" }, "ExtractTemplateResponsePublicV2": { "properties": { "created_at": { "description": "When the extract template was created.", "format": "date-time", "title": "Created At", "type": "string" }, "id": { "description": "Unique extract template identifier.", "format": "uuid", "title": "Id", "type": "string" }, "name": { "description": "Stable extract template name.", "title": "Name", "type": "string" }, "published_version": { "anyOf": [ { "$ref": "#/components/schemas/ExtractTemplateVersionResponsePublicV2" }, { "type": "null" } ], "description": "Published version details, when available." }, "published_version_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Identifier of the published version.", "title": "Published Version Id" }, "updated_at": { "description": "When the extract template was last updated.", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "name", "created_at", "updated_at" ], "title": "ExtractTemplateResponsePublicV2", "type": "object" }, "ExtractTemplateSamplePublicV2": { "properties": { "input": { "anyOf": [ { "$ref": "#/components/schemas/JsonValue" }, { "type": "null" } ], "description": "Sample input parameters for the version." }, "output": { "anyOf": [ { "$ref": "#/components/schemas/JsonValue" }, { "type": "null" } ], "description": "Sample output produced by the version." } }, "title": "ExtractTemplateSamplePublicV2", "type": "object" }, "ExtractTemplateVersionMetadataPublicV2": { "properties": { "data_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Data source associated with the version.", "title": "Data Source" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Version description shown to users.", "title": "Description" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-friendly version display name.", "title": "Display Name" }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Domain associated with the version.", "title": "Domain" }, "entity_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Entity type produced by the version.", "title": "Entity Type" }, "tags": { "description": "Tags associated with the version.", "items": { "type": "string" }, "title": "Tags", "type": "array" }, "vertical": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Business vertical associated with the version.", "title": "Vertical" } }, "title": "ExtractTemplateVersionMetadataPublicV2", "type": "object" }, "ExtractTemplateVersionResponsePublicV2": { "properties": { "created_at": { "description": "When the version was created.", "format": "date-time", "title": "Created At", "type": "string" }, "id": { "description": "Unique extract template version identifier.", "format": "uuid", "title": "Id", "type": "string" }, "input_schema": { "additionalProperties": true, "description": "JSON schema describing accepted input parameters.", "title": "Input Schema", "type": "object" }, "metadata": { "$ref": "#/components/schemas/ExtractTemplateVersionMetadataPublicV2", "description": "Metadata associated with this version." }, "name": { "description": "Extract template name this version belongs to.", "title": "Name", "type": "string" }, "output_schema": { "additionalProperties": true, "description": "JSON schema describing extracted output.", "title": "Output Schema", "type": "object" }, "samples": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ExtractTemplateSamplePublicV2" }, "type": "array" }, { "type": "null" } ], "description": "Sample input and output pairs for the version.", "title": "Samples" }, "version_number": { "description": "Monotonic version number for the extract template.", "title": "Version Number", "type": "integer" } }, "required": [ "id", "name", "version_number", "metadata", "input_schema", "output_schema", "created_at" ], "title": "ExtractTemplateVersionResponsePublicV2", "type": "object" }, "ExtractionTemplateBatchBody": { "description": "Request body for executing a batch of Extraction Template requests", "properties": { "inputs": { "items": { "additionalProperties": false, "properties": { "formats": { "description": "Response formats to include. All disabled by default.", "examples": [ [ "html", "markdown" ] ], "items": { "enum": [ "html", "markdown", "screenshot", "headers", "links" ], "type": "string" }, "minItems": 1, "type": "array" }, "localization": { "type": "boolean" }, "params": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "type": "object" }, "minItems": 1, "type": "array" }, "shared_inputs": { "properties": { "formats": { "description": "Response formats to include. All disabled by default.", "examples": [ [ "html", "markdown" ] ], "items": { "enum": [ "html", "markdown", "screenshot", "headers", "links" ], "type": "string" }, "minItems": 1, "type": "array" }, "localization": { "type": "boolean" }, "params": { "additionalProperties": {}, "properties": {}, "type": "object" }, "template": { "type": "string" } }, "required": [ "template" ], "type": "object" } }, "required": [ "inputs", "shared_inputs" ], "type": "object" }, "ExtractionTemplateBody": { "description": "Request body for executing an Extraction Template", "properties": { "formats": { "description": "Response formats to include. All disabled by default.", "examples": [ [ "html", "markdown" ] ], "items": { "enum": [ "html", "markdown", "screenshot", "headers", "links" ], "type": "string" }, "minItems": 1, "type": "array" }, "localization": { "default": false, "type": "boolean" }, "params": { "additionalProperties": {}, "properties": {}, "type": "object" }, "template": { "type": "string" } }, "required": [ "params", "template" ], "type": "object" }, "JsonPatchDocument": { "description": "A JSON Patch document per RFC 6902 — a JSON array of patch operations.", "items": { "$ref": "#/components/schemas/JsonPatchOp" }, "title": "JsonPatchDocument", "type": "array" }, "JsonPatchOp": { "additionalProperties": false, "description": "A single JSON Patch operation per RFC 6902.", "properties": { "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From" }, "op": { "enum": [ "add", "remove", "replace", "move", "copy", "test" ], "title": "Op", "type": "string" }, "path": { "title": "Path", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/JsonValue" }, { "type": "null" } ] } }, "required": [ "op", "path" ], "title": "JsonPatchOp", "type": "object" }, "JsonValue": {}, "ListResponse_ExtractTemplateResponsePublicV2_": { "properties": { "items": { "description": "Items returned in this page.", "items": { "$ref": "#/components/schemas/ExtractTemplateResponsePublicV2" }, "title": "Items", "type": "array" }, "limit": { "description": "Maximum number of items returned.", "title": "Limit", "type": "integer" }, "offset": { "description": "Number of items skipped before this page.", "title": "Offset", "type": "integer" }, "total": { "description": "Total number of items matching the query.", "title": "Total", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "title": "ListResponse[ExtractTemplateResponsePublicV2]", "type": "object" }, "ListResponse_ExtractTemplateVersionResponsePublicV2_": { "properties": { "items": { "description": "Items returned in this page.", "items": { "$ref": "#/components/schemas/ExtractTemplateVersionResponsePublicV2" }, "title": "Items", "type": "array" }, "limit": { "description": "Maximum number of items returned.", "title": "Limit", "type": "integer" }, "offset": { "description": "Number of items skipped before this page.", "title": "Offset", "type": "integer" }, "total": { "description": "Total number of items matching the query.", "title": "Total", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "title": "ListResponse[ExtractTemplateVersionResponsePublicV2]", "type": "object" }, "ParsingErrorResult": { "additionalProperties": false, "properties": { "error": { "type": "string" }, "status": { "const": "error", "type": "string" } }, "required": [ "status", "error" ], "type": "object" }, "ParsingSuccessResult": { "additionalProperties": false, "properties": { "entities": { "additionalProperties": {}, "propertyNames": { "type": "string" }, "type": "object" }, "status": { "const": "success", "type": "string" } }, "required": [ "status", "entities" ], "type": "object" }, "TaskErrorResponse": { "additionalProperties": false, "description": "Error response for task operations.", "properties": { "error": { "description": "Error message describing what went wrong.", "examples": [ "task not found" ], "type": "string" }, "status": { "const": "failed", "description": "Status indicating the request failed.", "type": "string" } }, "required": [ "status", "error" ], "type": "object" }, "TaskFailedResponse": { "additionalProperties": false, "description": "Response when task execution failed.", "properties": { "error": { "description": "Error message.", "examples": [ "task failed" ], "type": "string" }, "status": { "const": "failed", "description": "Status indicating the task failed.", "type": "string" }, "task": { "additionalProperties": false, "description": "The failed task details.", "properties": { "_query": {}, "account_name": { "description": "Account name that owns the task.", "type": "string" }, "api_type": { "enum": [ "web", "serp", "ecommerce", "social", "media", "agent", "extract", "fast-serp", "labs" ], "type": "string" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Batch ID if this task is part of a batch.", "examples": [ "4b0a90bf-c951-42e4-95b3-a95a65ba69fc" ] }, "created_at": { "description": "Timestamp when the task was created.", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "download_url": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ], "description": "URL for downloading the task results.", "examples": [ "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000/results" ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if the task failed.", "examples": [ "Connection timeout" ] }, "error_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Classification of the error type.", "examples": [ "timeout_error" ] }, "id": { "description": "Unique task identifier.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "minLength": 1, "type": "string" }, "input": { "description": "Original input data for the task." }, "modified_at": { "description": "Timestamp when the task was last modified.", "examples": [ "2024-01-15T10:35:00Z" ], "type": "string" }, "output_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Storage location of the output data." }, "queue": { "description": "Queue name the task was submitted to.", "type": "string" }, "state": { "description": "Current state of the task.", "enum": [ "pending", "queued", "in_progress", "success", "error" ], "examples": [ "pending" ], "type": "string" }, "status_code": { "description": "HTTP status code from the task execution.", "examples": [ 200 ], "type": "number" }, "status_url": { "description": "URL for checking the task status.", "examples": [ "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000" ], "format": "uri", "type": "string" } }, "required": [ "id", "state", "status_url", "created_at", "input", "_query" ], "type": "object" } }, "required": [ "status", "error", "task" ], "type": "object" }, "TaskNotFoundErrorResponse": { "additionalProperties": false, "description": "Error response when the specified task is not found.", "properties": { "error": { "const": "task not found", "description": "Error message indicating the task was not found.", "type": "string" }, "status": { "const": "failed", "description": "Status indicating the request failed.", "type": "string" } }, "required": [ "status", "error" ], "type": "object" }, "TaskPendingResponse": { "additionalProperties": false, "description": "Response when task is still pending.", "properties": { "error": { "const": "task not finished yet", "description": "Error message indicating task is not finished yet.", "type": "string" }, "status": { "const": "failed", "description": "Status indicating the task is still pending.", "type": "string" } }, "required": [ "status", "error" ], "type": "object" }, "TaskResponseSchema": { "additionalProperties": false, "description": "Response containing task details.", "properties": { "task": { "additionalProperties": false, "properties": { "_query": {}, "account_name": { "description": "Account name that owns the task.", "type": "string" }, "api_type": { "enum": [ "web", "serp", "ecommerce", "social", "media", "agent", "extract", "fast-serp", "labs" ], "type": "string" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Batch ID if this task is part of a batch.", "examples": [ "4b0a90bf-c951-42e4-95b3-a95a65ba69fc" ] }, "created_at": { "description": "Timestamp when the task was created.", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "download_url": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ], "description": "URL for downloading the task results.", "examples": [ "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000/results" ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if the task failed.", "examples": [ "Connection timeout" ] }, "error_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Classification of the error type.", "examples": [ "timeout_error" ] }, "id": { "description": "Unique task identifier.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "minLength": 1, "type": "string" }, "input": { "description": "Original input data for the task." }, "modified_at": { "description": "Timestamp when the task was last modified.", "examples": [ "2024-01-15T10:35:00Z" ], "type": "string" }, "output_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Storage location of the output data." }, "queue": { "description": "Queue name the task was submitted to.", "type": "string" }, "state": { "description": "Current state of the task.", "enum": [ "pending", "queued", "in_progress", "success", "error" ], "examples": [ "pending" ], "type": "string" }, "status_code": { "description": "HTTP status code from the task execution.", "examples": [ 200 ], "type": "number" }, "status_url": { "description": "URL for checking the task status.", "examples": [ "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000" ], "format": "uri", "type": "string" } }, "required": [ "id", "state", "status_url", "created_at", "input", "_query" ], "type": "object" } }, "required": [ "task" ], "type": "object" }, "AgentSourcesPublicV2": { "additionalProperties": false, "properties": { "allow": { "description": "Source groups the agent is allowed to use.", "items": { "$ref": "#/components/schemas/WebSearchAgentSourceCreateRequestPublicV2" }, "title": "Allow", "type": "array" }, "avoid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text guidance describing sources or domains to avoid.", "title": "Avoid" }, "block": { "description": "Source groups the agent should not use.", "items": { "$ref": "#/components/schemas/WebSearchAgentSourceCreateRequestPublicV2" }, "title": "Block", "type": "array" }, "prioritize": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text guidance describing sources or domains to prioritize.", "title": "Prioritize" } }, "title": "AgentSourcesPublicV2", "type": "object" }, "AgentSourcesResponsePublicV2": { "additionalProperties": false, "properties": { "allow": { "description": "Source groups the agent is allowed to use.", "items": { "$ref": "#/components/schemas/WebSearchAgentSourceResponsePublicV2" }, "title": "Allow", "type": "array" }, "avoid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text guidance describing sources or domains to avoid.", "title": "Avoid" }, "block": { "description": "Source groups the agent should not use.", "items": { "$ref": "#/components/schemas/WebSearchAgentSourceResponsePublicV2" }, "title": "Block", "type": "array" }, "prioritize": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text guidance describing sources or domains to prioritize.", "title": "Prioritize" } }, "title": "AgentSourcesResponsePublicV2", "type": "object" }, "Effort": { "description": "Canonical effort tier names for the research graph.", "enum": [ "low", "medium", "high", "x-high", "max" ], "title": "Effort", "type": "string" }, "JsonClaimTrust": { "description": "Trust metadata for one value in a structured (JSON) answer, keyed by JSON path.", "properties": { "citations": { "description": "Citations backing this value.", "items": { "$ref": "#/components/schemas/TrustCitation" }, "title": "Citations", "type": "array" }, "confidence": { "$ref": "#/components/schemas/TrustConfidence", "description": "Confidence in this value." }, "path": { "description": "JSON path of the value in the structured output this claim refers to.", "title": "Path", "type": "string" }, "reasoning": { "description": "Why this confidence level was assigned.", "title": "Reasoning", "type": "string" } }, "required": [ "citations", "confidence", "reasoning", "path" ], "title": "JsonClaimTrust", "type": "object" }, "JsonRunTrust": { "description": "Trust metadata for a structured answer: run-level confidence plus per-value citations.", "properties": { "claims": { "description": "Per-value trust, keyed by JSON path in the structured output.", "items": { "$ref": "#/components/schemas/JsonClaimTrust" }, "title": "Claims", "type": "array" }, "confidence": { "$ref": "#/components/schemas/TrustConfidence", "description": "Overall confidence in the answer." }, "reasoning": { "description": "Why this confidence level was assigned.", "title": "Reasoning", "type": "string" }, "sources": { "description": "Sources consulted while producing the answer.", "items": { "$ref": "#/components/schemas/TrustSource" }, "title": "Sources", "type": "array" } }, "required": [ "sources", "confidence", "reasoning", "claims" ], "title": "JsonRunTrust", "type": "object" }, "ListResponse_TaskRunResponsePublicV2_": { "properties": { "items": { "description": "Items returned in this page.", "items": { "$ref": "#/components/schemas/TaskRunResponsePublicV2" }, "title": "Items", "type": "array" }, "limit": { "description": "Maximum number of items returned.", "title": "Limit", "type": "integer" }, "offset": { "description": "Number of items skipped before this page.", "title": "Offset", "type": "integer" }, "total": { "description": "Total number of items matching the query.", "title": "Total", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "title": "ListResponse[TaskRunResponsePublicV2]", "type": "object" }, "ListResponse_WebSearchAgentResponsePublicV2_": { "properties": { "items": { "description": "Items returned in this page.", "items": { "$ref": "#/components/schemas/WebSearchAgentResponsePublicV2" }, "title": "Items", "type": "array" }, "limit": { "description": "Maximum number of items returned.", "title": "Limit", "type": "integer" }, "offset": { "description": "Number of items skipped before this page.", "title": "Offset", "type": "integer" }, "total": { "description": "Total number of items matching the query.", "title": "Total", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "title": "ListResponse[WebSearchAgentResponsePublicV2]", "type": "object" }, "ListResponse_WebSearchAgentTemplateResponsePublicV2_": { "properties": { "items": { "description": "Items returned in this page.", "items": { "$ref": "#/components/schemas/WebSearchAgentTemplateResponsePublicV2" }, "title": "Items", "type": "array" }, "limit": { "description": "Maximum number of items returned.", "title": "Limit", "type": "integer" }, "offset": { "description": "Number of items skipped before this page.", "title": "Offset", "type": "integer" }, "total": { "description": "Total number of items matching the query.", "title": "Total", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "title": "ListResponse[WebSearchAgentTemplateResponsePublicV2]", "type": "object" }, "SourceCategory": { "description": "What *kind* of source this is (classified by the compress LLM), independent\nof TrustSourceType (how authoritative it is for a specific claim). Deliberately\nuses \"official\" rather than \"primary\" so the two axes can never collide.\n\nAlso doubles as the sub-question's ``source_intent`` (what kind of source a\nquestion *needs*) — the two concepts overlap enough that a single enum lets\n``classify_source_importance`` compare \"what we got\" against \"what we asked\nfor\" directly.", "enum": [ "official", "news", "social", "academic", "aggregator", "other" ], "title": "SourceCategory", "type": "string" }, "TaskRunErrorPublicV2": { "properties": { "message": { "description": "Human-readable error description.", "title": "Message", "type": "string" }, "ref_id": { "description": "Reference ID (equals the run id).", "title": "Ref Id", "type": "string" } }, "required": [ "ref_id", "message" ], "title": "TaskRunErrorPublicV2", "type": "object" }, "TaskRunFailedResultPublicV2": { "properties": { "error": { "$ref": "#/components/schemas/TaskRunErrorPublicV2", "description": "Structured error detail." }, "run": { "$ref": "#/components/schemas/TaskRunResponsePublicV2", "description": "Task run object with status 'failed'." } }, "required": [ "run", "error" ], "title": "TaskRunFailedResultPublicV2", "type": "object" }, "TaskRunJsonOutputPublicV2": { "properties": { "content": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" } ], "description": "The final structured output.", "title": "Content" }, "trust": { "$ref": "#/components/schemas/JsonRunTrust", "description": "Trust and citation metadata for the output." }, "type": { "const": "json", "default": "json", "description": "Output content type.", "title": "Type", "type": "string" } }, "required": [ "content", "trust" ], "title": "TaskRunJsonOutputPublicV2", "type": "object" }, "TaskRunResponsePublicV2": { "properties": { "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the run completed.", "title": "Completed At" }, "created_at": { "description": "When the run was created.", "format": "date-time", "title": "Created At", "type": "string" }, "effort": { "$ref": "#/components/schemas/Effort", "description": "Effort level used for the run.", "example": "high" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/TaskRunErrorPublicV2" }, { "type": "null" } ], "description": "Error details when the run failed." }, "id": { "description": "Run identifier, format \"task_run_{uuid}\".", "title": "Id", "type": "string", "example": "task_run_c0ffee00-0000-4000-8000-000000000000" }, "interaction_id": { "description": "Interaction ID.", "title": "Interaction Id", "type": "string" }, "is_active": { "description": "True while status is 'queued' or 'running'.", "title": "Is Active", "type": "boolean" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Prompt submitted for the run.", "title": "Prompt" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the run started executing.", "title": "Started At" }, "status": { "$ref": "#/components/schemas/TaskRunStatusValue", "description": "Current run status.", "example": "queued" }, "web_search_agent_id": { "description": "Web Search Agent instance this run belongs to.", "title": "Web Search Agent Id", "type": "string", "example": "wsa_2af5b0e2-58b8-4b60-a1a4-9e57e4d33f00" } }, "required": [ "id", "interaction_id", "status", "is_active", "effort", "created_at", "web_search_agent_id" ], "title": "TaskRunResponsePublicV2", "type": "object" }, "TaskRunResultPublicV2": { "properties": { "output": { "anyOf": [ { "$ref": "#/components/schemas/TaskRunTextOutputPublicV2" }, { "$ref": "#/components/schemas/TaskRunJsonOutputPublicV2" } ], "description": "Output from the completed task.", "title": "Output" }, "run": { "$ref": "#/components/schemas/TaskRunResponsePublicV2", "description": "Task run object with status 'completed'." } }, "required": [ "run", "output" ], "title": "TaskRunResultPublicV2", "type": "object" }, "TaskRunStatusValue": { "description": "Lowercase status values used in API responses (distinct from the DB-level TaskRunStatus enum).", "enum": [ "queued", "running", "completed", "failed", "cancelled" ], "title": "TaskRunStatusValue", "type": "string" }, "TaskRunTextOutputPublicV2": { "properties": { "content": { "description": "The final prose answer.", "title": "Content", "type": "string" }, "trust": { "$ref": "#/components/schemas/TextRunTrust", "description": "Trust and citation metadata for the output." }, "type": { "const": "text", "default": "text", "description": "Output content type.", "title": "Type", "type": "string" } }, "required": [ "content", "trust" ], "title": "TaskRunTextOutputPublicV2", "type": "object" }, "TextClaimTrust": { "description": "Trust metadata for one claim in a prose answer, keyed by callout marker.", "properties": { "callout": { "description": "Callout marker number referencing this claim in the answer text.", "title": "Callout", "type": "integer" }, "citations": { "description": "Citations backing this claim.", "items": { "$ref": "#/components/schemas/TrustCitation" }, "title": "Citations", "type": "array" }, "confidence": { "$ref": "#/components/schemas/TrustConfidence", "description": "Confidence in this claim." }, "reasoning": { "description": "Why this confidence level was assigned.", "title": "Reasoning", "type": "string" } }, "required": [ "citations", "confidence", "reasoning", "callout" ], "title": "TextClaimTrust", "type": "object" }, "TextRunTrust": { "description": "Trust metadata for a prose answer: run-level confidence plus per-claim citations.", "properties": { "claims": { "description": "Per-claim trust, keyed by callout markers in the answer text.", "items": { "$ref": "#/components/schemas/TextClaimTrust" }, "title": "Claims", "type": "array" }, "confidence": { "$ref": "#/components/schemas/TrustConfidence", "description": "Overall confidence in the answer." }, "reasoning": { "description": "Why this confidence level was assigned.", "title": "Reasoning", "type": "string" }, "sources": { "description": "Sources consulted while producing the answer.", "items": { "$ref": "#/components/schemas/TrustSource" }, "title": "Sources", "type": "array" } }, "required": [ "sources", "confidence", "reasoning", "claims" ], "title": "TextRunTrust", "type": "object" }, "TrustCitation": { "description": "A citation backing a specific claim in the answer.", "properties": { "excerpts": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Verbatim excerpts supporting the claim.", "title": "Excerpts", "example": [ "Acme raised a $30M Series B in June 2026." ] }, "extract_template_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Extract template used to read the source, when one was used.", "title": "Extract Template Name" }, "source_category": { "anyOf": [ { "$ref": "#/components/schemas/SourceCategory" }, { "type": "null" } ], "description": "Kind of source: official, news, social, academic, aggregator, or other." }, "source_intent": { "anyOf": [ { "$ref": "#/components/schemas/SourceCategory" }, { "type": "null" } ], "description": "Kind of source the underlying question asked for." }, "source_type": { "anyOf": [ { "$ref": "#/components/schemas/TrustSourceType" }, { "type": "null" } ], "description": "How authoritative the source is: 'primary' or 'secondary'." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Title of the cited page.", "title": "Title" }, "url": { "description": "URL of the cited page.", "title": "Url", "type": "string", "example": "https://www.linkedin.com/company/acme" } }, "required": [ "url" ], "title": "TrustCitation", "type": "object" }, "TrustConfidence": { "enum": [ "high", "medium", "low", "pre_existing" ], "title": "TrustConfidence", "type": "string" }, "TrustSource": { "description": "A source consulted while producing the answer.", "properties": { "extract_template_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Extract template used to read the source, when one was used.", "title": "Extract Template Name" }, "source_category": { "anyOf": [ { "$ref": "#/components/schemas/SourceCategory" }, { "type": "null" } ], "description": "Kind of source: official, news, social, academic, aggregator, or other." }, "source_intent": { "anyOf": [ { "$ref": "#/components/schemas/SourceCategory" }, { "type": "null" } ], "description": "Kind of source the underlying question asked for." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Title of the source page.", "title": "Title" }, "type": { "$ref": "#/components/schemas/TrustSourceType", "description": "How authoritative the source is: 'primary' or 'secondary'." }, "url": { "description": "URL of the source page.", "title": "Url", "type": "string" } }, "required": [ "url", "type" ], "title": "TrustSource", "type": "object" }, "TrustSourceType": { "enum": [ "primary", "secondary" ], "title": "TrustSourceType", "type": "string" }, "WebSearchAgentCreateRequestPublicV2": { "properties": { "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stable agent name.", "title": "Agent Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description shown to users.", "title": "Description" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-friendly agent name shown to users.", "title": "Display Name" }, "effort": { "$ref": "#/components/schemas/Effort", "default": "high", "description": "Default effort level for this agent's runs." }, "goals": { "description": "Ordered goals for the agent to follow.", "items": { "type": "string" }, "title": "Goals", "type": "array", "example": [ "Find recent company announcements", "Summarize funding history" ] }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Icon identifier used when presenting the agent.", "title": "Icon" }, "is_active": { "default": true, "description": "Whether the agent can be used to start new runs.", "title": "Is Active", "type": "boolean" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "JSON Schema for structured output. Root must be an object with non-empty properties or an array of objects. Hard limits: nesting depth ≤ 5, ≤ 100 properties, ≤ 500 enum values, no unsupported keywords (format, pattern, min/max*, root anyOf, standalone null). Invalid schemas return 422.", "title": "Output Schema" }, "skill": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Skill or operating context for the agent.", "title": "Skill" }, "sources": { "$ref": "#/components/schemas/AgentSourcesPublicV2", "description": "Source guidance for the agent." }, "suggested_questions": { "description": "Suggested prompts users can run with this agent.", "items": { "type": "string" }, "title": "Suggested Questions", "type": "array" }, "template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Template name to materialize this instance from. When set, the scalar fields and child rows are copied from the template.", "title": "Template", "example": "linkedin_company_profiles" }, "use_case": { "anyOf": [ { "$ref": "#/components/schemas/WebSearchAgentUseCase" }, { "type": "null" } ], "description": "Primary use case supported by the agent." } }, "title": "WebSearchAgentCreateRequestPublicV2", "type": "object" }, "WebSearchAgentGoalResponsePublicV2": { "properties": { "goal": { "description": "Goal text.", "title": "Goal", "type": "string" }, "id": { "description": "Unique goal identifier (wsag_).", "title": "Id", "type": "string" }, "order": { "description": "Zero-based goal position.", "title": "Order", "type": "integer" } }, "required": [ "id", "goal", "order" ], "title": "WebSearchAgentGoalResponsePublicV2", "type": "object" }, "WebSearchAgentResponsePublicV2": { "properties": { "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stable agent name.", "title": "Agent Name" }, "created_at": { "description": "When the agent was created.", "format": "date-time", "title": "Created At", "type": "string" }, "description": { "description": "Agent description shown to users.", "title": "Description", "type": "string" }, "display_name": { "description": "Human-friendly agent name shown to users.", "title": "Display Name", "type": "string", "example": "Company News Tracker" }, "effort": { "$ref": "#/components/schemas/Effort", "description": "Default effort level for this agent's runs.", "example": "high" }, "goals": { "description": "Ordered goals for the agent to follow.", "items": { "$ref": "#/components/schemas/WebSearchAgentGoalResponsePublicV2" }, "title": "Goals", "type": "array" }, "icon": { "description": "Icon identifier used when presenting the agent.", "title": "Icon", "type": "string" }, "id": { "description": "Unique web search agent identifier (wsa_).", "title": "Id", "type": "string", "example": "wsa_2af5b0e2-58b8-4b60-a1a4-9e57e4d33f00" }, "is_active": { "description": "Whether the agent can be used to start new runs.", "title": "Is Active", "type": "boolean" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "JSON Schema for structured output. Root must be an object with non-empty properties or an array of objects. Hard limits: nesting depth ≤ 5, ≤ 100 properties, ≤ 500 enum values, no unsupported keywords (format, pattern, min/max*, root anyOf, standalone null). Invalid schemas return 422.", "title": "Output Schema" }, "skill": { "description": "Skill or operating context for the agent.", "title": "Skill", "type": "string" }, "sources": { "$ref": "#/components/schemas/AgentSourcesResponsePublicV2", "description": "Source guidance for the agent." }, "suggested_questions": { "description": "Suggested prompts users can run with this agent.", "items": { "$ref": "#/components/schemas/WebSearchAgentSuggestedQuestionResponsePublicV2" }, "title": "Suggested Questions", "type": "array" }, "updated_at": { "description": "When the agent was last updated.", "format": "date-time", "title": "Updated At", "type": "string" }, "use_case": { "$ref": "#/components/schemas/WebSearchAgentUseCase", "description": "Primary use case supported by the agent.", "example": "research" } }, "required": [ "id", "display_name", "description", "icon", "effort", "skill", "use_case", "output_schema", "is_active", "created_at", "updated_at", "sources", "goals", "suggested_questions" ], "title": "WebSearchAgentResponsePublicV2", "type": "object" }, "WebSearchAgentRunCreateRequestPublicV2": { "properties": { "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stable agent name. On this no-agent-id route, an unseen name creates a new agent; an existing name reuses it. Ignored on the /{agent_id}/runs route.", "title": "Agent Name" }, "effort": { "anyOf": [ { "$ref": "#/components/schemas/Effort" }, { "type": "null" } ], "description": "Effort level overriding the agent default for this run." }, "enable_events": { "default": false, "description": "Whether to stream run events when supported.", "title": "Enable Events", "type": "boolean" }, "input": { "description": "User prompt or task instructions for the run.", "title": "Input", "type": "string", "example": "Find the 10 fastest growing AI startups in Europe and their latest funding rounds." }, "input_data": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Existing records to ENRICH: a list of partial rows, or a single object, mirroring output_schema's shape.", "title": "Input Data" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "JSON Schema overriding the agent's default structured output for this run. Root must be an object with non-empty properties or an array of objects. Hard limits: nesting depth ≤ 5, ≤ 100 properties, ≤ 500 enum values, no unsupported keywords (format, pattern, min/max*, root anyOf, standalone null). Invalid schemas return 422.", "title": "Output Schema" }, "previous_interaction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Previous interaction identifier used to continue a conversation.", "title": "Previous Interaction Id" }, "skill": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Skill override for this run. One-time only, except when this run creates a new agent via agent_name, in which case it becomes the new agent's stored skill.", "title": "Skill" }, "sources": { "anyOf": [ { "$ref": "#/components/schemas/AgentSourcesPublicV2" }, { "type": "null" } ], "description": "Source guidance overriding the agent default." }, "use_case": { "anyOf": [ { "$ref": "#/components/schemas/WebSearchAgentUseCase" }, { "type": "null" } ], "description": "Only settable when this run creates a new agent (via agent_name, or when no agent is resolved), in which case it becomes the new agent's stored use_case. For a run against an existing agent, this must match the agent's own use_case - passing the same value is accepted as a no-op, a different value is rejected." } }, "required": [ "input" ], "title": "WebSearchAgentRunCreateRequestPublicV2", "type": "object" }, "WebSearchAgentSourceCreateRequestPublicV2": { "properties": { "domains": { "description": "Domains included in this source group.", "items": { "type": "string" }, "title": "Domains", "type": "array", "example": [ "linkedin.com", "crunchbase.com" ] }, "order": { "default": 0, "description": "Zero-based source group position.", "title": "Order", "type": "integer" }, "title": { "description": "Source group title.", "title": "Title", "type": "string", "example": "Professional networks" } }, "required": [ "title", "domains" ], "title": "WebSearchAgentSourceCreateRequestPublicV2", "type": "object" }, "WebSearchAgentSourceResponsePublicV2": { "properties": { "domains": { "description": "Domains included in this source group.", "items": { "type": "string" }, "title": "Domains", "type": "array", "example": [ "linkedin.com", "crunchbase.com" ] }, "id": { "description": "Unique source group identifier (wsas_).", "title": "Id", "type": "string" }, "order": { "description": "Zero-based source group position.", "title": "Order", "type": "integer" }, "title": { "description": "Source group title.", "title": "Title", "type": "string", "example": "Professional networks" } }, "required": [ "id", "title", "domains", "order" ], "title": "WebSearchAgentSourceResponsePublicV2", "type": "object" }, "WebSearchAgentSuggestedQuestionResponsePublicV2": { "properties": { "id": { "description": "Unique suggested question identifier (wsasq_).", "title": "Id", "type": "string" }, "order": { "description": "Zero-based suggested question position.", "title": "Order", "type": "integer" }, "question": { "description": "Suggested prompt text.", "title": "Question", "type": "string" } }, "required": [ "id", "question", "order" ], "title": "WebSearchAgentSuggestedQuestionResponsePublicV2", "type": "object" }, "WebSearchAgentTemplateResponsePublicV2": { "properties": { "created_at": { "description": "When the template was created.", "format": "date-time", "title": "Created At", "type": "string" }, "description": { "description": "Template description shown to users.", "title": "Description", "type": "string" }, "display_name": { "description": "Human-friendly template name shown to users.", "title": "Display Name", "type": "string" }, "effort": { "$ref": "#/components/schemas/Effort", "description": "Default effort level for runs created from this template.", "example": "high" }, "goals": { "description": "Ordered goals for the template.", "items": { "$ref": "#/components/schemas/WebSearchAgentGoalResponsePublicV2" }, "title": "Goals", "type": "array" }, "icon": { "description": "Icon identifier used when presenting the template.", "title": "Icon", "type": "string" }, "id": { "description": "Unique template identifier (wsat_).", "title": "Id", "type": "string", "example": "wsat_7d1e4f7a-9f3c-4a7b-b0d0-1c2c3d4e5f60" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "JSON Schema for structured output. Root must be an object with non-empty properties or an array of objects. Hard limits: nesting depth ≤ 5, ≤ 100 properties, ≤ 500 enum values, no unsupported keywords (format, pattern, min/max*, root anyOf, standalone null). Invalid schemas return 422.", "title": "Output Schema" }, "skill": { "description": "Skill or operating context for the template.", "title": "Skill", "type": "string" }, "sources": { "description": "Ordered source groups for the template.", "items": { "$ref": "#/components/schemas/WebSearchAgentSourceResponsePublicV2" }, "title": "Sources", "type": "array" }, "suggested_questions": { "description": "Suggested prompts for the template.", "items": { "$ref": "#/components/schemas/WebSearchAgentSuggestedQuestionResponsePublicV2" }, "title": "Suggested Questions", "type": "array" }, "template_name": { "description": "Stable template name used to create agent instances.", "title": "Template Name", "type": "string", "example": "linkedin_company_profiles" }, "updated_at": { "description": "When the template was last updated.", "format": "date-time", "title": "Updated At", "type": "string" }, "use_case": { "$ref": "#/components/schemas/WebSearchAgentUseCase", "description": "Primary use case supported by the template.", "example": "research" } }, "required": [ "id", "template_name", "display_name", "description", "icon", "effort", "skill", "use_case", "output_schema", "created_at", "updated_at", "sources", "goals", "suggested_questions" ], "title": "WebSearchAgentTemplateResponsePublicV2", "type": "object" }, "WebSearchAgentUseCase": { "enum": [ "research", "enrichment", "dataset_building" ], "title": "WebSearchAgentUseCase", "type": "string" }, "ArtifactDownloadUrlPublicV2": { "description": "A pre-signed URL for downloading an artifact.", "properties": { "expires_at": { "description": "When the download URL expires.", "format": "date-time", "title": "Expires At", "type": "string" }, "url": { "description": "Pre-signed URL to download the artifact.", "title": "Url", "type": "string" } }, "required": [ "url", "expires_at" ], "title": "ArtifactDownloadUrlPublicV2", "type": "object" }, "ArtifactListPublicV2": { "description": "Artifacts produced by a run.", "properties": { "items": { "description": "Artifacts produced by the run.", "items": { "$ref": "#/components/schemas/ArtifactPublicV2" }, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "ArtifactListPublicV2", "type": "object" }, "ArtifactPreviewPublicV2": { "description": "A tabular preview of an artifact's contents.", "properties": { "columns": { "description": "Column names in the preview.", "items": { "type": "string" }, "title": "Columns", "type": "array" }, "row_count": { "description": "Total number of rows in the artifact.", "title": "Row Count", "type": "integer" }, "rows": { "description": "Sample rows from the artifact.", "items": { "additionalProperties": true, "type": "object" }, "title": "Rows", "type": "array" } }, "required": [ "columns", "row_count", "rows" ], "title": "ArtifactPreviewPublicV2", "type": "object" }, "ArtifactPublicV2": { "description": "A file produced by a run.", "properties": { "created_at": { "description": "When the artifact was created.", "format": "date-time", "title": "Created At", "type": "string" }, "description": { "description": "Human-readable artifact description.", "title": "Description", "type": "string" }, "id": { "description": "Artifact identifier.", "title": "Id", "type": "string" }, "type": { "description": "Artifact type.", "title": "Type", "type": "string" } }, "required": [ "id", "type", "description", "created_at" ], "title": "ArtifactPublicV2", "type": "object" }, "CreateJobRequestPublicV2": { "description": "Payload to create a new job.", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text description of the job.", "title": "Description" }, "destination": { "anyOf": [ { "$ref": "#/components/schemas/JobDestinationPublicV2" }, { "type": "null" } ], "description": "Where the job writes its results." }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-friendly job name shown in the UI.", "title": "Display Name" }, "extract_template_name": { "description": "Name of the extract template to run.", "title": "Extract Template Name", "type": "string" }, "inputs": { "anyOf": [ { "$ref": "#/components/schemas/JobInputsPublicV2" }, { "type": "null" } ], "description": "Input data configuration for the job." }, "name": { "description": "Job name.", "title": "Name", "type": "string" }, "schedule": { "anyOf": [ { "$ref": "#/components/schemas/JobSchedulePublicV2" }, { "type": "null" } ], "description": "Cron schedule controlling automatic runs." } }, "required": [ "name", "extract_template_name" ], "title": "CreateJobRequestPublicV2", "type": "object" }, "JobContextPublicV2": { "description": "Minimal job context embedded in a run detail.", "properties": { "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-friendly job name shown in the UI.", "title": "Display Name" }, "extract_template_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the extract template this job runs.", "title": "Extract Template Name" }, "id": { "description": "Unique job identifier (job_).", "pattern": "^job_[1-9][0-9]*$", "title": "Id", "type": "string" }, "name": { "description": "Internal job name.", "title": "Name", "type": "string" }, "schedule": { "anyOf": [ { "$ref": "#/components/schemas/JobSchedulePublicV2" }, { "type": "null" } ], "description": "Cron schedule controlling automatic runs." } }, "required": [ "id", "name" ], "title": "JobContextPublicV2", "type": "object" }, "JobDestinationPublicV2": { "description": "Where a job writes its results.", "properties": { "format": { "default": "parquet", "description": "Output file format.", "enum": [ "jsonl", "csv", "parquet" ], "title": "Format", "type": "string" }, "path": { "description": "Destination path the output is written to.", "title": "Path", "type": "string" }, "type": { "description": "Destination kind: a local 'file' or an 's3' bucket.", "enum": [ "file", "s3" ], "title": "Type", "type": "string" } }, "required": [ "type", "path" ], "title": "JobDestinationPublicV2", "type": "object" }, "JobInputsPublicV2": { "description": "Configuration for the input data a job processes.", "properties": { "data": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Inline list of input records. Used when type is 'inline'.", "title": "Data" }, "file_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Path to the input file; must start with 's3' or 'file_'. Used for 's3'/'file' types.", "title": "File Path" }, "type": { "description": "How inputs are supplied: an 's3' bucket, 'inline' records, or an uploaded 'file'.", "enum": [ "s3", "inline", "file" ], "title": "Type", "type": "string" } }, "required": [ "type" ], "title": "JobInputsPublicV2", "type": "object" }, "JobPublicV2": { "description": "A configured job: an agent plus its schedule, inputs, and destination.", "properties": { "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the job was created.", "title": "Created At" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text description of the job.", "title": "Description" }, "destination": { "anyOf": [ { "$ref": "#/components/schemas/JobDestinationPublicV2" }, { "type": "null" } ], "description": "Where the job writes its results." }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-friendly job name shown in the UI.", "title": "Display Name" }, "extract_template_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the extract template this job runs.", "title": "Extract Template Name" }, "id": { "description": "Unique job identifier (job_).", "pattern": "^job_[1-9][0-9]*$", "title": "Id", "type": "string" }, "inputs": { "anyOf": [ { "$ref": "#/components/schemas/JobInputsPublicV2" }, { "type": "null" } ], "description": "Input data configuration for the job." }, "last_run_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Timestamp of the most recent run.", "title": "Last Run At" }, "last_run_status": { "anyOf": [ { "enum": [ "PENDING", "RUNNING", "SUCCESS", "FAILED", "CANCELLED", "TIMEOUT", "WARNING" ], "type": "string" }, { "type": "null" } ], "description": "Status of the most recent run.", "title": "Last Run Status" }, "name": { "description": "Job name.", "title": "Name", "type": "string" }, "schedule": { "anyOf": [ { "$ref": "#/components/schemas/JobSchedulePublicV2" }, { "type": "null" } ], "description": "Cron schedule controlling automatic runs." }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the job was last updated.", "title": "Updated At" } }, "required": [ "id", "name" ], "title": "JobPublicV2", "type": "object" }, "JobRunCancelResponsePublicV2": { "description": "Result of cancelling a run.", "properties": { "id": { "description": "Identifier of the cancelled run.", "pattern": "^run_[1-9][0-9]*$", "title": "Id", "type": "string" }, "status": { "description": "Run status after cancellation.", "enum": [ "PENDING", "RUNNING", "SUCCESS", "FAILED", "CANCELLED", "TIMEOUT", "WARNING" ], "title": "Status", "type": "string" } }, "required": [ "id", "status" ], "title": "JobRunCancelResponsePublicV2", "type": "object" }, "JobRunDetailPublicV2": { "description": "Full detail for a single run.", "properties": { "created_at": { "description": "When the run was created.", "format": "date-time", "title": "Created At", "type": "string" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/JobRunErrorPublicV2" }, { "type": "null" } ], "description": "Error details when the run failed." }, "finished_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the run finished.", "title": "Finished At" }, "id": { "description": "Unique run identifier (run_).", "pattern": "^run_[1-9][0-9]*$", "title": "Id", "type": "string" }, "inputs_sample": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "description": "Sample of the run's input records.", "title": "Inputs Sample" }, "job": { "$ref": "#/components/schemas/JobContextPublicV2", "description": "Context of the job this run belongs to." }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the run started executing.", "title": "Started At" }, "status": { "description": "Current run status.", "enum": [ "PENDING", "RUNNING", "SUCCESS", "FAILED", "CANCELLED", "TIMEOUT", "WARNING" ], "title": "Status", "type": "string" }, "summary": { "anyOf": [ { "$ref": "#/components/schemas/JobRunSummaryPublicV2" }, { "type": "null" } ], "description": "Aggregate metrics for the run." }, "triggered_by": { "description": "What triggered the run: 'schedule' or 'manual'.", "enum": [ "schedule", "manual" ], "title": "Triggered By", "type": "string" } }, "required": [ "id", "status", "triggered_by", "job", "created_at" ], "title": "JobRunDetailPublicV2", "type": "object" }, "JobRunErrorPublicV2": { "description": "Error details for a failed run.", "properties": { "errors_sample": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Sample of individual error records from the run.", "title": "Errors Sample" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable error message.", "title": "Message" }, "step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pipeline step where the error occurred.", "title": "Step" } }, "title": "JobRunErrorPublicV2", "type": "object" }, "JobRunPublicV2": { "description": "A single execution of a job.", "properties": { "created_at": { "description": "When the run was created.", "format": "date-time", "title": "Created At", "type": "string" }, "finished_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the run finished.", "title": "Finished At" }, "id": { "description": "Unique run identifier (run_).", "pattern": "^run_[1-9][0-9]*$", "title": "Id", "type": "string" }, "input_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of input records processed.", "title": "Input Count" }, "job_id": { "description": "Identifier of the job this run belongs to.", "pattern": "^job_[1-9][0-9]*$", "title": "Job Id", "type": "string" }, "result_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of result records produced.", "title": "Result Count" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the run started executing.", "title": "Started At" }, "status": { "description": "Current run status.", "enum": [ "PENDING", "RUNNING", "SUCCESS", "FAILED", "CANCELLED", "TIMEOUT", "WARNING" ], "title": "Status", "type": "string" }, "triggered_by": { "description": "What triggered the run: 'schedule' or 'manual'.", "enum": [ "schedule", "manual" ], "title": "Triggered By", "type": "string" } }, "required": [ "id", "job_id", "status", "triggered_by", "created_at" ], "title": "JobRunPublicV2", "type": "object" }, "JobRunSummaryPublicV2": { "description": "Aggregate metrics for a run.", "properties": { "input_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of input records processed.", "title": "Input Count" }, "match_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Fraction of inputs that produced a result (result_count / input_count), from 0.0 to 1.0.", "title": "Match Rate" }, "result_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of result records produced.", "title": "Result Count" } }, "title": "JobRunSummaryPublicV2", "type": "object" }, "JobSchedulePublicV2": { "description": "Cron-based schedule controlling when a job runs automatically.", "properties": { "cron": { "description": "Cron expression defining when the job runs.", "title": "Cron", "type": "string" }, "enabled": { "description": "Whether the schedule is currently active.", "title": "Enabled", "type": "boolean" } }, "required": [ "cron", "enabled" ], "title": "JobSchedulePublicV2", "type": "object" }, "ListResponse_JobPublicV2_": { "properties": { "items": { "description": "Items returned in this page.", "items": { "$ref": "#/components/schemas/JobPublicV2" }, "title": "Items", "type": "array" }, "limit": { "description": "Maximum number of items returned.", "title": "Limit", "type": "integer" }, "offset": { "description": "Number of items skipped before this page.", "title": "Offset", "type": "integer" }, "total": { "description": "Total number of items matching the query.", "title": "Total", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "title": "ListResponse[JobPublicV2]", "type": "object" }, "ListResponse_JobRunPublicV2_": { "properties": { "items": { "description": "Items returned in this page.", "items": { "$ref": "#/components/schemas/JobRunPublicV2" }, "title": "Items", "type": "array" }, "limit": { "description": "Maximum number of items returned.", "title": "Limit", "type": "integer" }, "offset": { "description": "Number of items skipped before this page.", "title": "Offset", "type": "integer" }, "total": { "description": "Total number of items matching the query.", "title": "Total", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "title": "ListResponse[JobRunPublicV2]", "type": "object" }, "UpdateJobRequestPublicV2": { "description": "Partial update for an existing job; omitted fields are left unchanged.", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "New description.", "title": "Description" }, "destination": { "anyOf": [ { "$ref": "#/components/schemas/JobDestinationPublicV2" }, { "type": "null" } ], "description": "New output destination." }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "New display name.", "title": "Display Name" }, "inputs": { "anyOf": [ { "$ref": "#/components/schemas/JobInputsPublicV2" }, { "type": "null" } ], "description": "New input data configuration." }, "schedule": { "anyOf": [ { "$ref": "#/components/schemas/JobSchedulePublicV2" }, { "type": "null" } ], "description": "New cron schedule." } }, "title": "UpdateJobRequestPublicV2", "type": "object" }, "MediaAsyncPayload": { "allOf": [ { "properties": { "country": { "type": "string" }, "expected_mime_types": { "items": { "type": "string" }, "type": "array" }, "locale": { "type": "string" }, "storage": { "properties": { "object_name": { "type": "string" }, "type": { "default": "s3", "enum": [ "s3", "gcs", "do", "oci" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "url": { "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" }, { "properties": { "callback_url": { "description": "URL to call back when async operation completes", "examples": [ "https://example.com/webhook/callback" ], "type": "string" }, "storage_compress": { "description": "Whether to compress stored data", "examples": [ true ], "type": "boolean" }, "storage_object_name": { "description": "Custom name for the stored object", "examples": [ "result-2024-01-15.json" ], "type": "string" }, "storage_type": { "description": "Type of storage to use for results", "examples": [ "s3" ], "type": "string" }, "storage_url": { "description": "URL for storage location", "examples": [ "s3://bucket-name/path/to/object" ], "type": "string" } }, "type": "object" } ] }, "ScrollAction": { "additionalProperties": false, "description": "Scroll the page or an element", "properties": { "scroll": { "oneOf": [ { "type": "number" }, { "type": "string" }, { "additionalProperties": false, "properties": { "container": { "$ref": "#/components/schemas/Selector" }, "required": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether this action is required. If true, pipeline stops on failure. Accepts boolean or string \"true\"/\"false\". Default: true." }, "skip": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether to skip this action. Accepts boolean or string \"true\"/\"false\". Default: false." }, "to": { "$ref": "#/components/schemas/Selector" }, "visible": { "type": "boolean" }, "x": { "type": "number" }, "y": { "type": "number" } }, "type": "object" } ] } }, "required": [ "scroll" ], "type": "object" }, "GotoAction": { "additionalProperties": false, "description": "Navigate to a URL", "properties": { "goto": { "oneOf": [ { "format": "uri", "type": "string" }, { "additionalProperties": false, "properties": { "referer": { "type": "string" }, "required": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether this action is required. If true, pipeline stops on failure. Accepts boolean or string \"true\"/\"false\". Default: true." }, "skip": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether to skip this action. Accepts boolean or string \"true\"/\"false\". Default: false." }, "timeout": { "default": 15000, "description": "Timeout in milliseconds. Set to 0 for infinite timeout (no timeout). Default: 15000ms.", "minimum": 0, "type": "number" }, "url": { "format": "uri", "type": "string" }, "wait_until": { "default": "load", "enum": [ "load", "domcontentloaded", "networkidle0", "networkidle2" ], "type": "string" } }, "required": [ "url" ], "type": "object" } ] } }, "required": [ "goto" ], "type": "object" }, "WaitAction": { "additionalProperties": false, "description": "Wait for a specified duration", "properties": { "wait": { "oneOf": [ { "$ref": "#/components/schemas/Duration" }, { "additionalProperties": false, "properties": { "duration": { "$ref": "#/components/schemas/Duration" }, "required": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether this action is required. If true, pipeline stops on failure. Accepts boolean or string \"true\"/\"false\". Default: true." }, "skip": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether to skip this action. Accepts boolean or string \"true\"/\"false\". Default: false." } }, "required": [ "duration" ], "type": "object" } ] } }, "required": [ "wait" ], "type": "object" }, "AutoScrollAction": { "additionalProperties": false, "description": "Continuously scroll to load dynamic content", "properties": { "auto_scroll": { "oneOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/Duration" }, { "additionalProperties": false, "properties": { "click_selector": { "$ref": "#/components/schemas/Selector" }, "container": { "$ref": "#/components/schemas/Selector" }, "delay_after_scroll": { "$ref": "#/components/schemas/Duration" }, "idle_timeout": { "$ref": "#/components/schemas/Duration" }, "loading_selector": { "$ref": "#/components/schemas/Selector" }, "max_duration": { "$ref": "#/components/schemas/Duration" }, "pause_on_selector": { "$ref": "#/components/schemas/Selector" }, "required": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether this action is required. If true, pipeline stops on failure. Accepts boolean or string \"true\"/\"false\". Default: true." }, "skip": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether to skip this action. Accepts boolean or string \"true\"/\"false\". Default: false." }, "step_size": { "type": "number" } }, "type": "object" } ] } }, "required": [ "auto_scroll" ], "type": "object" }, "ScreenshotAction": { "additionalProperties": false, "description": "Capture a page screenshot", "properties": { "screenshot": { "oneOf": [ { "type": "boolean" }, { "additionalProperties": false, "properties": { "format": { "enum": [ "png", "jpeg", "webp" ], "type": "string" }, "full_page": { "type": "boolean" }, "quality": { "maximum": 100, "minimum": 0, "type": "number" }, "required": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether this action is required. If true, pipeline stops on failure. Accepts boolean or string \"true\"/\"false\". Default: true." }, "skip": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether to skip this action. Accepts boolean or string \"true\"/\"false\". Default: false." } }, "type": "object" } ] } }, "required": [ "screenshot" ], "type": "object" }, "SERPMetadata": { "description": "Metadata for SERP-based search results (general, news, location).", "properties": { "country": { "title": "Country", "type": "string" }, "driver": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Driver" }, "entity_type": { "title": "Entity Type", "type": "string" }, "locale": { "title": "Locale", "type": "string" }, "position": { "title": "Position", "type": "integer" } }, "required": [ "position", "entity_type", "country", "locale" ], "title": "SERPMetadata", "type": "object" }, "WaitForNavigationAction": { "additionalProperties": false, "description": "Wait for page navigation to complete", "properties": { "wait_for_navigation": { "oneOf": [ { "enum": [ "load", "domcontentloaded", "networkidle0", "networkidle2" ], "type": "string" }, { "additionalProperties": false, "properties": { "navigation": { "enum": [ "load", "domcontentloaded", "networkidle0", "networkidle2" ], "type": "string" }, "required": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether this action is required. If true, pipeline stops on failure. Accepts boolean or string \"true\"/\"false\". Default: true." }, "skip": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether to skip this action. Accepts boolean or string \"true\"/\"false\". Default: false." }, "timeout": { "default": 15000, "description": "Timeout in milliseconds. Set to 0 for infinite timeout (no timeout). Default: 15000ms.", "minimum": 0, "type": "number" } }, "required": [ "navigation" ], "type": "object" } ] } }, "required": [ "wait_for_navigation" ], "type": "object" }, "WSAMetadata": { "description": "Metadata for WSA-based search results.", "properties": { "agent_name": { "title": "Agent Name", "type": "string" } }, "required": [ "agent_name" ], "title": "WSAMetadata", "type": "object" }, "ClickAction": { "additionalProperties": false, "description": "Click on an element by selector", "properties": { "click": { "oneOf": [ { "$ref": "#/components/schemas/Selector" }, { "additionalProperties": false, "properties": { "count": { "default": 1, "minimum": 1, "type": "number" }, "delay": { "$ref": "#/components/schemas/Duration" }, "offset_x": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "offset_y": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "required": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether this action is required. If true, pipeline stops on failure. Accepts boolean or string \"true\"/\"false\". Default: true." }, "scroll": { "default": true, "type": "boolean" }, "selector": { "$ref": "#/components/schemas/Selector" }, "skip": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether to skip this action. Accepts boolean or string \"true\"/\"false\". Default: false." }, "steps": { "minimum": 1, "type": "number" }, "strategy": { "enum": [ "linear", "ghost-cursor", "windmouse" ], "type": "string" }, "timeout": { "default": 15000, "description": "Timeout in milliseconds. Set to 0 for infinite timeout (no timeout). Default: 15000ms.", "minimum": 0, "type": "number" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "selector" ], "type": "object" } ] } }, "required": [ "click" ], "type": "object" }, "FetchAction": { "additionalProperties": false, "description": "Make an HTTP request in browser context", "properties": { "fetch": { "oneOf": [ { "format": "uri", "type": "string" }, { "additionalProperties": false, "properties": { "body": { "type": "string" }, "headers": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "method": { "enum": [ "GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH" ], "type": "string" }, "required": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether this action is required. If true, pipeline stops on failure. Accepts boolean or string \"true\"/\"false\". Default: true." }, "skip": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether to skip this action. Accepts boolean or string \"true\"/\"false\". Default: false." }, "timeout": { "default": 15000, "description": "Timeout in milliseconds. Set to 0 for infinite timeout (no timeout). Default: 15000ms.", "minimum": 0, "type": "number" }, "url": { "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" } ] } }, "required": [ "fetch" ], "type": "object" }, "CrawlApiResponse": { "additionalProperties": false, "description": "Crawl API response", "properties": { "account_name": { "type": "string" }, "completed": { "type": "number" }, "completed_at": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, { "type": "null" } ] }, "crawl_id": { "format": "uuid", "type": "string" }, "crawl_options": { "additionalProperties": {}, "properties": { "allow_external_links": { "default": false, "type": "boolean" }, "allow_subdomains": { "default": false, "type": "boolean" }, "callback": { "anyOf": [ { "additionalProperties": false, "properties": { "events": { "items": { "enum": [ "started", "page", "completed", "failed" ], "type": "string" }, "type": "array" }, "headers": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "metadata": { "additionalProperties": {}, "propertyNames": { "type": "string" }, "type": "object" }, "url": { "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" }, { "format": "uri", "type": "string" } ] }, "crawl_entire_domain": { "default": false, "type": "boolean" }, "exclude_paths": { "items": { "type": "string" }, "type": "array" }, "ignore_query_parameters": { "default": false, "type": "boolean" }, "include_paths": { "items": { "type": "string" }, "type": "array" }, "limit": { "default": 5000, "maximum": 10000, "minimum": 1, "type": "integer" }, "max_discovery_depth": { "default": 5, "maximum": 20, "minimum": 1, "type": "integer" }, "sitemap": { "default": "include", "enum": [ "skip", "include", "only" ], "type": "string" } }, "required": [ "sitemap", "crawl_entire_domain", "limit", "max_discovery_depth", "ignore_query_parameters", "allow_external_links", "allow_subdomains" ], "type": "object" }, "created_at": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "extract_options": { "anyOf": [ { "additionalProperties": {}, "properties": {}, "type": "object" }, { "type": "null" } ] }, "failed": { "type": "number" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pending": { "type": "number" }, "status": { "enum": [ "queued", "running", "succeeded", "failed", "canceled" ], "type": "string" }, "tasks": { "items": { "additionalProperties": false, "properties": { "created_at": { "type": "string" }, "status": { "enum": [ "pending", "completed", "failed" ], "type": "string" }, "task_id": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "task_id", "status" ], "type": "object" }, "type": "array" }, "total": { "type": "number" }, "updated_at": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "url": { "format": "uri", "type": "string" } }, "required": [ "url", "status", "account_name", "created_at", "updated_at", "crawl_options", "crawl_id" ], "type": "object" }, "WaitForElementAction": { "additionalProperties": false, "description": "Wait for an element to appear or reach a specific state", "properties": { "wait_for_element": { "oneOf": [ { "$ref": "#/components/schemas/Selector" }, { "additionalProperties": false, "properties": { "required": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether this action is required. If true, pipeline stops on failure. Accepts boolean or string \"true\"/\"false\". Default: true." }, "selector": { "$ref": "#/components/schemas/Selector" }, "skip": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether to skip this action. Accepts boolean or string \"true\"/\"false\". Default: false." }, "timeout": { "default": 15000, "description": "Timeout in milliseconds. Set to 0 for infinite timeout (no timeout). Default: 15000ms.", "minimum": 0, "type": "number" }, "visible": { "type": "boolean" } }, "required": [ "selector" ], "type": "object" } ] } }, "required": [ "wait_for_element" ], "type": "object" }, "TimeRange": { "description": "Time range filters passed to Webit SERP API as 'time' parameter.", "enum": [ "hour", "day", "week", "month", "year" ], "title": "TimeRange", "type": "string" }, "EvalAction": { "additionalProperties": false, "description": "Execute JavaScript code in page context", "properties": { "eval": { "oneOf": [ { "type": "string" }, { "additionalProperties": false, "properties": { "code": { "minLength": 1, "type": "string" }, "required": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether this action is required. If true, pipeline stops on failure. Accepts boolean or string \"true\"/\"false\". Default: true." }, "skip": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether to skip this action. Accepts boolean or string \"true\"/\"false\". Default: false." }, "timeout": { "default": 15000, "description": "Timeout in milliseconds. Set to 0 for infinite timeout (no timeout). Default: 15000ms.", "minimum": 0, "type": "number" } }, "required": [ "code" ], "type": "object" } ] } }, "required": [ "eval" ], "type": "object" }, "PressAction": { "additionalProperties": false, "description": "Press a keyboard key", "properties": { "press": { "oneOf": [ { "type": "string" }, { "additionalProperties": false, "properties": { "delay": { "$ref": "#/components/schemas/Duration" }, "key": { "enum": [ "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "Power", "Eject", "Abort", "Help", "Backspace", "Tab", "Numpad5", "NumpadEnter", "Enter", "\r", "\n", "ShiftLeft", "ShiftRight", "ControlLeft", "ControlRight", "AltLeft", "AltRight", "Pause", "CapsLock", "Escape", "Convert", "NonConvert", "Space", "Numpad9", "PageUp", "Numpad3", "PageDown", "End", "Numpad1", "Home", "Numpad7", "ArrowLeft", "Numpad4", "Numpad8", "ArrowUp", "ArrowRight", "Numpad6", "Numpad2", "ArrowDown", "Select", "Open", "PrintScreen", "Insert", "Numpad0", "Delete", "NumpadDecimal", "Digit0", "Digit1", "Digit2", "Digit3", "Digit4", "Digit5", "Digit6", "Digit7", "Digit8", "Digit9", "KeyA", "KeyB", "KeyC", "KeyD", "KeyE", "KeyF", "KeyG", "KeyH", "KeyI", "KeyJ", "KeyK", "KeyL", "KeyM", "KeyN", "KeyO", "KeyP", "KeyQ", "KeyR", "KeyS", "KeyT", "KeyU", "KeyV", "KeyW", "KeyX", "KeyY", "KeyZ", "MetaLeft", "MetaRight", "ContextMenu", "NumpadMultiply", "NumpadAdd", "NumpadSubtract", "NumpadDivide", "F1", "F2", "F3", "F4", "F5", "F6", "F7", "F8", "F9", "F10", "F11", "F12", "F13", "F14", "F15", "F16", "F17", "F18", "F19", "F20", "F21", "F22", "F23", "F24", "NumLock", "ScrollLock", "AudioVolumeMute", "AudioVolumeDown", "AudioVolumeUp", "MediaTrackNext", "MediaTrackPrevious", "MediaStop", "MediaPlayPause", "Semicolon", "Equal", "NumpadEqual", "Comma", "Minus", "Period", "Slash", "Backquote", "BracketLeft", "Backslash", "BracketRight", "Quote", "AltGraph", "Props", "Cancel", "Clear", "Shift", "Control", "Alt", "Accept", "ModeChange", " ", "Print", "Execute", "\u0000", "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "Meta", "*", "+", "-", "/", ";", "=", ",", ".", "`", "[", "\\", "]", "'", "Attn", "CrSel", "ExSel", "EraseEof", "Play", "ZoomOut", ")", "!", "@", "#", "$", "%", "^", "&", "(", "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z", ":", "<", "_", ">", "?", "~", "{", "|", "}", "\"", "SoftLeft", "SoftRight", "Camera", "Call", "EndCall", "VolumeDown", "VolumeUp" ], "type": "string" }, "required": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether this action is required. If true, pipeline stops on failure. Accepts boolean or string \"true\"/\"false\". Default: true." }, "skip": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether to skip this action. Accepts boolean or string \"true\"/\"false\". Default: false." } }, "required": [ "key" ], "type": "object" } ] } }, "required": [ "press" ], "type": "object" }, "FillAction": { "additionalProperties": false, "description": "Fill text into an input field", "properties": { "fill": { "$ref": "#/components/schemas/FillOptions" } }, "required": [ "fill" ], "type": "object" }, "SearchRequest": { "description": "Request body model for the /search endpoint.", "properties": { "query": { "description": "Search query string", "minLength": 1, "title": "Query", "type": "string" }, "search_depth": { "anyOf": [ { "$ref": "#/components/schemas/SearchDepth" }, { "type": "null" } ], "description": "Content richness: 'lite' (titles, URLs, snippets) or 'standard' (rich content, default)." }, "full_content": { "default": false, "description": "Return full page content for each result, in addition to its title, url, and description. Works with either search_depth value. Higher recall and cost.", "title": "Full Content", "type": "boolean" }, "content_type": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Filter by content type (only supported with focus=general). Supports semantic groups ('documents', 'spreadsheets', 'presentations') and specific formats ('pdf', 'docx', 'xlsx', etc.)", "title": "Content Type" }, "country": { "default": "US", "description": "Country code for geo-targeted results (e.g., 'US', 'GB', 'IL')", "title": "Country", "type": "string" }, "end_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter results before this date (format: YYYY-MM-DD or YYYY)", "title": "End Date" }, "exclude_domains": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 50, "type": "array" }, { "type": "null" } ], "description": "List of domains to exclude from search results. Maximum 50 domains.", "title": "Exclude Domains" }, "focus": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" } ], "default": "general", "description": "Search focus mode (e.g., 'general', 'news', 'shopping') or a list of explicit subagent names (e.g., ['amazon_serp', 'target_serp'])", "title": "Focus" }, "include_domains": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 50, "type": "array" }, { "type": "null" } ], "description": "List of domains to include in search results. Maximum 50 domains.", "title": "Include Domains" }, "locale": { "default": "en", "description": "Language/locale code (e.g., 'en', 'fr', 'de')", "title": "Locale", "type": "string" }, "max_results": { "default": 10, "description": "Maximum number of results to return. Actual count may be lower depending on availability.", "maximum": 100.0, "minimum": 1.0, "title": "Max Results", "type": "integer" }, "output_format": { "$ref": "#/components/schemas/ParsingType", "default": "markdown", "description": "Output format: plain_text, markdown, or simplified_html" }, "start_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter results after this date (format: YYYY-MM-DD or YYYY)", "title": "Start Date" }, "time_range": { "anyOf": [ { "$ref": "#/components/schemas/TimeRange" }, { "type": "null" } ], "description": "Filter by recency: hour, day, week, month, or year. Cannot be combined with start_date/end_date." } }, "required": [ "query" ], "title": "SearchRequest", "type": "object" }, "SerpAsyncResponse": { "additionalProperties": false, "description": "Response when an async SERP task is created successfully.", "properties": { "status": { "const": "success", "description": "Status indicating the async SERP task was created successfully.", "type": "string" }, "task": { "additionalProperties": false, "description": "The created async task details.", "properties": { "_query": {}, "account_name": { "description": "Account name that owns the task.", "type": "string" }, "api_type": { "enum": [ "web", "serp", "ecommerce", "social", "media", "agent", "extract", "fast-serp", "labs" ], "type": "string" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Batch ID if this task is part of a batch.", "examples": [ "4b0a90bf-c951-42e4-95b3-a95a65ba69fc" ] }, "created_at": { "description": "Timestamp when the task was created.", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "download_url": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ], "description": "URL for downloading the task results.", "examples": [ "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000/results" ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if the task failed.", "examples": [ "Connection timeout" ] }, "error_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Classification of the error type.", "examples": [ "timeout_error" ] }, "id": { "description": "Unique task identifier.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "minLength": 1, "type": "string" }, "input": { "description": "Original input data for the task." }, "modified_at": { "description": "Timestamp when the task was last modified.", "examples": [ "2024-01-15T10:35:00Z" ], "type": "string" }, "output_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Storage location of the output data." }, "queue": { "description": "Queue name the task was submitted to.", "type": "string" }, "state": { "description": "Current state of the task.", "enum": [ "pending", "queued", "in_progress", "success", "error" ], "examples": [ "pending" ], "type": "string" }, "status_code": { "description": "HTTP status code from the task execution.", "examples": [ 200 ], "type": "number" }, "status_url": { "description": "URL for checking the task status.", "examples": [ "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000" ], "format": "uri", "type": "string" } }, "required": [ "id", "state", "status_url", "created_at", "input", "_query" ], "type": "object" } }, "required": [ "status", "task" ], "type": "object" }, "Selector": { "description": "CSS selector or array of alternative selectors. Use an array when you have multiple possible selectors for the same element.", "examples": [ "#submit-button", "button.primary", [ "#submit-button", ".submit-btn", "button[type=\"submit\"]" ] ], "oneOf": [ { "minLength": 1, "type": "string" }, { "items": { "minLength": 1, "type": "string" }, "minItems": 1, "type": "array" } ] }, "SerpBatchResponse": { "additionalProperties": false, "description": "Response when a batch of SERP tasks is created successfully.", "properties": { "batch_id": { "description": "Unique identifier for the batch.", "type": "string" }, "batch_size": { "description": "Number of tasks in the batch.", "type": "number" }, "tasks": { "description": "List of created tasks.", "items": { "additionalProperties": false, "properties": { "_query": {}, "account_name": { "description": "Account name that owns the task.", "type": "string" }, "api_type": { "enum": [ "web", "serp", "ecommerce", "social", "media", "agent", "extract", "fast-serp", "labs" ], "type": "string" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Batch ID if this task is part of a batch.", "examples": [ "4b0a90bf-c951-42e4-95b3-a95a65ba69fc" ] }, "created_at": { "description": "Timestamp when the task was created.", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "download_url": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ], "description": "URL for downloading the task results.", "examples": [ "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000/results" ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if the task failed.", "examples": [ "Connection timeout" ] }, "error_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Classification of the error type.", "examples": [ "timeout_error" ] }, "id": { "description": "Unique task identifier.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "minLength": 1, "type": "string" }, "input": { "description": "Original input data for the task." }, "modified_at": { "description": "Timestamp when the task was last modified.", "examples": [ "2024-01-15T10:35:00Z" ], "type": "string" }, "output_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Storage location of the output data." }, "queue": { "description": "Queue name the task was submitted to.", "type": "string" }, "state": { "description": "Current state of the task.", "enum": [ "pending", "queued", "in_progress", "success", "error" ], "examples": [ "pending" ], "type": "string" }, "status_code": { "description": "HTTP status code from the task execution.", "examples": [ 200 ], "type": "number" }, "status_url": { "description": "URL for checking the task status.", "examples": [ "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000" ], "format": "uri", "type": "string" } }, "required": [ "id", "state", "status_url", "created_at", "input", "_query" ], "type": "object" }, "type": "array" } }, "required": [ "batch_id", "batch_size", "tasks" ], "type": "object" }, "BrowserActions": { "description": "Array of browser automation actions to execute sequentially", "example": [ { "goto": "https://example.com/login" }, { "wait_for_element": "#login-form" }, { "fill": { "selector": "#username", "value": "user@example.com" } }, { "fill": { "selector": "#password", "value": "password123" } }, { "click": "#submit" }, { "screenshot": { "full_page": true } } ], "items": { "$ref": "#/components/schemas/BrowserAction" }, "minItems": 1, "type": "array" }, "ResultModel": { "description": "Unified result model for all search types (SERP and WSA).\n\nThis model provides a consistent structure for search results,\nwith platform-specific data in additional_data and typed metadata.", "properties": { "additional_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Platform-specific fields (e.g., price, rating, publish_date). Omitted from response when no extra data.", "title": "Additional Data" }, "content": { "description": "Full scraped page content, when `full_content` was requested. Empty string otherwise.", "title": "Content", "type": "string" }, "description": { "title": "Description", "type": "string" }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/SERPMetadata" }, { "$ref": "#/components/schemas/WSAMetadata" } ], "description": "Shape depends on the focus mode. SERP-backed modes (e.g. general, news) return SERPMetadata: position, entity_type, country, locale. WSA-backed modes (e.g. shopping, social, geo) return WSAMetadata: agent_name only.", "title": "Metadata" }, "title": { "title": "Title", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "title", "description", "url", "content", "metadata" ], "title": "ResultModel", "type": "object" }, "ParsingType": { "description": "Enum representing the parsing types supported by Nimble", "enum": [ "plain_text", "markdown", "simplified_html" ], "title": "ParsingType", "type": "string" }, "GetCookiesAction": { "additionalProperties": false, "description": "Retrieve browser cookies", "properties": { "get_cookies": { "oneOf": [ { "type": "boolean" }, { "additionalProperties": {}, "properties": { "required": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether this action is required. If true, pipeline stops on failure. Accepts boolean or string \"true\"/\"false\". Default: true." }, "skip": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether to skip this action. Accepts boolean or string \"true\"/\"false\". Default: false." } }, "type": "object" } ] } }, "required": [ "get_cookies" ], "type": "object" }, "Duration": { "description": "Duration value that accepts various formats. Supports: number (ms), string (\"1000\"), or string with unit (\"2s\", \"500ms\", \"2m\", \"1h\")", "examples": [ 1000, "2s", "500ms", "1.5m", "1h" ], "oneOf": [ { "minimum": 0, "type": "number" }, { "type": "string" } ] }, "ExtractAsyncResponse": { "additionalProperties": false, "description": "Response when an async extract task is created successfully.", "properties": { "status": { "const": "success", "description": "Status indicating the async task was created successfully.", "type": "string" }, "task": { "additionalProperties": false, "description": "The created async task details.", "properties": { "_query": {}, "account_name": { "description": "Account name that owns the task.", "type": "string" }, "api_type": { "enum": [ "web", "serp", "ecommerce", "social", "media", "agent", "extract", "fast-serp", "labs" ], "type": "string" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Batch ID if this task is part of a batch.", "examples": [ "4b0a90bf-c951-42e4-95b3-a95a65ba69fc" ] }, "created_at": { "description": "Timestamp when the task was created.", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "download_url": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ], "description": "URL for downloading the task results.", "examples": [ "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000/results" ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if the task failed.", "examples": [ "Connection timeout" ] }, "error_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Classification of the error type.", "examples": [ "timeout_error" ] }, "id": { "description": "Unique task identifier.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "minLength": 1, "type": "string" }, "input": { "description": "Original input data for the task." }, "modified_at": { "description": "Timestamp when the task was last modified.", "examples": [ "2024-01-15T10:35:00Z" ], "type": "string" }, "output_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Storage location of the output data." }, "queue": { "description": "Queue name the task was submitted to.", "type": "string" }, "state": { "description": "Current state of the task.", "enum": [ "pending", "queued", "in_progress", "success", "error" ], "examples": [ "pending" ], "type": "string" }, "status_code": { "description": "HTTP status code from the task execution.", "examples": [ 200 ], "type": "number" }, "status_url": { "description": "URL for checking the task status.", "examples": [ "https://api.webit.live/api/v2/tasks/123e4567-e89b-12d3-a456-426614174000" ], "format": "uri", "type": "string" } }, "required": [ "id", "state", "status_url", "created_at", "input", "_query" ], "type": "object" } }, "required": [ "status", "task" ], "type": "object" }, "MediaAsyncResponse": { "$ref": "#/components/schemas/ExtractAsyncResponse", "description": "Response when an async media download task is created successfully." }, "SearchDepth": { "description": "Controls content richness and latency of search results.\n\n- lite: Token-efficient metadata for high-volume pipelines (title, URL, description only)\n- standard: Rich content (~2K chars) optimized for AI agents", "enum": [ "lite", "standard" ], "title": "SearchDepth", "type": "string" }, "CrawlByFiltersResponse": { "additionalProperties": false, "description": "Successful get crawl response", "properties": { "data": { "items": { "$ref": "#/components/schemas/CrawlApiResponse" }, "type": "array" }, "pagination": { "additionalProperties": false, "properties": { "has_next": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "total": { "type": "number" } }, "required": [ "has_next" ], "type": "object" } }, "required": [ "data", "pagination" ], "type": "object" }, "FillOptions": { "description": "Fill options with mode-specific fields. Use \"type\" mode for behavioral typing simulation, or \"paste\" mode for instant paste.", "discriminator": { "propertyName": "mode" }, "oneOf": [ { "additionalProperties": false, "properties": { "click_on_element": { "default": true, "type": "boolean" }, "delay": { "$ref": "#/components/schemas/Duration" }, "mode": { "const": "type", "default": "type", "type": "string" }, "mouse_movement_strategy": { "enum": [ "linear", "ghost-cursor", "windmouse" ], "type": "string" }, "required": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether this action is required. If true, pipeline stops on failure. Accepts boolean or string \"true\"/\"false\". Default: true." }, "scroll": { "default": true, "type": "boolean" }, "selector": { "$ref": "#/components/schemas/Selector" }, "skip": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether to skip this action. Accepts boolean or string \"true\"/\"false\". Default: false." }, "timeout": { "default": 15000, "description": "Timeout in milliseconds. Set to 0 for infinite timeout (no timeout). Default: 15000ms.", "minimum": 0, "type": "number" }, "typing_interval": { "$ref": "#/components/schemas/Duration" }, "typing_strategy": { "enum": [ "simple", "distribution" ], "type": "string" }, "value": { "minLength": 1, "type": "string" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "selector", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "click_on_element": { "default": true, "type": "boolean" }, "delay": { "$ref": "#/components/schemas/Duration" }, "mode": { "const": "paste", "type": "string" }, "required": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether this action is required. If true, pipeline stops on failure. Accepts boolean or string \"true\"/\"false\". Default: true." }, "scroll": { "default": true, "type": "boolean" }, "selector": { "$ref": "#/components/schemas/Selector" }, "skip": { "anyOf": [ { "type": "boolean" }, { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ], "description": "Whether to skip this action. Accepts boolean or string \"true\"/\"false\". Default: false." }, "timeout": { "default": 15000, "description": "Timeout in milliseconds. Set to 0 for infinite timeout (no timeout). Default: 15000ms.", "minimum": 0, "type": "number" }, "value": { "minLength": 1, "type": "string" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "selector", "value", "mode" ], "type": "object" } ] } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "servers": [ { "url": "https://sdk.nimbleway.com" } ] }