NAnace
Documents

Classify a document

Classifies a document, or each page, into your classes.

  • 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.
post/v1/documents/classify

Request

Query parameters

wait_secondsinteger

Hold the request open until the job finishes, up to this many seconds. 0 (default) returns at once; a value above 60 waits 60.

Headers

Idempotency-Keystring

Up to 200 characters, unique per account. Retry with the same key and body to get the same job instead of a second one.

Request body

granularity'document' | 'page'

Score the whole document once, or return one unit per selected page.

namestring nullable

Optional display name for the run.

parse_mode'low' | 'medium' | 'high'

How much parsing effort to use: Low uses native OCR, Medium routes to the best parser, and High adds page verification and correction.

project_idstring uuid nullable

Caller-minted grouping id; jobs submitted together share it. Not a server-side resource.

sourceobject required

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).

unknown_policy'allow' | 'force_best'

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.

Response

The job finished within wait_seconds, or this is a replay of its Idempotency-Key.

job_idstring uuid required
kind'parse' | 'split' | 'classify' | 'extract' | 'ground' required
status'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' required
resultunknown
creditsinteger nullable

Credits the job used; final once usage_final is true. Drex charges the job's final billable usage once, at the USD price pinned when it was admitted (see Models & pricing). credits is the document service's usage count, not a multiplier for the per-page or per-target price. A failed job is never charged, including when it produced partial results. A job cancelled before completion is not charged, including delivered parts.

usage_finalboolean

Changes

No recorded changes to this operation across all 1 revision of this API.