Skip to main content
POST
Start a workflow run

Body

application/json

Request to start a workflow run from a script — exactly one of scriptPath or source.

scriptPath
string
required

Absolute path of the workflow script on this machine.

Maximum string length: 4096
source
string

Inline workflow script source.

args
string[]

Arguments passed to the script.

Maximum array length: 64

Response

Run accepted and starting; watch events or poll the run.

A deterministic orchestration run with per-step progress.

id
string<uuid>
required
status
enum<string>
required
Available options:
pending,
running,
completed,
failed,
stopped
scriptPath
string

Reserved response field. The current host snapshots a local path into the run's stored source and does not retain or return the path, so this field is absent for both source forms.

Maximum string length: 4096
sessionId
string<uuid>

The session the run's agents work in, so their transcripts can be read back after the run and after a restart. Absent until the run has started one, and cleared if that session is later purged.

args
string[]
steps
object[]
error
object

Present when the run itself failed outside any step.

Example:
startedAt
string<date-time>
finishedAt
string<date-time>