NAnace
Documents

Extract fields

Extracts structured fields from a document with a JSON schema.

  • Schema: send it inline as schema, or save it with POST /v1/extraction-schemas and name it with schema_id. Add schema_version to pin one version.
  • Body: the document service's request for this operation. Extract lists its options and result.
  • source: a url, a parse_result of one of your own jobs, or a workspace_file you uploaded. Upload one with POST /v1/documents/upload-grants.
  • Billing: admitted only with reserved free/prepaid credit or explicitly enabled pay-as-you-go. Execution stops at its funded limit. Final credits are charged once after successful completion. A job that fails or is cancelled before completion is not charged.
  • Retries: the same Idempotency-Key with the same body returns the same job. With a different body, it answers 409.
post/v1/documents/extract

Request

Query parameters

wait_secondsinteger

Hold the request open until the job finishes, up to this many seconds. 0 (default) returns at once; a value above 60 waits 60.

Headers

Idempotency-Keystring

Up to 200 characters, unique per account. Retry with the same key and body to get the same job instead of a second one.

Request body

delivery'complete' | 'progressive'

Progressive publishes extracted values on the running job before citation enrichment finishes. Poll GET /v1/jobs/{job_id} for the completed result; complete waits for all enrichment. Parquet currently returns only a complete result in either mode.

instructionsstring nullable

Optional guidance for how to fill the declared schema. Cannot add undeclared result fields.

namestring nullable

Optional display name for the run.

parse_mode'low' | 'medium' | 'high'

How much parsing effort to use: Low uses native OCR, Medium routes to the best parser, and High adds page verification and correction.

project_idstring uuid nullable

Caller-minted grouping id; jobs submitted together share it. Not a server-side resource.

schemaobject nullable

Inline JSON Schema of fields to extract. Mutually exclusive with schema_id.

schema_idstring nullable

Catalog schema family id (sch_...). Mutually exclusive with an inline schema.

schema_versioninteger nullable

Pin a published catalog version. Omit with schema_id to use the latest version.

sourceobject required

One of three kinds:

  • A URL: {"type":"url","url":"https://...","file_name":"a.pdf"}
  • A parse of one of your jobs: {"type":"parse_result","job_id":"..."}
  • A workspace file: {"type":"workspace_file","workspace_id":"...","file_id":"..."}

Response

The job finished within wait_seconds, or this is a replay of its Idempotency-Key.

job_idstring uuid required
kind'parse' | 'split' | 'classify' | 'extract' | 'ground' required
status'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' required
resultunknown
creditsinteger nullable

Credits the job used; final once usage_final is true. Drex charges the job's final billable usage once, at the USD price pinned when it was admitted (see Models & pricing). credits is the document service's usage count, not a multiplier for the per-page or per-target price. A failed job is never charged, including when it produced partial results. A job cancelled before completion is not charged, including delivered parts.

usage_finalboolean

Changes

No recorded changes to this operation across all 1 revision of this API.