API Reference

HyperAPI provides four document intelligence endpoints. All requests are authenticated with an API key and accept multipart file uploads.

Base URLhttps://apis.hyperbots.com

Get started in 5 minutes

Create an API key, install the SDK, and make your first call.

Get Your API Key Try Playground

Authentication

All API requests require an X-API-Key header. Keys are prefixed with hk_live_ for production or hk_test_ for testing. Generate keys from your dashboard.

curl -X POST https://apis.hyperbots.com/v1/parse \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "file=@invoice.pdf"

Quickstart

Install the Python SDK and run your first API call in under a minute.

Install

pip install hyperapi

Parse a document

from hyperapi import HyperAPIClient

client = HyperAPIClient(api_key="hk_live_your_key_here")

result = client.parse("invoice.pdf")
print(result["result"]["ocr"])

client.close()

POST/v1/parse

Parse

Extract raw text from documents using OCR. Supports PDFs and images. Returns structured markdown with page-level text.

Cost: $0.05/page

Latency: ~1s

Model: hyperbots_vlm_ocr

Request Headers

X-API-Keyrequired — your API key

Content-Typemultipart/form-data

Request Body

filerequired — PDF, PNG, JPG

Code Examples

curl -X POST https://apis.hyperbots.com/v1/parse \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "file=@document.pdf"

Response (200 OK)

JSON

{
  "status": "success",
  "request_id": "req_01j9x...",
  "task": "parse",
  "model_used": "hyperbots_vlm_ocr",
  "result": {
    "ocr": "Invoice\n\nBill To: Acme Corp\nDate: 2024-01-15\n\n..."
  },
  "duration_ms": 843,
  "metadata": {
    "pages": 2,
    "file_type": "pdf"
  }
}

POST/v1/classify

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

Model: hyperbots_vlm_ocr

Request Headers

X-API-Keyrequired — your API key

Content-Typemultipart/form-data

Request Body

filerequired — PDF, PNG, JPG

Code Examples

curl -X POST https://apis.hyperbots.com/v1/classify \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "file=@document.pdf"

Response (200 OK)

JSON

{
  "status": "success",
  "request_id": "req_01j9y...",
  "task": "classify",
  "model_used": "hyperbots_vlm_ocr",
  "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 }
}

POST/v1/split

Split

Segment a multi-document PDF into individual logical documents. Returns page ranges for each detected document.

Cost: $0.02/page

Latency: ~0.5s

Model: hyperbots_vlm_ocr

Request Headers

X-API-Keyrequired — your API key

Content-Typemultipart/form-data

Request Body

filerequired — PDF, PNG, JPG

Code Examples

curl -X POST https://apis.hyperbots.com/v1/split \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "file=@document.pdf"

Response (200 OK)

JSON

{
  "status": "success",
  "request_id": "req_01j9z...",
  "task": "split",
  "model_used": "hyperbots_vlm_ocr",
  "result": {
    "segments": [
      { "document_index": 0, "start_page": 1, "end_page": 3, "type": "invoice" },
      { "document_index": 1, "start_page": 4, "end_page": 5, "type": "receipt" }
    ]
  },
  "duration_ms": 490,
  "metadata": { "pages": 5 }
}

POST/v1/extract

Extract

Extract structured data fields from documents using a vision-language model. Returns named entities and line items.

Cost: $0.08/page

Latency: ~2s

Model: hyperbots_vlm_extract

Request Headers

X-API-Keyrequired — your API key

Content-Typemultipart/form-data

Request Body

filerequired — PDF, PNG, JPG

Code Examples

curl -X POST https://apis.hyperbots.com/v1/extract \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "file=@document.pdf"

Response (200 OK)

JSON

{
  "status": "success",
  "request_id": "req_01ja0...",
  "task": "extract",
  "model_used": "hyperbots_vlm_extract",
  "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 }
}

Errors

All errors return a JSON body with an error object and a standard HTTP status code.

401UnauthorizedMissing or invalid X-API-Key

402Payment RequiredInsufficient credit balance

413Payload Too LargeFile exceeds 50 MB limit

422Unprocessable EntityUnsupported file type

429Too Many RequestsRate limit exceeded

503Service UnavailableInference backend unavailable (circuit open)

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your credit balance is too low to process this request."
  }
}

Rate Limits

Rate limits are applied per API key, per minute. Limits scale with your plan tier.

Tier	Requests / min	Concurrency	Priority weight
Free	10	1	1
Pro	100	10	10
Enterprise	Unlimited	100	100

See our pricing page for plan details and upgrade options.

SDKs

Official SDK for Python. Node.js SDK coming soon.

Python SDK

Python 3.9+ · httpx · asyncio support

pip install hyperapi

client.parse(file)

client.extract(file)

client.classify(file)

client.split(file)

client.process(file)

client.upload_document(file)

Node.js SDK

Coming soon

npm install hyperapi

