Dispatch a named repo pipeline at a ref (ADR-0043 "World B"). Authorized as a write (like [`create_run`]); a dispatch is a *trigger*, so a deploy pipeline still hits its Environment's protection rules at admission. Returns the new run id (mirrors [`CreateRunResponse`]); creates **no** run on any error.
const url = 'https://example.com/v1/repos/example/example/dispatch';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"kind":"manual","params":{},"pipeline":"example","reason":"example","ref":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/repos/example/example/dispatch \ --header 'Content-Type: application/json' \ --data '{ "kind": "manual", "params": {}, "pipeline": "example", "reason": "example", "ref": "example" }'Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Repo owner
Repo name
Request Bodyrequired
Section titled “Request Bodyrequired”POST /v1/repos/{org}/{repo}/dispatch body: dispatch a named pipeline at
a ref, supplying its declared launch parameters (ADR-0043 “World B”). Unlike
the inline POST /v1/runs escape hatch, this rides the read-at-ref → compile
→ admission machinery — a dispatched deploy hits Environment governance.
object
Which trigger to dispatch: manual (default) or api. The pipeline must
declare the matching on:.
Supplied launch parameters, name → value (ADR-0043). Resolved against
the pipeline’s interface.inputs at the resolved commit: coerced,
defaulted, validated fail-closed. Absent = none supplied.
object
The pipeline to run — a .scarab name (e.g. deploy) or a full
.scarab/*.yaml path.
Optional operator-supplied reason for this dispatch (ADR-0057 §3),
stamped as the run Headline (trigger_title). The endpoint accepts and
stamps it verbatim — it performs no requiredness check; requiredness is
an Environment ProtectionRule enforced at admission (thread D). Absent =
no headline.
The ref to dispatch at (branch/tag/sha). Resolved to a concrete commit; the run pins to that commit.
Responses
Section titled “Responses”Run created
object
Examplegenerated
{ "id": "example", "status": "example"}