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

Creation and parent-scoped browsing follow ownership: Tasks and Records live below their Case, and Suggestions below their Playbook. Cross-Case Task and cross-Playbook Suggestion lists remain top-level inbox views. Alias operations are top-level because (ownerId, alias) identifies the namespace resource; each personal or managed Workspace namespace can assign one alias to any readable Playbook. The Playbook owner's alias is surfaced as official; a third-party alias is returned only in its namespace owner's own context. Use assignedTo=me for your Task inbox. For Suggestions, view=sent lists the ones you sent and view=inbox the ones on Playbooks you manage; both require authentication.

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.