{ "openapi": "3.1.0", "info": { "title": "Scraply API", "version": "1.1.0", "description": "Local MVP. External scraping and language extraction are simulated. Validated success costs base 1 + language 2 + JavaScript 3 credits; failures use zero. Quotes are persisted at admission; UTC daily key limits reserve quoted credits. Previously accepted jobs retain their original price." }, "servers": [ { "url": "https://www.scraply.net", "description": "Public Scraply API" } ], "security": [ { "ApiKey": [] }, { "Bearer": [] } ], "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "Bearer": { "type": "http", "scheme": "bearer" } }, "schemas": { "JobRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "format": { "type": "string", "enum": [ "html", "json", "markdown" ], "default": "html" }, "template": { "type": "string", "enum": [ "product" ] }, "render_js": { "type": "boolean", "description": "Isolated mock-intercepted browser navigation. Adds 3 credits only on successful completion." }, "wait_for": { "type": "string" }, "wait_for_selector": { "type": "string", "description": "Alias for wait_for; conflicting values are rejected." }, "geo_country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Reserved advanced transport; execution returns 501." }, "custom_headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Reserved; credential headers are rejected. Execution returns 501." }, "forward_cookies": { "type": "boolean", "description": "Reserved; true returns 501. Application cookies are never forwarded." }, "byop_proxy": { "type": "string", "writeOnly": true, "description": "Reserved; use account settings for encrypted storage. Execution returns 501." }, "extract_prompt": { "type": "string", "maxLength": 8000, "description": "Enables mock language extraction. JSON output only, cannot combine with CSS selectors/template. Adds 2 success credits. The mock maps product fields and does not interpret natural language." }, "extract_schema": { "type": "object", "description": "Object JSON Schema, default draft 2020-12, 16 KiB, depth 16, offline references only. Requires extract_prompt. Omit for default title/price/currency/in_stock schema. Invalid schema=400; invalid output=failed job, zero credits." }, "selectors": { "type": "object", "additionalProperties": { "type": "string" } }, "required_fields": { "type": "array", "items": { "type": "string" } }, "callback_url": { "type": "string", "format": "uri" }, "mock_scenario": { "type": "string", "enum": [ "success", "retry", "blocked", "empty", "captcha", "captcha_fail", "http_error", "price_change" ] } } }, "ScrapeResult": { "type": "object", "required": [ "id", "url", "success", "status", "credits_charged" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "success": { "type": "boolean" }, "status": { "type": "integer" }, "attempts": { "type": "integer", "minimum": 0, "maximum": 6 }, "credits_charged": { "type": "integer", "enum": [ 0, 1, 3, 4, 6 ] }, "llm_calls": { "type": "integer", "minimum": 0 }, "browser_ms": { "type": "integer", "minimum": 0 }, "extraction_mode": { "type": "string", "enum": [ "mock" ] }, "html": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "markdown": { "type": "string" }, "error": { "type": "string" }, "error_reason": { "type": "string", "description": "Terminal human-readable failure diagnosis. Omitted on success." }, "duration_ms": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } } } }, "paths": { "/mcp/v1/scrape": { "post": { "summary": "Authenticated Streamable HTTP MCP endpoint", "description": "Local deployment hosts only. JSON-RPC initialize, tools/list and tools/call, negotiated by the official MCP SDK. Tools: scrape (url, required stable idempotency_key, optional options), scrape_status (id), credit_balance. Same ownership, quoted prices, rate limits and durable jobs as REST. No cross-account sessions. No foreign browser origins.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "MCP JSON-RPC response; tool failures use isError. Initialize before invoking tools.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/capabilities": { "get": { "summary": "Implemented and pending capabilities", "responses": { "200": { "description": "Mock mode, stage 4. Durable queues, active UTC cron, signed aggregate callbacks and MCP available. Advanced transport and script execution remain disabled. Success prices: base=1, language extra=2, JS extra=3.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/batch": { "get": { "summary": "List up to 100 owned batches", "responses": { "200": { "description": "Owned batches", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "summary": "Submit jobs atomically to the existing durable queue, up to your plan's batch size", "description": "Provide urls plus common config OR requests. Explicit webhook_url enables a signed aggregate callback after every job is terminal. Five delivery attempts, stable event ID/body, zero callback charge. HTML/Markdown use result references; large data may use references too. Old batches retain their previous opt-out. Each success costs its persisted quote (base 1 + language 2 + JS 3); failures cost zero. Admission checks the submitted total without debiting.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "urls": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "format": "uri" } }, "requests": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/JobRequest" } }, "config": { "type": "object", "description": "JobRequest options; target URL is supplied by the enclosing object." }, "webhook_url": { "type": "string", "format": "uri" } }, "oneOf": [ { "required": [ "urls" ], "not": { "required": [ "requests" ] } }, { "required": [ "requests" ], "not": { "required": [ "urls" ] } } ] } } } }, "responses": { "202": { "description": "Accepted: batch_id, job_ids, status_url, webhook_delivery_enabled reflecting persisted opt-in", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/batch/{id}": { "get": { "summary": "Owned batch status and individual results", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "pending/processing/completed/failed; completed_urls counts all terminal jobs, including failures. HTML omitted; fetch individual result for content.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/schedules": { "get": { "summary": "List owned cron schedules", "responses": { "200": { "description": "Schedules with UTC next_run_at, last_error and execution_enabled mirroring is_active", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "summary": "Create UTC cron schedule; is_active=true explicitly enables future jobs", "description": "Five fields, minimum minute precision. Scan at startup and each minute. No overlapping run for one schedule; downtime coalesces to one due run. API-key-created schedules remain bound to that key's limits/revocation. Creation costs zero; each accepted job has normal success pricing. Default inactive. Retain Idempotency-Key for retries; identical payload replays the same ID and current state, changed payload returns 409, replay after deletion returns 410.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cron_expression", "target_url" ], "properties": { "cron_expression": { "type": "string", "description": "Five fields, UTC. No seconds or @every." }, "target_url": { "type": "string", "format": "uri" }, "config": { "type": "object", "description": "JobRequest options; target URL is supplied by the enclosing object." }, "webhook_url": { "type": "string", "format": "uri" }, "is_active": { "type": "boolean", "default": false, "description": "Explicit opt-in to automatic jobs; existing blueprints stay inactive." } } } } } }, "responses": { "201": { "description": "Saved; active flag and next_run_at", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "410": { "description": "The idempotent schedule was deleted; it is not recreated", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/schedules/{id}/delete": { "post": { "summary": "Delete owned schedule; already accepted work may finish", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/schedules/{id}/toggle": { "post": { "summary": "Pause/resume an owned schedule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_active" ], "properties": { "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Saved. Resume computes a fresh UTC next run. API-key calls bind future work to that key; session calls preserve an existing binding.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/schedules/{id}/runs": { "get": { "summary": "Last 50 owned schedule runs", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job IDs, states, quoted credit prices, scheduled_for and result URLs", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/analytics/errors": { "get": { "summary": "Last 50 failed results belonging to the account", "responses": { "200": { "description": "Error diagnostics with error_reason; HTML and extracted data omitted", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/extraction-templates": { "get": { "summary": "List owned extraction blueprints", "responses": { "200": { "description": "Templates; execution_enabled=false", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "summary": "Save extraction prompt and schema metadata", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "prompt", "json_schema" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "prompt": { "type": "string", "maxLength": 8000 }, "json_schema": { "type": "object", "description": "Root type=object; 16 KiB, depth 16, no external references. Fully compiled before saving. Copy prompt/json_schema to scrape extract_prompt/extract_schema to execute." } } } } } }, "responses": { "201": { "description": "Saved; metadata endpoint does not execute a scrape. Copy prompt/schema into a job request.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/extraction-templates/{id}/delete": { "post": { "summary": "Delete owned template", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/webhooks/test": { "post": { "summary": "Send a signed test event to a public URL", "description": "Explicit outbound request. Zero credits, five attempts/minute/account, 8-second client timeout. Private addresses and redirects blocked. Existing X-ProxWraith signature headers retained for compatibility.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } } } } }, "responses": { "200": { "description": "delivered=true, event_id, credits_charged=0", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "502": { "description": "Delivery failed; credits_charged=0", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/analytics/costs": { "get": { "summary": "Owned per-domain credit and estimated cost usage", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 30 } } ], "responses": { "200": { "description": "Credits are actual charges. Cost is an estimate in USD micros; check rates_configured before interpreting zeros.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/marketplace": { "get": { "summary": "Public scripts, own drafts and installed snapshots", "description": "No code URL is fetched or executed. Paid code/config hidden from non-authors. Free installation freezes title, description and configuration, preserving access if the publisher later changes the listing. Installed request configurations can be opened in Playground; normal scrape pricing applies only when submitted successfully.", "responses": { "200": { "description": "Scripts with installation state", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "summary": "Administrator: publish script metadata", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 150 }, "description": { "type": "string", "maxLength": 4000 }, "code_url": { "type": "string", "format": "uri" }, "price": { "type": "number", "minimum": 0, "maximum": 1000000, "multipleOf": 0.01 }, "is_public": { "type": "boolean" }, "config": { "$ref": "#/components/schemas/JobRequest" } } } } } }, "responses": { "201": { "description": "Saved; execution_enabled=false", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/marketplace/{id}/use": { "post": { "summary": "Save a free script to the account", "description": "Idempotent installation metadata; zero credits. Paid checkout returns 409 and script execution is disabled.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "installed=true, execution_enabled=false, credits_charged=0", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/account/scraping": { "get": { "summary": "Session only: read redacted scraping defaults", "security": [ { "Bearer": [] } ], "responses": { "200": { "description": "default_webhook_url, geo_target_country, byop_configured, defaults_execution_enabled=false; never returns proxy credentials", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "summary": "Session only: save defaults for future execution", "security": [ { "Bearer": [] } ], "description": "Proxy is encrypted at rest using SETTINGS_ENCRYPTION_KEY. Omit proxy to preserve it, empty string clears it. These settings are not applied automatically in stage 1.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "default_webhook_url": { "type": "string", "description": "Public HTTP(S) URL or empty" }, "geo_target_country": { "type": "string", "pattern": "^([A-Z]{2})?$" }, "byop_proxy_url": { "type": "string", "writeOnly": true } } } } } }, "responses": { "200": { "description": "Redacted saved settings", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/webhooks/test": { "post": { "summary": "Session-only alias for POST /v1/webhooks/test", "security": [ { "Bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } } } } }, "responses": { "200": { "description": "Signed test delivery; zero credits", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Administrator or session access required", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Owned resource not found", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Conflict; no credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Rate or capacity limit", "content": { "application/json": { "schema": { "type": "object" } } } }, "501": { "description": "Requested execution capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object" } } } }, "502": { "description": "Delivery failed; zero credits", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/me": { "get": { "operationId": "getAccount", "summary": "Account and current credits", "responses": { "200": { "description": "Account summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "credits": { "type": "integer" }, "email": { "type": "string" } } } } } } } }, "400": { "description": "Invalid URL or options", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Rate, capacity, or daily key limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "501": { "description": "Requested capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "502": { "description": "Failed scrape; zero credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/scrape": { "get": { "operationId": "scrape", "summary": "Scrape and validate a target", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "format", "in": "query", "schema": { "type": "string" } }, { "name": "template", "in": "query", "schema": { "type": "string" } }, { "name": "wait_for", "in": "query", "schema": { "type": "string" } }, { "name": "mock_scenario", "in": "query", "schema": { "type": "string" } }, { "name": "render_js", "in": "query", "schema": { "type": "boolean" } }, { "name": "wait_for_selector", "in": "query", "schema": { "type": "string" }, "description": "Alias for wait_for." }, { "name": "geo_country", "in": "query", "schema": { "type": "string" }, "description": "Reserved advanced option; nonempty value returns 501 before admission. custom_headers and extract_schema are JSON encoded. Prefer session-protected settings for proxy credentials." }, { "name": "custom_headers", "in": "query", "schema": { "type": "string" }, "description": "Reserved advanced option; nonempty value returns 501 before admission. custom_headers and extract_schema are JSON encoded. Prefer session-protected settings for proxy credentials." }, { "name": "byop_proxy", "in": "query", "schema": { "type": "string" }, "description": "Reserved advanced option; nonempty value returns 501 before admission. custom_headers and extract_schema are JSON encoded. Prefer session-protected settings for proxy credentials." }, { "name": "extract_prompt", "in": "query", "schema": { "type": "string", "maxLength": 8000 }, "description": "Enables mock JSON language extraction; +2 successful-job credits." }, { "name": "extract_schema", "in": "query", "schema": { "type": "string" }, "description": "URL-encoded JSON object schema; requires extract_prompt. Same validation as JobRequest." }, { "name": "forward_cookies", "in": "query", "schema": { "type": "boolean" }, "description": "true returns 501 before admission." }, { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 128 } } ], "responses": { "200": { "description": "Validated result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeResult" } } } }, "202": { "description": "Accepted; poll the job until terminal. This is not a billable success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status_url": { "type": "string" }, "result_url": { "type": "string" }, "success_credit_cost": { "type": "integer", "enum": [ 1, 3, 4, 6 ], "description": "Persisted quote for new jobs; replay preserves original quote. A quote is not a debit." } } } } } }, "400": { "description": "Invalid URL or options", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Rate, capacity, or daily key limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "501": { "description": "Requested capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "502": { "description": "Failed scrape; zero credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/jobs": { "post": { "operationId": "createJob", "summary": "Queue a durable job", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRequest" } } } }, "responses": { "202": { "description": "Accepted; poll the job until terminal. This is not a billable success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status_url": { "type": "string" }, "result_url": { "type": "string" }, "success_credit_cost": { "type": "integer", "enum": [ 1, 3, 4, 6 ], "description": "Persisted quote for new jobs; replay preserves original quote. A quote is not a debit." } } } } } }, "400": { "description": "Invalid URL or options", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Rate, capacity, or daily key limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "501": { "description": "Requested capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "502": { "description": "Failed scrape; zero credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/jobs/{id}": { "get": { "operationId": "getJob", "summary": "Poll a job until succeeded, failed, or dead", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current job state", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "succeeded", "failed", "dead" ] }, "result": { "$ref": "#/components/schemas/ScrapeResult" } } } } } }, "400": { "description": "Invalid URL or options", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Rate, capacity, or daily key limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "501": { "description": "Requested capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "502": { "description": "Failed scrape; zero credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/requests": { "get": { "operationId": "getHistory", "summary": "Last 50 completed results", "responses": { "200": { "description": "Results without raw HTML", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ScrapeResult" } } } } }, "400": { "description": "Invalid URL or options", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Rate, capacity, or daily key limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "501": { "description": "Requested capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "502": { "description": "Failed scrape; zero credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/requests/{id}": { "get": { "operationId": "getResult", "summary": "Completed result owned by this account", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Validated result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeResult" } } } }, "400": { "description": "Invalid URL or options", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Rate, capacity, or daily key limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "501": { "description": "Requested capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "502": { "description": "Failed scrape; zero credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/batches": { "post": { "operationId": "createBatch", "summary": "Queue requests atomically up to your plan's batch size", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "requests" ], "properties": { "requests": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/JobRequest" } } } } } } }, "responses": { "202": { "description": "Batch accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "batch_id": { "type": "string" }, "job_ids": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid URL or options", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Rate, capacity, or daily key limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "501": { "description": "Requested capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "502": { "description": "Failed scrape; zero credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/batches/{id}": { "get": { "operationId": "getBatch", "summary": "Poll batch progress", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Batch jobs", "content": { "application/json": { "schema": { "type": "object", "properties": { "batch_id": { "type": "string" }, "jobs": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Invalid URL or options", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Rate, capacity, or daily key limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "501": { "description": "Requested capability is not enabled; zero credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "502": { "description": "Failed scrape; zero credits charged", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Required service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } } } }