POST/api/v1/extract

Extract

Extract structured data from raw HTML you already have. Same pipeline as /api/v1/scrape minus the fetch step. An API key is required — there is no keyless sample path here, and the key is checked before the request body is parsed.

Parameters

Parameter	Type	Required	Description
html	string	Required	The raw HTML to extract from. Max 5 MB.
url	string	Optional	Source URL, used as context and to resolve relative links. Not fetched.
extract	string	Optional	Natural language description of what to extract. Max 4,000 characters.
schema	object	Optional	JSON Schema subset to enforce the output shape. Same rules as /api/v1/scrape. Max 10 KB.
format	string	Optional	`json` (default), `markdown`, or `both`.

Request Example

curl

curl -X POST https://contrie.com/api/v1/extract \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ck_live_your_key_here" \
  -d '{
    "html": "<html><body><h1>Hello World</h1><p>Price: $29.99</p></body></html>",
    "extract": "Get the heading and price",
    "url": "https://example.com/product"
  }'

Response

Same response shape as /api/v1/scrape, including the full metadata object and trace array — there is no fetch stage, so the trace starts at heuristic.

200 OK

{
  "success": true,
  "data": {
    "heading": "Hello World",
    "price": "$29.99"
  },
  "metadata": {
    "extractionMethod": "ai",
    "model": "minimax/minimax-m3:free",
    "qualityScore": 95,
    "grounding": 1,
    "escalations": 0,
    "latencyMs": 1820,
    "costUsd": 0,
    "trace": [
      { "stage": "heuristic", "detail": "no structured data found" },
      { "stage": "markdown", "detail": "page reduced to 0.2KB markdown" },
      { "stage": "classify", "detail": "simple" },
      { "stage": "route", "detail": "hedged", "tier": "free" },
      { "stage": "extract", "model": "minimax/minimax-m3:free", "detail": "180 in / 24 out", "ms": 1120 },
      { "stage": "validate", "detail": "quality 95, grounding 1", "quality": 95 }
    ],
    "cached": false,
    "credits": 1
  }
}

Streaming

Same as /api/v1/scrape: send Accept: application/x-ndjson for a line per pipeline stage. See Streaming.

When to Use Extract vs Scrape

Use Case	Endpoint
You have a URL and want data from it	/api/v1/scrape
You already fetched the HTML yourself	/api/v1/extract
You need custom fetch headers or auth cookies	/api/v1/extract
The page is a JavaScript-only shell (server HTML has no content)	Render it yourself, then /api/v1/extract
You want a single endpoint that handles everything	/api/v1/scrape

/api/v1/scrape does not run a browser, so a JavaScript-only page returns RENDER_REQUIRED (see Error Codes) — render it yourself and send the HTML here instead.