Cases API
Read case status, intake events, and decision-ready handoff packages
Use your workspace API base URL
Set
KLAREFI_API_BASE_URLto the value in Settings → Developer before using the examples. Current workspaces may use ahttps://<deployment>.convex.siteURL.
Case reads expose Klarefi's current case record. Use them when your system needs current data; use webhooks as notifications that a read may be useful.
runtime_status uses the runtime vocabulary: processing,
intake_in_progress, gate_ready, gate_evaluating, ready_for_review, or
complete.
GET /api/v1/cases/{caseId}
Required scope: cases:read
curl "$KLAREFI_API_BASE_URL/api/v1/cases/case_abc123" \
-H "Authorization: Bearer $KLAREFI_API_KEY"The response is the current operator workspace projection. Unknown fields should be ignored.
{
"case_id": "case_abc123",
"case_type_id": "motor_claim",
"workflow_id": "motor_claim_intake",
"workflow_version": "3",
"operating_mode": "system_of_action",
"runtime_status": "ready_for_review",
"workspace": {
"current_node_id": "review",
"current_node_title": "Operator review",
"current_gate_id": null,
"current_gate_title": null,
"next_action": null,
"operational_summary": {
"reason": {
"why_here": "Ready for operator review.",
"why_here_code": "ready_for_review",
"queue_category": "ready_for_review",
"queue_status": "ready_for_review",
"current_gate_id": null,
"current_node_id": "review"
},
"blocking_items": [],
"primary_action": null,
"ownership": null,
"blocking_fact_ids": [],
"has_needs_input_facts": false,
"has_failed_facts": false
},
"facts": [
{
"fact_id": "incident_date",
"fact_label": "Incident date",
"status": "resolved",
"value": "2023-02-03",
"candidate_id": "cand_001",
"anchor_match_quality": 1,
"source": "document",
"reason_codes": [],
"provenance": [
{
"kind": "document_span",
"document_id": "doc_def456",
"page_index": 0,
"quote": "3 februari 2023",
"char_start": 142,
"char_end": 158
}
],
"verification_metadata": [],
"evidence": [
{
"evidence_id": "ev_001",
"quote": "3 februari 2023",
"location": { "char_start": 142, "char_end": 158 },
"doc_id": "doc_def456",
"page_index": 0
}
]
}
],
"documents": [
{
"doc_id": "doc_def456",
"status": "processed",
"mime_type": "application/pdf"
}
],
"structured_inputs": {},
"summary": {
"resolved_count": 1,
"needs_input_count": 0,
"failed_count": 0,
"document_count": 1
},
"jobs": [],
"intake_session": null
},
"queue_row": {
"case_id": "case_abc123",
"operating_mode": "system_of_action",
"runtime_status": "ready_for_review",
"queue_category": "ready_for_review",
"queue_status": "ready_for_review",
"why_here": "Ready for operator review.",
"why_here_code": "ready_for_review",
"blocking_items": [],
"blocking_fact_ids": [],
"sort_timestamp": "2026-01-15T10:30:00.000Z",
"updated_at": "2026-01-15T10:30:00.000Z"
},
"updated_at": "2026-01-15T10:30:00.000Z"
}GET /api/v1/cases/{caseId}/events
Required scope: cases:read
Query parameters: after_cursor, default 0; limit, default 100, maximum
500.
curl "$KLAREFI_API_BASE_URL/api/v1/cases/case_abc123/events?after_cursor=0" \
-H "Authorization: Bearer $KLAREFI_API_KEY"{
"case_id": "case_abc123",
"events": [
{
"event_id": "evt_001",
"event_type": "document.uploaded",
"cursor": 1,
"created_at": "2026-01-15T10:30:00.000Z"
}
],
"next_cursor": 1,
"has_more": false
}Store next_cursor and pass it as after_cursor on the next poll. When
has_more is true, poll again immediately with after_cursor set to
next_cursor to drain the next page.
GET /api/v1/cases/{caseId}/package
Required scope: cases:read
curl "$KLAREFI_API_BASE_URL/api/v1/cases/case_abc123/package" \
-H "Authorization: Bearer $KLAREFI_API_KEY"{
"case_id": "case_abc123",
"case_file_url": "https://app.klarefi.com/case-file/case_abc123?token=...",
"facts": {},
"documents": []
}case_file_url may be null if a signed case-file link cannot be created for
the deployment.