Skip to main content

Case Operations

Update the lifecycle status of a case from discovered through confirmed and active to Closed. Transitions are forward-only and can carry resolution notes.

The case status endpoint manages the case lifecycle: PATCH /v1/cases/:key/status moves a case through discovered → confirmed → active → Closed as your team reviews it. Closed is the terminal state; the API payload value for it remains resolved. Any status update can carry optional resolution_notes documenting the decision.

The lifecycle is forward-only: a case can advance (e.g. discovered → active) or stay in place, but moving backward returns a 400. Closed (resolved) is terminal. Optional resolution_notes can be attached with any status update.
PATCH/v1/cases/:key/status

Body parameters

status*stringNew lifecycle status for the case: `discovered`, `confirmed`, `active`, or `resolved` (Closed).
resolution_notesstringOptional notes to record with the status update.

Request

Response

The response is the updated case row.

Response fields

idstringCase UUID — the stable resource id.
case_keystringContent-derived case key (hex).
statusstringThe new case status.
display_namestring | nullUser-curated display name, if set.
resolution_notesstring | nullResolution notes, if provided.

Response

{
  "id": "5c7fa78c-4d92-4613-9f42-9fe74458d8a9",
  "case_key": "8c1ca050535e3ea3",
  "status": "resolved",
  "display_name": "Acme Corp Q4 Invoices",
  "resolution_notes": "All invoices reconciled."
}

Errors

Error responses

400bad_requestInvalid case key format, unknown status value, or a backward lifecycle transition.
401unauthorizedMissing or invalid API key.
404not_foundCase not found.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

Get Case
Case Merge & Split
List Cases