API reference

Pipelines

A pipeline stores a declared sequence of Activity definitions. The API creates an independent persisted Activity record for every supplied step, then stores the generated Activity IDs in that display order. A step can declare dependsOn conditions for other named steps, forming an acyclic execution graph that controls execution eligibility. Pipeline runs persist a frozen graph and wait for a runtime worker to claim and select one eligible Activity run at a time.

Pipeline calls

Creation requires a non-empty name, a description, and at least one step. New pipelines are enabled. PATCH accepts name, description, enabled, and steps; supplying steps replaces the complete ordered array. Archived pipelines are immutable and omitted from unfiltered listings.

Pipeline Step Schema

Every item in steps uses the Activity definition schema. Its name follows the same name restrictions as the Pipeline name. Each item can also contain a dependsOn array.

Each step has a dependsOn array. Every item contains an activity name from another step and a condition of success or failure. The array can be empty. Dependency targets must be unambiguous and the graph cannot contain cycles.

List pipelines

GET /api/v1/pipelines returns ten pipelines after the optional non-negative offset. search matches name and description case-insensitively, and status accepts active, disabled, or archived. Each Pipeline resolves every stored step to its full persisted Activity.

GET /api/v1/pipelines?offset=0&status=active&search=release
X-Workspace-ID: workspace-acme

Example response (200 OK):

{
  "items": [
    {
      "id": "pipeline-production-release-review",
      "name": "ProductionReleaseReview",
      "description": "Review a release, collect readiness information, and request approval.",
      "enabled": true,
      "steps": [
        {
          "id": "activity-release-review",
          "workspace_id": "workspace-acme",
          "name": "ReviewReleasePlan",
          "dependsOn": [],
          "description": "Reach a shared decision about release readiness.",
          "status": "active",
          "type": "roundtable_loop",
          "config": {
            "stop_conditions": {
              "max_iterations": 2
            },
            "agents": [],
            "output_contract": {
              "type": "text",
              "description": "Release decision."
            }
          },
          "created_at": "2026-08-13T10:00:00Z",
          "created_by": "user-123",
          "updated_at": "2026-08-13T10:00:00Z",
          "updated_by": "user-123"
        },
        {
          "id": "activity-readiness-quiz",
          "workspace_id": "workspace-acme",
          "name": "DeploymentReadinessQuiz",
          "dependsOn": [
            {"activity": "ReviewReleasePlan", "condition": "success"}
          ],
          "description": "Confirm operational readiness before deployment.",
          "status": "active",
          "type": "quiz",
          "config": {
            "quiz": {
              "questions": []
            }
          },
          "created_at": "2026-08-13T10:00:00Z",
          "created_by": "user-123",
          "updated_at": "2026-08-13T10:00:00Z",
          "updated_by": "user-123"
        },
        {
          "id": "activity-production-approval",
          "workspace_id": "workspace-acme",
          "name": "ApproveProductionRelease",
          "dependsOn": [
            {"activity": "DeploymentReadinessQuiz", "condition": "success"},
            {"activity": "ReviewReleasePlan", "condition": "failure"}
          ],
          "description": "A release manager approves deployment.",
          "status": "active",
          "type": "approval",
          "config": {},
          "created_at": "2026-08-13T10:00:00Z",
          "created_by": "user-123",
          "updated_at": "2026-08-13T10:00:00Z",
          "updated_by": "user-123"
        }
      ],
      "created_at": "2026-08-13T10:00:00Z",
      "updated_at": "2026-08-13T10:00:00Z"
    }
  ],
  "total": 1
}

Describe a pipeline

GET /api/v1/pipelines/{pipeline_id} returns the complete ordered definition with the full persisted Activity for every step, including its generated ID.

GET /api/v1/pipelines/pipeline-production-release-review
X-Workspace-ID: workspace-acme

Example response (200 OK):

