curl --request POST \
  --url http://localhost:3773/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "What is the capital of France?"
        }
      ],
      "kind": "message",
      "message_id": "550e8400-e29b-41d4-a716-446655440002",
      "contextId": "550e8400-e29b-41d4-a716-446655440003",
      "taskId": "550e8400-e29b-41d4-a716-446655440004"
    },
    "configuration": {
      "acceptedOutputModes": [
        "application/json",
        "text/plain",
        "text/markdown"
      ]
    }
  }
}
'

{
  "jsonrpc": "2.0",
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440004",
    "context_id": "550e8400-e29b-41d4-a716-446655440003",
    "kind": "task",
    "status": {
      "state": "submitted",
      "timestamp": "2026-04-19T18:30:00.000000+00:00"
    },
    "history": [
      {
        "kind": "message",
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "What is the capital of France?"
          }
        ],
        "task_id": "550e8400-e29b-41d4-a716-446655440004",
        "context_id": "550e8400-e29b-41d4-a716-446655440003",
        "message_id": "550e8400-e29b-41d4-a716-446655440002"
      }
    ],
    "artifacts": [],
    "metadata": {}
  }
}

JSON-RPC

JSON-RPC 2.0 endpoint (all agent operations dispatch here)

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.

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.

POST

curl --request POST \
  --url http://localhost:3773/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "What is the capital of France?"
        }
      ],
      "kind": "message",
      "message_id": "550e8400-e29b-41d4-a716-446655440002",
      "contextId": "550e8400-e29b-41d4-a716-446655440003",
      "taskId": "550e8400-e29b-41d4-a716-446655440004"
    },
    "configuration": {
      "acceptedOutputModes": [
        "application/json",
        "text/plain",
        "text/markdown"
      ]
    }
  }
}
'

{
  "jsonrpc": "2.0",
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440004",
    "context_id": "550e8400-e29b-41d4-a716-446655440003",
    "kind": "task",
    "status": {
      "state": "submitted",
      "timestamp": "2026-04-19T18:30:00.000000+00:00"
    },
    "history": [
      {
        "kind": "message",
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "What is the capital of France?"
          }
        ],
        "task_id": "550e8400-e29b-41d4-a716-446655440004",
        "context_id": "550e8400-e29b-41d4-a716-446655440003",
        "message_id": "550e8400-e29b-41d4-a716-446655440002"
      }
    ],
    "artifacts": [],
    "metadata": {}
  }
}

Authorizations

Authorization

string

header

required

OAuth2 access token issued by Ory Hydra. Required for most operations.

Scopes:

agent:read — Read-only operations (tasks/get, tasks/list, contexts/list)
agent:write — Write operations (message/send, tasks/cancel, contexts/clear)
agent:execute — (legacy) Both read and write access

How to obtain:

Register your client with Hydra
Complete OAuth2 client credentials or authorization code flow
Include token in Authorization: Bearer <token> header

Body

application/json

JSON-RPC 2.0 request envelope. One of the per-method params shapes must be supplied via the method field.

jsonrpc

string

required

Allowed value: "2.0"

method

enum<string>

required

Available options:

message/send,

message/stream,

tasks/get,

tasks/list,

tasks/cancel,

tasks/feedback,

tasks/pushNotificationConfig/set,

tasks/pushNotificationConfig/get,

tasks/pushNotificationConfig/list,

tasks/pushNotificationConfig/delete,

contexts/list,

contexts/clear

id

required

Caller-chosen request id. The response echoes it back.

params

object

Method-specific params (see per-method schemas below)

Show child attributes

Response

Successful JSON-RPC response. result contains the typed output per method — see components/schemas/*Result.

JSON-RPC 2.0 response envelope. Exactly one of result or error is present.

jsonrpc

string

required

Allowed value: "2.0"

id

required

result

object

Method-specific result (see per-method result schemas)

Option 1 · object
Option 2 · object[]
Option 3 · object[]
Option 4 · object
Option 5 · object

Show child attributes

error

object

Show child attributes

HEAD the agent card

Resolve a DID (via query string)