API Reference
Complete reference for all Klarefi API endpoints
Authentication
All API requests require a Bearer token in the Authorization header:
Authorization: Bearer sk_live_your_api_key_hereAPI keys are prefixed with sk_live_ for production and sk_test_ for test environments.
Base URL
https://api.klarefi.comRate Limits
All authenticated endpoints enforce per-organization rate limits. Every response includes these headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests per window |
X-RateLimit-Remaining | Remaining requests in current window |
X-RateLimit-Reset | UTC epoch seconds when the window resets |
Default limit: 100 requests per minute per organization.
When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header.
Error Format
All error responses (4xx and 5xx) follow a consistent format:
{
"error": {
"type": "validation_error",
"code": "missing_document_url",
"message": "document_url is required and must be a string",
"request_id": "req_abc123def456"
}
}Error Types
| Type | Status | Description |
|---|---|---|
authentication_error | 401 | Invalid or missing API key |
authorization_error | 403 | Valid key, insufficient permissions |
validation_error | 400 | Invalid request body or parameters |
not_found | 404 | Resource not found |
rate_limit_error | 429 | Per-org rate limit exceeded |
internal_error | 500 | Unexpected server error |
Endpoints
GET /api/v1/health
Health check endpoint. No authentication required.
Response:
{
"status": "ok"
}POST /api/v1/process
Submit a document for extraction processing.
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
document_url | string | Yes | URL of the document to process |
skill_ids | string[] | Yes | Skills to run (e.g., ["incident_date", "policy_number"]) |
case_type_id | string | No | Case type for contextual processing |
webhook_url | string | No | URL to receive completion webhook |
metadata | object | No | Arbitrary metadata attached to the case |
Response (201):
{
"case_id": "case_abc123",
"doc_id": "doc_def456",
"job_id": "job_ghi789",
"status": "queued"
}GET /api/v1/cases/{case_id}
Get the current status of a case with evidence-backed extraction results.
Response (200):
{
"case_id": "case_abc123",
"org_id": "org_xyz",
"document_ids": ["doc_def456"],
"features": {
"incident_date": {
"decision": {
"decision_id": "dec_001",
"decision": "keep",
"selected_candidate_id": "cand_001"
},
"candidates": [
{
"candidate_id": "cand_001",
"value_raw": "3 februari 2023",
"value_normalized": "2023-02-03",
"confidence": 0.95,
"evidence_ids": ["ev_001"]
}
],
"evidence": [
{
"evidence_id": "ev_001",
"doc_id": "doc_def456",
"page_index": 0,
"location": { "char_start": 142, "char_end": 158 },
"quote": "3 februari 2023",
"method": "born_digital_text"
}
]
}
}
}GET /api/v1/cases/{case_id}/events
Poll for new events on a case. Uses cursor-based pagination.
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
after_cursor | number | 0 | Return events after this cursor position |
Response (200):
{
"case_id": "case_abc123",
"events": [
{
"event_id": "evt_001",
"event_type": "document.processed",
"cursor": 1,
"created_at": "2026-01-15T10:30:00Z"
}
],
"next_cursor": 1
}POST /api/v1/sessions
Create a Mode 1 intake session. Returns a signed URL for claimant redirect.
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
case_type_id | string | Yes | Case type for the session |
ttl_hours | number | No | Session expiry in hours (default: 168 / 7 days) |
return_url | string | No | URL to redirect after completion |
locale | string | No | Language for the intake conversation |
Response (201):
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"signed_url": "https://app.klarefi.com/s/550e8400...?token=...",
"expires_at": "2026-01-22T10:30:00Z",
"snippet": "<script>window.location.href=\"https://app.klarefi.com/s/...\";</script>"
}DELETE /api/v1/documents/{doc_id}
GDPR erasure: permanently delete a document and all derived data.
Response (200):
{
"erasure_receipt": {
"doc_id": "doc_def456",
"audit_id": "audit_001",
"deleted_evidence": 5,
"deleted_candidates": 3,
"deleted_decisions": 2,
"deleted_document": true,
"timestamp": "2026-01-15T10:30:00Z"
}
}GET /api/v1/me
Returns the authenticated organization info.
Response (200):
{
"org_id": "org_abc123",
"environment": "live"
}POST /api/v1/webhooks/test
Send a test webhook event to a registered endpoint to verify the receiver works.
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
endpoint_url | string | Yes | URL to send the test event to |
signing_secret | string | Yes | Signing secret for HMAC verification |
Response (200):
{
"success": true,
"status_code": 200
}