API Reference

HyperAPI provides four document intelligence endpoints. All requests are authenticated with an API key and accept multipart file uploads.

Base URLhttps://apis.hyperbots.com

Get started in 5 minutes

Create an API key, install the SDK, and make your first call.

Get Your API Key Try Playground

Authentication

All API requests require an X-API-Key header. Keys are prefixed with hk_live_ for production or hk_test_ for testing. Generate keys from your dashboard.

curl -X POST https://apis.hyperbots.com/v1/parse \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "file=@invoice.pdf"

Quickstart

Install the Python SDK and run your first API call in under a minute.

Install

pip install hyperapi

Parse a document

from hyperapi import HyperAPIClient

client = HyperAPIClient(api_key="hk_live_your_key_here")

result = client.parse("invoice.pdf")
print(result["result"]["ocr"])

client.close()

POST/v1/parse

Parse

Extract raw text from documents using OCR. Supports PDFs and images. Returns structured markdown with page-level text.

Cost: $0.05/page

Latency: ~1s

Model: hyperbots_vlm_ocr

Request Headers

X-API-Keyrequired — your API key

Content-Typemultipart/form-data

Request Body

filerequired — PDF, PNG, JPG

Code Examples

curl -X POST https://apis.hyperbots.com/v1/parse \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "file=@document.pdf"

Response (200 OK)

JSON

{
  "status": "success",
  "request_id": "req_01j9x...",
  "task": "parse",
  "model_used": "hyperbots_vlm_ocr",
  "result": {
    "ocr": "Invoice\n\nBill To: Acme Corp\nDate: 2024-01-15\n\n..."
  },
  "duration_ms": 843,
  "metadata": {
    "pages": 2,
    "file_type": "pdf"
  }
}

POST/v1/classify

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

Model: hyperbots_vlm_ocr

Request Headers

X-API-Keyrequired — your API key

Content-Typemultipart/form-data

Request Body

filerequired — PDF, PNG, JPG

Code Examples

curl -X POST https://apis.hyperbots.com/v1/classify \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "file=@document.pdf"

Response (200 OK)

JSON

{
  "status": "success",
  "request_id": "req_01j9y...",
  "task": "classify",
  "model_used": "hyperbots_vlm_ocr",
  "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 }
}

POST/v1/split

Split

Segment a multi-document PDF into individual logical documents. Returns page ranges for each detected document.

Cost: $0.02/page

Latency: ~0.5s

Model: hyperbots_vlm_ocr

Request Headers

X-API-Keyrequired — your API key

Content-Typemultipart/form-data

Request Body

filerequired — PDF, PNG, JPG

Code Examples

curl -X POST https://apis.hyperbots.com/v1/split \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "file=@document.pdf"

Response (200 OK)

JSON

{
  "status": "success",
  "request_id": "req_01j9z...",
  "task": "split",
  "model_used": "hyperbots_vlm_ocr",
  "result": {
    "segments": [
      { "document_index": 0, "start_page": 1, "end_page": 3, "type": "invoice" },
      { "document_index": 1, "start_page": 4, "end_page": 5, "type": "receipt" }
    ]
  },
  "duration_ms": 490,
  "metadata": { "pages": 5 }
}

POST/v1/extract

Extract

Extract structured data fields from documents using a vision-language model. Returns named entities and line items.

Cost: $0.08/page

Latency: ~2s

Model: hyperbots_vlm_extract

Request Headers

X-API-Keyrequired — your API key

Content-Typemultipart/form-data

Request Body

filerequired — PDF, PNG, JPG

Code Examples

curl -X POST https://apis.hyperbots.com/v1/extract \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "file=@document.pdf"

Response (200 OK)

JSON

{
  "status": "success",
  "request_id": "req_01ja0...",
  "task": "extract",
  "model_used": "hyperbots_vlm_extract",
  "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 }
}

Errors

All errors return a JSON body with an error object and a standard HTTP status code.

401UnauthorizedMissing or invalid X-API-Key

402Payment RequiredInsufficient credit balance

413Payload Too LargeFile exceeds 50 MB limit

422Unprocessable EntityUnsupported file type

429Too Many RequestsRate limit exceeded

503Service UnavailableInference backend unavailable (circuit open)

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your credit balance is too low to process this request."
  }
}

Rate Limits

Rate limits are applied per API key, per minute. Limits scale with your plan tier.

Tier	Requests / min	Concurrency	Priority weight
Free	10	1	1
Pro	100	10	10
Enterprise	Unlimited	100	100

See our pricing page for plan details and upgrade options.

SDKs

Official SDK for Python. Node.js SDK coming soon.

Python SDK

Python 3.9+ · httpx · asyncio support

pip install hyperapi

client.parse(file)

client.extract(file)

client.classify(file)

client.split(file)

client.process(file)

client.upload_document(file)

Node.js SDK

Coming soon

npm install hyperapi