Skip to main content
POST
Start an agent run

Authorizations

Authorization
string
header
required

Workspace API key. Create one via the dashboard or POST /v1/auth/keys.

Body

application/json
tenant_user_id
string<uuid>

Defaults to the caller's resolved subject user id, else null.

objective_id
string<uuid>
ceo_message_id
string<uuid>
task_id
string<uuid>
task_run_id
string<uuid>
parent_run_id
string<uuid>
run_type
enum<string>
default:manual
Available options:
ceo,
hermes,
worker,
tool,
maintenance,
manual
status
enum<string>
default:running
Available options:
queued,
running,
blocked,
completed,
failed,
cancelled
requested_by
object

Defaults to the calling principal (agent key, owner session, or system).

assigned_profile
string
Maximum string length: 255
agent_id
string<uuid>
model
string
Maximum string length: 255
runtime
string
Maximum string length: 255
external_runtime_id
string

Unique per (company, runtime); reusing one linked to another run returns 409.

Maximum string length: 255
objective
string
Maximum string length: 4000
metadata
object
attach_brain
boolean

Set false to skip the ambient brain capsule.

brain_knowledge_base_id
string<uuid>
brain_since_watermark
string<date-time>

Previous capsule's as_of, to receive deltas since then.

Response

Run created.

run
object
required

Serialised agent run (contracts/brain-ops.ts formatRun).

brain_capsule
object | null
required

Ambient brain capsule attached when the run has an objective and attach_brain is not false. Null when no objective, when opted out, or when the (best-effort) attach failed.