# Kreuzberg Cloud Extraction API

Public document extraction API. Base URL: `https://api.kreuzberg.dev`. The full live OpenAPI specification is published under `/api-doc/openapi.json`; integration guides live at <https://docs.kreuzberg.dev/>.

## Authentication

All endpoints require a project API key passed as a Bearer token:

```text
Authorization: Bearer kbg_live_<your-api-key>
```

API keys are created in the Kreuzberg Cloud dashboard at <https://kreuzberg.dev/dashboard>.

## Async model

Extraction is asynchronous. You submit documents and receive job IDs immediately (HTTP 202). Results are delivered in one of two ways:

1. **Webhook** — provide a `webhook.url` in the request and receive an HMAC-SHA256-signed POST when each job finishes. Header: `X-Webhook-Signature: sha256=<hex>`.
2. **Polling** — call `GET /v1/jobs/{id}` until status is `completed`, `partial_success`, or `failed`.

Recommended polling cadence: every 1 second for the first ~10 seconds, then back off to every 5 seconds. `chunking` and `aggregating` are normal in-progress states between `processing` and `completed`.

Job statuses: `awaiting_upload`, `pending`, `processing`, `chunking`, `aggregating`, `completed`, `partial_success`, `failed`, `cancelled`.

## Endpoints

### `POST /v1/extract` — Submit documents inline

Accepts `application/json` or `multipart/form-data`. Maximum **10 documents per request**; submit larger batches as multiple requests or use the presigned-upload flow.

**JSON body**:

```json
{
  "documents": [
    {
      "filename": "invoice.pdf",
      "mime_type": "application/pdf",
      "data": "<base64-encoded bytes>"
    }
  ],
  "options": {
    "extraction_config": {
      "output_format": "markdown",
      "ocr": { "backend": "tesseract", "language": "eng" }
    }
  },
  "webhook": {
    "url": "https://example.com/hooks/kreuzberg",
    "secret": "shared-secret-for-hmac",
    "metadata": { "request_id": "abc123" }
  }
}
```

`webhook` is optional for JSON requests (poll if you skip it). For `multipart/form-data` the `webhook` part is **required** — the API rejects multipart submissions without it.

`ocr.backend` only accepts `"tesseract"` on the cloud. VLM and other backends are validated and rejected.

**Response (HTTP 202)**:

```json
{
  "job_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "status": "pending"
}
```

Inline extraction is best for files ≤ 1 MB. For larger files, use the presigned-upload flow.

### `POST /v1/uploads/presign` — Get presigned upload URLs

Use for files larger than the inline limit. Send only document metadata; receive a `batch_id` and one presigned `PUT` URL per document.

**Request**:

```json
{
  "documents": [
    { "filename": "report.pdf", "mime_type": "application/pdf" }
  ],
  "config": {
    "output_format": "markdown",
    "ocr": { "backend": "tesseract", "language": "eng" }
  },
  "webhook": { "url": "https://example.com/hooks/kreuzberg", "secret": "..." }
}
```

Note that the presign body uses a top-level `config` field, not the `options.extraction_config` nesting that `POST /v1/extract` uses.

**Response**:

```json
{
  "batch_id": "...",
  "uploads": [
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440000",
      "upload_url": "https://...",
      "object_key": "...",
      "method": "PUT",
      "expires_in_secs": 900
    }
  ]
}
```

Upload each file directly to its `upload_url` with `PUT`, then call `/v1/uploads/confirm` with the `batch_id`.

### `POST /v1/uploads/confirm` — Trigger processing

```json
{ "batch_id": "<batch_id from presign>" }
```

**Response (HTTP 202)**:

```json
{
  "job_ids": ["..."],
  "status": "pending"
}
```

### `GET /v1/jobs/{id}` — Poll job status and results

Returns job metadata and, on completion, the full extraction result:

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "invoice.pdf",
  "status": "completed",
  "created_at": "2026-05-08T10:00:00Z",
  "processing_time_ms": 1234,
  "result": {
    "content": [{ "text": "Invoice total: $1,234.56", "page_number": 1, "confidence": 0.95 }],
    "tables": [],
    "images": [],
    "metadata": { "title": "Invoice #12345", "page_count": 1 }
  }
}
```

`processing_time_ms` and `result` are only present once the job reaches `completed` or `partial_success`.

### `GET /v1/usage` — Project usage and quota

Query params: `start` and `end` (both `YYYY-MM-DD`; default to the current calendar month).

**Response**:

```json
{
  "period_start": "2026-05-01",
  "period_end": "2026-06-01",
  "total_pages": 1234,
  "total_documents": 56,
  "total_failed": 0,
  "quota_limit": 10000,
  "quota_remaining": 8766,
  "by_mime_type": {
    "application/pdf": { "documents": 40, "pages": 1100, "failed": 0 },
    "image/png":       { "documents": 16, "pages": 134,  "failed": 0 }
  }
}
```

`quota_limit` and `quota_remaining` are `null` when the project has unlimited quota.

### `GET /healthz`, `GET /readyz`

Liveness and readiness probes — open to all callers, no auth required.

## Errors

JSON errors of the form `{"error": "<message>"}`. Status codes:

- `400` — invalid request (bad MIME type, missing field, malformed JSON, OCR backend other than Tesseract, more than 10 documents, missing multipart `webhook`)
- `401` — missing or invalid API key
- `404` — job/resource not found
- `429` — free page credit exhausted; add a payment method to continue
- `500` / `503` — internal or upstream failure

## Webhook payload

When a job completes (or fails), Kreuzberg POSTs to your `webhook.url`.

- **Signature**: HMAC-SHA256 over the raw request body, using `webhook.secret` as the key, hex-encoded. Sent as `X-Webhook-Signature: sha256=<hex>`. The header is only present when you supply a `secret`.
- **Body**: same shape as `GET /v1/jobs/{id}`, plus any `webhook.metadata` you supplied at submit time.

## See also

- [Capabilities](https://kreuzberg.dev/llms/capabilities.md)
- [Getting started](https://kreuzberg.dev/llms/getting-started.md)
- [Pricing](https://kreuzberg.dev/llms/pricing.md)
- [Full documentation](https://docs.kreuzberg.dev/)