Quickstart

Extract structured data from a document in five steps.

curl -X POST https://api.bloh.dev/extract \
  -H "x-api-key: bloh_your_api_key" \
  -F "file=@invoice.pdf" \
  -F "document_type=invoice"

# pip install requests
import requests

with open("invoice.pdf", "rb") as f:
    response = requests.post(
        "https://api.bloh.dev/extract",
        headers={"x-api-key": "bloh_your_api_key"},
        files={"file": f},
        data={"document_type": "invoice"},
    )

print(response.json())

import fs from "node:fs";

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("invoice.pdf")]));
form.append("document_type", "invoice");

const res = await fetch("https://api.bloh.dev/extract", {
  method: "POST",
  headers: { "x-api-key": "bloh_your_api_key" },
  body: form,
});

console.log(await res.json());

{
  "success": true,
  "document_type": "invoice",
  "data": {
    "vendor_name": "Muller GmbH",
    "invoice_number": "2026-0847",
    "gross_amount": 1992.66,
    "currency": "EUR",
    "line_items": [
      { "description": "Consulting", "quantity": 40, "unit_price": 49.82, "amount": 1992.66 }
    ]
  },
  "confidence": "high",
  "credits_used": 2,
  "processing_time_ms": 1340
}

Authentication

All API requests require an API key passed in the x-api-key header. Generate keys from the Dashboard.

API keys start with bloh_ followed by a random hex string. Each account can have up to 5 active keys. You can revoke a key at any time from the Dashboard — revoked keys are rejected immediately.

The playground endpoints (/playground/extract and /playground/estimate) do not require an API key. They are rate limited to 3 extractions per day per IP address.

POST /extract

Request body

Success response 200

{
  "success": true,
  "document_type": "invoice",
  "data": {
    "vendor_name": "Muller GmbH",
    "invoice_number": "2026-0847",
    "date": "2026-01-15",
    "due_date": "2026-02-15",
    "net_amount": 1674.50,
    "vat_rate": 19,
    "vat_amount": 318.16,
    "gross_amount": 1992.66,
    "currency": "EUR",
    "iban": "DE89370400440532013000",
    "line_items": [
      {
        "description": "Consulting — January",
        "quantity": 40,
        "unit": "hours",
        "unit_price": 41.86,
        "amount": 1674.50
      }
    ]
  },
  "confidence": "high",
  "credits_used": 2,
  "processing_time_ms": 1340
}

Response fields

Error response

{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FILE_TYPE",
    "message": "File type .zip is not supported. Supported types: pdf, jpg, jpeg, png, webp, tiff, docx, xlsx, pptx, csv, tsv"
  }
}

See Error codes for the full list.

POST /estimate

Request body

Same as POST /extract: send a file field, with optional document_type.

Success response 200

{
  "success": true,
  "input_tokens": 1450,
  "estimated_credits": 3,
  "file_size_bytes": 245760,
  "mime_type": "application/pdf"
}

Response fields

Example

curl -X POST https://api.bloh.dev/estimate \
  -H "x-api-key: bloh_your_api_key" \
  -F "file=@contract.pdf"

Custom schemas

By default, Bloh extracts a standard set of fields for each document type. To extract only specific fields, pass a JSON schema in the schema form field.

Schema format

The schema must be a JSON object with a fields array of strings. Each string is a field name to extract.

{
  "fields": ["vendor_name", "total_amount", "currency", "due_date"]
}

Constraints

• Maximum 50 fields per schema.
• Field names must be 64 characters or fewer.
• Field names may only contain letters, numbers, underscores, hyphens, and spaces.

Example request

curl -X POST https://api.bloh.dev/extract \
  -H "x-api-key: bloh_your_api_key" \
  -F "file=@invoice.pdf" \
  -F 'schema={"fields":["vendor_name","total_amount","currency"]}'

Example response

{
  "success": true,
  "document_type": "invoice",
  "data": {
    "vendor_name": "Muller GmbH",
    "total_amount": 1992.66,
    "currency": "EUR"
  },
  "confidence": "high",
  "credits_used": 2,
  "processing_time_ms": 980
}

When a custom schema is provided, the document_type parameter is ignored — the LLM extracts only the fields you specify.

Error codes

All error responses share the same shape:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Rate limits

When you exceed a rate limit, the API returns a 429 status with the RATE_LIMITED error code. Wait for the window to reset before retrying.

Monthly credit limits

Credit usage is visible on the Dashboard. Use POST /estimate to check costs before extracting.

Supported document types

Pass a document_type to optimize extraction, or use auto (default) to let Bloh detect the type.

All dates are normalized to ISO 8601 (YYYY-MM-DD). All monetary amounts are returned as numbers without currency symbols. Currency is always a separate ISO 4217 field.