{
  "id": "pipeline-production-release-review",
  "name": "ProductionReleaseReview",
  "description": "Review a release, collect readiness information, and request approval.",
  "enabled": true,
  "steps": [
    {
      "id": "activity-release-review",
      "workspace_id": "workspace-acme",
      "name": "ReviewReleasePlan",
      "dependsOn": [],
      "description": "Reach a shared decision about release readiness.",
      "status": "active",
      "type": "roundtable_loop",
      "config": {
        "stop_conditions": {
          "max_iterations": 2
        },
        "agents": [],
        "output_contract": {
          "type": "text",
          "description": "Release decision."
        }
      },
      "created_at": "2026-08-13T10:00:00Z",
      "created_by": "user-123",
      "updated_at": "2026-08-13T10:00:00Z",
      "updated_by": "user-123"
    },
    {
      "id": "activity-readiness-quiz",
      "workspace_id": "workspace-acme",
      "name": "DeploymentReadinessQuiz",
      "dependsOn": [
        {"activity": "ReviewReleasePlan", "condition": "success"}
      ],
      "description": "Confirm operational readiness before deployment.",
      "status": "active",
      "type": "quiz",
      "config": {
        "quiz": {
          "questions": []
        }
      },
      "created_at": "2026-08-13T10:00:00Z",
      "created_by": "user-123",
      "updated_at": "2026-08-13T10:00:00Z",
      "updated_by": "user-123"
    },
    {
      "id": "activity-production-approval",
      "workspace_id": "workspace-acme",
      "name": "ApproveProductionRelease",
      "dependsOn": [
        {"activity": "DeploymentReadinessQuiz", "condition": "success"},
        {"activity": "ReviewReleasePlan", "condition": "failure"}
      ],
      "description": "A release manager approves deployment.",
      "status": "active",
      "type": "approval",
      "config": {},
      "created_at": "2026-08-13T10:00:00Z",
      "created_by": "user-123",
      "updated_at": "2026-08-13T10:00:00Z",
      "updated_by": "user-123"
    }
  ],
  "created_at": "2026-08-13T10:00:00Z",
  "updated_at": "2026-08-13T10:00:00Z"
}

Create a pipeline

POST /api/v1/pipelines creates an enabled pipeline in the workspace supplied by X-Workspace-ID. Supply complete Activity definitions in execution order. The API validates and persists each Activity in the same transaction, assigns each one an ID, and stores those IDs as Pipeline steps. The response resolves each stored step to its full persisted Activity.

Create Request Properties

POST /api/v1/pipelines
X-Workspace-ID: workspace-acme
Content-Type: application/json

{
  "name": "ProductionReleaseReview",
  "description": "Review a release, collect readiness information, and request approval.",
  "steps": [
    {
      "name": "ReviewReleasePlan",
      "dependsOn": [],
      "description": "Reach a shared decision about release readiness.",
      "type": "roundtable_loop",
      "config": {
        "stop_conditions": {
          "max_iterations": 2
        },
        "agents": [],
        "output_contract": {
          "type": "text",
          "description": "Release decision."
        }
      }
    },
    {
      "name": "DeploymentReadinessQuiz",
      "dependsOn": [
        {"activity": "ReviewReleasePlan", "condition": "success"}
      ],
      "description": "Confirm operational readiness before deployment.",
      "type": "quiz",
      "config": {
        "quiz": {
          "questions": []
        }
      }
    },
    {
      "name": "ApproveProductionRelease",
      "dependsOn": [
        {"activity": "DeploymentReadinessQuiz", "condition": "success"},
        {"activity": "ReviewReleasePlan", "condition": "failure"}
      ],
      "description": "A release manager approves deployment.",
      "type": "approval",
      "config": {}
    }
  ]
}

Example response (201 Created):

