Launch a run
Launches a pipeline. A launch that needs approval is left awaiting approval, exactly as the Web UI would leave it; the person approves it in the web app, not through this call. The run is always launched inside an ecosystem, so X-Ecosystem-Id is required: without it the call is refused with status 400. Every run belongs to an ecosystem, for usage metering and for the runs list.
Launches a pipeline. A launch that needs approval is left awaiting approval, exactly as the Web UI would leave it; the person approves it in the web app, not through this call. The run is always launched inside an ecosystem, so X-Ecosystem-Id is required: without it the call is refused with status 400. Every run belongs to an ecosystem, for usage metering and for the runs list.
POST /api/v1/pipelines/{pipelineId}/runs
Authorization
Requires a signed-in person with this scope: runs:launch.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
X-Workspace-Id | header | yes | string (uuid) | The workspace the call acts in. Take it from the workspace list. |
X-Ecosystem-Id | header | yes | string (uuid) | The ecosystem (within the workspace named by X-Workspace-Id) the call acts in. Must belong to that workspace; an ecosystem of another workspace, or one that does not exist, is refused with no further detail. |
pipelineId | path | yes | string (uuid) | The pipeline's id. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
parameterValues | object | no | Per action id, a map of parameter name to value (Script actions only). |
Example request:
{
"parameterValues": {}
}Responses
201
The run has started.
| Field | Type | Required | Description |
|---|---|---|---|
executionId | string (uuid) | yes | |
pipelineId | string (uuid) | yes | |
status | string | yes | |
startedAt | string (date-time) | yes | |
message | string | yes |
Example response:
{
"executionId": "6d4e5f60-7182-93a4-b5c6-d7e8f9a0b1c2",
"pipelineId": "3a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
"status": "PENDING",
"startedAt": "2026-10-12T09:10:00Z",
"message": "Run started."
}202
The run is awaiting approval, so no run has started: executionId, pipelineId and startedAt are null, status is PENDING_APPROVAL, and message holds the id of the approval a person decides in the web app.
| Field | Type | Required | Description |
|---|---|---|---|
executionId | string (uuid) | yes | |
pipelineId | string (uuid) | yes | |
status | string | yes | |
startedAt | string (date-time) | yes | |
message | string | yes |
Example response:
{
"executionId": null,
"pipelineId": null,
"status": "PENDING_APPROVAL",
"startedAt": null,
"message": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90"
}400
Either pipelineId is not a valid id, or X-Ecosystem-Id is missing (ILLEGAL_ARGUMENT — see this operation's own description above).
| Field | Type | Required | Description |
|---|---|---|---|
message | string | yes | |
status | integer | yes | |
errorCode | string | yes | |
timestamp | string (date-time) | no | |
path | string | no | |
details | object | no |
404
There is no such pipeline.
| Field | Type | Required | Description |
|---|---|---|---|
message | string | yes | |
status | integer | yes | |
errorCode | string | yes | |
timestamp | string (date-time) | no | |
path | string | no | |
details | object | no |
409
Another run of this pipeline is already in progress.
| Field | Type | Required | Description |
|---|---|---|---|
errorCode | one of CONCURRENT_EXECUTION | yes | |
message | string | yes | |
blockingExecutionId | string | no | |
blockingExecutionStatus | string | no |