Perception
Parse a document
- Body: the document service's request for this operation. Parse 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.
- Body: the document service's request for this operation. Parse 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.
Delivery remains job-based, with wait_seconds=0 by default. Optional retained-job page previews are available through /v1/documents/jobs/{id}/parse-progress/events; no stream request flag is needed.
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
page_ranges selects pages: one-based and inclusive.
password unlocks a protected file. It is write-only and never returned in any response.
Optional RAG chunking of the parsed document.
Show child attributes
Workspace files the run can see besides source.
items <= 50Show child attributes
Whether diagram-like figures are rewritten as Mermaid.
Show child attributes
How figure regions are kept or captioned.
Show child attributes
Optional display name for the run.
Show variants
Which text renderings, table style, images, and OCR geometry to return.
Show child attributes
One-based inclusive page ranges to process. 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"Deprecated parse implementation override. Prefer parse_mode. Omit or null for native; 'datalab' and 'nace_router' remain accepted for compatibility.
Show variants
Optional PDF password. Never stored in the job payload or returned in any response.
Show variants
Caller-minted grouping id; jobs submitted together share it. Not a server-side resource.
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":"..."}
Workbook-only filters for sheets, hidden cells, and formulas.
Show child attributes
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/documents/parse" \ -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" }, "output": { "formats": [ "markdown", "blocks" ] } }'{ "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" } ] }}