Conventions

Protected /v1 endpoints take Authorization: Bearer <access-token> and JSON request bodies. The API validates public request shapes, resolves caller and workspace context, then delegates to the domain services; it owns no product storage itself.

Core endpoint map

Tasks and Records are top-level resources carrying caseId; their APIs are not duplicated below /v1/cases/:id. This makes assigned-Task inboxes and cross-Case Record feeds first-class.

Context and pagination

Supported administrative endpoints take workspaceId as a query parameter. Product-domain routes resolve the actor context from the bearer credential. Never assume that a locally selected CLI workspace applies to a raw HTTP request.

List operations use pageSize and an opaque cursor. Preserve the cursor exactly; do not construct or decode it. Records use stable (createdAt, id) ordering and accept order=asc|desc. Record filters always intersect the caller's live Case access.

Mutations

Mutation bodies carry idempotencyKey. Reuse a key only for an identical request after a network failure or uncertain response. Case and Task mutations include expectedLockVersion; Playbook publication includes baseVersionId. A mismatch returns a conflict so the client can re-read and rebuild intent from fresh state.

Close Task and close Case requests may include new Records, allowing the state transition and final durable outputs to commit together.

Errors

Retry 429 and transient 5xx responses with bounded exponential backoff. Do not automatically retry validation, authorization, or conflict responses. For a conflict, read current state and obtain human or agent judgment before issuing a new mutation.