Do I have to fetch a live URL?
No. Send html with the document inline and skip the network entirely. Use url only when you want the service to fetch a public page. Exactly one of url or html is required.
Structured Extraction API
CSS selectors
HTML or URL
SSRF-safe
Point selectors. Get the fields.
Turn a page into named JSON fields. Send inline HTML or a public URL, map CSS selectors, and receive first-match values with timing metadata.
1-25 · fieldsHTML · 1 MB inlineURL · 2 MB fetchNull · unmatched
Pull fields from a snippet.
This demo posts a tiny canned HTML document with title and heading selectors. Production also accepts a public URL behind SSRF guards.
Request builder
Inline HTML in, named fields out. Click to run.
POST /extract
Canned HTML
<html><head><title>Widget Store</title></head><body><h1>Amazing Widget</h1><p class="lead">In stock today</p></body></html>
selectors: title → title, heading → h1
Output preview
Live response from the API, plus the exact request to reproduce it.
Run the request to extract title and heading.
Why Structured Extraction API
Fields, not full scrapes.
Named JSON fields
Map output keys to CSS selectors and get a clean object back, not a full page dump.
Inline HTML preferred
Skip the network: post HTML up to 1 MB when you already have the document.
URL fetch when needed
Static HTTP fetch with a 2 MB cap, HTTPS in production, and a 1-hour cache per URL.
Attribute fallbacks
If an element has no text, the extractor tries content, href, value, src, then title.
SSRF-safe destinations
Private and reserved hosts are blocked with machine-readable reasons, not silent failures.
Timing on every response
metadata.timingMs and fromCache tell you whether you hit cache or paid for a fetch.
/api/v1/structured-extraction
Endpoints, at a glance.
One POST contract: send HTML or a URL, name the fields, get first-match values plus timing metadata.
POST/api/v1/structured-extraction/extract
Extract fields
Exactly one of html or url, plus a selectors map of 1 to 25 CSS selectors.
| Parameter | Type | Required | Description |
|---|---|---|---|
| html | string | one of | Raw inline HTML, max 1 MB. Mutually exclusive with url. |
| url | string | one of | Public http/https URL, SSRF-guarded, max 2 MB response. |
| selectors | object | yes | 1 to 25 entries mapping output field names to CSS selectors. |
Error reference
Failures you can plan for.
Unmatched selectors are null, not errors. SSRF and fetch failures include a machine-readable reason.
400Validation Error
Missing selectors, or both/neither of url and html.
401Authentication Error
Missing or invalid gateway API key. Send x-api-key or api_key with every request.
403SSRF Blocked
URL destination failed SSRF policy. Reasons include blocked-hostname.
413Response Too Large
Upstream HTML exceeds 2 MB (reason response-too-large).
429Rate Limit Error
More than 30 requests in a 15-minute window.
502Fetch Error
URL fetch failed or the upstream returned an error status.
Example error response
{
"success": false,
"error": { "code": "VALIDATION_ERROR", "message": "Invalid input parameters" },
"correlationId": "req_abc123"
}FAQ
API questions developers ask first.
What happens if a selector does not match?
That field is returned as null. The rest of the extraction still succeeds, so missing optional fields do not fail the request.
How many fields can I extract?
The selectors map accepts 1 to 25 entries. Each key is the output field name and each value is a CSS selector. The first matching element wins.
Is URL fetching protected against SSRF?
Yes. Private and reserved destinations are blocked with machine-readable reasons such as blocked-hostname. Production URL fetches require HTTPS.
How do I authenticate requests?
Send your Datpaq API key as an x-api-key header or an api_key query parameter. Keys are created in the Datpaq dashboard and a free tier is included.
Extract the fields you actually need.
Point CSS selectors at HTML or a public URL and get a clean key/value object, with SSRF-safe fetching.