API Reference

Klarefi API surfaces support both:

system_of_action flows where Klarefi owns hosted intake
system_of_intelligence flows where your system owns more of the intake experience

The canonical product result is still the runtime-backed case state and its shared projections.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer sk_live_your_api_key_here

API keys are prefixed with sk_live_ for production and sk_test_ for test environments.

Base URL

https://api.klarefi.com

Rate 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 processing.

Request Body:

Field	Type	Required	Description
`document_url`	string	Yes	URL of the document to process
`case_type_id`	string	Yes	Case type for contextual processing
`idempotency_key`	string	Yes	Customer-generated key that makes retries safe
`external_case_id`	string	No	Your case identifier
`external_applicant_id`	string	No	Your applicant identifier
`external_customer_id`	string	No	Your customer/account identifier
`trace_id`	string	No	Correlation ID included in case reads and webhooks

Per-request webhook_url is rejected. Configure registered webhook endpoints in the dashboard and subscribe them to versioned event types.

Response (201):

{
  "case_id": "case_abc123",
  "doc_id": "doc_def456",
  "job_id": "job_ghi789",
  "status": "queued",
  "idempotent_replay": false
}

GET /api/v1/cases/{case_id}

Get the current status of a case with runtime-backed evidence-backed 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 hosted intake session for system_of_action. Returns a signed URL for applicant redirect.

Request Body:

Field	Type	Required	Description
`case_type_id`	string	Yes	Case type for the session
`idempotency_key`	string	Yes	Customer-generated key that makes retries safe
`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
`external_case_id`	string	No	Your case identifier
`external_applicant_id`	string	No	Your applicant identifier
`external_customer_id`	string	No	Your customer/account identifier
`trace_id`	string	No	Correlation ID included in case reads and webhooks

Response (201):

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "signed_url": "https://your-configured-app.example/s/550e8400...?token=...",
  "expires_at": "2026-01-22T10:30:00Z",
  "snippet": "<script>window.location.href=\"https://your-configured-app.example/s/...\";</script>",
  "idempotent_replay": false
}

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
}

Klarefi API surfaces support both:

system_of_action flows where Klarefi owns hosted intake
system_of_intelligence flows where your system owns more of the intake experience

The canonical product result is still the runtime-backed case state and its shared projections.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer sk_live_your_api_key_here

API keys are prefixed with sk_live_ for production and sk_test_ for test environments.

Base URL

https://api.klarefi.com

Rate 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 processing.

Request Body:

Field	Type	Required	Description
`document_url`	string	Yes	URL of the document to process
`case_type_id`	string	Yes	Case type for contextual processing
`idempotency_key`	string	Yes	Customer-generated key that makes retries safe
`external_case_id`	string	No	Your case identifier
`external_applicant_id`	string	No	Your applicant identifier
`external_customer_id`	string	No	Your customer/account identifier
`trace_id`	string	No	Correlation ID included in case reads and webhooks

Per-request webhook_url is rejected. Configure registered webhook endpoints in the dashboard and subscribe them to versioned event types.

Response (201):

{
  "case_id": "case_abc123",
  "doc_id": "doc_def456",
  "job_id": "job_ghi789",
  "status": "queued",
  "idempotent_replay": false
}

GET /api/v1/cases/{case_id}

Get the current status of a case with runtime-backed evidence-backed 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 hosted intake session for system_of_action. Returns a signed URL for applicant redirect.

Request Body:

Field	Type	Required	Description
`case_type_id`	string	Yes	Case type for the session
`idempotency_key`	string	Yes	Customer-generated key that makes retries safe
`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
`external_case_id`	string	No	Your case identifier
`external_applicant_id`	string	No	Your applicant identifier
`external_customer_id`	string	No	Your customer/account identifier
`trace_id`	string	No	Correlation ID included in case reads and webhooks

Response (201):

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "signed_url": "https://your-configured-app.example/s/550e8400...?token=...",
  "expires_at": "2026-01-22T10:30:00Z",
  "snippet": "<script>window.location.href=\"https://your-configured-app.example/s/...\";</script>",
  "idempotent_replay": false
}

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
}

Klarefi API surfaces support both:

system_of_action flows where Klarefi owns hosted intake
system_of_intelligence flows where your system owns more of the intake experience

The canonical product result is still the runtime-backed case state and its shared projections.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer sk_live_your_api_key_here

API keys are prefixed with sk_live_ for production and sk_test_ for test environments.

Base URL

https://api.klarefi.com

Rate 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 processing.

Request Body:

Field	Type	Required	Description
`document_url`	string	Yes	URL of the document to process
`case_type_id`	string	Yes	Case type for contextual processing
`idempotency_key`	string	Yes	Customer-generated key that makes retries safe
`external_case_id`	string	No	Your case identifier
`external_applicant_id`	string	No	Your applicant identifier
`external_customer_id`	string	No	Your customer/account identifier
`trace_id`	string	No	Correlation ID included in case reads and webhooks

Per-request webhook_url is rejected. Configure registered webhook endpoints in the dashboard and subscribe them to versioned event types.

Response (201):

{
  "case_id": "case_abc123",
  "doc_id": "doc_def456",
  "job_id": "job_ghi789",
  "status": "queued",
  "idempotent_replay": false
}

GET /api/v1/cases/{case_id}

Get the current status of a case with runtime-backed evidence-backed 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 hosted intake session for system_of_action. Returns a signed URL for applicant redirect.

Request Body:

Field	Type	Required	Description
`case_type_id`	string	Yes	Case type for the session
`idempotency_key`	string	Yes	Customer-generated key that makes retries safe
`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
`external_case_id`	string	No	Your case identifier
`external_applicant_id`	string	No	Your applicant identifier
`external_customer_id`	string	No	Your customer/account identifier
`trace_id`	string	No	Correlation ID included in case reads and webhooks

Response (201):

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "signed_url": "https://your-configured-app.example/s/550e8400...?token=...",
  "expires_at": "2026-01-22T10:30:00Z",
  "snippet": "<script>window.location.href=\"https://your-configured-app.example/s/...\";</script>",
  "idempotent_replay": false
}

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
}

API Reference

On this page

API Reference

On this page

API Reference

On this page