Extract

Extract structured data fields from documents. Returns named entities and line items. This is the Basic extractor; for mixed or unknown document types, the SDK's Advanced extractor (extract_advanced()) auto-detects the type instead of you declaring a category.

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.

Body

Name	Type	Required	Description
`document_key`	`string`	required	S3 document key obtained from the presigned upload endpoint (/v1/documents/upload).

Query Parameters

Name	Type	Default	Allowed values	Description
`category`	`string`	`financial`	`financialnon_financial`	Basic extractor profile: `financial` (default — the two-leg adapter for invoices/receipts) or `non_financial` (a generic single-pass extractor). For auto-detecting the document type instead of declaring it, 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`.

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"

# 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"

# 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 }
}