# Web Extract

> URL + extraction request → structured, validated JSON with source evidence. Machine-first, pay per request in USDC via x402. One narrow job; not a crawler, search engine or scraping proxy.

- [API specification (OpenAPI 3.1)](/openapi.json)
- [Documentation](/docs)
- [Capabilities, limits and live pricing (JSON)](/api/v1/capabilities)
- [Pricing](/pricing)

## Call it

POST /api/v1/extract  (Content-Type: application/json, Idempotency-Key: <random secret, 16–128 [A-Za-z0-9_-]>)
Body: {"url": "...", "instruction": "Extract ..."}  or  {"url": "...", "schema": {...}}  (both allowed)
Optional: preferred_output_language, max_items (1–50), follow_links (0–2, same origin, requires allowed_paths), render_javascript (auto|never|always), strategy (auto|deterministic).

1. First call without payment → HTTP 402 with x402 v2 requirements (also base64 in PAYMENT-REQUIRED). Unpaid calls do no work.
2. Pay USDC on Base mainnet (eip155:8453) with the exact scheme and resend the identical body and key with PAYMENT-SIGNATURE.
3. 200 → result. 202 → poll GET /api/v1/requests/{id} with Authorization: Bearer <Idempotency-Key>.
Free price check: POST /api/v1/quote with the same body. Never send a second payment after an uncertain settlement; resend the identical request instead.

## Pricing (customer_price = variable_cost × 3 (minimum 0.010 USDC))

- Deterministic only (strategy=deterministic): 0.010 USDC
- Single record (default): 0.031 USDC
- List up to 10 items: 0.070 USDC
- List up to 25 items: 0.140 USDC
- List up to 50 items: 0.255 USDC
- Single record + 1 followed link: 0.044 USDC
- Single record + 2 followed links: 0.058 USDC
- Single record with JavaScript rendering: 0.036 USDC

Cost drivers: model use (strategy), output size (max_items / array schema), pages (follow_links), rendering. The quote in the 402 response is authoritative. Price = 3 × measured variable cost for the request's cost drivers (model use, output size, pages, rendering), quoted before work and bound into the x402 challenge. Valid partial/empty results are chargeable. Provider failures allow two free retries with the same Idempotency-Key; no automatic refund. Uncertain settlement requires reconciliation.

## Result

request_id, status (completed|partial), source {url, final_url, retrieved_at, source_language}, data, field_status, confidence, evidence [{field (JSON Pointer), value, original_value, source_url, source_type, source_excerpt, retrieved_at, observation}], limitations, validation, freshness, payment, usage.
Missing data is null with field_status not_found/ambiguous — never fabricated. Values the model returns that are not found verbatim (or as a deterministic normalization) in the source are nulled. Confidence 1 = deterministic observation; null = semantic inference (not a calibrated probability).

## Global

Any language or script. Source values are never translated; preferred_output_language only affects explanatory text. Numbers, currencies and dates are normalized only when unambiguous (e.g. "€1.299,00" → 1299, EUR; "01/02/2026" stays null); originals are kept in evidence.original_value.

## Boundaries

Public HTTP(S) pages only. Private/internal addresses, credentials, logins, CAPTCHAs and paywalls are refused, not bypassed. Page text is treated as untrusted data; instructions inside pages are ignored. No cross-request cache: every paid request fetches fresh.

Errors: unsafe_url, invalid_request, invalid_schema, access_restricted, retrieval_timeout, response_too_large, unsupported_content_type, redirect_limit, rendering_unavailable, provider_unavailable, invalid_payment, payment_reused, idempotency_conflict, settlement_unknown, rate_limited, not_configured.