---
title: "Extract structured JSON with an LLM"
method: POST
path: "/extract"
tags: ["AI"]
---

# Extract structured JSON with an LLM

`POST /extract`

## Request

- Base URL: `https://api.domscout.io`
- URL: `https://api.domscout.io/extract`
- Auth: API key in header `x-api-key`

Accepts a URL, HTML, or text content plus a prompt and JSON Schema. The configured LLM provider must return JSON that passes the schema validator. When the first valid JSON object fails that schema, the service may make one corrective provider call inside the same request deadline; a second mismatch remains AI_SCHEMA_VALIDATION_FAILED. Requires Pro or higher. Intelligence work has one 18-second synchronous deadline across the complete request.

## Request body

- union
  - object
    - `url` string, uri, required
    - `content` string
    - `html` string
    - `prompt` string, required
    - `schema` object, required: A JSON Schema object describing the expected output. domscout enforces a declared SUBSET of JSON Schema: type, enum, const, properties, required, additionalProperties, minProperties, maxProperties, items, minItems, maxItems, uniqueItems, minLength, maxLength, pattern, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, anyOf, oneOf. The annotations title, description, default, examples, $comment and $schema are accepted and carry no constraint. Any other keyword — including format, $ref, allOf, not and patternProperties — is rejected with a 400 rather than accepted and ignored, so a 200 means every constraint supplied was checked. Maximum nesting depth is 12. A `pattern` is a caller-supplied regular expression run against model output and is refused at 400 if it exceeds 512 characters or its structure permits catastrophic backtracking.
    - `model` string: Optional. When present it must equal the model this deployment is configured to run (the value echoed as `model` in a successful response); any other value is refused with 400 VALIDATION_FAILED before a provider is called. The route's credit price does not depend on the model, so the model is the deployment's choice, not the caller's.
  - object
    - `url` string, uri
    - `content` string, required
    - `html` string
    - `prompt` string, required
    - `schema` object, required: A JSON Schema object describing the expected output. domscout enforces a declared SUBSET of JSON Schema: type, enum, const, properties, required, additionalProperties, minProperties, maxProperties, items, minItems, maxItems, uniqueItems, minLength, maxLength, pattern, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, anyOf, oneOf. The annotations title, description, default, examples, $comment and $schema are accepted and carry no constraint. Any other keyword — including format, $ref, allOf, not and patternProperties — is rejected with a 400 rather than accepted and ignored, so a 200 means every constraint supplied was checked. Maximum nesting depth is 12. A `pattern` is a caller-supplied regular expression run against model output and is refused at 400 if it exceeds 512 characters or its structure permits catastrophic backtracking.
    - `model` string: Optional. When present it must equal the model this deployment is configured to run (the value echoed as `model` in a successful response); any other value is refused with 400 VALIDATION_FAILED before a provider is called. The route's credit price does not depend on the model, so the model is the deployment's choice, not the caller's.
  - object
    - `url` string, uri
    - `content` string
    - `html` string, required
    - `prompt` string, required
    - `schema` object, required: A JSON Schema object describing the expected output. domscout enforces a declared SUBSET of JSON Schema: type, enum, const, properties, required, additionalProperties, minProperties, maxProperties, items, minItems, maxItems, uniqueItems, minLength, maxLength, pattern, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, anyOf, oneOf. The annotations title, description, default, examples, $comment and $schema are accepted and carry no constraint. Any other keyword — including format, $ref, allOf, not and patternProperties — is rejected with a 400 rather than accepted and ignored, so a 200 means every constraint supplied was checked. Maximum nesting depth is 12. A `pattern` is a caller-supplied regular expression run against model output and is refused at 400 if it exceeds 512 characters or its structure permits catastrophic backtracking.
    - `model` string: Optional. When present it must equal the model this deployment is configured to run (the value echoed as `model` in a successful response); any other value is refused with 400 VALIDATION_FAILED before a provider is called. The route's credit price does not depend on the model, so the model is the deployment's choice, not the caller's.

## Response `200`

Validated structured extraction.

- ExtractResponse
  - `status` 'success'
  - `data` object
  - `source` object
    - `url` string, nullable
    - `characters` integer
  - `model` string
  - `usage` object, nullable
  - `billing` BillingInfo
    - `credits` integer
    - `chargedTo` string, nullable
    - `remaining` integer, nullable
    - `quotaRemaining` integer, nullable
  - `metadata` object: Present only when the request needs something reported back. Currently carries ignoredFields.
    - `ignoredFields` string[]: Top-level request fields this route does not understand. They were ignored, not rejected — existing requests stay valid — but an ignored field changes the answer without changing the price, so it is named here. A misspelling such as maxChunk for maxChunks appears in this array. At most 20 are listed.

## Other responses

- `400`: The request failed validation.
- `403`: The request was refused. Returned when the x-api-key header is missing, revoked, or invalid, and when a valid key is blocked by a plan entitlement, the trusted-JavaScript account entitlement, a global product pause, or a security policy. A plan-only restriction returns code PLAN_FEATURE_UNAVAILABLE and can include upgrade_url. FEATURE_NOT_ENABLED identifies either the global product emergency pause or an eligible Business account without trusted-JavaScript permission; it carries no upgrade_url, so upgrading or retrying cannot clear it. Browser capture can return BROWSER_ISOLATION_REQUIRED or BROWSER_EXECUTION_DENIED with reason public_capture_not_enabled when browser work is unavailable for your account. These platform restrictions carry no upgrade_url and are not resolved by changing plan or key. Check GET /credits for current account capabilities. The API does not use 401: it authenticates with an API key header rather than an HTTP authentication scheme, so there is no WWW-Authenticate challenge to issue.
- `429`: The plan quota or rate limit has been reached.
- `502`: An unexpected service error occurred.
- `503`: A required intelligence provider is unavailable or misconfigured. This response can also have code `INTELLIGENCE_FINALIZATION_UNCERTAIN`: in that case no result is returned, but the work may have completed, so do not automatically retry. Retain `requestId` and contact support so the outcome can be investigated; any pending usage record is reconciled separately.
- `504`: The shared 18-second synchronous intelligence-work deadline expired. In that case the response code is `INTELLIGENCE_DEADLINE_EXCEEDED`. For a URL-based /extract request, retry with a bounded content or HTML excerpt from the page rather than asking the service to fetch it again; that advice is what the response carries, and when fetching the page alone exhausted the budget the message says so, because no model call was attempted. Other intelligence routes should retry with a smaller input or fewer pages. A provider that reaches its own shorter timeout first retains its provider-specific timeout code.

---

[API](https://skmtc.dev/domscout/apis/domscout-api.md) · [All operations](https://skmtc.dev/domscout/apis/domscout-api/llms.txt) · [OpenAPI document](https://skmtc.dev/domscout/apis/domscout-api/revisions/20562d5b5d94?raw)