---
title: "Send a JSON-RPC request"
method: POST
path: "/api/v1beta1/assistant/trademe/conversations/{conversation_id}/rpc"
tags: ["v1beta1"]
---

# Send a JSON-RPC request

`POST /api/v1beta1/assistant/trademe/conversations/{conversation_id}/rpc`

## Request

- Base URL: `https://api.trademeai.co.nz` (the document declares no server; this is the origin it was published from)
- URL: `https://api.trademeai.co.nz/api/v1beta1/assistant/trademe/conversations/{conversation_id}/rpc`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/trademeai/apis/trade-me-ai-platform/docs/api/v1beta1/assistant/trademe/conversations/:conversation_id/rpc/post.ts> (a function with typed inputs; its response is checked against the schema)

The single entry point for a session and for talking to the assistant. Set `method` to `initialize` (open a session), `notifications/initialized` (confirm it), `message/send` (send the member's message) or `action/invoke` (run a button's action; v1alpha1 only). See the request examples for each. Send the `Anvil-Session-Id` header returned by `initialize` on the other calls.

Any request that reaches this endpoint answers HTTP 200. Success carries `result` and failure carries `error`.

Error bodies are described in the [error contract](https://trademe.gitlab.io/shared/projects/ai-engineering/anvil/anvil/domains/assistant-gateway/concepts/error-contract.html).

## Path parameters

- `conversation_id` string, required

## Headers

- `Anvil-Session-Id` string, nullable
- `authorization` string, nullable

## Request body

- AnyRpcRequest: Flexible JSON-RPC 2.0 envelope — dispatches to per-method sub-handlers. ``method`` accepts any string so that the dispatch handler can return an appropriate -32600 (Invalid Request) for unrecognised methods rather than letting Pydantic raise a 422 before the handler runs. ``id`` is optional because JSON-RPC 2.0 notifications (e.g. ``notifications/initialized``) do not include an id field. ``params`` is validated per-method inside the dispatch handler.
  - `jsonrpc` '2.0', required
  - `id` union
    - string
    - integer
  - `method` string, required
  - `params` object, nullable

## Response `200`

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, -32004 action, -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.

- RpcResponse: Single JSON-RPC 2.0 response envelope — always HTTP 200. Exactly one of result/error is non-None on a valid response. Both fields are kept optional so one model covers success and error shapes. response_model_exclude_none=True on the route omits the absent field from the wire format per JSON-RPC 2.0 §5.
  - `jsonrpc` '2.0'
  - `id` union, required
    - string
    - integer
  - `result` union
    - RpcResultPayload: Successful result payload returned inside the JSON-RPC envelope.
      - `messageId` string, required
    - RpcActionInvokeResult: Successful result of ``action/invoke``. ``outcome`` is built from the receipt, so a replay carries it too. ``artifact_versions`` is empty on a replay and when no card needed updating.
      - `action` string, required
      - `receiptId` string, required
      - `replayed` boolean, required
      - `outcome` RpcActionOutcome, required: The block to draw in place of the tapped container, and what the tap changed (``changes``, may be empty).
        - `status` 'done', required
        - `block` NonBindingActionBlock, required: A container a member can act from, whose action takes effect at once with no confirm step. :ivar id: Opaque hex Anvil makes, so a later push can name this container. Never sent back. :ivar participant_id: The member the action is for, the same id as a message's ``author.memberId``. A shared conversation shows every card to everyone, so an app draws the action only for that member. :ivar artifact_uri: Set only on an inline reply offer, so an app can match an ``artifact/updated`` push for that artifact to this container. Left out of the wire form when ``None``.
          - `children` union[]
            - union
              - …
          - `type` 'non_binding_action'
          - `version` '1'
          - `id` string, required
          - `participantId` string, required
          - `artifactUri` string, nullable
        - `changes` object[], required
      - `artifactVersions` ArtifactVersionRef[], required
        - `artifactId` string, required
        - `versionId` string, required
  - `error` RpcErrorDetail: Error object per JSON-RPC 2.0 spec.
    - `code` integer, required
    - `message` string, required
    - `data` object, nullable

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-12** `1164c8a5c534`: 2 breaking, 2 info
  - added `#/components/schemas/WatchlistToggleBlock` to the `result/oneOf[subschema #2: _RpcActionInvokeResult]/outcome/block/children/items/` response property `oneOf` list for the response status `200`
  - added `#/components/schemas/WatchlistToggleBlock` to the `result/oneOf[subschema #2: _RpcActionInvokeResult]/outcome/block/children/items/oneOf[subschema #4: PendingStateBlock]/children/items/` response property `oneOf` list for the response status `200`
  - added `watchlist_toggle` discriminator mapping keys to the `result/oneOf[subschema #2: _RpcActionInvokeResult]/outcome/block/children/items/` response property for the response status `200`
  - added `watchlist_toggle` discriminator mapping keys to the `result/oneOf[subschema #2: _RpcActionInvokeResult]/outcome/block/children/items/oneOf[subschema #4: PendingStateBlock]/children/items/` response property for the response status `200`
- …earlier changes not shown

[Operation history](https://skmtc.dev/trademeai/apis/trade-me-ai-platform/changes/api/v1beta1/assistant/trademe/conversations/:conversation_id/rpc/post.md)

---

[API](https://skmtc.dev/trademeai/apis/trade-me-ai-platform.md) - [All operations](https://skmtc.dev/trademeai/apis/trade-me-ai-platform/llms.txt) - [OpenAPI document](https://skmtc.dev/trademeai/apis/trade-me-ai-platform/revisions/1164c8a5c534?raw)