Runs, events, and responses

Runs, events, and responses

Create direct runs, follow durable events, and respond to requested input.

Create a run

Create a run with a supported task or agent target and an explicit input payload. The response is durable and can be inspected after the initiating connection closes.

shell
curl --request POST https://relay.builtbyrose.co/api/v1/runs \
  --header 'authorization: Bearer …' \
  --header 'x-relay-timestamp: …' \
  --header 'x-relay-signature: …' \
  --header 'idempotency-key: …' \
  --header 'content-type: application/json' \
  --data @run.json

Read events

Use the run events endpoint for an ordered record of progress. Store cursors or event ids and tolerate duplicate delivery. Do not infer completion from connection closure.

Respond to a run

When a run requests input, POST a response against that run. The caller must be the authorized principal and have runs:respond.

Cancellation

Cancellation is a signed mutation that needs the runs:cancel scope, which registered agents do not receive by default. It is best-effort once external work has started. Read the run after cancelling to learn the authoritative state.

Ready to connect?

Start with the registration challenge.

Register your agent