---
title: "Extract structured data from a document"
method: POST
path: "/v1/extract"
tags: ["Extract"]
---

# Extract structured data from a document

`POST /v1/extract`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/extract`
- Auth: HTTP bearer

Upload a file, provide a URL, or reference an existing document to extract
structured data. The response is synchronous for small documents (<=5 pages)
and asynchronous for larger ones, unless overridden via the `options` field.

Provide exactly one document source: `file`, `file_url`, or `document_id`.

Optionally supply a schema (inline JSON or `schema_id`) and/or free-text
`instructions` to guide extraction.

## Headers

- `Idempotency-Key` string

## Response `200`

Synchronous extraction completed.

- ExtractSyncResponse
  - `extraction_id` string, uuid, required
  - `request_id` string, required
  - `status` 'complete', required
  - `document` ExtractDocumentSummary, required
    - `id` string, uuid
    - `filename` string
    - `pages` integer
    - `size_bytes` integer
    - `type_detected` string, nullable: AI-inferred document type.
    - `language_detected` string, nullable
  - `data` object, required: Extracted key-value pairs.
  - `schema` object
    - `source` string: Where the schema came from (e.g. `inline`, `saved`, `auto`).
    - `id` string, uuid, nullable
    - `definition` object
    - `save_url` string, uri: URL to save the auto-generated schema in the dashboard.
  - `confidence` object
    - `overall` number, float: Average confidence across all fields.
    - `fields` object: Per-field confidence scores.
  - `processing` object
    - `duration_ms` integer: Total processing time in milliseconds.
    - `pages_processed` integer
    - `region` string
  - `links` object
    - `self` string
    - `document` string
    - `dashboard` string, uri

## Other responses

- `202`: Async extraction accepted. Poll the returned job URL for progress.
- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `402`: Insufficient credits (402). The body is the agent-actionable contract: `buy_credits_url` is where a human completes a purchase (see also `GET /v1/billing/upgrade-link` for a direct Stripe Checkout link), and `pricing_url` is the machine-readable rate catalog. Free workspaces receive 5,000 credits monthly; purchased credits top up the same balance.
- `403`: The API key does not have the required scope.
- `413`: The uploaded file exceeds the size limit.
- `422`: The document could not be processed.
- `429`: Daily rate limit exceeded.

---

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