v4
latestOpenAPI 3.1.02026-08-0453110161.5 KBRpc Dispatch
Dispatch JSON-RPC 2.0 requests for the unified /rpc POST endpoint.
Supported methods: initialize — MCP-aligned session initialisation (no session header needed) notifications/initialized — client acknowledgement after initialize (requires session header) message/send — send a user message (session header optional for backward compat)
Error envelope (camelCase via AssistantGatewayMixin):
{"jsonrpc": "2.0", "id": <id>, "error": {
"code": <int>, "message": <str>,
"data": {"category", "kind", "retryable",
"resetAt", "retryAfter", "userMessage"}}}
See docs/source/domains/assistant-gateway/concepts/error-contract.md for full field semantics, per-category data.kind registry, and rendering guidance. The rationale lives in Decision 006 (docs/source/domains/assistant-gateway/decisions/decisions-006-error-taxonomy.md).
Error codes — five canonical categories plus the JSON-RPC envelope error:
-32600 Invalid Request — a structurally valid JSON-RPC envelope that is
not a usable request (unknown method, request missing its id, or
params/blocks that fail the per-method model). Bare shape, no
``data`` block; not one of the five canonical categories. An
unparseable body is rejected as HTTP 422 *before* this handler
(we do not emit -32700); unknown method is folded here rather
than -32601 (see Decision 006 §"What carries a JSON-RPC envelope").
-32602 validation — input shape, length, file size, structural limit
breach; see Decision 003 and Decision 006.
-32001 quota — token or turn quota exhausted; carries
``data.resetAt``; see Decision 005 and Decision 006.
-32002 safety — code-of-conduct or content-policy violation;
see Decision 006.
-32003 rate_limit — application-level concurrency or per-turn caps
(``concurrent_sessions`` per-member session cap at initialize,
``concurrent_conversations``, ``tool_calls_per_turn``,
``task_agents_per_input``). Distinct from Cloud Armor
transport-level rate limits.
-32603 internal — unanticipated server failure (incl. the
process/fleet-wide session backstop); assistant state
transactionally reverts so the next ``message/send`` is safe.
Clients should code defensively against all five canonical codes so that a future enforcement-mode change requires no client-side update.
Path parameters
Headers
Request body
Response
JSON-RPC 2.0 response. HTTP status is always 200 for any request that reaches the dispatcher; success vs error is signalled by the presence of result vs error in the body. On error, error.code is one of: -32600 Invalid Request, -32602 validation, -32001 quota, -32002 safety, -32003 rate_limit, -32603 internal. See the error contract reference for envelope shape and per-category data.kind registry. Non-200 responses (401/403 auth, 422 malformed body, 404 unknown route, 429 edge rate-limit/capacity) are resolved before the JSON-RPC envelope exists and are not part of this body contract.