REST API guide

The REST API gives you the same operations the app uses. This guide covers the conventions; for every operation's fields, see the Swagger reference or the live OpenAPI document.

Base URL and authentication#

https://app.custodycommander.com/api/v1

Authenticate every request with a personal API token:

export CASE_COMMANDER_URL="https://app.custodycommander.com"
export CASE_COMMANDER_API_TOKEN="cc_live_…"   # keep this out of shell history and code

curl "$CASE_COMMANDER_URL/api/v1/case" \
  -H "Authorization: Bearer $CASE_COMMANDER_API_TOKEN"

Cookies are never used for API authentication. A missing or invalid token returns 401 with a WWW-Authenticate: Bearer header.

Cases and court cases#

Two IDs appear everywhere:

• caseId — your case (the matter). Get it from GET /case.
• courtCaseId — one court file inside it. Get them from GET /court-cases?caseId=….

Evidence, documents, to-dos, the timeline, hearings, and messages accept an optional courtCaseId to narrow to one court file; leave it out to cover the whole case.

Working in a shared case#

Requests use your own case by default. To work in a case someone shared with you, send an X-Case-Context header — matter:<caseId> (or ws:<workspaceId>). POST /workspaces/switch returns the value to use. The header selects which view you're working in; the token's access and your sharing permissions still apply.

curl "$CASE_COMMANDER_URL/api/v1/case" \
  -H "Authorization: Bearer $CASE_COMMANDER_API_TOKEN" \
  -H "X-Case-Context: matter:CASE_ID"

Requests and responses#

• Send JSON bodies with Content-Type: application/json (up to 4 MB). File uploads use multipart/form-data.
• Responses are the same JSON the app receives — there's no wrapper. Some list endpoints return a bare array (GET /evidence); others return an object.
• File downloads stream as binary with a Content-Disposition filename.
• Creates usually return 201.
• Every response includes x-api-operation (the operation ID) and cache-control: no-store.

Errors#

Errors return JSON with an error message and usually a code:

{ "error": "This operation requires evidence:write.", "code": "insufficient_scope" }

Rate limits#

• 120 requests per minute per account, shared by every token and by REST and MCP together. The window resets on the clock minute; a 429 includes Retry-After.
• Built-in AI operations are also limited to 20 per 10 minutes per user, as in the app.

Pagination#

Most list endpoints return everything you can see. The exceptions:

• GET /messages returns up to 2,000 messages per call — pass offset for the next page.
• GET /documents/{id}/versions returns 50 versions per page with nextCursor; pass it back as before.

Safe retries and conflicts#

There are no idempotency keys, so don't automatically retry a change after a timeout — read the resource first to see whether it went through. Some operations protect against overwriting someone else's changes:

• PATCH /documents and version restore accept expectedUpdatedAt.
• POST /preparation requires the current revision.
• Court-document operations require expectedHash.

A mismatch returns 409.

Uploading files#

Uploads use multipart/form-data. Limits: 25 MB per file, 30 files and 32 MB per request.

Examples#

curl "$CASE_COMMANDER_URL/api/v1/court-cases?caseId=CASE_ID" \
  -H "Authorization: Bearer $CASE_COMMANDER_API_TOKEN"

curl -X POST "$CASE_COMMANDER_URL/api/v1/folders" \
  -H "Authorization: Bearer $CASE_COMMANDER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"caseId":"CASE_ID","name":"School expenses","kind":"evidence"}'

curl "$CASE_COMMANDER_URL/api/v1/evidence" \
  -H "Authorization: Bearer $CASE_COMMANDER_API_TOKEN" \
  -F "caseId=CASE_ID" -F "folderId=FOLDER_ID" -F "courtCaseId=COURT_CASE_ID" \
  -F "files=@./receipt.pdf"

curl -X PATCH "$CASE_COMMANDER_URL/api/v1/evidence/EVIDENCE_ID" \
  -H "Authorization: Bearer $CASE_COMMANDER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folderId":"FOLDER_ID","tagNames":["expenses"],"description":"School receipt","eventDate":"2026-08-21","exhibitNumber":"07"}'

curl -X POST "$CASE_COMMANDER_URL/api/v1/hearings" \
  -H "Authorization: Bearer $CASE_COMMANDER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"caseId":"CASE_ID","courtCaseId":"COURT_CASE_ID","date":"2026-11-03","time":"09:30","purpose":"Status review"}'

curl -X POST "$CASE_COMMANDER_URL/api/v1/todos" \
  -H "Authorization: Bearer $CASE_COMMANDER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"caseId":"CASE_ID","title":"Gather school records","due":"2026-10-15","courtCaseId":"COURT_CASE_ID"}'

curl -G "$CASE_COMMANDER_URL/api/v1/timeline" \
  -H "Authorization: Bearer $CASE_COMMANDER_API_TOKEN" \
  --data-urlencode "caseId=CASE_ID" \
  --data-urlencode "kinds=event,hearing" \
  --data-urlencode "years=2025,2026"

curl "$CASE_COMMANDER_URL/api/v1/messages/import" \
  -H "Authorization: Bearer $CASE_COMMANDER_API_TOKEN" \
  -F "caseId=CASE_ID" -F "attest=yes" -F "platform=sms" \
  -F "file=@./sms-backup.xml"

curl -o receipt.pdf "$CASE_COMMANDER_URL/api/v1/files/FILE_ID" \
  -H "Authorization: Bearer $CASE_COMMANDER_API_TOKEN"

Operations by area#

There are 140 operations. Paths are relative to /api/v1; the ability needed is <area>:read for GET and <area>:write otherwise.

For plan and usage information, use GET /billing/status rather than GET /account.

Not available through the API#

Sign-up, sign-in, password reset, and email verification (integrations use tokens instead), payment webhooks, analytics beacons, and the MCP and OpenAPI transports themselves.

Versioning#

There's one version, v1. The operation catalog is generated from the app's own routes, so new app features appear in the API as they ship. Regenerate your client from the live OpenAPI document when you upgrade. Request fields in the reference are discovery hints; the server validates the full request.