Pipelines API Reference¶

Base path: /api/v1/pipelines

All endpoints require a valid JWT bearer token. Include the Authorization: Bearer <token> header on every request.

Pipeline Object¶

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "deploy-to-production",
  "description": "Runs tests, approval gate, then deploys.",
  "stages": [
    {
      "id": "stage-1",
      "name": "Run tests",
      "type": "script",
      "order": 1,
      "config": { "command": "npm test" }
    }
  ],
  "organizationId": null,
  "createdBy": "user-uuid",
  "createdAt": "2026-03-16T00:00:00.000Z",
  "updatedAt": "2026-03-16T00:00:00.000Z"
}

Pipeline Run Object¶

{
  "id": "run-uuid",
  "pipelineId": "pipeline-uuid",
  "status": "succeeded | queued | running | waiting_approval | failed | cancelled",
  "triggeredBy": "user-uuid",
  "startedAt": "2026-03-16T00:00:00.000Z",
  "finishedAt": "2026-03-16T00:00:05.000Z",
  "durationMs": 5000,
  "logs": "Stage 1 started...\nStage 1 succeeded.\n",
  "stageResults": [
    {
      "stageId": "stage-1",
      "status": "succeeded",
      "startedAt": "2026-03-16T00:00:00.000Z",
      "finishedAt": "2026-03-16T00:00:02.000Z",
      "output": ""
    }
  ],
  "createdAt": "2026-03-16T00:00:00.000Z",
  "updatedAt": "2026-03-16T00:00:05.000Z"
}

Endpoints¶

List Pipelines¶

GET /api/v1/pipelines

Returns all pipelines. Supports pagination and optional organization filter.

Query parameters

Response 200 OK

{
  "data": [ /* Pipeline objects */ ],
  "total": 10,
  "page": 1,
  "limit": 20
}

Create Pipeline¶

POST /api/v1/pipelines

Request body

Response 201 Created — the created Pipeline object.

Error 409 Conflict — a pipeline with that name already exists.

Get Pipeline¶

GET /api/v1/pipelines/:id

Response 200 OK — the Pipeline object.

Error 404 Not Found.

Update Pipeline¶

PATCH /api/v1/pipelines/:id

Request body — any subset of CreatePipelineDto fields.

Response 200 OK — the updated Pipeline object.

Delete Pipeline¶

DELETE /api/v1/pipelines/:id

Response 204 No Content.

Trigger a Run¶

POST /api/v1/pipelines/:id/trigger

Enqueues a new pipeline execution. Returns immediately with the created run in queued status.

Response 201 Created — the PipelineRun object with status: "queued".

List Runs¶

GET /api/v1/pipelines/:id/runs

Returns the last 50 runs for the pipeline, ordered by most recent first.

Response 200 OK

[ /* PipelineRun objects */ ]

Get Run¶

GET /api/v1/pipelines/:id/runs/:runId

Response 200 OK — the PipelineRun object including full logs and stageResults.

Error 404 Not Found — run does not exist or does not belong to the pipeline.

Run Actions¶

Approve Run¶

POST /api/v1/pipelines/:id/runs/:runId/approve

Approves a run that is paused at an approval stage. The run must be in waiting_approval status. Execution resumes from the next stage after the approval gate.

• Roles required: admin
• Response 200 OK — the updated PipelineRun object with status: "running".
• Error 404 Not Found — run does not exist or does not belong to this pipeline.
• Error 400 Bad Request — run is not in waiting_approval status.

Reject Run¶

POST /api/v1/pipelines/:id/runs/:runId/reject

Rejects a run paused at an approval stage. Sets the run status to failed.

• Roles required: admin
• Response 200 OK — the updated PipelineRun object with status: "failed".
• Error 400 Bad Request — run is not in waiting_approval status.

Cancel Run¶

POST /api/v1/pipelines/:id/runs/:runId/cancel

Cancels a run that is in queued or running status. The processor will abort before the next stage.

• Roles required: admin
• Response 200 OK — the updated PipelineRun object with status: "cancelled".
• Error 400 Bad Request — run cannot be cancelled (already in a terminal state).

Run Status¶

WebSocket Events¶

Pipeline execution emits real-time events on the /events Socket.IO namespace.

See the WebSocket documentation for connection details.

Stage Config Reference¶

Each stage type accepts specific config fields:

script¶

approval¶

deploy¶

notify¶