---
title: "ADE Extract"
method: POST
path: "/v2/extract"
tags: ["Extract"]
---

# ADE Extract

`POST /v2/extract`

Extract structured data from a Markdown document according to a JSON schema, with character-span grounding into the source Markdown. Runs synchronously and returns the result inline.

## Request body

- object — Input to V2ExtractOperationWorkflow. Provide the markdown as an inline ``markdown`` string, as a multipart file part named ``markdown`` (for large inputs — the gateway stages the upload internally), or via a public ``markdown_url``. Exactly one source must be supplied.
  - `schema` object, required — JSON Schema describing the fields to extract. The schema must be an object type with a ``properties`` map of field names to their types and descriptions.
  - `markdown` string, nullable — Markdown string to extract from, or a multipart FILE part carrying the markdown (large inputs — uploads are staged by the gateway). Can come from any source — LandingAI parse output, a third-party parser, or hand-authored text. When the markdown was produced by ``POST /v2/parse``, it ends with a ``<!-- doc_id=<id> -->`` comment that the service reads automatically and echoes as ``metadata.doc_id``.
  - `markdown_url` string, nullable — URL to fetch the markdown from. Must be a public http(s) URL; private/loopback IPs are rejected at submit time.
  - `model` string, nullable — The version of the model to use for extraction. Use ``extract-latest`` to use the latest version.
  - `options` V2ExtractOptions — Extraction options (``docs/extract-v2-proposal.md`` → Options).
    - `strict` boolean — When ``true``, a schema containing fields the model cannot extract fails with a validation error — HTTP 422 on the sync route, or a failed job (``status: "failed"``) on the async ``/jobs`` route. When ``false`` (default), unsupported fields are skipped and extraction continues.

## Response `200`

v2-extract result

- object — Result returned by V2ExtractOperationWorkflow — the ``/v2/extract`` response body (``docs/extract-v2-proposal.md`` → Response). ``extraction`` and ``extraction_metadata`` mirror each other structurally: leaf values in ``extraction`` are replaced by ``ExtractionFieldMetadata`` objects in ``extraction_metadata``.
  - `extraction` object, required — Extracted values conforming to the request ``schema``.
  - `extraction_metadata` object, required — Per-field metadata, mirroring ``extraction`` with leaf values replaced by ``{value, ranges}`` objects.
  - `markdown` string, required — Echoed input markdown.
  - `metadata` V2ExtractMetadata, required — Response metadata for a v2 extract call.
    - `job_id` string, required — Gateway job id (workflow id). Matches the ``x-request-id`` the gateway minted for this request and the billing row id in vision-agent.
    - `model_version` string, required — Resolved model version.
    - `duration_ms` integer, required — End-to-end request duration in milliseconds.
    - `doc_id` string, nullable — Present when the input markdown contained a ``<!-- doc_id=<id> -->`` comment (embedded by ``POST /v2/parse``). Links this extract call to the originating parse job.
    - `range_units` 'unicode_codepoints', required — Units of every `range` offset in the response. Always `"unicode_codepoints"` (Unicode code points into `markdown`). Declared explicitly so consumers know how to slice the string — e.g. JavaScript strings are UTF-16, so a naive `.slice()` drifts when the markdown contains astral characters.
    - `input_markdown_chars` integer, nullable — Characters (Unicode code points) in the input markdown as submitted — the input basis of the credit charge.
    - `output_extraction_chars` integer, nullable — Characters in the serialized extraction output — the output basis of the credit charge.
    - `openapi_spec` string, required — URL of the OpenAPI spec covering this API, for inspection and client generation.
    - `billing` V2Billing — Billing summary: the service tier the request ran in and the credits charged.
      - `service_tier` 'standard' | 'priority', nullable — The service tier the request ran in: `standard` or `priority`. A sync request reports `priority` (same lane, same price).
      - `total_credits` number, nullable — Credits charged for this request.
  - `schema_violation_error` string, nullable — Set when ``options.strict`` is false and the schema contained fields the model could not extract — the extraction is partial.
  - `warnings` object[] — Non-fatal warnings emitted during extraction.

## Other responses

- `422` — Request validation failed.

---

[API](https://skmtc.net/landing-ai/apis/landingai-agentic-document-extraction-ade-api-v2-parse-and-e.md) · [All operations](https://skmtc.net/landing-ai/apis/landingai-agentic-document-extraction-ade-api-v2-parse-and-e/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/landing-ai/landingai-agentic-document-extraction-ade-api-v2-parse-and-e/revisions/b07477df91eb/schema)