Create and durably persist a new run from an inline pipeline.

POST

/v1/runs

curl --request POST \
  --url https://example.com/v1/runs \
  --header 'Content-Type: application/json' \
  --data '{ "params": {}, "pipeline": { "budget": 1, "interface": {}, "ir_version": 1, "steps": [ { "command": [ "example" ], "env": { "additionalProperty": "example" }, "id": "example", "image": "example", "inputs": [ "example" ], "k8s_overlay": {}, "needs": [ "example" ], "outputs": [ "example" ], "placement_profiles": [ "example" ], "resources": {}, "retry": {}, "secrets": [ "example" ], "security": {}, "services": {}, "timeout": 1, "uses": [ "example" ] } ] }, "reason": "example" }'

Request Body^required

Media typeapplication/json

POST /v1/runs body: an inline pipeline to run immediately, plus any launch parameters (ADR-0043) declared by the pipeline’s interface.

object

params

Supplied launch parameters, name → value (ADR-0043). Resolved against pipeline.interface.inputs at creation: coerced to the declared types, defaults applied, validated fail-closed. Absent = none supplied.

object

pipeline

required

The inline pipeline (IR subset).

object

budget

Opt-in run budget in seconds (ADR-0047): the run fails once its active time (gate-suspended time excluded) exceeds this. No default.

integer | null format: int32

interface

The pipeline’s launch/reuse interface (ADR-0038, 0043) — its declared typed parameters (inputs) and exposed outputs. Carried as the pure scarab_pipeline::Interface (opaque object in the schema; the pure crate cannot derive ToSchema). Absent = no parameters.

object

ir_version

required

IR schema version (ADR-0022).

integer format: int32

steps

required

Array<object>

One step (IR subset): the step contract is an OCI image + command.

object

command

Array<string>

env

object

key

additional properties

string

id

required

string

image

required

string

inputs

Explicit input workspaces (ADR-0007): the subset of needs whose output workspace this step consumes. Absent = implicit-by-default (inherit every need’s workspace). Naming a subset both restricts what flows in and sharpens restart invalidation — the skip-if-unchanged signature is then computed over exactly these inputs (mirrors scarab_pipeline::StepSpec).

Array<string> | null

k8s_overlay

Governed raw pod-spec overlay (ADR-0055). Carries no authority; an inline API run targets no Environment, so any overlay is rejected fail-closed.

object

needs

Array<string>

outputs

Explicit output workspace paths (ADR-0007): the workspace-relative paths this step publishes downstream. Absent = the whole workspace. A declared path the step did not produce fails the step (fail-closed), so this is a contract, not a filter (mirrors scarab_pipeline::StepSpec).

Array<string> | null

placement_profiles

PlacementProfile names this step runs on (ADR-0055); their admin-defined k8s overlays merge onto the Pod in listed order. Empty = the default profile.

Array<string>

resources

Requested compute resources (ADR-0055): exact cpu_millis/memory_mib.

object

retry

Opt-in retry policy {on, max} (ADR-0047). ⚠ At-least-once: retry re-runs the whole step at-least-once; enable only if the step is idempotent or fenced against a cooperating sink. Never-started infra failures auto-retry regardless.

object

secrets

Secret keys to resolve and inject at launch (ADR-0037).

Array<string>

security

Privilege escalation requested above the hardened baseline (ADR-0039). On an inline API run only the self-service run_as_root grant is admitted (it stays inside the sandbox); governed grants (add-capabilities / privileged) require a target Environment and are rejected fail-closed.

object

services

Sidecar services (ADR-0058): throwaway backing containers co-located in this step’s Pod, reachable at localhost:<port>, with an optional readiness probe gating the step’s main container start.

object

timeout

Per-step execution deadline in seconds (ADR-0047). Absent = the global default (1h). Exceeding it is a Timeout failure.

integer | null format: int32

uses

Shared-service opt-in (ADR-0058): names of pipeline-level shared services this step reaches over the network (DNS <name>:<port> + readiness gate).

Array<string>

reason

Optional caller-supplied reason for this inline run (ADR-0057 §3), stamped as the run Headline (trigger_title) for this api-style dispatch. Accepted and stamped verbatim, no requiredness check. Absent = no headline.

string | null

Example^generated

{
  "params": {},
  "pipeline": {
    "budget": 1,
    "interface": {},
    "ir_version": 1,
    "steps": [
      {
        "command": [
          "example"
        ],
        "env": {
          "additionalProperty": "example"
        },
        "id": "example",
        "image": "example",
        "inputs": [
          "example"
        ],
        "k8s_overlay": {},
        "needs": [
          "example"
        ],
        "outputs": [
          "example"
        ],
        "placement_profiles": [
          "example"
        ],
        "resources": {},
        "retry": {},
        "secrets": [
          "example"
        ],
        "security": {},
        "services": {},
        "timeout": 1,
        "uses": [
          "example"
        ]
      }
    ]
  },
  "reason": "example"
}

Responses

201

Run created

Media typeapplication/json

object

id

required

string

status

required

string

Example^generated

{
  "id": "example",
  "status": "example"
}