One endpoint. Clean JSON.

Extract data from public web pages using natural language or your own schema. Original values and source evidence stay together.

1. Send a request

curl https://webextract.online/api/v1/extract   -H 'Content-Type: application/json'   -H 'Idempotency-Key: YOUR_RANDOM_SECRET_UUID'   -d '{"url":"https://example.com/product","schema":{"product_name":"string","price":"number|null","currency":"string|null"},"render_javascript":"never"}'

Alternatively send instruction, for example “Extract all plans with plan name, monthly price and included storage.” A schema alongside an instruction can constrain the result while the instruction provides context or filters.

2. Pay through x402

The first request returns HTTP 402 with a base64 PAYMENT-REQUIRED header and a readable JSON body. Check the amount, network, USDC asset and recipient. An x402 v2 client signs a payment authorization, then repeats the identical body and Idempotency-Key with PAYMENT-SIGNATURE. Never share a wallet recovery phrase or private key with this service.

Use POST /api/v1/quote for a free price check. Live settlement uses Coinbase CDP and USDC on Base. The health endpoint returns 503 if required live configuration is missing. Demo explicitly simulates payments with demo:<Idempotency-Key> and accepts only the synthetic fixture URL.

3. Read the result

{
  "request_id": "uuid",
  "status": "partial",
  "source": {
    "url": "https://example.com",
    "final_url": "https://example.com",
    "retrieved_at": "2026-09-28T12:00:00Z",
    "source_language": "ja"
  },
  "data": {
    "product_name": "京都の抹茶",
    "price": null
  },
  "field_status": {
    "/product_name": "directly_observed",
    "/price": "not_found"
  },
  "validation": {
    "valid": true,
    "errors": []
  },
  "evidence": [
    {
      "field": "/product_name",
      "source_excerpt": "京都の抹茶",
      "original_value": "京都の抹茶",
      "source_type": "json_ld"
    }
  ],
  "cache_status": "fresh"
}

This is an abbreviated illustrative response. Full evidence includes source URL, original value, source language and retrieval time. Missing or ambiguous values are null. A non-nullable required field that is absent produces validation.valid=false and partial status. We do not invent data to pass a schema.

Retrieve saved results at GET /api/v1/requests/{id} with Authorization: Bearer <original Idempotency-Key>. Treat this token like a password. A 202 response indicates an already-running request; poll the Location. If a paid extraction fails, repeat the same body/key for up to two free retries. Unknown settlement must be reconciled; do not authorize a new payment.

Inputs and limits

Request body 16 KiB. Page size defaults to 2 MB. Three redirects, 12-second HTTP deadline, one semantic call per attempt. HTML, XHTML, JSON and plain text are accepted. Unsupported content, CAPTCHA, authentication and paywall restrictions return limitations/errors; they are not bypassed.

Price and retrieval behavior

Read current pricing. Price = 3 × the measured variable cost of the request shape (model use, output size via max_items or an array schema, followed pages, render_javascript=always), quoted before work and bound into the x402 challenge. Structured data, semantic markup and tables are inspected before any model call. Semantic inference is quote-anchored but is not independently verified truth; numeric confidence is null for inference.

Freshness and normalization

Every extraction records retrieved_at. There is no shared content cache. An idempotent retry returns the same result and original timestamp, marked idempotent_replay. Request a new extraction with a new key for fresh prices. Original price strings and dates remain in evidence. Ambiguous currency symbols and date formats are not silently interpreted as U.S. formats.

Errors

{"error":{"code":"unsafe_url","message":"Only public HTTP(S) URLs are accepted."}}

Validation: invalid_request, invalid_schema, invalid_json, request_too_large. Retrieval: unsafe_url, access_restricted, page_unavailable, retrieval_timeout, response_too_large, unsupported_content_type, redirect_limit. Providers: rendering_unavailable, renderer_unavailable, provider_unavailable, provider_invalid_response. Payments: invalid_payment, payment_reused, idempotency_conflict, settlement_unknown. Operations: rate_limited, not_configured. Paid failures include request_id and retryable.

Security

DNS addresses are checked and pinned at connection time. Private, loopback, link-local and reserved networks are rejected. Every redirect is checked. Browser requests use the same restricted retrieval boundary. Retrieved content is untrusted data; it cannot call tools, change payment policy or access server secrets. Quoted evidence is checked against source text before semantic values are returned.

Privacy & retention

Only request inputs, bounded results/evidence, transaction metadata and usage estimates are stored. Full pages are transient. Default result retention is seven days; expired records are pruned lazily after paid requests (there is no scheduled job). Retention always exceeds the short payment authorization window; unresolved settlements are retained for reconciliation. Idempotency keys are stored as hashes. Avoid putting personal secrets in URLs or instructions. Semantic extraction sends the bounded source representation and request to the configured provider. Provider retention terms apply independently.

Multilingual behavior

Unicode input, international domains and source text are preserved. Request language, source language and geography are independent. We do not translate names, quotes, URLs or identifiers. Semantic interpretation supports multilingual input through a replaceable provider. Real-provider acceptance covered a Russian instruction on a Japanese page; other languages are covered by fixtures, not certified per language.