Perception
Extract fields
- 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.
- Schema: send it inline as
schema, or save it withPOST /v1/extraction-schemasand name it withschema_id. Addschema_versionto pin one version. - Body: the document service's request for this operation. Extract lists its options and result.
source: aurl, aparse_resultof one of your own jobs, or aworkspace_fileyou uploaded. Upload one withPOST /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-Keywith the same body returns the same job. With a different body, it answers409.
Other errors (413, 500, 502, 503, 504, 529) are on Errors.
Authorization
bearerAuth Your API key, sent as Authorization: Bearer nace_sk_...
- Where: the dashboard's API Keys page. It is shown once, when you create it.
- Format:
nace_sk_followed by 43 URL-safe characters (A-Z,a-z,0-9,_and-). - Limit: an account can hold at most 3 active keys.
- Wrong or missing key: returns
401 authentication_error.
In: header
Query Parameters
Hold the request open until the job finishes, up to this many seconds. 0 (default) returns at once; a value above 60 waits 60.
0 <= valueHeader Parameters
Up to 200 characters, unique per account. Retry with the same key and body to get the same job instead of a second one.
length <= 200Request Body
application/json
Send exactly one of schema (inline) or schema_id (a saved schema). With schema_id, schema_version pins a saved version; omit it to use the latest.
Whether extracted fields include locations and quoted source text.
Show child attributes
Workspace files the run can see besides source.
items <= 50Show child attributes
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.
"complete""complete""progressive"Optional guidance for how to fill the declared schema. Cannot add undeclared result fields.
Show variants
Optional display name for the run.
Show variants
One-based inclusive page ranges to extract. Omit to use the whole document.
Show variants
How much parsing effort to use: Low uses native OCR, Medium routes to the best parser, and High adds page verification and correction.
"low""low""medium""high"Caller-minted grouping id; jobs submitted together share it. Not a server-side resource.
Show variants
Inline JSON Schema of fields to extract. Mutually exclusive with schema_id.
Show variants
Catalog schema family id (sch_...). Mutually exclusive with an inline schema.
Show variants
Pin a published catalog version. Omit with schema_id to use the latest version.
Show variants
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 Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/documents/extract" \ -H "Content-Type: application/json" \ -d '{ "source": { "type": "url", "url": "https://console.nace.ai/samples/wm-recycle-america-invoice-iac3353061-2022-08-15.pdf", "file_name": "invoice.pdf" }, "schema": { "type": "object", "properties": { "invoice_number": { "type": "string" }, "total": { "type": "number" } }, "required": [ "invoice_number", "total" ] } }'{ "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f", "kind": "parse", "status": "queued", "result": null, "credits": 0, "usage_final": true, "created_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "timing": { "received_at": "2019-08-24T14:15:22Z", "observed_at": "2019-08-24T14:15:22Z", "completed_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "total_ms": 0, "first_response_ms": 0, "breakdown": { "preparation_ms": 0, "queue_ms": 0, "ndi_processing_ms": 0, "result_preparation_ms": 0, "delivery_wait_ms": 0, "document_finalization_ms": 0 } }, "cost": { "pricing_version": "string", "total_usd": "string", "lines": [ { "operation": "parse", "quantity": 0, "unit": "page", "execution": "fresh", "unit_price_usd": "string", "amount_usd": "string", "reuse_reason": "string" } ] }}