Extract

Extract structured data with Basic Financial or Other formats. Other accepts a JSON output template through the schema field. For mixed or unknown document types, the SDK's Advanced extractor (extract_advanced()) detects the type automatically.

Cost$0.05/page

Latency~2s

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.
`Cache-Control`	`string`	optional	—	Send `no-cache` (or `no-store`) as an alternative to `force_refresh=true`; both have the same effect. Other directives, including `max-age=0` and `public`, do not bypass the cache.

Body

Name	Type	Required	Description
`document_key`	`string`	required	S3 document key obtained from the presigned upload endpoint (/v1/documents/upload).
`schema`	`string`	optional	Use this optional field for Basic + Other (`category=non_financial`). Send a non-empty JSON object as a multipart string. Use `null`, `false`, or `unselected` placeholders to define the output shape. HyperAPI fills the same structure from the document. The schema applies only to this request. Omit it to use your organization's stored template when configured.

Query Parameters

Name	Type	Default	Allowed values	Description
`category`	`string`	`financial`	`financialnon_financial`	Basic document format: `financial` (default) handles invoices and receipts. `non_financial`, shown as Other in the dashboard, accepts an optional `schema` multipart field. For automatic document-type detection, use the SDK's Advanced extractor (`extract_advanced()`).
`parse_mode`	`string`	`fast`	`fastadvanced`	Stage-1 OCR engine, independent of `category`. `fast` (default) is quick text extraction; `advanced` runs layout-aware parsing for dense tables and forms — higher accuracy, slower, costs more. Advanced is available on paid tiers (Pro/Enterprise) and returns `403` for other tiers (or `400` where it is not enabled). Defaults to `fast`.
`force_refresh`	`boolean`	`false`	—	When `true`, reprocess the document instead of returning the cached result. Results are cached per (document + parameters) for 24 hours, so re-submitting an unchanged request normally returns the stored output — this is how to force a genuinely fresh run after a bad result. A forced run is billed at the normal page rate, where a cached one is not charged. Defaults to `false`.

Code examples

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

# Basic + Other with a request-specific output template:
curl -X POST "https://apis.hyperbots.com/v1/extract?category=non_financial" \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "document_key=550e8400-e29b-41d4-a716-446655440000" \
  -F 'schema={"patient_name":null,"active":false}'

# Advanced layout parsing (Pro/Enterprise tiers):
#   add ?parse_mode=advanced to the URL

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

# Basic + Other with a request-specific output template:
curl -X POST "https://apis.hyperbots.com/v1/extract?category=non_financial" \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "document_key=550e8400-e29b-41d4-a716-446655440000" \
  -F 'schema={"patient_name":null,"active":false}'

# Advanced layout parsing (Pro/Enterprise tiers):
#   add ?parse_mode=advanced to the URL

Response

200 OK

application/json

JSON

{
  "status": "success",
  "request_id": "req_01ja0...",
  "task": "extract",
  "model_used": "HyperLM",
  "result": {
    "entities": {
      "invoice_number": "INV-2024-0042",
      "date": "2024-01-15",
      "due_date": "2024-02-15",
      "vendor_name": "Acme Supplies Ltd",
      "total_amount": "1,250.00",
      "currency": "USD"
    },
    "line_items": [
      { "description": "Widget A", "quantity": 10, "unit_price": "100.00", "total": "1,000.00" },
      { "description": "Shipping", "quantity": 1, "unit_price": "250.00", "total": "250.00" }
    ]
  },
  "duration_ms": 1820,
  "metadata": { "pages": 2 }
}

{
  "status": "success",
  "request_id": "req_01ja0...",
  "task": "extract",
  "model_used": "HyperLM",
  "result": {
    "entities": {
      "invoice_number": "INV-2024-0042",
      "date": "2024-01-15",
      "due_date": "2024-02-15",
      "vendor_name": "Acme Supplies Ltd",
      "total_amount": "1,250.00",
      "currency": "USD"
    },
    "line_items": [
      { "description": "Widget A", "quantity": 10, "unit_price": "100.00", "total": "1,000.00" },
      { "description": "Shipping", "quantity": 1, "unit_price": "250.00", "total": "250.00" }
    ]
  },
  "duration_ms": 1820,
  "metadata": { "pages": 2 }
}