--- title: "JSON-RPC 2.0 endpoint (all agent operations dispatch here)" method: POST path: "/" tags: ["JSON-RPC"] --- # JSON-RPC 2.0 endpoint (all agent operations dispatch here) `POST /` Every write or read operation on tasks, messages, and contexts uses this endpoint. The `method` field in the body selects the operation. See the *Error catalog* in the top-level description for every possible `error.code`. **Accepted methods:** `message/send`, `message/stream` *(experimental)*, `tasks/get`, `tasks/list`, `tasks/cancel`, `tasks/feedback`, `contexts/list`, `contexts/clear`. **Casing tolerance:** the server accepts both camelCase (`taskId`) and snake_case (`task_id`) in `params` — pick one and stick with it per-call. Responses are always snake_case for legacy consistency (see [`bugs/known-issues.md#wire-field-casing-is-mixed`](../bugs/known-issues.md)). **Size limit:** request bodies over 10 MB return `413 Payload Too Large` at the ASGI layer (does not use the JSON-RPC error envelope). **Idempotency:** `message/send` is NOT idempotent — a repeat call creates a new task. If you need idempotency, have your client generate a stable `messageId` and use `contexts/list` + `tasks/list` to check whether you've already sent it. ## Request body - JsonRpcRequest — JSON-RPC 2.0 request envelope. One of the per-method `params` shapes must be supplied via the `method` field. - `jsonrpc` '2.0', required - `method` 'message/send' | 'message/stream' | 'tasks/get' | 'tasks/list' | 'tasks/cancel' | 'tasks/feedback' | 'contexts/list' | 'contexts/clear', required - `id` union, required — Caller-chosen request id. The response echoes it back. - string - integer - `params` union — Method-specific params (see per-method schemas below) - MessageSendParams - `message` UserMessage, required - `role` 'user', required - `parts` MessagePart[], required - union - object - … - object - … - object - … - `kind` 'message', required - `message_id` string, uuid, required - `contextId` string, uuid — Conversation context. New contexts are created automatically when omitted; pass a previous `contextId` to continue the same conversation. - `taskId` string, uuid — Caller-provided task id. The server uses this as the outbound task's id — lets clients correlate before a response arrives. - `referenceTaskIds` string[] — Earlier tasks this task depends on. The server fetches their artifacts and makes them available to the handler as context. - `metadata` object — Free-form. Two reserved keys: - `x402.payment` — inline x402 payment submission (see the `message/send - With Payment` example). - `_payment_context` — server-injected, read-only; the verified x402 context. Do not set this yourself. - `configuration` MessageSendConfiguration - `acceptedOutputModes` string[], required — MIME types the client accepts in artifacts. Common values: `application/json`, `text/plain`, `text/markdown`. If the agent can't produce any of these, it returns `-32005 ContentTypeNotSupported`. - `blocking` boolean — If `true`, the server holds the HTTP connection open until the task reaches a terminal state. Use sparingly — most agents work asynchronously and blocking defeats that design. Short tasks (<1s) only. - `historyLength` integer — Cap `history` array in the returned task. - `pushNotificationConfig` object — [Reserved] Push-notification webhook config. Currently unsupported. - `longRunning` boolean — Hint that the task will take >60s. Some agents use this to pre-check resources before acknowledging. - `metadata` object - TasksGetParams - `taskId` string, uuid, required - `historyLength` integer — Cap `history` array in the returned task. - `metadata` object - TasksListParams — **Note on naming:** `history_length` is snake_case per the server code. Older reference specs (and the current Postman collection) use `limit`/`offset` — those are ignored. The server returns all tasks scoped to the caller's DID (or the whole agent's tasks if auth is off); pagination is tracked in [known-issues.md](../bugs/known-issues.md). - `history_length` integer — Cap `history` array per returned task. - `metadata` object - TasksCancelParams - `taskId` string, uuid, required - TasksFeedbackParams - `taskId` string, uuid, required - `feedback` string, required — Human-readable feedback text. - `rating` integer — 1 (worst) – 5 (best). - `metadata` object - ContextsListParams — **Note on naming:** `history_length` is snake_case per the server code. Reference specs and Postman show `length` — that field is silently ignored. - `history_length` integer - `metadata` object - ContextsClearParams - `contextId` string, uuid, required ## Response `200` Successful JSON-RPC response. `result` contains the typed output per method — see `components/schemas/*Result`. - JsonRpcResponse — JSON-RPC 2.0 response envelope. Exactly one of `result` or `error` is present. - `jsonrpc` '2.0', required - `id` union, required - string - integer - `result` union — Method-specific result (see per-method result schemas) - Task - `id` string, uuid, required - `context_id` string, uuid, required - `kind` 'task', required - `status` TaskStatus, required - `state` 'submitted' | 'working' | 'input-required' | 'auth-required' | 'completed' | 'failed' | 'canceled' | 'rejected', required — See the top-level description for the state machine. Terminal states (`completed`, `failed`, `canceled`, `rejected`) are immutable. - `timestamp` string, date-time, required — ISO 8601 with UTC offset, of the last state transition. - `message` HistoryMessage - `kind` 'message', required - `role` 'user' | 'assistant' | 'agent', required - `parts` MessagePart[], required - union - … - `task_id` string, uuid - `context_id` string, uuid - `message_id` string, uuid - `history` HistoryMessage[] — Conversation history for this task - `kind` 'message', required - `role` 'user' | 'assistant' | 'agent', required - `parts` MessagePart[], required - union - object - … - object - … - object - … - `task_id` string, uuid - `context_id` string, uuid - `message_id` string, uuid - `artifacts` Artifact[] — Work product. Populated as work proceeds; final result is here when state = `completed`. - `artifact_id` string, uuid, required - `name` string — Short display label, e.g. `"result"`, `"summary"`, `"sources"`. - `description` string - `parts` MessagePart[], required — Each part has its own MIME kind. The `metadata` on a part may include `did.message.signature` — a base58 Ed25519 signature the agent made over `parts[i].text` (or `data`), verifiable via the agent's DID document. - union - object - … - object - … - object - … - `metadata` object - `metadata` object - Task[] - `id` string, uuid, required - `context_id` string, uuid, required - `kind` 'task', required - `status` TaskStatus, required - `state` 'submitted' | 'working' | 'input-required' | 'auth-required' | 'completed' | 'failed' | 'canceled' | 'rejected', required — See the top-level description for the state machine. Terminal states (`completed`, `failed`, `canceled`, `rejected`) are immutable. - `timestamp` string, date-time, required — ISO 8601 with UTC offset, of the last state transition. - `message` HistoryMessage - `kind` 'message', required - `role` 'user' | 'assistant' | 'agent', required - `parts` MessagePart[], required - union - … - `task_id` string, uuid - `context_id` string, uuid - `message_id` string, uuid - `history` HistoryMessage[] — Conversation history for this task - `kind` 'message', required - `role` 'user' | 'assistant' | 'agent', required - `parts` MessagePart[], required - union - object - … - object - … - object - … - `task_id` string, uuid - `context_id` string, uuid - `message_id` string, uuid - `artifacts` Artifact[] — Work product. Populated as work proceeds; final result is here when state = `completed`. - `artifact_id` string, uuid, required - `name` string — Short display label, e.g. `"result"`, `"summary"`, `"sources"`. - `description` string - `parts` MessagePart[], required — Each part has its own MIME kind. The `metadata` on a part may include `did.message.signature` — a base58 Ed25519 signature the agent made over `parts[i].text` (or `data`), verifiable via the agent's DID document. - union - object - … - object - … - object - … - `metadata` object - `metadata` object - Context[] - `context_id` string, uuid, required - `kind` 'context', required - `role` string, required — Conversation participant role. Typically `"user"`. Some agents use `"system"` for system-managed contexts. - `name` string — Short label for UIs. - `description` string - `tasks` string[] — IDs of every task in this context. - `status` 'active' | 'paused' | 'completed' | 'archived' - `tags` string[] - `created_at` string, date-time, required - `updated_at` string, date-time, required - `parent_context_id` string, uuid — For nested conversations (threads within a thread). - `reference_context_ids` string[] - `extensions` object - `metadata` object - TasksFeedbackResult - `success` boolean, required - ContextsClearResult - `success` boolean, required - `error` JsonRpcError - `code` integer, required — Error code. See the *Error catalog* in the top-level description for the full list. - `message` string, required - `data` object — Optional structured detail — varies per error. ## Other responses - `400` — Invalid JSON-RPC request (malformed body) - `401` — Missing or invalid bearer token - `403` — Token valid but DID signature failed (when DID signing is required) - `413` — Request body exceeded the 10 MB limit - `500` — Internal error ## Changes - **2026-04-21** `8a22dc180044` — 7 breaking, 23 info - request property `method` was restricted to a list of enum values - the `jsonrpc` request property const value `2.0` was added - removed the enum value `2.0` of the request property `jsonrpc` - the `params` request property type/format changed from `object`/`` to ``/`` - …26 more - **2026-02-12** `aec28fa7bf81` — 6 breaking, 6 info - added the new required request property `id` - added the new required request property `jsonrpc` - added the new required request property `method` - removed `#/components/schemas/MessageSendRequest, #/components/schemas/TasksGetRequest, #/components/schemas/TasksListRequest, #/components/schemas/TasksCancelRequest, #/components/schemas/TasksFeedbackRequest, #/components/schemas/ContextsListRequest, #/components/schemas/ContextsClearRequest` from the request body `oneOf` list - …8 more [Change history](https://skmtc.dev/getbindu/apis/bindu-agent-api/changes/post.md) --- [API](https://skmtc.dev/getbindu/apis/bindu-agent-api.md) · [All operations](https://skmtc.dev/getbindu/apis/bindu-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/getbindu/bindu-agent-api/revisions/8a22dc180044/schema)