{
  "id": "pipeline-production-release-review",
  "name": "ProductionReleaseReview",
  "description": "Review a release, collect readiness information, and request approval.",
  "enabled": true,
  "steps": [
    {
      "id": "activity-release-review",
      "workspace_id": "workspace-acme",
      "name": "ReviewReleasePlan",
      "dependsOn": [],
      "description": "Reach a shared decision about release readiness.",
      "status": "active",
      "type": "roundtable_loop",
      "config": {
        "stop_conditions": {
          "max_iterations": 2
        },
        "agents": [],
        "output_contract": {
          "type": "text",
          "description": "Release decision."
        }
      },
      "created_at": "2026-08-13T10:00:00Z",
      "created_by": "user-123",
      "updated_at": "2026-08-13T10:00:00Z",
      "updated_by": "user-123"
    },
    {
      "id": "activity-readiness-quiz",
      "workspace_id": "workspace-acme",
      "name": "DeploymentReadinessQuiz",
      "dependsOn": [
        {"activity": "ReviewReleasePlan", "condition": "success"}
      ],
      "description": "Confirm operational readiness before deployment.",
      "status": "active",
      "type": "quiz",
      "config": {
        "quiz": {
          "questions": []
        }
      },
      "created_at": "2026-08-13T10:00:00Z",
      "created_by": "user-123",
      "updated_at": "2026-08-13T10:00:00Z",
      "updated_by": "user-123"
    },
    {
      "id": "activity-production-approval",
      "workspace_id": "workspace-acme",
      "name": "ApproveProductionRelease",
      "dependsOn": [
        {"activity": "DeploymentReadinessQuiz", "condition": "success"},
        {"activity": "ReviewReleasePlan", "condition": "failure"}
      ],
      "description": "A release manager approves deployment.",
      "status": "active",
      "type": "approval",
      "config": {},
      "created_at": "2026-08-13T10:00:00Z",
      "created_by": "user-123",
      "updated_at": "2026-08-13T10:00:00Z",
      "updated_by": "user-123"
    }
  ],
  "created_at": "2026-08-13T10:00:00Z",
  "updated_at": "2026-08-13T10:00:00Z"
}

Update a pipeline

PATCH /api/v1/pipelines/{pipeline_id} accepts one or more of name, description, enabled, and steps. Supplying steps replaces the complete ordered array and creates new independent Activity records from the supplied inline definitions. The response resolves every stored step to its full persisted Activity.

Update Request Properties

At least one property is required.

PATCH /api/v1/pipelines/pipeline-production-release-review
X-Workspace-ID: workspace-acme
Content-Type: application/json

{
  "enabled": false
}

Example response (200 OK):

{
  "id": "pipeline-production-release-review",
  "name": "ProductionReleaseReview",
  "description": "Review a release, collect readiness information, and request approval.",
  "enabled": false,
  "steps": [
    {
      "id": "activity-release-review",
      "workspace_id": "workspace-acme",
      "name": "ReviewReleasePlan",
      "dependsOn": [],
      "description": "Reach a shared decision about release readiness.",
      "status": "active",
      "type": "roundtable_loop",
      "config": {
        "stop_conditions": {
          "max_iterations": 2
        },
        "agents": [],
        "output_contract": {
          "type": "text",
          "description": "Release decision."
        }
      },
      "created_at": "2026-08-13T10:00:00Z",
      "created_by": "user-123",
      "updated_at": "2026-08-13T10:00:00Z",
      "updated_by": "user-123"
    },
    {
      "id": "activity-readiness-quiz",
      "workspace_id": "workspace-acme",
      "name": "DeploymentReadinessQuiz",
      "dependsOn": [
        {"activity": "ReviewReleasePlan", "condition": "success"}
      ],
      "description": "Confirm operational readiness before deployment.",
      "status": "active",
      "type": "quiz",
      "config": {
        "quiz": {
          "questions": []
        }
      },
      "created_at": "2026-08-13T10:00:00Z",
      "created_by": "user-123",
      "updated_at": "2026-08-13T10:00:00Z",
      "updated_by": "user-123"
    },
    {
      "id": "activity-production-approval",
      "workspace_id": "workspace-acme",
      "name": "ApproveProductionRelease",
      "dependsOn": [
        {"activity": "DeploymentReadinessQuiz", "condition": "success"},
        {"activity": "ReviewReleasePlan", "condition": "failure"}
      ],
      "description": "A release manager approves deployment.",
      "status": "active",
      "type": "approval",
      "config": {},
      "created_at": "2026-08-13T10:00:00Z",
      "created_by": "user-123",
      "updated_at": "2026-08-13T10:00:00Z",
      "updated_by": "user-123"
    }
  ],
  "created_at": "2026-08-13T10:00:00Z",
  "updated_at": "2026-08-13T10:15:00Z"
}

