Requests and responses

Format

• Send JSON with Content-Type: application/json. Uploads use multipart/form-data.
• Responses are JSON objects. A single resource is wrapped in a named key ({ "case": { ... } }), and lists in a plural key ({ "cases": [ ... ] }).
• Unknown fields in a request body are rejected with 422 validation_error, so typos never pass silently.

IDs

Resources are identified by UUIDs, for example 5b0e2c1a-7d4f-4c2b-9a61-2f8e3d4c5b6a. Cases also have a human-readable case_number such as RA-2026-K7QX2, which you can use in the q search filter but not in URLs.

Timestamps and money

• Timestamps are ISO 8601 in UTC, for example 2026-10-14T15:42:07.000Z. When you send one, include an offset (Z or +00:00).
• Amounts are US dollars. Send them as JSON numbers with up to two decimals, for example 48250.00.
• A case’s balance comes back as a string holding the exact decimal (for example "48250" or "48250.5"), so no precision is lost. Ledger amounts and totals come back as numbers.

Pagination

List endpoints take take (page size) and skip (how many to skip), and return:

{
  "cases": [ ... ],
  "total": 412,
  "skip": 0,
  "take": 50,
  "has_more": true
}

Keep requesting with skip increased by take while has_more is true.

Safe concurrent updates

Cases and tasks carry a row_version. Updates must send it back as expected_row_version. If someone else changed the record since you read it, you get 409 and should re-read, re-apply your change and try again. This stops two systems from silently overwriting each other.

Idempotent writes

Recovery entries accept an idempotency_key. Re-sending the same request with the same key returns the original entry (with "replayed": true) instead of recording it twice, so retries after a network error are safe.

Long-running work

Some actions, like running the case pipeline, return 202 Accepted with a job_id. Follow the job with Background jobs.