{"openapi":"3.1.0","info":{"title":"Web Extract","version":"1.0.0","description":"URL + instruction/schema → structured data with source evidence. x402 v2 USDC; strict SSRF checks; no authenticated scraping."},"servers":[{"url":"https://webextract.online"}],"paths":{"/api/v1/extract":{"post":{"operationId":"extract","summary":"Quote or execute one bounded extraction","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"}},{"name":"PAYMENT-SIGNATURE","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractInput"}}}},"responses":{"200":{"description":"Completed or partial result. Check validation.valid and field_status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractResult"}}}},"202":{"description":"Concurrent request is processing; poll Location with bearer token."},"400":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"x402 v2 payment required; PAYMENT-REQUIRED is base64 encoded. Body includes accepts, mode, price {amount, tier, output_class, pages, rendering_reserved} and policy. Price = 3 × measured variable cost of the request's cost drivers."},"409":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/quote":{"post":{"operationId":"quote","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractInput"}}}},"responses":{"200":{"description":"Free, database-free price quote: amount (USDC), tier, output_class, pages, rendering_reserved and the x402 payment requirement."},"400":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/requests/{id}":{"get":{"operationId":"retrieve","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"resultToken":[]}],"responses":{"200":{"description":"Original result with original retrieval timestamp"},"202":{"description":"Processing"},"401":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/health":{"get":{"operationId":"health","description":"Configuration/liveness only; never touches the database. Add ?ready=1 for a cached database readiness check.","parameters":[{"in":"query","name":"ready","required":false,"schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Ready"},"503":{"description":"Not ready; no new payment accepted"}}}},"/api/v1/capabilities":{"get":{"operationId":"capabilities","responses":{"200":{"description":"Modes, pricing, rendering availability and limits"}}}}},"components":{"securitySchemes":{"resultToken":{"type":"http","scheme":"bearer","description":"Original secret Idempotency-Key"}},"schemas":{"ExtractInput":{"type":"object","additionalProperties":false,"required":["url"],"anyOf":[{"required":["instruction"]},{"required":["schema"]}],"properties":{"url":{"type":"string","format":"uri","maxLength":2048},"instruction":{"type":"string","minLength":1,"maxLength":2000},"schema":{"type":"object","description":"Shorthand field:type map, or bounded JSON Schema. Supports type/properties/items/required/enum/additionalProperties/description. No $ref, regex or remote schemas."},"render_javascript":{"oneOf":[{"type":"boolean"},{"type":"string","enum":["auto","never","always"]}],"default":"auto"},"preferred_output_language":{"type":"string","maxLength":64},"max_items":{"type":"integer","minimum":1,"maximum":50,"default":20},"follow_links":{"type":"integer","minimum":0,"maximum":2,"default":0},"allowed_paths":{"type":"array","maxItems":10,"items":{"type":"string","pattern":"^/"}},"strategy":{"type":"string","enum":["auto","deterministic"],"default":"auto"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"ExtractResult":{"type":"object","required":["request_id","status","source","data","evidence","validation","field_status","confidence","limitations","cache_status","freshness","payment","usage"],"properties":{"request_id":{"type":"string","format":"uuid"},"status":{"enum":["completed","partial"]},"source":{"type":"object","required":["url","final_url","retrieved_at"],"properties":{"url":{"type":"string"},"final_url":{"type":"string"},"retrieved_at":{"type":"string","format":"date-time"},"source_language":{"type":["string","null"]}}},"data":{},"evidence":{"type":"array","items":{"type":"object","required":["field","value","original_value","source_url","source_type","source_excerpt","retrieved_at","source_language","observation"],"properties":{"field":{"type":"string"},"value":{},"original_value":{},"source_url":{"type":"string"},"source_type":{"type":"string"},"source_excerpt":{"type":"string"},"retrieved_at":{"type":"string","format":"date-time"},"source_language":{"type":["string","null"]},"observation":{"enum":["directly_observed","strongly_inferred","ambiguous","not_found"]}}}},"validation":{"type":"object","properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"object"}}}},"field_status":{"type":"object","additionalProperties":{"type":"string"}},"confidence":{"type":"object","additionalProperties":{"type":["number","null"]}},"limitations":{"type":"array","items":{"type":"string"}},"cache_status":{"enum":["fresh","idempotent_replay"]},"freshness":{"type":"object","properties":{"retrieved_at":{"type":"string","format":"date-time"},"age_seconds":{"type":"integer"},"cache_status":{"enum":["fresh","idempotent_replay"]},"note":{"type":"string"}}},"payment":{"type":"object","properties":{"amount":{"type":"string"},"currency":{"const":"USDC"},"network":{"type":"string"},"transaction":{"type":["string","null"]}}},"usage":{"type":"object","description":"Operational usage: retrieval_mode, pages_fetched, bytes_fetched, links_followed, items_extracted, model_calls, browser_calls, input_tokens, output_tokens, duration_ms, price_usdc."}}}}}}