Protocol guide
Use the contract. Keep authority server-owned.
These are the API-wide rules that apply across endpoint families. Product architecture and Business App Engine explanation live elsewhere; this guide covers only developer protocol semantics.
Language: The default documentation edition is American English. Exact paths, JSON fields, OAuth scopes, schema names, enum values, and error codes remain verbatim wire identifiers and are not localized.
Authentication and authority
Authorization Code + PKCE is the delegated human flow. Personal Memory V2, Session and Continuity operations, project-membership administration, and authorized issuer binding are PKCE-only.
Client Credentials is a bounded service-principal flow. A service principal acts only as itself. It cannot manufacture a human principal, human approval, membership, Work participation, or personal Memory authority.
An OAuth scope is necessary but never sufficient. Organization, project, workspace, Work, Case, Installation, object, Cognitive Contract, evidence, human-participation, budget, and other backend authorities remain independently enforced.
Errors and refusals
Canonical launch failures use application/problem+json with type, title, status, detail, instance, code, traceId, and retryable.
The machine-readable code expresses a customer-safe reason. traceId is a correlation handle, not an authority token. Internal exception strings, component topology, storage coordinates, and worker details do not belong in the public refusal contract.
Some Session/Continuity refusal details remain intentionally absent from endpoint examples until the canonical runtime error-envelope migration is adjudicated.
Idempotency and preconditions
Where an operation declares Idempotency-Key, callers should reuse the same key only for the same logical mutation. Idempotency does not bypass revision checks, acceptance, role authority, or governance.
Expected-version or expected-revision fields are authority preconditions, not hints. Scheduled Work version commands, for example, can refuse with HTTP 428 when the required expected charter version is absent.
Durable asynchronous work
A timeout is not cancellation. Work, Runs, Scheduled Work, and Parallel Cognition can outlive the HTTP connection that initiated or inspected them.
Persist returned resource identities and re-read authoritative state after connection loss. Cancellation is an explicit governed transition exposed only where the stable public abstraction permits it. Raw durable Jobs remain internal orchestration substrate.
Compatibility
Compatibility routes remain discoverable without defining the canonical product model. Memory V1, root Session mutation aliases, and /start, POST /chat, and GET /history are not substitutes for the canonical Memory V2, Work, Session/Continuity, and Run resource grammar.