HyperAPI Skill

This skill provides access to HyperAPI, a financial document intelligence platform with four core endpoints for processing invoices, receipts, and financial documents.

Capabilities

HyperAPI provides four document intelligence endpoints:

Base URL

https://api.hyperapi.dev

Authentication

All API requests require an X-API-Key header:

• Production keys: hk_live_...
• Test keys: hk_test_...

Generate keys from your dashboard at https://hyperbots.com/dashboard

Quick Start

Installation

pip install hyperapi

Basic Usage

from hyperapi import HyperAPIClient

client = HyperAPIClient(api_key="hk_live_your_key_here")

# Parse - extract OCR text
result = client.parse("document.pdf")
print(result["result"]["ocr"])

# Extract - get structured data
result = client.extract("invoice.pdf")
print(result["result"]["entities"])
print(result["result"]["line_items"])

client.close()

API Reference

Parse Endpoint

Extract raw text from documents using OCR.

Request:

curl -X POST https://api.hyperapi.dev/v1/parse \
  -H "X-API-Key: hk_live_..." \
  -F "file=@document.pdf"

Response:

{
  "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..."
  },
  "duration_ms": 843,
  "metadata": {
    "pages": 2,
    "file_type": "pdf"
  }
}

Extract Endpoint

Extract structured entities and line items from documents.

Request:

curl -X POST https://api.hyperapi.dev/v1/extract \
  -H "X-API-Key: hk_live_..." \
  -F "file=@invoice.pdf"

Response:

{
  "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"
      }
    ]
  },
  "duration_ms": 1820,
  "metadata": { "pages": 2 }
}

Classify Endpoint

Categorize documents into financial document types.

Request:

curl -X POST https://api.hyperapi.dev/v1/classify \
  -H "X-API-Key: hk_live_..." \
  -F "file=@document.pdf"

Response:

{
  "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 }
}

Split Endpoint

Segment multi-document PDFs into individual documents.

Request:

curl -X POST https://api.hyperapi.dev/v1/split \
  -H "X-API-Key: hk_live_..." \
  -F "file=@batch.pdf"

Response:

{
  "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 }
}

Error Handling

All errors return a JSON body with an error object:

Error Response:

{
  "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:

SDK Methods

Python SDK

from hyperapi import HyperAPIClient

client = HyperAPIClient(api_key="hk_live_...")

# All available methods
client.parse(file_path)                    # OCR extraction
client.extract(file_path)                  # Structured data extraction
client.classify(file_path)                 # Document classification
client.split(file_path)                    # PDF segmentation
client.process(file_path)                  # Parse + Extract combined
client.upload_document(file_path)          # S3 presigned upload

client.close()

Node.js SDK

Coming soon.

Best Practices

1. Use Presigned Uploads: For files > 50 MB, use client.upload_document() which handles S3 presigned URL flow.

2. Choose the Right Endpoint:

   • Need raw text? Use parse
   • Need structured data? Use extract
   • Need to categorize? Use classify
   • Have multi-doc PDFs? Use split

3. Handle Rate Limits: Implement exponential backoff for 429 responses.

4. Verify File Types: Supported formats are PDF, PNG, and JPG.

CLI Usage

A bundled CLI script is available:

export HYPERAPI_KEY=hk_live_...
python3 scripts/hyperbots_cli.py extract invoice.pdf

See references/api_docs.md for complete documentation.