API reference

Workers

Workers are API-provisioned, Project-scoped runtime identities. A runtime stores its assigned worker_id in the Project configuration and refreshes a heartbeat before each Project poll. An active heartbeat and a matching Harness capability are required to claim a PipelineRun.

Worker provisioning is separate from a PipelineRun lease. A heartbeat does not extend a lease, and an expired heartbeat does not revoke an existing lease.

Resource Endpoints

Method	Path	Purpose
`POST`	`/api/v1/workers`	Provision a worker identity.
`POST`	`/api/v1/workers/{worker_id}/heartbeat`	Refresh an existing worker heartbeat.

Both endpoints require X-User-ID and use X-Project-ID to select one of that User’s Projects.

Observe Worker Liveness

The API intentionally exposes no raw Worker list or identity read endpoint. Runtimes verify their own registration by sending a heartbeat and inspecting the returned last_heartbeat_at. Web clients diagnose queued work through GET /api/v1/pipelines/{pipeline_id}/runs/{run_id}/readiness, which returns only Project-scoped aggregate liveness and Harness-compatibility counts. Pipeline-run claim admission remains the authoritative mutation-time check.

Provision A Worker

POST /api/v1/workers provisions a worker identity in the selected Project. Its optional harnesses array declares local execution capabilities. Omitting the request body registers the compatibility default: louie v1 with an empty configuration. Store the returned ID in that Project’s runtime configuration.

POST /api/v1/workers
X-User-ID: user-acme
X-Project-ID: project-acme
Content-Type: application/json

{
  "harnesses": [
    {
      "kind": "louie",
      "version": "v1",
      "config": {
      }
    }
  ]
}

Example response (201 Created):

{
  "id": "c1fa5f23a0fb4c4cad6b08a2ea774b21",
  "registered_at": "2026-08-21T10:00:00Z",
  "last_heartbeat_at": "2026-08-21T10:00:00Z",
  "harnesses": [
    {
      "kind": "louie",
      "version": "v1",
      "config": {
      }
    }
  ]
}

Send A Heartbeat

POST /api/v1/workers/{worker_id}/heartbeat refreshes the liveness timestamp for an existing provisioned worker. Its optional harnesses array atomically replaces the worker’s currently observed capabilities. Omitting the body keeps the previously recorded capabilities for compatibility with older runtimes. Workers report Harness health, not a model list: codex_cli means that the configured executable and local login check currently succeed. An unknown worker returns 404 worker_not_found.

POST /api/v1/workers/runtime-local-01/heartbeat
X-User-ID: user-acme
X-Project-ID: project-acme
Content-Type: application/json

{
  "harnesses": [
    {
      "kind": "louie",
      "version": "v1",
      "config": {}
    },
    {
      "kind": "codex_cli",
      "version": "v1",
      "config": {}
    }
  ]
}

A queued PipelineRun is not invalid merely because no active worker currently advertises its frozen Harness. It remains queued and can be claimed automatically after a later heartbeat replaces the capability set with a matching Harness.