Perception
Extract
client.documents.extract(params, options?) fills a JSON Schema from a document. params is an ExtractParams: the shared parameters, and either an inline schema or a saved schema_id, never both.
| Parameter | Type | Required | Description |
|---|---|---|---|
schema | Record<string, unknown> | Yes, or schema_id | The fields to extract, as a JSON Schema. |
schema_id | string | Yes, or schema | A saved schema's id (sch_...). |
schema_version | number | No | The saved version to use, with schema_id only. Default: the latest. |
instructions | string | No | Extra guidance for filling the declared fields. Can't add fields the schema doesn't list. |
page_ranges | Array<{ start, end }> | No | Pages to read. Not with a parse_result source. Default: all pages. |
citations | { enabled?, include_source_text? } | No | Where each field was read from. See citations. |
parse_mode | "low" | "medium" | "high" | No | How hard the parse behind the extraction works. Only low with a parse_result source. Default: "low". |
Both schema and schema_id, neither of them, or a schema_version without schema_id fail to compile, and throw a NaceError before sending if the types are bypassed.
citations
| Key | Type | Default | Description |
|---|---|---|---|
citations.enabled | boolean | true | Say where in the document each field was read. |
citations.include_source_text | boolean | true | Add a short quote from the source. |
const parsed = await client.jobs.wait(
(await client.documents.parse({ source: "https://example.com/invoice.pdf" })).job_id,
);
const job = await client.documents.extract({
source: { type: "parse_result", job_id: parsed.job_id },
schema: {
type: "object",
properties: { invoice_number: { type: "string" }, total: { type: "number" } },
required: ["invoice_number", "total"],
},
});
const done = await client.jobs.wait(job.job_id);
console.log((done.result as { data: unknown }).data); // { invoice_number: 'INV-1042', total: 1200.5 }See Extract for the result: data, shaped by your schema, and fields, one entry per schema field with its path, value, status (found, not_found or ambiguous), confidence and citations.