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.
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.jsonRead 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.