Workflow start request

Start a workflow, optionally with per-run overrides

Endpoint

PUT /api/workflow/start/

Auth

Authorization: Bearer ${token}

Query Parameters

Key	Default	Description
identity		The workflow to start
fit	`false`	Cap every step's `cpu` and `memory` to the host capacity, and match its `gpu` to the host
link	`false`	Assign a link to every step declaring one

fit caps each step's cpu and memory to the engine host's core count and total memory, and matches its gpu to the cards the host holds, so a resource the host cannot satisfy no longer fails the start.

Applied after the override body — a resource.<step>.cpu set too high is capped too.
Holds for that start only; never written back to workflow.ini.
Steps already within the host's capacity are left untouched.

A gpu is matched by vendor: nvidia/cuda needs an NVIDIA card, amd/rocm an AMD one, and all either. Ask for a vendor the host does not have while it holds the other and the request switches over — nvidia on an AMD-only host becomes amd. Only a host with no GPU at all drops it to none, leaving the step on CPU. Detection asks the vendor tooling (nvidia-smi, rocm-smi) rather than the PCI inventory, so a card whose driver is not installed counts as absent.

link assigns a link to every step declaring one under link in the definition, while the license carries any. Left out, the start runs the steps with their declared links idle. The response entity lists what the workflow holds under links, each entry carrying step, port, name and host.

Body

Optional. A JSON object of override values written to the workflow's workflow.ini before it starts. When omitted, the existing workflow.ini (if any) is used unchanged.

Keys are <category>.<step>.<key>, scoped to a step by its name:

Category	Key form	Replaces
`volume`	`volume.<step>.<volume-name>`	Host side of a named volume
`port`	`port.<step>.<port-name>`	Host side of a named port
`env`	`env.<step>.<VAR>`	An environment variable
`resource`	`resource.<step>.<cpu\|memory\|gpu>`	A resource limit

Overrides are applied only at launch and never modify the definition. An unknown step / volume / port name, or an invalid cpu/memory/gpu value, fails the start. A volume value is a host path, resolved like the one in the definition: relative to the engine's directory, so ./volume/data is the data/ of Artifacts.

Resource key	Accepts
`cpu`	A core count, fractions allowed
`memory`	A byte count with an optional single-letter unit, case-insensitive and binary: `b`, `k` (KiB), `m` (MiB), `g` (GiB) — so `8g` is 8 GiB, while a bare `8` is 8 bytes, not gigabytes
`gpu`	One of `nvidia`, `cuda`, `amd`, `rocm`, `all`, or `none`

Every resource key also accepts none, which means ignore this parameter — the step runs with no limit for it. It is how an override lifts a limit the definition sets, and it is what fit writes for a gpu on a host holding none. none is an engine-side value and never reaches the runtime.

Json

{
    "override": {
        "volume.step-name.data": "/mnt/host/data",
        "env.step-name.KEY": "value",
        "resource.step-name.cpu": "8",
        "resource.step-name.memory": "8g",
        "resource.step-name.gpu": "none"
    }
}

Response

Json

[
    {
        "kind": "status",
        "payload": {
            "code": 0,
            "message": ""
        }
    },
    {
        "kind": "",
        "payload": ""
    },
    {
        "kind": "entity",
        "payload": {
            "created_at": 0,
            "identity": "",
            "links": [
                {
                    "host": "",
                    "name": "",
                    "port": "",
                    "step": ""
                }
            ],
            "name": "",
            "status": "",
            "tags": [
                ""
            ]
        }
    }
]

Notes

Workflow Permission Required

Workflow signals request

Stream workflow events in real-time

Workflow stop request

Stop a running workflow