# Klaaro API (v1)

> Klaaro developer API — upload documents, read extracted data, and automate your document pipeline.

**Spec version:** 1.0.0

**Base path:** `/api/v1`

**Interactive docs:** https://klaaro.ai/docs/api/v1

**OpenAPI JSON:** https://klaaro.ai/api/v1/openapi

**This document:** https://klaaro.ai/api/docs.md

## Servers

- https://klaaro.ai/api/v1 — Klaaro API v1

## Authentication

All v1 endpoints require an API key:

```
Authorization: Bearer sk_<your-api-key>
```

Create keys under **Team → API keys**. Scopes: `read`, `write`, `export`. Session auth (cookies) is not accepted on `/api/v1`.

## Endpoints

- `GET /datasets` — List datasets
- `DELETE /datasets/{id}` — Delete dataset
- `GET /datasets/{id}` — Get dataset
- `GET /datasets/{id}/approval-queue` — List approval queue
- `GET /datasets/{id}/classes` — List classes
- `GET /datasets/{id}/classes/{class}` — Get class
- `GET /datasets/{id}/records` — Get records (JSON)
- `GET /datasets/{id}/records-flat` — Get records (flat)
- `GET /datasets/{id}/records-nested` — Get records (nested)
- `GET /documents` — List documents
- `POST /documents` — Upload a document
- `DELETE /documents/{id}` — Delete document
- `GET /documents/{id}` — Get document
- `GET /documents/{id}/records` — Get records (JSON)
- `GET /documents/{id}/records-flat` — Get records (flat)
- `GET /documents/{id}/records-nested` — Get records (nested)
- `POST /documents/{id}/rerun` — Re-run document pipeline
- `GET /records-flat/{id}` — Get record (flat)
- `GET /records-nested/{id}` — Get record (nested)
- `GET /records/{id}` — Get record (JSON)
- `GET /records/{id}/approvals` — Get approval events
- `GET /records/{id}/comments` — List record-level comments
- `GET /records/{id}/field-events` — List field events
- `GET /webhooks` — List webhooks
- `POST /webhooks` — Create webhook
- `DELETE /webhooks/{webhookId}` — Delete webhook
- `PATCH /webhooks/{webhookId}` — Update webhook
- `POST /webhooks/{webhookId}/rotate-secret` — Rotate signing secret

## Error codes

- `not_authenticated` (401) — Authentication required. Provide a valid API key via Authorization: Bearer <key>.
- `api_key_required` (401) — This endpoint requires an API key. Session auth is not accepted on /api/v1.
- `insufficient_scope` (403) — API key does not have the '<scope>' scope required for this action.
- `dataset_not_found` (404) — Dataset '<id>' not found or not accessible.
- `document_not_found` (404) — Document '<id>' not found.
- `record_not_found` (404) — Record '<id>' not found.
- `webhook_not_found` (404) — Webhook '<id>' not found.
- `class_not_found` (404) — Class '<slug>' not found in this dataset.
- `not_found` (404) — <Resource> not found.
- `validation_error` (400) — <Field> is invalid.
- `business_rule_violation` (422) — <Business rule description>.
- `rate_limited` (429) — Too many requests. Slow down and retry after the Retry-After interval.
- `idempotency_conflict` (409) — An in-flight request with this Idempotency-Key already exists. Retry after it completes.
- `internal_error` (500) — An internal error occurred. Contact support with the requestId.

## Related

- [Quickstart](https://klaaro.ai/docs/quickstart.md)
- [SDKs](https://klaaro.ai/docs/sdk.md)
- [MCP](https://klaaro.ai/docs/mcp.md)
- [Integrations](https://klaaro.ai/docs/integrations.md)
- [llms.txt index](https://klaaro.ai/llms.txt)
- [llms-full.txt](https://klaaro.ai/llms-full.txt)