Skip to main content
POST
Start a workflow run

Authorizations

Authorization
string
header
required

Enforced on every transport, with no exempt operation. A person's request — over the default local unix socket exactly as over a TCP listener — must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011. The socket's file permissions are transport and are not an authorisation.

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.

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>