Start a workflow run

Starts a deterministic orchestration of multiple agents from a script — by path or inline source — with arguments. The script runs in the host’s confined runtime: no filesystem, no network, no module loading; only the agent API the host provides. Script validation failures return 422 NRY-0010 before anything executes. Progress streams as workflow-progress events. A hosted home runs every session inside a container. A run there that names no environment opens its session as createSession does: with a container of its own made at its first turn, or, naming a repository in clone, made with that clone before the run starts.

POST /v1/workflows/runs

Start a workflow run

cURL

curl --request POST \
  --url https://api.example.com/v1/workflows/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "scriptPath": "/Users/dev/repos/midaz/.narya/workflows/release.js",
  "args": [
    "--dry-run"
  ]
}
'

202

{
  "id": "2d4e6f8a-0b2c-4d6e-8f0a-2b4c6d8e0f2a",
  "status": "running",
  "args": [
    "--dry-run"
  ],
  "steps": [
    {
      "name": "run-tests",
      "status": "completed",
      "output": "412 tests passed"
    },
    {
      "name": "build-artifacts",
      "status": "running"
    }
  ],
  "startedAt": "2026-08-08T13:00:00.000Z"
}

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

Option 1

Option 2

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

environment · string

Run the session this run opens, and with it every step and delegate, inside this environment, which must already exist (createEnvironment). Absent means the host's own machine on a person's own home, and a container of the session's own on a hosted home (createSession).

Required string length: 1 - 64

Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$

clone · string

A repository to clone into the run session's own container before the run starts, exactly as createSession's clone: on a hosted home, without environment, and the session's repository.

Maximum string length: 200

Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*$

setupScript · string

Run once in place of the clone's own .narya/setup.sh, as createSession's setupScript. Only with clone (422 otherwise).

Required string length: 1 - 65536

Response

202

application/json

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[]

Show child attributes

error · object

Present when the run itself failed outside any step.

Show child attributes

Example:

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

startedAt · string<date-time>

finishedAt · string<date-time>