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

_Docs version: 2026-11-10_
