{"openapi":"3.1.0","info":{"title":"Sparkcrawl API","version":"1.0.0","description":"Scrape, crawl, map, search and research the public web. Authenticate with an organization API key (Authorization: Bearer sc_live_…) created at https://sparkcrawl.com/app/api. One organization balance in USD pays every operation. Errors share one envelope: { \"error\": { \"code\": \"…\" } }. Feature availability is runtime-gated; check GET /api/v1/capabilities before optional operations."},"servers":[{"url":"https://sparkcrawl.com"}],"tags":[{"name":"scrape","description":"Single pages, batches and browser sessions"},{"name":"crawl","description":"Same-host crawls, URL maps and recrawl schedules"},{"name":"search","description":"Cited answers and judged results from the open web"},{"name":"research","description":"Asynchronous multi-question research reports"},{"name":"jobs","description":"Status, pages, exports and artifacts of any job"},{"name":"account","description":"API keys, usage, metrics and capabilities"},{"name":"billing","description":"Balance, tariff and balance top-ups"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"sc_live_<43 characters>","description":"Organization API key created at /app/api. Scopes: scrape, crawl, search, research. The secret is shown once."},"sessionCookie":{"type":"apiKey","in":"cookie","name":"sparkcrawl_session","description":"Signed-in browser session at sparkcrawl.com. Key management and checkout accept only a session."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"security":[{"bearerAuth":[]}],"paths":{"/api/v1/artifacts":{"get":{"tags":["jobs"],"x-scope":"any","summary":"Download a ready, unexpired artifact authorized for this job","description":"Requires PostgreSQL and an artifact store; otherwise returns 503 artifact_disabled. Local downloads require the same API authentication and expire with the artifact; optional S3 URLs are signed for 60 seconds. GET with download=1 streams local bytes.","parameters":[{"name":"key","in":"query","required":true,"schema":{"type":"string","maxLength":1024}},{"name":"download","in":"query","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Download metadata, or local bytes when download=1","content":{"application/json":{"schema":{"type":"object","required":["downloadUrl","expiresInSeconds","requiresAuthorization"],"properties":{"downloadUrl":{"type":"string","format":"uri"},"expiresInSeconds":{"type":"integer","minimum":0},"requiresAuthorization":{"type":"boolean"}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"503":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/schedules":{"get":{"tags":["crawl"],"x-scope":"crawl","summary":"List recrawl schedules when automation is enabled","description":"Conditional capability: SCRAPING_AUTOMATION_ENABLED=1 and PostgreSQL are required; otherwise returns 503 automation_unavailable. Requires crawl scope.","responses":{"200":{"description":"Tenant schedules","content":{"application/json":{"schema":{"type":"object","properties":{"schedules":{"type":"array","items":{"type":"object","required":["id","organizationId","url","intervalMs","nextRunAt","paused"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"url":{"type":"string","format":"uri"},"intervalMs":{"type":"integer"},"nextRunAt":{"type":"integer"},"paused":{"type":"boolean"}}}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"503":{"description":"Automation is disabled or PostgreSQL is unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"const":"automation_unavailable"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"post":{"tags":["crawl"],"x-scope":"crawl","summary":"Create a bounded recrawl schedule when automation is enabled","description":"Conditional capability; check capabilities.schedules. Requires crawl scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string","maxLength":8192,"format":"uri"},"intervalMinutes":{"type":"integer","minimum":1,"maximum":43200}},"required":["url","intervalMinutes"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created schedule","content":{"application/json":{"schema":{"type":"object","required":["id","organizationId","url","intervalMs","nextRunAt","paused"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"url":{"type":"string","format":"uri"},"intervalMs":{"type":"integer"},"nextRunAt":{"type":"integer"},"paused":{"type":"boolean"}}}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"503":{"description":"Automation is disabled or PostgreSQL is unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"const":"automation_unavailable"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/schedules/{id}":{"patch":{"tags":["crawl"],"x-scope":"crawl","summary":"Pause or resume a recrawl schedule when automation is enabled","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"paused":{"type":"boolean"}},"required":["paused"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated schedule","content":{"application/json":{"schema":{"type":"object","required":["id","organizationId","url","intervalMs","nextRunAt","paused"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"url":{"type":"string","format":"uri"},"intervalMs":{"type":"integer"},"nextRunAt":{"type":"integer"},"paused":{"type":"boolean"}}}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"Automation is disabled or PostgreSQL is unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"const":"automation_unavailable"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"tags":["crawl"],"x-scope":"crawl","summary":"Pause a recrawl schedule when automation is enabled","description":"DELETE soft-pauses the schedule; it does not remove its record.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Paused schedule","content":{"application/json":{"schema":{"type":"object","required":["id","organizationId","url","intervalMs","nextRunAt","paused"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"url":{"type":"string","format":"uri"},"intervalMs":{"type":"integer"},"nextRunAt":{"type":"integer"},"paused":{"type":"boolean"}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"Automation is disabled or PostgreSQL is unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"const":"automation_unavailable"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/batches":{"post":{"tags":["scrape"],"x-scope":"scrape","summary":"Enqueue up to 100 independent requests","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"entries":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"url":{"type":"string","maxLength":8192,"format":"uri"},"method":{"default":"GET","type":"string","enum":["GET","POST"]},"headers":{"default":{},"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":80},"additionalProperties":{"type":"string","maxLength":2048}},"body":{"type":"string","maxLength":65536},"cookies":{"default":{},"type":"object","propertyNames":{"type":"string","pattern":"^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,128}$"},"additionalProperties":{"type":"string","maxLength":2048}},"waitFor":{"type":"string","minLength":1,"maxLength":512},"waitMs":{"default":0,"type":"integer","minimum":0,"maximum":10000},"actions":{"default":[],"maxItems":10,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"click"},"selector":{"type":"string","minLength":1,"maxLength":512}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"fill"},"selector":{"type":"string","minLength":1,"maxLength":512},"value":{"type":"string","maxLength":4096}},"required":["type","selector","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scroll"},"pixels":{"type":"integer","minimum":-5000,"maximum":5000}},"required":["type","pixels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"wait"},"ms":{"type":"integer","minimum":0,"maximum":5000}},"required":["type","ms"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hover"},"selector":{"type":"string","minLength":1,"maxLength":512}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"select"},"selector":{"type":"string","minLength":1,"maxLength":512},"value":{"type":"string","maxLength":256}},"required":["type","selector","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"keyboard"},"key":{"type":"string","minLength":1,"maxLength":80}},"required":["type","key"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scrollUntil"},"selector":{"type":"string","minLength":1,"maxLength":512},"maxScrolls":{"default":10,"type":"integer","minimum":1,"maximum":20}},"required":["type","selector"],"additionalProperties":false}]}},"screenshot":{"default":false,"type":"boolean"},"screenshotFullPage":{"default":false,"type":"boolean"},"screenshotSelector":{"type":"string","minLength":1,"maxLength":512},"pdf":{"default":false,"type":"boolean"},"jsonSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"cacheTtlSeconds":{"default":0,"type":"integer","minimum":0,"maximum":3600},"sessionId":{"type":"string","pattern":"^sess_[a-f0-9]{32}$"},"maxCustomerCostUsd":{"type":"number","minimum":0,"maximum":100},"formats":{"default":["html","markdown"],"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["html","markdown","json"]}},"maxTier":{"default":"auto","anyOf":[{"type":"string","const":"auto"},{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3},{"type":"number","const":4}]},"proxy":{"default":"auto","type":"string","enum":["auto","none","residential"]},"country":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"timeoutMs":{"default":120000,"type":"integer","minimum":1000,"maximum":180000},"maxCostUsd":{"default":0.02,"type":"number","minimum":0,"maximum":10},"selectors":{"default":{},"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":80},"additionalProperties":{"type":"object","properties":{"selector":{"type":"string","minLength":1,"maxLength":512},"attribute":{"type":"string","minLength":1,"maxLength":80},"type":{"type":"string","enum":["string","number","boolean"]}},"required":["selector"],"additionalProperties":false}},"requiredSelectors":{"default":[],"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":512}},"containsText":{"default":[],"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":2000}}},"required":["url"],"additionalProperties":false}},"maxCostUsd":{"default":0.15,"type":"number","minimum":0,"maximum":10},"maxCustomerCostUsd":{"type":"number","minimum":0,"maximum":100,"description":"Optional ceiling in USD on what this request may charge the organization balance. When omitted and billing is enabled, the server reserves exactly the required ceiling: success-page fee × requested pages + maxCostUsd × (1 + upstream markup) — today US$0.005 per page and a 50% markup (GET /api/v1/pricing). The reservation settles down to the measured charge; a value below the required ceiling is rejected."},"webhook":{"type":"object","properties":{"url":{"type":"string","pattern":"^https:\\/\\/"},"secret":{"type":"string","minLength":32,"maxLength":256}},"required":["url","secret"]}},"required":["entries"],"additionalProperties":false}}}},"parameters":[{"name":"Idempotency-Key","in":"header","description":"Replays the original job instead of creating a second one when the same key and body are retried.","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9._~-]{1,128}$"}}],"responses":{"202":{"description":"Batch accepted","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","required":["id","kind","status","url","pagesCompleted","pagesFailed","pagesQueued"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["scrape","crawl","batch","map","search","research"]},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"url":{"type":"string","format":"uri"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"expiresAt":{"type":"integer"},"pagesCompleted":{"type":"integer"},"pagesFailed":{"type":"integer"},"pagesQueued":{"type":"integer"},"maxPages":{"type":"integer"},"upstreamCostUsd":{"type":"number"},"reservedCostUsd":{"type":"number"},"uncertainCostUsd":{"type":"number"},"customerChargeUsd":{"type":"number"},"pricingVersion":{"type":"string"},"result":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"replayed":{"type":"boolean"}}}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"402":{"description":"The organization balance cannot cover the reserved ceiling, or the job reached its customer ceiling; top up at /app/billing","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["insufficient_scraping_balance","customer_budget_exceeded"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"429":{"description":"Monthly plan quota, per-job page limit or concurrent capacity (20 active jobs per organization) reached","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["monthly_quota_exceeded","plan_page_limit","scraping_capacity_reached"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/maps":{"post":{"tags":["crawl"],"x-scope":"crawl","summary":"Discover up to 1000 URLs under robots and budget limits","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string","maxLength":8192,"format":"uri"},"method":{"default":"GET","type":"string","enum":["GET","POST"]},"headers":{"default":{},"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":80},"additionalProperties":{"type":"string","maxLength":2048}},"body":{"type":"string","maxLength":65536},"cookies":{"default":{},"type":"object","propertyNames":{"type":"string","pattern":"^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,128}$"},"additionalProperties":{"type":"string","maxLength":2048}},"waitFor":{"type":"string","minLength":1,"maxLength":512},"waitMs":{"default":0,"type":"integer","minimum":0,"maximum":10000},"actions":{"default":[],"maxItems":10,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"click"},"selector":{"type":"string","minLength":1,"maxLength":512}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"fill"},"selector":{"type":"string","minLength":1,"maxLength":512},"value":{"type":"string","maxLength":4096}},"required":["type","selector","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scroll"},"pixels":{"type":"integer","minimum":-5000,"maximum":5000}},"required":["type","pixels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"wait"},"ms":{"type":"integer","minimum":0,"maximum":5000}},"required":["type","ms"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hover"},"selector":{"type":"string","minLength":1,"maxLength":512}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"select"},"selector":{"type":"string","minLength":1,"maxLength":512},"value":{"type":"string","maxLength":256}},"required":["type","selector","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"keyboard"},"key":{"type":"string","minLength":1,"maxLength":80}},"required":["type","key"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scrollUntil"},"selector":{"type":"string","minLength":1,"maxLength":512},"maxScrolls":{"default":10,"type":"integer","minimum":1,"maximum":20}},"required":["type","selector"],"additionalProperties":false}]}},"screenshot":{"default":false,"type":"boolean"},"screenshotFullPage":{"default":false,"type":"boolean"},"screenshotSelector":{"type":"string","minLength":1,"maxLength":512},"pdf":{"default":false,"type":"boolean"},"jsonSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"cacheTtlSeconds":{"default":0,"type":"integer","minimum":0,"maximum":3600},"sessionId":{"type":"string","pattern":"^sess_[a-f0-9]{32}$"},"maxCustomerCostUsd":{"type":"number","minimum":0,"maximum":100,"description":"Optional ceiling in USD on what this request may charge the organization balance. When omitted and billing is enabled, the server reserves exactly the required ceiling: success-page fee × requested pages + maxCostUsd × (1 + upstream markup) — today US$0.005 per page and a 50% markup (GET /api/v1/pricing). The reservation settles down to the measured charge; a value below the required ceiling is rejected."},"formats":{"default":["html","markdown"],"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["html","markdown","json"]}},"maxTier":{"default":"auto","anyOf":[{"type":"string","const":"auto"},{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3},{"type":"number","const":4}]},"proxy":{"default":"auto","type":"string","enum":["auto","none","residential"]},"country":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"timeoutMs":{"default":120000,"type":"integer","minimum":1000,"maximum":180000},"maxCostUsd":{"default":0.15,"type":"number","minimum":0,"maximum":10},"selectors":{"default":{},"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":80},"additionalProperties":{"type":"object","properties":{"selector":{"type":"string","minLength":1,"maxLength":512},"attribute":{"type":"string","minLength":1,"maxLength":80},"type":{"type":"string","enum":["string","number","boolean"]}},"required":["selector"],"additionalProperties":false}},"requiredSelectors":{"default":[],"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":512}},"containsText":{"default":[],"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":2000}},"maxPages":{"default":100,"type":"integer","minimum":1,"maximum":1000},"maxDepth":{"default":2,"type":"integer","minimum":0,"maximum":10},"prompt":{"type":"string","minLength":1,"maxLength":500},"webhook":{"type":"object","properties":{"url":{"type":"string","pattern":"^https:\\/\\/"},"secret":{"type":"string","minLength":32,"maxLength":256}},"required":["url","secret"]}},"required":["url"],"additionalProperties":false}}}},"parameters":[{"name":"Idempotency-Key","in":"header","description":"Replays the original job instead of creating a second one when the same key and body are retried.","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9._~-]{1,128}$"}}],"responses":{"202":{"description":"Map accepted","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","required":["id","kind","status","url","pagesCompleted","pagesFailed","pagesQueued"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["scrape","crawl","batch","map","search","research"]},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"url":{"type":"string","format":"uri"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"expiresAt":{"type":"integer"},"pagesCompleted":{"type":"integer"},"pagesFailed":{"type":"integer"},"pagesQueued":{"type":"integer"},"maxPages":{"type":"integer"},"upstreamCostUsd":{"type":"number"},"reservedCostUsd":{"type":"number"},"uncertainCostUsd":{"type":"number"},"customerChargeUsd":{"type":"number"},"pricingVersion":{"type":"string"},"result":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"replayed":{"type":"boolean"}}}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"402":{"description":"The organization balance cannot cover the reserved ceiling, or the job reached its customer ceiling; top up at /app/billing","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["insufficient_scraping_balance","customer_budget_exceeded"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"429":{"description":"Monthly plan quota, per-job page limit or concurrent capacity (20 active jobs per organization) reached","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["monthly_quota_exceeded","plan_page_limit","scraping_capacity_reached"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/jobs/{id}/pages":{"get":{"tags":["jobs"],"x-scope":"any","summary":"Read the pages of any job, a page of results at a time","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Job pages","content":{"application/json":{"schema":{"type":"object","properties":{"pages":{"type":"array","items":{"type":"object","required":["id","url","depth","status"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"depth":{"type":"integer"},"status":{"type":"string"},"result":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"nextCursor":{"type":"string"}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/batches/{id}/pages":{"get":{"tags":["scrape"],"x-scope":"any","summary":"Read the independent page results of a batch","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Independent page results","content":{"application/json":{"schema":{"type":"object","properties":{"pages":{"type":"array","items":{"type":"object","required":["id","url","depth","status"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"depth":{"type":"integer"},"status":{"type":"string"},"result":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"nextCursor":{"type":"string"}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/maps/{id}/links":{"get":{"tags":["crawl"],"x-scope":"any","summary":"Read the URLs a map discovered, with their status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Discovered URLs with status","content":{"application/json":{"schema":{"type":"object","properties":{"pages":{"type":"array","items":{"type":"object","required":["id","url","depth","status"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"depth":{"type":"integer"},"status":{"type":"string"},"result":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"nextCursor":{"type":"string"}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/capabilities":{"get":{"tags":["account"],"x-scope":"any","summary":"Read the capabilities and limits enabled on this deployment","responses":{"200":{"description":"Configured capabilities and limits","content":{"application/json":{"schema":{"type":"object","properties":{"capabilities":{"type":"object","properties":{"batch":{"type":"boolean"},"map":{"type":"boolean"},"schedules":{"type":"boolean","description":"True only when automation is enabled and PostgreSQL is configured."}},"additionalProperties":{"type":"boolean"}},"limits":{"type":"object","properties":{"batchEntries":{"type":"integer"},"mapUrls":{"type":"integer"},"cacheTtlSeconds":{"type":"integer"}},"additionalProperties":{"type":"integer"}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/research":{"post":{"tags":["research"],"x-scope":"research","summary":"Start an asynchronous deep research job (research scope)","description":"Plans 5 (standard) or 8 (max) sub-questions, researches each with the cited-answer pipeline (balanced or deep effort) plus arXiv abstracts for academic angles, and writes one report whose citations are checked against the collected sources. Always returns 202 with the job; read GET /api/v1/jobs/{id} until completed — result.research has outline, findings, sources, report, citationCoverage, completion, costUsd, durationMs. maxCostUsd (0.05-5, default 1) is the upstream budget, settled at the measured cost; runs are capped at 10 minutes. With billing on, the balance must cover US$0.005 + maxCostUsd × 1.5 up front (≈US$1.50 at the default, ≈US$7.50 at 5): on a US$1 balance pass maxCostUsd 0.6 or less.","parameters":[{"name":"Idempotency-Key","in":"header","description":"Replays the original job instead of creating a second one when the same key and body are retried.","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9._~-]{1,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":400},"depth":{"default":"standard","type":"string","enum":["standard","max"]},"language":{"type":"string","minLength":2,"maxLength":10},"country":{"type":"string","minLength":2,"maxLength":2},"maxCostUsd":{"default":0.5,"type":"number","minimum":0.05,"maximum":5},"webhook":{"type":"object","properties":{"url":{"type":"string","pattern":"^https:\\/\\/"},"secret":{"type":"string","minLength":32,"maxLength":256}},"required":["url","secret"]}},"required":["query"],"additionalProperties":false}}}},"responses":{"202":{"description":"Queued research job","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","required":["id","kind","status","url","pagesCompleted","pagesFailed","pagesQueued"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["scrape","crawl","batch","map","search","research"]},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"url":{"type":"string","format":"uri"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"expiresAt":{"type":"integer"},"pagesCompleted":{"type":"integer"},"pagesFailed":{"type":"integer"},"pagesQueued":{"type":"integer"},"maxPages":{"type":"integer"},"upstreamCostUsd":{"type":"number"},"reservedCostUsd":{"type":"number"},"uncertainCostUsd":{"type":"number"},"customerChargeUsd":{"type":"number"},"pricingVersion":{"type":"string"},"result":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"replayed":{"type":"boolean"}}}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"402":{"description":"The organization balance cannot cover the reserved ceiling, or the job reached its customer ceiling; top up at /app/billing","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["insufficient_scraping_balance","customer_budget_exceeded"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"429":{"description":"Monthly plan quota, per-job page limit or concurrent capacity (20 active jobs per organization) reached","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["monthly_quota_exceeded","plan_page_limit","scraping_capacity_reached"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/search":{"post":{"tags":["search"],"x-scope":"search","summary":"Answer a question with cited web evidence (search scope)","description":"mode=answer runs the verified pipeline (citations, completion); mode=results returns the judged SERP without synthesis; mode=fast returns Google AI Mode output via Scrappa with verified=false (third-party generated). Synchronous by default; async=1 or Prefer: respond-async returns 202 with the job. Result fields: query, mode, verified, answer, citations, sources[{id,url,title,snippet?}], completion{status,reason}, costUsd, customerChargeUsd, jobId. A search is billed as one page.","parameters":[{"name":"async","in":"query","schema":{"type":"string","enum":["1"]}},{"name":"Idempotency-Key","in":"header","description":"Replays the original job instead of creating a second one when the same key and body are retried.","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9._~-]{1,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":400},"mode":{"default":"answer","type":"string","enum":["answer","results","fast"]},"effort":{"default":"balanced","type":"string","enum":["fast","balanced","deep"]},"language":{"type":"string","minLength":2,"maxLength":10},"country":{"type":"string","minLength":2,"maxLength":2},"maxCostUsd":{"default":0.1,"type":"number","minimum":0,"maximum":1},"timeoutMs":{"default":90000,"type":"integer","minimum":5000,"maximum":120000},"webhook":{"type":"object","properties":{"url":{"type":"string","pattern":"^https:\\/\\/"},"secret":{"type":"string","minLength":32,"maxLength":256}},"required":["url","secret"]}},"required":["query"],"additionalProperties":false}}}},"responses":{"200":{"description":"Search result"},"202":{"description":"Queued search job","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","required":["id","kind","status","url","pagesCompleted","pagesFailed","pagesQueued"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["scrape","crawl","batch","map","search","research"]},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"url":{"type":"string","format":"uri"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"expiresAt":{"type":"integer"},"pagesCompleted":{"type":"integer"},"pagesFailed":{"type":"integer"},"pagesQueued":{"type":"integer"},"maxPages":{"type":"integer"},"upstreamCostUsd":{"type":"number"},"reservedCostUsd":{"type":"number"},"uncertainCostUsd":{"type":"number"},"customerChargeUsd":{"type":"number"},"pricingVersion":{"type":"string"},"result":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"replayed":{"type":"boolean"}}}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"402":{"description":"The organization balance cannot cover the reserved ceiling, or the job reached its customer ceiling; top up at /app/billing","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["insufficient_scraping_balance","customer_budget_exceeded"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"429":{"description":"Monthly plan quota, per-job page limit or concurrent capacity (20 active jobs per organization) reached","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["monthly_quota_exceeded","plan_page_limit","scraping_capacity_reached"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/scrape":{"post":{"tags":["scrape"],"x-scope":"scrape","summary":"Scrape one page synchronously or enqueue with async=1","parameters":[{"name":"async","in":"query","schema":{"type":"string","enum":["1"]}},{"name":"Idempotency-Key","in":"header","description":"Replays the original job instead of creating a second one when the same key and body are retried.","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9._~-]{1,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string","maxLength":8192,"format":"uri"},"method":{"default":"GET","type":"string","enum":["GET","POST"]},"headers":{"default":{},"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":80},"additionalProperties":{"type":"string","maxLength":2048}},"body":{"type":"string","maxLength":65536},"cookies":{"default":{},"type":"object","propertyNames":{"type":"string","pattern":"^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,128}$"},"additionalProperties":{"type":"string","maxLength":2048}},"waitFor":{"type":"string","minLength":1,"maxLength":512},"waitMs":{"default":0,"type":"integer","minimum":0,"maximum":10000},"actions":{"default":[],"maxItems":10,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"click"},"selector":{"type":"string","minLength":1,"maxLength":512}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"fill"},"selector":{"type":"string","minLength":1,"maxLength":512},"value":{"type":"string","maxLength":4096}},"required":["type","selector","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scroll"},"pixels":{"type":"integer","minimum":-5000,"maximum":5000}},"required":["type","pixels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"wait"},"ms":{"type":"integer","minimum":0,"maximum":5000}},"required":["type","ms"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hover"},"selector":{"type":"string","minLength":1,"maxLength":512}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"select"},"selector":{"type":"string","minLength":1,"maxLength":512},"value":{"type":"string","maxLength":256}},"required":["type","selector","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"keyboard"},"key":{"type":"string","minLength":1,"maxLength":80}},"required":["type","key"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scrollUntil"},"selector":{"type":"string","minLength":1,"maxLength":512},"maxScrolls":{"default":10,"type":"integer","minimum":1,"maximum":20}},"required":["type","selector"],"additionalProperties":false}]}},"screenshot":{"default":false,"type":"boolean"},"screenshotFullPage":{"default":false,"type":"boolean"},"screenshotSelector":{"type":"string","minLength":1,"maxLength":512},"pdf":{"default":false,"type":"boolean"},"jsonSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"cacheTtlSeconds":{"default":0,"type":"integer","minimum":0,"maximum":3600},"sessionId":{"type":"string","pattern":"^sess_[a-f0-9]{32}$"},"maxCustomerCostUsd":{"type":"number","minimum":0,"maximum":100,"description":"Optional ceiling in USD on what this request may charge the organization balance. When omitted and billing is enabled, the server reserves exactly the required ceiling: success-page fee × requested pages + maxCostUsd × (1 + upstream markup) — today US$0.005 per page and a 50% markup (GET /api/v1/pricing). The reservation settles down to the measured charge; a value below the required ceiling is rejected."},"formats":{"default":["html","markdown"],"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["html","markdown","json"]}},"maxTier":{"default":"auto","anyOf":[{"type":"string","const":"auto"},{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3},{"type":"number","const":4}]},"proxy":{"default":"auto","type":"string","enum":["auto","none","residential"]},"country":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"timeoutMs":{"default":120000,"type":"integer","minimum":1000,"maximum":180000},"maxCostUsd":{"default":0.02,"type":"number","minimum":0,"maximum":10},"selectors":{"default":{},"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":80},"additionalProperties":{"type":"object","properties":{"selector":{"type":"string","minLength":1,"maxLength":512},"attribute":{"type":"string","minLength":1,"maxLength":80},"type":{"type":"string","enum":["string","number","boolean"]}},"required":["selector"],"additionalProperties":false}},"requiredSelectors":{"default":[],"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":512}},"containsText":{"default":[],"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":2000}},"webhook":{"type":"object","properties":{"url":{"type":"string","pattern":"^https:\\/\\/"},"secret":{"type":"string","minLength":32,"maxLength":256}},"required":["url","secret"]}},"required":["url"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scrape result","content":{"application/json":{"schema":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"202":{"description":"Durable job accepted","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","required":["id","kind","status","url","pagesCompleted","pagesFailed","pagesQueued"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["scrape","crawl","batch","map","search","research"]},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"url":{"type":"string","format":"uri"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"expiresAt":{"type":"integer"},"pagesCompleted":{"type":"integer"},"pagesFailed":{"type":"integer"},"pagesQueued":{"type":"integer"},"maxPages":{"type":"integer"},"upstreamCostUsd":{"type":"number"},"reservedCostUsd":{"type":"number"},"uncertainCostUsd":{"type":"number"},"customerChargeUsd":{"type":"number"},"pricingVersion":{"type":"string"},"result":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"replayed":{"type":"boolean"}}}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"402":{"description":"The organization balance cannot cover the reserved ceiling, or the job reached its customer ceiling; top up at /app/billing","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["insufficient_scraping_balance","customer_budget_exceeded"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"429":{"description":"Monthly plan quota, per-job page limit or concurrent capacity (20 active jobs per organization) reached","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["monthly_quota_exceeded","plan_page_limit","scraping_capacity_reached"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/crawls":{"post":{"tags":["crawl"],"x-scope":"crawl","summary":"Enqueue a bounded same-host crawl","parameters":[{"name":"Idempotency-Key","in":"header","description":"Replays the original job instead of creating a second one when the same key and body are retried.","schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9._~-]{1,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string","maxLength":8192,"format":"uri"},"method":{"default":"GET","type":"string","enum":["GET","POST"]},"headers":{"default":{},"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":80},"additionalProperties":{"type":"string","maxLength":2048}},"body":{"type":"string","maxLength":65536},"cookies":{"default":{},"type":"object","propertyNames":{"type":"string","pattern":"^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,128}$"},"additionalProperties":{"type":"string","maxLength":2048}},"waitFor":{"type":"string","minLength":1,"maxLength":512},"waitMs":{"default":0,"type":"integer","minimum":0,"maximum":10000},"actions":{"default":[],"maxItems":10,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"click"},"selector":{"type":"string","minLength":1,"maxLength":512}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"fill"},"selector":{"type":"string","minLength":1,"maxLength":512},"value":{"type":"string","maxLength":4096}},"required":["type","selector","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scroll"},"pixels":{"type":"integer","minimum":-5000,"maximum":5000}},"required":["type","pixels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"wait"},"ms":{"type":"integer","minimum":0,"maximum":5000}},"required":["type","ms"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"hover"},"selector":{"type":"string","minLength":1,"maxLength":512}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"select"},"selector":{"type":"string","minLength":1,"maxLength":512},"value":{"type":"string","maxLength":256}},"required":["type","selector","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"keyboard"},"key":{"type":"string","minLength":1,"maxLength":80}},"required":["type","key"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scrollUntil"},"selector":{"type":"string","minLength":1,"maxLength":512},"maxScrolls":{"default":10,"type":"integer","minimum":1,"maximum":20}},"required":["type","selector"],"additionalProperties":false}]}},"screenshot":{"default":false,"type":"boolean"},"screenshotFullPage":{"default":false,"type":"boolean"},"screenshotSelector":{"type":"string","minLength":1,"maxLength":512},"pdf":{"default":false,"type":"boolean"},"jsonSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"cacheTtlSeconds":{"default":0,"type":"integer","minimum":0,"maximum":3600},"sessionId":{"type":"string","pattern":"^sess_[a-f0-9]{32}$"},"maxCustomerCostUsd":{"type":"number","minimum":0,"maximum":100,"description":"Optional ceiling in USD on what this request may charge the organization balance. When omitted and billing is enabled, the server reserves exactly the required ceiling: success-page fee × requested pages + maxCostUsd × (1 + upstream markup) — today US$0.005 per page and a 50% markup (GET /api/v1/pricing). The reservation settles down to the measured charge; a value below the required ceiling is rejected."},"formats":{"default":["html","markdown"],"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["html","markdown","json"]}},"maxTier":{"default":"auto","anyOf":[{"type":"string","const":"auto"},{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3},{"type":"number","const":4}]},"proxy":{"default":"auto","type":"string","enum":["auto","none","residential"]},"country":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"timeoutMs":{"default":120000,"type":"integer","minimum":1000,"maximum":180000},"maxCostUsd":{"default":0.15,"type":"number","minimum":0,"maximum":10},"selectors":{"default":{},"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":80},"additionalProperties":{"type":"object","properties":{"selector":{"type":"string","minLength":1,"maxLength":512},"attribute":{"type":"string","minLength":1,"maxLength":80},"type":{"type":"string","enum":["string","number","boolean"]}},"required":["selector"],"additionalProperties":false}},"requiredSelectors":{"default":[],"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":512}},"containsText":{"default":[],"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":2000}},"maxPages":{"default":20,"type":"integer","minimum":1,"maximum":100},"maxDepth":{"default":2,"type":"integer","minimum":0,"maximum":3},"prompt":{"type":"string","minLength":1,"maxLength":500},"webhook":{"type":"object","properties":{"url":{"type":"string","pattern":"^https:\\/\\/"},"secret":{"type":"string","minLength":32,"maxLength":256}},"required":["url","secret"]}},"required":["url"],"additionalProperties":false}}}},"responses":{"202":{"description":"Durable crawl job accepted","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","required":["id","kind","status","url","pagesCompleted","pagesFailed","pagesQueued"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["scrape","crawl","batch","map","search","research"]},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"url":{"type":"string","format":"uri"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"expiresAt":{"type":"integer"},"pagesCompleted":{"type":"integer"},"pagesFailed":{"type":"integer"},"pagesQueued":{"type":"integer"},"maxPages":{"type":"integer"},"upstreamCostUsd":{"type":"number"},"reservedCostUsd":{"type":"number"},"uncertainCostUsd":{"type":"number"},"customerChargeUsd":{"type":"number"},"pricingVersion":{"type":"string"},"result":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"replayed":{"type":"boolean"}}}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"402":{"description":"The organization balance cannot cover the reserved ceiling, or the job reached its customer ceiling; top up at /app/billing","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["insufficient_scraping_balance","customer_budget_exceeded"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"429":{"description":"Monthly plan quota, per-job page limit or concurrent capacity (20 active jobs per organization) reached","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["monthly_quota_exceeded","plan_page_limit","scraping_capacity_reached"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"get":{"tags":["crawl"],"x-scope":"crawl","summary":"List crawl jobs","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Jobs and optional nextCursor","content":{"application/json":{"schema":{"type":"object","properties":{"jobs":{"type":"array","items":{"type":"object","required":["id","kind","status","url","pagesCompleted","pagesFailed","pagesQueued"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["scrape","crawl","batch","map","search","research"]},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"url":{"type":"string","format":"uri"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"expiresAt":{"type":"integer"},"pagesCompleted":{"type":"integer"},"pagesFailed":{"type":"integer"},"pagesQueued":{"type":"integer"},"maxPages":{"type":"integer"},"upstreamCostUsd":{"type":"number"},"reservedCostUsd":{"type":"number"},"uncertainCostUsd":{"type":"number"},"customerChargeUsd":{"type":"number"},"pricingVersion":{"type":"string"},"result":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"nextCursor":{"type":"string"}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/jobs":{"get":{"tags":["jobs"],"x-scope":"any","summary":"List all authorized jobs","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Jobs and optional nextCursor","content":{"application/json":{"schema":{"type":"object","properties":{"jobs":{"type":"array","items":{"type":"object","required":["id","kind","status","url","pagesCompleted","pagesFailed","pagesQueued"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["scrape","crawl","batch","map","search","research"]},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"url":{"type":"string","format":"uri"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"expiresAt":{"type":"integer"},"pagesCompleted":{"type":"integer"},"pagesFailed":{"type":"integer"},"pagesQueued":{"type":"integer"},"maxPages":{"type":"integer"},"upstreamCostUsd":{"type":"number"},"reservedCostUsd":{"type":"number"},"uncertainCostUsd":{"type":"number"},"customerChargeUsd":{"type":"number"},"pricingVersion":{"type":"string"},"result":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"nextCursor":{"type":"string"}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/jobs/{id}":{"get":{"tags":["jobs"],"x-scope":"any","summary":"Read the status and result of any job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job status and optional result","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","required":["id","kind","status","url","pagesCompleted","pagesFailed","pagesQueued"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["scrape","crawl","batch","map","search","research"]},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"url":{"type":"string","format":"uri"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"expiresAt":{"type":"integer"},"pagesCompleted":{"type":"integer"},"pagesFailed":{"type":"integer"},"pagesQueued":{"type":"integer"},"maxPages":{"type":"integer"},"upstreamCostUsd":{"type":"number"},"reservedCostUsd":{"type":"number"},"uncertainCostUsd":{"type":"number"},"customerChargeUsd":{"type":"number"},"pricingVersion":{"type":"string"},"result":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"replayed":{"type":"boolean"}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"tags":["jobs"],"x-scope":"any","summary":"Cancel any queued or running job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled job","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","required":["id","kind","status","url","pagesCompleted","pagesFailed","pagesQueued"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["scrape","crawl","batch","map","search","research"]},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"url":{"type":"string","format":"uri"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"expiresAt":{"type":"integer"},"pagesCompleted":{"type":"integer"},"pagesFailed":{"type":"integer"},"pagesQueued":{"type":"integer"},"maxPages":{"type":"integer"},"upstreamCostUsd":{"type":"number"},"reservedCostUsd":{"type":"number"},"uncertainCostUsd":{"type":"number"},"customerChargeUsd":{"type":"number"},"pricingVersion":{"type":"string"},"result":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"replayed":{"type":"boolean"}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/crawls/{id}/pages":{"get":{"tags":["crawl"],"x-scope":"crawl","summary":"Read crawled pages, a page of results at a time","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Pages and optional nextCursor","content":{"application/json":{"schema":{"type":"object","properties":{"pages":{"type":"array","items":{"type":"object","required":["id","url","depth","status"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"depth":{"type":"integer"},"status":{"type":"string"},"result":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"nextCursor":{"type":"string"}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/crawls/{id}":{"get":{"tags":["crawl"],"x-scope":"crawl","summary":"Read crawl progress, retention and cost","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Crawl status","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","required":["id","kind","status","url","pagesCompleted","pagesFailed","pagesQueued"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["scrape","crawl","batch","map","search","research"]},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"url":{"type":"string","format":"uri"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"expiresAt":{"type":"integer"},"pagesCompleted":{"type":"integer"},"pagesFailed":{"type":"integer"},"pagesQueued":{"type":"integer"},"maxPages":{"type":"integer"},"upstreamCostUsd":{"type":"number"},"reservedCostUsd":{"type":"number"},"uncertainCostUsd":{"type":"number"},"customerChargeUsd":{"type":"number"},"pricingVersion":{"type":"string"},"result":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"replayed":{"type":"boolean"}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"tags":["crawl"],"x-scope":"crawl","summary":"Cancel a crawl and keep the pages already captured","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled crawl","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","required":["id","kind","status","url","pagesCompleted","pagesFailed","pagesQueued"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["scrape","crawl","batch","map","search","research"]},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"url":{"type":"string","format":"uri"},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"expiresAt":{"type":"integer"},"pagesCompleted":{"type":"integer"},"pagesFailed":{"type":"integer"},"pagesQueued":{"type":"integer"},"maxPages":{"type":"integer"},"upstreamCostUsd":{"type":"number"},"reservedCostUsd":{"type":"number"},"uncertainCostUsd":{"type":"number"},"customerChargeUsd":{"type":"number"},"pricingVersion":{"type":"string"},"result":{"type":"object","required":["id","url","finalUrl","status","attempts","customerChargeUsd"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["success","challenge","empty","validation_failed","error"]},"httpStatus":{"type":["integer","null"]},"tierUsed":{"type":["integer","null"]},"htmlSource":{"type":["string","null"],"enum":["response","dom",null]},"title":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"object"},"structuredJson":{},"jsonLd":{"type":"array","items":{}},"screenshotBase64":{"type":"string"},"pdfBase64":{"type":"string"},"cacheHit":{"type":"boolean"},"cacheRevalidated":{"type":"boolean"},"etag":{"type":"string"},"cacheControl":{"type":"string"},"engine":{"type":"string","enum":["http","impit","lightpanda","chromium","patchright","2captcha","scrapingbee","scrappa"]},"stage":{"type":"string","enum":["http_direct","js_direct","residential","captcha","managed"]},"verification":{"type":"string","enum":["passed","not_requested","failed"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tier":{"type":"integer"},"provider":{"type":"string"},"proxy":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"engine":{"type":"string"},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string"}}}},"durationMs":{"type":"integer"},"bytes":{"type":"integer"},"links":{"type":"array","items":{"type":"string","format":"uri"}},"upstreamCostUsd":{"type":["number","null"]},"pricingStatus":{"type":"string","enum":["known","estimated","unknown"]},"customerChargeUsd":{"type":"number"},"artifacts":{"type":"object","properties":{"html":{"type":"string"},"screenshot":{"type":"string"},"pdf":{"type":"string"},"json":{"type":"string"}},"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"replayed":{"type":"boolean"}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/jobs/{id}/export":{"get":{"tags":["jobs"],"x-scope":"any","summary":"Stream every page of a job as JSON or JSON Lines","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","jsonl"]}}],"responses":{"200":{"description":"Full streamed export"},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/crawls/{id}/export":{"get":{"tags":["crawl"],"x-scope":"any","summary":"Stream every page of a crawl as JSON or JSON Lines","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","jsonl"]}}],"responses":{"200":{"description":"Full streamed crawl export"},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/usage":{"get":{"tags":["account"],"x-scope":"any","summary":"Read organization job, page and cost totals","responses":{"200":{"description":"Tenant usage","content":{"application/json":{"schema":{"type":"object","properties":{"usage":{"type":"object","properties":{"jobs":{"type":"integer"},"pages":{"type":"integer"},"upstreamCostUsd":{"type":"number"},"customerChargeUsd":{"type":"number"}}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/metrics":{"get":{"tags":["account"],"x-scope":"scrape","summary":"Read scraping metrics for the last 1–30 days","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":30}}],"responses":{"200":{"description":"Tenant scraping metrics","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/openapi":{"get":{"tags":["account"],"x-scope":"none","summary":"Read this OpenAPI document","security":[],"responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/sessions":{"get":{"tags":["scrape"],"x-scope":"scrape","summary":"List reusable browser sessions","responses":{"200":{"description":"Session metadata","content":{"application/json":{"schema":{"type":"object","properties":{"sessions":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"post":{"tags":["scrape"],"x-scope":"scrape","summary":"Create a reusable browser session (cookies kept across scrapes)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ttlMs":{"type":"integer","minimum":60000,"maximum":604800000}}}}}},"responses":{"201":{"description":"New session metadata","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"type":"object"}}}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/sessions/{id}":{"get":{"tags":["scrape"],"x-scope":"scrape","summary":"Read a browser session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Session metadata","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"type":"object"}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"delete":{"tags":["scrape"],"x-scope":"scrape","summary":"Delete a browser session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/pricing":{"get":{"tags":["billing"],"x-scope":"scrape","summary":"Current tariff and available plans","responses":{"200":{"description":"Tariff and plans","content":{"application/json":{"schema":{"type":"object","properties":{"billingEnabled":{"type":"boolean"},"billingReady":{"type":"boolean"},"pricing":{"type":"object","properties":{"version":{"type":"string"},"configured":{"type":"boolean"},"successPageFeeMicroUsd":{"type":"integer"},"upstreamMarkupBps":{"type":"integer"}}},"plans":{"type":"array","items":{"type":"object"}},"packs":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/pricing/simulate":{"post":{"tags":["billing"],"x-scope":"scrape","summary":"Simulate unit economics for a bounded sample","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"validatedSuccesses":{"type":"integer","minimum":0,"maximum":10000000},"upstreamUsd":{"type":"number","minimum":0,"maximum":1000000},"billableUpstreamUsd":{"type":"number","minimum":0,"maximum":1000000},"unknownUpstreamCharges":{"type":"integer","minimum":0,"maximum":10000000},"allocatedCoreMs":{"type":"number","minimum":0,"maximum":1000000000000000},"allocatedMemoryGiBMs":{"type":"number","minimum":0,"maximum":1000000000000000},"storedGiBDays":{"type":"number","minimum":0,"maximum":1000000000000},"nonProxyEgressBytes":{"type":"number","minimum":0,"maximum":1000000000000000000},"paymentTransactions":{"type":"integer","minimum":0,"maximum":10000000}},"required":["validatedSuccesses","upstreamUsd","billableUpstreamUsd","unknownUpstreamCharges","allocatedCoreMs","allocatedMemoryGiBMs","storedGiBDays","nonProxyEgressBytes","paymentTransactions"],"additionalProperties":false}}}},"responses":{"200":{"description":"Estimated sample economics","content":{"application/json":{"schema":{"type":"object","properties":{"simulation":{"type":"object"}}}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/billing":{"get":{"tags":["billing"],"x-scope":"scrape","summary":"Organization balance, quotas and ledger","responses":{"200":{"description":"Billing overview","content":{"application/json":{"schema":{"type":"object","properties":{"billing":{"type":"object","properties":{"billingEnabled":{"type":"boolean"},"balanceMicroUsd":{"type":"integer"},"plan":{"type":"object"},"limits":{"type":"object"},"tariff":{"type":"object"},"ledger":{"type":"array","items":{"type":"object"}}}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/checkout":{"post":{"tags":["billing"],"x-scope":"session","summary":"Start a balance top-up checkout; session owner/admin only","description":"Used by /app/billing. Packs: usd-8, usd-50, usd-200, usd-1000 (balance credited 1:1 in USD after the signed Stripe webhook).","security":[{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"packId":{"type":"string","pattern":"^[a-z0-9_-]{1,40}$"}},"required":["packId"]}}}},"responses":{"201":{"description":"Checkout session and reference","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"429":{"description":"Too many open checkouts for this organization","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["checkout_rate_limited"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/checkout/sessions/{id}":{"get":{"tags":["billing"],"x-scope":"session","summary":"Read whether a checkout session was paid and credited; session only","description":"Polled by /app/billing after the embedded Checkout returns. credited turns true only after the signed Stripe webhook credits the balance.","security":[{"sessionCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Checkout session status","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"type":"object","properties":{"status":{"type":"string"},"credited":{"type":"boolean"},"creditMicroUsd":{"type":"integer"},"packId":{"type":"string"}}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/keys":{"get":{"tags":["account"],"x-scope":"session","summary":"List scoped API keys; session only","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"Keys without secrets","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"post":{"tags":["account"],"x-scope":"session","summary":"Create a scoped key; secret returned once; session owner/admin only","security":[{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"scopes":{"minItems":1,"maxItems":4,"type":"array","items":{"type":"string","enum":["scrape","crawl","search","research"]}}},"required":["name","scopes"]}}}},"responses":{"201":{"description":"Key and one-time secret","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"object"},"secret":{"type":"string"}}}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/keys/{id}":{"delete":{"tags":["account"],"x-scope":"session","summary":"Revoke key; session owner/admin only","security":[{"sessionCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Revocation","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed or revoked credentials, or an API key without the scope this operation requires","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The session has no organization, lacks the owner/admin role this operation requires, or a session mutation came from another origin","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["organization_required","forbidden","invalid_origin"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"The feature is not configured on this deployment or a dependency is temporarily unavailable; retry later","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["scraping_disabled","auth_store_unavailable","postgres_required","worker_unavailable","billing_not_configured"]},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/webhooks/stripe":{"post":{"tags":["billing"],"x-scope":"none","summary":"Internal Stripe event receiver","description":"Stripe-Signature over the exact raw body is required. This is not a bearer-client operation.","security":[],"parameters":[{"name":"Stripe-Signature","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Event receipt","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean"},"duplicate":{"type":"boolean"},"handled":{"type":"boolean"}}}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"500":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"default":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}}}