The list accepts a non-negative offset, optional case-insensitive search over name and description, and optional status of active, disabled, or archived. Active pipelines sort before disabled and archived pipelines.

Every Pipeline response resolves each step to the complete Activity representation. Pipeline creation and step replacement both accept the same full Activity definition shape as POST /api/v1/activities. Replacing steps creates new Activity records; it does not modify or delete Activities from prior steps.

Every create, patch, enablement change, and archival appends a changelog entry in the same transaction. Step diffs report additions, removals, positional changes, and order changes.

Archive a pipeline

DELETE /api/v1/pipelines/{pipeline_id} archives a Pipeline and returns {"deleted": true}. Archival is terminal: archived Pipelines reject PATCH requests and are omitted from unfiltered listings. Existing Pipeline runs retain their frozen graph and execution history.

DELETE /api/v1/pipelines/pipeline-production-release-review
X-Workspace-ID: workspace-acme

Example response (200 OK):

{
  "deleted": true
}

List pipeline changelog entries

GET /api/v1/pipelines/{pipeline_id}/changelog returns ten newest entries after the optional non-negative offset.

GET /api/v1/pipelines/pipeline-production-release-review/changelog?offset=0
X-Workspace-ID: workspace-acme

Example response (200 OK):

{
  "items": [
    {
      "id": "pipeline-change-002",
      "pipeline_id": "pipeline-production-release-review",
      "change_type": "disabled",
      "actor_id": "user-123",
      "changed_at": "2026-08-13T10:15:00Z",
      "diff": {
        "enabled": {
          "from": true,
          "to": false
        }
      },
      "content": null
    }
  ],
  "total": 2
}

Request schema failures use the standard API error envelope. Invalid step structures use invalid_pipeline_steps.

Execution Model

A Pipeline is a reusable graph definition. A PipelineRun is one requested execution of its frozen graph. Each scheduled step creates an ActivityRun owned by that PipelineRun; an ActivityRun is not an independently runnable workflow.

The runtime is a pull-based executor. It polls the API for eligible Pipeline runs and attempts ETag-protected claims; the API admits or rejects each claim. The CLI is a control-plane client. It creates, starts, inspects, and operates Pipeline runs, but it does not select a checkout or perform filesystem or Git operations.

Human Activities are normal ActivityRuns with the human executor. Runtime workers do not claim them. A dependency-ready human ActivityRun places its PipelineRun in waiting until a user submits the human decision checkpoint.

Lifecycle

prepared -> queued -> claimed -> in_progress -> completed
                      |             |
                      |             -> waiting (human ActivityRun)
                      |
                      -> queued again when a lease expires

Creating a PipelineRun produces a prepared execution with frozen input, steps, and commit policy. An explicit operator action transitions it to queued, making runtime-owned work eligible for polling and claims. If the first dependency-ready step has a human executor, the API instead creates its waiting human ActivityRun without exposing the PipelineRun to workers.

The corresponding CLI commands are:

ll pipelines runs create PIPELINE_ID --input "..."
  -> create a prepared PipelineRun

ll pipelines runs start PIPELINE_ID RUN_ID
  -> transition the PipelineRun from prepared to queued

Workers remain independent pollers; an operator does not direct a specific worker to accept a claim.

Activity definitions remain reusable but are not directly callable. Retrying execution is a PipelineRun-level operation because it needs the frozen graph, input, commit mode, configured runtime checkout, and correction history. A future retry command should create a new prepared PipelineRun rather than altering completed ActivityRuns. Any future restart-from-step operation must define its dependency reset and reuse semantics explicitly.

List workspace Pipeline runs

