Protocol v2 Command

Send a single protocol command scoped to a thread. The request body is a ProtocolCommand envelope with a method (e.g. run.start, input.respond, agent.getTree) and method-specific params. The response is either a ProtocolSuccess (with method-specific result) or a ProtocolError.

Commands that create runs (run.start, input.respond) leave the run executing in the background on the worker queue. Event streaming for that run is observed via a concurrent POST /threads/{thread_id}/stream/events connection.

WebSocket clients use the same command envelope in-band on /threads/{thread_id}/stream/events and additionally have access to subscription.subscribe / subscription.unsubscribe over the same connection.

POST /threads/{thread_id}/commands

Protocol v2 Command

cURL

curl --request POST \
  --url https://api.example.com/threads/{thread_id}/commands \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": 1,
  "method": "<string>",
  "params": {}
}
'

200

{
  "type": "<string>",
  "id": 1,
  "result": {},
  "meta": {
    "applied_through_seq": 1
  }
}

Path Parameters

thread_id · string<uuid> · required

The ID of the thread the command applies to.

Body

application/json

A client → server command envelope. Known methods: run.start, input.respond, subscription.subscribe (WS only), subscription.unsubscribe (WS only), agent.getTree.

id · integer · required

Client-assigned command id; echoed in the response.

Required range: x >= 0

method · string · required

Command method name (e.g. run.start).

params · object

Method-specific parameters. See the CDDL spec for per-method shapes.

Response

200

application/json

Protocol response — either ProtocolSuccess or ProtocolError.

ProtocolSuccess

ProtocolError

Successful command response.

type · string · required

Allowed value: "success"

id · integer · required

Required range: x >= 0

result · object · required

Method-specific result payload.

meta · ProtocolResponseMeta · object

Optional metadata attached to command responses.

Show child attributes