Perception
Classify a document
- Body: the document service's request for this operation. Classify lists its options and result.
- `source`: a url, a parse_result of one of your own jobs, or a workspace_file you uploaded. Document granularity reads that Parse result. Page granularity cannot reuse a Parse, so a parse_result source with granularity page answers 422. Send the original file for page labels. Upload a file 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: for the same operation, an Idempotency-Key replays the first accepted request and its job, even if a later body differs. Use a new key for changed settings. Sending that same Idempotency-Key header on a different document operation answers 409. The Python client sends the header only through idempotency_key. extra_headers cannot set it.
- Body: the document service's request for this operation. Classify lists its options and result.
source: aurl, aparse_resultof one of your own jobs, or aworkspace_fileyou uploaded. Document granularity reads that Parse result. Page granularity cannot reuse a Parse, so aparse_resultsource withgranularitypageanswers422. Send the original file for page labels. Upload a file 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: for the same operation, an
Idempotency-Keyreplays the first accepted request and its job, even if a later body differs. Use a new key for changed settings. Sending that sameIdempotency-Keyheader on a different document operation answers409. The Python client sends the header only throughidempotency_key.extra_headerscannot set it.
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. For the same operation, reuse the key to replay the first accepted request and its job; later body changes are ignored. Use a new key for changed settings.
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 three kinds:
- A URL:
{"type":"url","url":"https://...","file_name":"a.pdf"} - A parse of one of your jobs:
{"type":"parse_result","job_id":"..."}. Document granularity reads that Parse result. Page granularity cannot reuse a Parse and answers422. Send the original file for page labels. - A workspace file:
{"type":"workspace_file","workspace_id":"...","file_id":"..."}
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
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" } ] }}