Perception
Classify a document
- Body: the document service's request for this operation. Classify lists its options and result.
- `source`: a url, or a workspace_file you uploaded. Classify reads the original file, so a parse_result source answers 422. 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. Classify lists its options and result.
source: aurl, or aworkspace_fileyou uploaded. Classify reads the original file, so aparse_resultsource answers422. 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
Classifies one document against the classes you supply.
Caller-defined classes to score the document against.
1 <= itemsShow child attributes
Caller-supplied context about the document, such as the audited entity's name.
Show variants
Workspace files the run can see besides source.
items <= 50Show child attributes
Score the whole document once, or return one unit per selected page.
"document""document""page"Optional display name for the run.
Show variants
How many alternative labels to keep and whether to include reasons.
Show child attributes
One-based inclusive page ranges to classify. Omit to use the whole document. A spreadsheet source (xlsx, xlsm, xls, csv or parquet) is refused with 422 invalid_request whose detail is {"field": "page_ranges", "reason": "spreadsheet_source", "file_type": "spreadsheet"}; leave page_ranges out to classify a workbook.
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
One of two kinds:
- A URL:
{"type":"url","url":"https://...","file_name":"a.pdf"} - A workspace file:
{"type":"workspace_file","workspace_id":"...","file_id":"..."}
Classify reads the original file, so it doesn't take a parse_result source (422).
allow may mark a unit unknown. force_best commits an ambiguous unit to one of your classes instead of abstaining. A blank or unreadable page the model sees is assigned the closest listed class — the closed decode vocabulary has no page-state tokens. A unit that could not be parsed is still returned unknown. Pages never read by any model because of document size are also returned unknown and disclosed as classification_unread_pages.
"allow""allow""force_best"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/documents/classify" \ -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": "contract", "label": "Contract", "description": "A signed agreement between two parties" } ] }'{ "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" } ] }}