hyperbots-api

name: hyperbots-api description: "Integrate with HyperAPI for financial document processing - OCR text extraction, document classification, PDF splitting, and structured data extraction from invoices, receipts, and financial documents. Use when the user needs to parse PDFs, extract text from documents, classify document types, split multi-document PDFs, or extract structured entities like invoice numbers, vendor names, line items. Keywords: hyperapi, hyperbots, document parsing, OCR, PDF processing, invoice extraction, receipt processing, document classification, VLM, vision language model." license: MIT metadata: author: hyperbots version: "2.0.0" tags: ["api", "document-processing", "ocr", "financial", "pdf"]

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.