GET /api/v1/pipeline-runs returns ten newest Pipeline runs in the selected workspace after the optional non-negative offset. Unlike the worker-only claimable route, every item is a normal PipelineRun response and the result includes prepared, active, waiting, completed, and failed executions.

The optional pipeline_id and status filters select one Pipeline or one public lifecycle state. created_from and created_to accept ISO 8601 timestamps and form inclusive creation-time boundaries. Filters can be combined.

GET /api/v1/pipeline-runs?offset=0&pipeline_id=pipeline-production-release-review&status=completed&created_from=2026-08-01T00:00:00Z&created_to=2026-08-31T23:59:59Z
X-Workspace-ID: workspace-acme

The response uses the shared list envelope:

{
  "items": [
    {
      "id": "pipeline-run-001",
      "pipeline_id": "pipeline-production-release-review",
      "input": "Review the release candidate.",
      "commit_mode": "allow",
      "status": "completed",
      "current_activity_run": null,
      "steps": [],
      "created_at": "2026-08-18T10:00:00Z",
      "created_by": "user-123",
      "updated_at": "2026-08-18T10:05:00Z"
    }
  ],
  "total": 1
}

GET /api/v1/pipelines/{pipeline_id}/runs?claimable=true remains a separate runtime contract. It returns only claimable candidates wrapped with their opaque ETags and must not be used as execution history.

Execute pipelines

POST /api/v1/pipelines/{pipeline_id}/runs accepts an input string used by every scheduled Activity and a run-level commit_mode. The API freezes the Pipeline graph and commit policy, then returns a prepared run. Creation does not start repository execution or allocate an ActivityRun. Use the start operation to make the run eligible for its assigned executor. allow is the default mode. forbid leaves successfully applied and approved changes uncommitted, and the API never schedules a commit checkpoint for that run.

POST /api/v1/pipelines/pipeline-production-release-review/runs
X-Workspace-ID: workspace-acme
Content-Type: application/json

{
  "input": "Review the release candidate and determine whether it is ready for production.",
  "commit_mode": "allow"
}

Example response (201 Created):

{
  "id": "pipeline-run-001",
  "pipeline_id": "pipeline-production-release-review",
  "input": "Review the release candidate and determine whether it is ready for production.",
  "commit_mode": "allow",
  "status": "prepared",
  "current_activity_run": null,
  "steps": [
    {
      "activity_id": "activity-release-review",
      "status": "pending",
      "activity_run_id": null
    },
    {
      "activity_id": "activity-readiness-quiz",
      "status": "pending",
      "activity_run_id": null
    },
    {
      "activity_id": "activity-production-approval",
      "status": "pending",
      "activity_run_id": null
    }
  ],
  "created_at": "2026-08-18T10:00:00Z",
  "created_by": "user-123",
  "updated_at": "2026-08-18T10:00:00Z"
}

Start a pipeline run

POST /api/v1/pipelines/{pipeline_id}/runs/{run_id}/start transitions a prepared PipelineRun to queued when its next dependency-ready step has a runtime executor. The runtime can then discover and conditionally claim it.

When the next ready step has a human executor, start creates that ActivityRun and returns the PipelineRun in waiting; it never becomes runtime claimable. Starting a run that is not prepared returns 409 pipeline_run_unavailable.

List claimable pipeline runs

The runtime first lists active Pipelines, then requests claimable runs beneath each Pipeline. GET /api/v1/pipelines/{pipeline_id}/runs?claimable=true returns queued runs and claimed runs whose lease has expired. The API owns that decision; callers must not infer claimability from a raw persisted status.

GET /api/v1/pipelines/pipeline-production-release-review/runs?claimable=true
X-Workspace-ID: workspace-acme

Example response (200 OK):

{
  "items": [
    {
      "etag": "\"c1e5185f48a77b2f\"",
      "run": {
        "id": "pipeline-run-001",
        "pipeline_id": "pipeline-production-release-review",
        "input": "Review the release candidate and determine whether it is ready for production.",
        "commit_mode": "allow",
        "status": "queued",
        "current_activity_run": null,
        "steps": [
          {
            "activity_id": "activity-release-review",
            "status": "pending",
            "activity_run_id": null
          }
        ],
        "created_at": "2026-08-18T10:00:00Z",
        "created_by": "user-123",
        "updated_at": "2026-08-18T10:00:00Z"
      }
    }
  ],
  "total": 1
}

