Perception
Split a document
- Body: the document service's request for this operation. Split 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. Split 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
Splits a packet into documents by page range. A spreadsheet splits into one file per worksheet, and each worksheet is classified against classes.
Document classes to split the packet into; spreadsheets classify worksheets against these classes.
1 <= itemsShow child attributes
Workspace files the run can see besides source.
items <= 50Show child attributes
Optional display name for the run.
Show variants
Whether segments include markdown content and/or materialized file URLs.
Show child attributes
Whether a boundary page may belong to two adjacent segments or only one.
"exclusive""exclusive""shared_boundary_page"One-based inclusive page ranges to consider. 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
Latency versus accuracy preference for this run. Only auto is accepted today.
"auto""auto""fast""accurate"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":"..."}
Optional free-text guidance for how to cut the packet (for example, split on cover sheets).
Show variants
What to do with pages that match no class. include keeps them as unclassified; force assigns the best class; error fails the job.
"include""include""force""error"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/documents/split" \ -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" }, "classes": [ { "id": "invoice", "label": "Invoice", "description": "A supplier invoice" }, { "id": "receipt", "label": "Receipt", "description": "A payment receipt" } ] }'{ "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" } ] }}