Reference · Workers API

Workers API

Workers are durable principals with a standing job; shifts are their bounded activations; schedules wake them. Everything a shift touches is linked on its record, and shift lifecycle events stream on the run-events firehose (shift.started / shift.completed / shift.failed).

Workers

GET/v1/workers?workspaceId=The roster.

POST/v1/workersHire a worker: name, description (the responsibility), job, template allow-list.

GET/v1/workers/{workerId}One worker.

PATCH/v1/workers/{workerId}Update the job, allow-list, or status (active | paused | retired).

POST/v1/workers/{workerId}/runStart a shift now (409 if one is already running; preconditions fail here, visibly).

Shifts

GET/v1/workers/{workerId}/shiftsThe shift timeline, newest first.

GET/v1/workers/{workerId}/shifts/{shiftId}One shift — deep-linkable; links update live during the shift.

GET/v1/runs?workerId=Every run attributed to a worker (plan runs + order children).

a shift recordjson

GET /v1/workers/{workerId}/shifts/{shiftId}

{
  "id": "shift-1a2b3c4d",
  "workerId": "worker-06997927",
  "trigger": "schedule",
  "status": "completed",
  "healthy": true,
  "summary": "Daily batch — 80/80 succeeded, $3.99",
  "totalCostUsd": 3.99,
  "links": {
    "runIds": ["run-…"], "orderIds": ["order-…"],
    "artifactIds": ["artifact-…"], "goalIds": ["goal-…"],
    "taskIds": ["task-…"], "messageIds": ["msg-…"]
  },
  "startedAt": "2026-07-06T10:00:04Z",
  "completedAt": "2026-07-06T10:14:31Z"
}

Schedules

GET/v1/schedules?workspaceId=All schedules.

POST/v1/schedulesCreate: five-field cron (UTC) + exactly one target — a worker to wake, or a template to run.

PATCH/v1/schedules/{scheduleId}Retime, rename, enable/disable.

DELETE/v1/schedules/{scheduleId}Remove a schedule.