etag is opaque. The runtime sends it unchanged as the standard HTTP If-Match request header when it attempts to claim that exact run. A Pipeline with no claimable work returns { "items": [], "total": 0 }.

Claim a pipeline run

PATCH /api/v1/pipelines/{pipeline_id}/runs/{run_id} atomically claims the named listed run when its If-Match entity tag is still current. The request requires the worker’s stable worker_id and the only accepted target status, claimed. On success, the API creates or resumes the selected Activity child, issues a one-minute lease, and returns its secret lease_token. Pipeline runs whose next ready step is an approval or quiz Activity are scheduled as waiting human-owned Activity runs by the API and do not appear in the runtime claimable-run list.

PATCH /api/v1/pipelines/pipeline-production-release-review/runs/pipeline-run-001
X-Workspace-ID: workspace-acme
If-Match: "c1e5185f48a77b2f"
Content-Type: application/json

{
  "worker_id": "runtime-local-01",
  "status": "claimed"
}

Example response (200 OK):

{
  "run": {
    "id": "pipeline-run-001",
    "pipeline_id": "pipeline-production-release-review",
    "input": "Review the release candidate and determine whether it is ready for production.",
    "commit_mode": "allow",
    "status": "claimed",
    "current_activity_run": {
      "id": "activity-run-001",
      "activity_id": "activity-release-review",
      "input": "Review the release candidate and determine whether it is ready for production.",
      "status": "in_progress",
      "state": "awaiting_snapshot",
      "next_action": "collect_snapshot",
      "iteration": 1,
      "token_revision": 0,
      "continuation_token": "activity-continuation-token",
      "created_at": "2026-08-18T10:01:00Z",
      "created_by": "user-123",
      "updated_at": "2026-08-18T10:01:00Z",
      "payload": {}
    },
    "steps": [
      {
        "activity_id": "activity-release-review",
        "status": "in_progress",
        "activity_run_id": "activity-run-001"
      }
    ],
    "created_at": "2026-08-18T10:00:00Z",
    "created_by": "user-123",
    "updated_at": "2026-08-18T10:01:00Z"
  },
  "lease_token": "runtime-lease-token"
}

The worker must treat lease_token as secret and supply it to every lease, Activity checkpoint, and Pipeline continuation request for the claim. A worker cannot claim a disabled or archived Pipeline. If another worker changes the run after it was listed, the API returns 412 pipeline_run_precondition_failed; the runtime discards that stale candidate and continues with another candidate or a later poll.

Describe a pipeline run

GET /api/v1/pipelines/{pipeline_id}/runs/{run_id} returns one durable Pipeline execution and its currently selected Activity child. A terminal run has current_activity_run: null; its steps retain the final outcome of every frozen Pipeline step.

An approval or quiz step remains the current Activity run while the Pipeline status is waiting. Its snapshot identifies the human executor and its continuation action is submit_human_decision.

GET /api/v1/pipelines/pipeline-production-release-review/runs/pipeline-run-001
X-Workspace-ID: workspace-acme

Example response (200 OK):

{
  "id": "pipeline-run-001",
  "pipeline_id": "pipeline-production-release-review",
  "input": "Review the release candidate and determine whether it is ready for production.",
  "commit_mode": "forbid",
  "status": "completed",
  "current_activity_run": null,
  "steps": [
    {
      "activity_id": "activity-release-review",
      "status": "completed",
      "activity_run_id": "activity-run-001"
    }
  ],
  "created_at": "2026-08-18T10:00:00Z",
  "created_by": "user-123",
  "updated_at": "2026-08-18T10:05:00Z"
}

The API returns 404 pipeline_run_not_found when the supplied run does not belong to the Pipeline in the selected workspace.

List pipeline run events

