Skip to main content
POST
Start an Agent run

Authorizations

Authorization
string
header
required

Bearer JWT token or API Key (sk-*).

Path Parameters

agentId
string
required

Body

application/json
instruction
string
required

Instruction or mission passed to the root agent run.

Minimum string length: 1
Example:

"Review the failed deployment and prepare a rollback recommendation."

storageEntryIds
string<uuid>[]

Readable Agent-workspace storage entries attached to the first conversation message.

Maximum array length: 8
Example:
triggerType
string

Optional trigger type such as REQUEST, EVENT, or SCHEDULE.

Example:

"SCHEDULE"

triggerRefType
string

Optional external reference type for correlation.

Example:

"scheduleId"

triggerRefId
string

Optional external reference id for correlation.

Example:

"44444444-4444-4444-8444-444444444444"

scheduleFor

Optional first-dispatch deadline, from acceptance through 30 days ahead. The run is recorded immediately.

Example:

"2026-06-13T10:30:00.000Z"

state
object

Optional run-scoped state merged into the initial supervisor state.

Example:
pluginIds
string<uuid>[]

Optional registry plugin ids attached for this run.

Example:

Response

201