Classify

Categorize document type automatically. Returns a label and confidence score from a set of financial document classes.

Cost$0.03/page

Latency~0.8s

HyperLM

Step 1: Upload your document — call POST /v1/documents/upload to get a document_key

Request

Headers

Name	Type	Required	Allowed values	Description
`X-API-Key`	`string`	required	—	Your HyperAPI key (hk_live_* or hk_test_*).
`X-Async`	`string`	optional	`truefalse`	Set to "true" to process asynchronously and receive a job ID.

Body

Name	Type	Required	Description
`document_key`	`string`	required	S3 document key obtained from the presigned upload endpoint (/v1/documents/upload).
`options`	`string`	optional	Optional JSON object of classifier tuning knobs, sent as a single JSON-encoded string. Invalid JSON or a non-object value returns HTTP 400. Accepted keys: `mode` (`fast` \| `balanced` \| `thorough`, default `balanced`) selects pipeline depth — distinct from the router query `mode` above; `active_classes` (array of class labels — omit for the server default set); `active_classes_type` (`default` \| `minimal`, default `default`; default = full class set, minimal = reduced set); `custom_llm_classes` (object of caller-defined classes); `system_instruction` (string prepended to the model prompt); `domain_options`, `non_domain_label`, `non_domain_exit_label` (strings refining domain routing and fallback labels); `confusion_neighbors` (object mapping a label to its list of commonly confused labels); `start_token_budget` (default 3200, range 256–8192) and `end_token_budget` (default 1600, range 256–8192) cap tokens read from the start/end of the document; `max_start_pages` (default 4, range 1–20) and `max_end_pages` (default 2, range 0–10) cap pages read from each end.

Query Parameters

Name	Type	Default	Allowed values	Description
`mode`	`string`	`default`	—	Router-level task-routing selector (picks the `classify:<mode>` binding). Leave at `default` for standard classification. Pipeline depth is controlled separately by `options.mode` (see the request body), not by this parameter.

Code examples

# Get a document_key first: see POST /v1/documents/upload
curl -X POST "https://apis.hyperbots.com/v1/classify?mode=default" \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "document_key=550e8400-e29b-41d4-a716-446655440000"

# Get a document_key first: see POST /v1/documents/upload
curl -X POST "https://apis.hyperbots.com/v1/classify?mode=default" \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "document_key=550e8400-e29b-41d4-a716-446655440000"

Response

200 OK

application/json

JSON

{
  "status": "success",
  "request_id": "req_01j9y...",
  "task": "classify",
  "model_used": "HyperLM",
  "result": {
    "label": "invoice",
    "confidence": 0.98,
    "candidates": [
      { "label": "invoice", "confidence": 0.98 },
      { "label": "receipt", "confidence": 0.01 },
      { "label": "contract", "confidence": 0.01 }
    ]
  },
  "duration_ms": 612,
  "metadata": { "pages": 1 }
}

{
  "status": "success",
  "request_id": "req_01j9y...",
  "task": "classify",
  "model_used": "HyperLM",
  "result": {
    "label": "invoice",
    "confidence": 0.98,
    "candidates": [
      { "label": "invoice", "confidence": 0.98 },
      { "label": "receipt", "confidence": 0.01 },
      { "label": "contract", "confidence": 0.01 }
    ]
  },
  "duration_ms": 612,
  "metadata": { "pages": 1 }
}