GET /api/v1/pipelines/{pipeline_id}/runs/{run_id}/events returns the append-only event ledger in creation order. Each entry has an ID, event type, optional Activity ID, actor ID, JSON payload, and creation time. The API emits the following events as their corresponding scheduler transitions are persisted:

• pipeline_run_created, with commit_mode.
• pipeline_run_started and pipeline_run_claimed; the claim includes its attempt number.
• step_started, with the Activity-run ID and executor type.
• agent_response_received, with Activity-run ID, Persona, role, model, provider, token usage, and model latency.
• human_gate_waiting, with Activity-run ID and gate type.
• human_gate_decided, with Activity-run ID, decision, and optional comment.
• step_completed or step_failed, with Activity-run ID and iteration; failed events also include the best persisted error message.
• pipeline_run_completed or pipeline_run_failed when the scheduler reaches a terminal Pipeline state.

Human decisions remain Activity-run checkpoints. Their ledger event is emitted when the caller subsequently continues the Pipeline run, keeping the event and Pipeline state transition atomic.

Complete a human Activity run

Submit an approval or quiz decision through the Activity-run continuation endpoint. The request carries the current continuation token and an idempotency key, but no worker lease token.

{
  "continuation_token": "activity-continuation-token",
  "idempotency_key": "review-decision-001",
  "result": {
    "action": "submit_human_decision",
    "decision": "approved",
    "comment": "Ready to release."
  }
}

After a terminal human result, call Pipeline continuation with no lease token to schedule the next step. A rejected decision resets the rejected step and its transitive predecessors to pending for corrective execution. Once those predecessors finish, the scheduler creates a new human Activity run.

Renew a pipeline run lease

POST /api/v1/pipelines/{pipeline_id}/runs/{run_id}/lease extends an active claim by one minute. Only the worker holding the current unexpired lease token can renew it.

POST /api/v1/pipelines/pipeline-production-release-review/runs/pipeline-run-001/lease
X-Workspace-ID: workspace-acme
Content-Type: application/json

{
  "lease_token": "runtime-lease-token"
}

Example response (200 OK):

{
  "lease_expires_at": "2026-08-18T10:02:00Z"
}

A missing, stale, or expired token returns 409 pipeline_run_unavailable.

Continue a pipeline run

POST /api/v1/pipelines/{pipeline_id}/runs/{run_id}/continue records the selected terminal Activity child outcome and schedules the next dependency-ready step. The worker calls this only after an Activity checkpoint response is terminal.

POST /api/v1/pipelines/pipeline-production-release-review/runs/pipeline-run-001/continue
X-Workspace-ID: workspace-acme
Content-Type: application/json

{
  "lease_token": "runtime-lease-token"
}

Example response (200 OK):

{
  "id": "pipeline-run-001",
  "pipeline_id": "pipeline-production-release-review",
  "input": "Review the release candidate and determine whether it is ready for production.",
  "commit_mode": "allow",
  "status": "in_progress",
  "current_activity_run": {
    "id": "activity-run-002",
    "activity_id": "activity-readiness-quiz",
    "input": "Review the release candidate and determine whether it is ready for production.",
    "status": "in_progress",
    "state": "awaiting_snapshot",
    "next_action": "collect_snapshot",
    "iteration": 1,
    "token_revision": 0,
    "continuation_token": "activity-continuation-token",
    "created_at": "2026-08-18T10:03:00Z",
    "created_by": "user-123",
    "updated_at": "2026-08-18T10:03:00Z",
    "payload": {}
  },
  "steps": [
    {
      "activity_id": "activity-release-review",
      "status": "completed",
      "activity_run_id": "activity-run-001"
    },
    {
      "activity_id": "activity-readiness-quiz",
      "status": "in_progress",
      "activity_run_id": "activity-run-002"
    }
  ],
  "created_at": "2026-08-18T10:00:00Z",
  "created_by": "user-123",
  "updated_at": "2026-08-18T10:03:00Z"
}

When no eligible step remains, the response has current_activity_run: null and a terminal completed or failed status. A missing, stale, or expired lease token returns 409 pipeline_run_unavailable.