# Cases API
Read case status, intake events, and decision-ready handoff packages
Source: https://www.klarefi.com/docs/api/cases

> **Use your workspace API base URL**
>
> Set `KLAREFI_API_BASE_URL` to the value in **Settings → Developer** before
> using the examples. Current workspaces may use a
> `https://<deployment>.convex.site` URL.

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`

```bash
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.

```json
{
  "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`.

```bash
curl "$KLAREFI_API_BASE_URL/api/v1/cases/case_abc123/events?after_cursor=0" \
  -H "Authorization: Bearer $KLAREFI_API_KEY"
```

```json
{
  "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`

```bash
curl "$KLAREFI_API_BASE_URL/api/v1/cases/case_abc123/package" \
  -H "Authorization: Bearer $KLAREFI_API_KEY"
```

```json
{
  "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.