Workers

A worker is a credential, not a machine. These endpoints manage the credential; the process that uses it is installed separately.

workers:* is human-only, so a machine key cannot provision or rotate a worker.

Create

curl -fsS -X POST https://api.saved.sh/v1/workers \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name": "prod-worker-1"}'

{
  "id": "0f2c9a1e-...",
  "name": "prod-worker-1",
  "secret": "sk_live_...",
  "created_at": "2026-08-08T09:14:02Z",
  "updated_at": "2026-08-08T09:14:02Z"
}

Permission: workers:write. Returns 201.

The key is created carrying exactly artifacts:upload and artifacts:confirm. You cannot choose its permissions, and there is no field to try.

List

curl -fsS https://api.saved.sh/v1/workers -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "0f2c9a1e-...",
      "name": "prod-worker-1",
      "instances": 1,
      "last_seen": "2026-08-08T09:41:12Z",
      "created_at": "2026-08-08T09:14:02Z",
      "updated_at": "2026-08-08T09:14:02Z"
    }
  ],
  "next_cursor": null
}

Permission: workers:read.

Presence

instances and last_seen are read live from the polling connections, not from a heartbeat we store.

instances above 1 is worth investigating. Several processes may share one credential and all poll the same queue, but a run's steps hand each other a path to a local file, so splitting them across machines breaks the run. See one process per credential.

instances is null when presence could not be read, which is not the same as 0.

Get

curl -fsS "https://api.saved.sh/v1/workers/$WORKER_ID" -H "Authorization: Bearer $TOKEN"

Permission: workers:read. Presence fields are not included on the single-worker read.

Rotate

curl -fsS -X POST "https://api.saved.sh/v1/workers/$WORKER_ID/rotate" \
  -H "Authorization: Bearer $TOKEN"

{ "id": "0f2c9a1e-...", "name": "prod-worker-1", "secret": "sk_live_...", "...": "..." }

Permission: workers:write.

The worker ID is unchanged, so every backup assigned to it keeps working once the new key is deployed. This is the answer to a leaked key, a decommissioned host, or ordinary hygiene.

Delete

curl -fsS -X DELETE "https://api.saved.sh/v1/workers/$WORKER_ID" -H "Authorization: Bearer $TOKEN"

Permission: workers:revoke, which is a separate permission from workers:write. Returns 204.

Deletion revokes the key permanently. Backups assigned to the worker are left with nowhere to run: their scheduled runs queue on a task queue nothing polls, silently.

Reassign or pause those backups before deleting the worker they point at.

What the credential authorizes

That is the entire surface. A worker key cannot read backup definitions, list artifacts, download anything, or manage workers. On the orchestration side it is bound to one namespace and one task queue, its own.

artifacts:confirm is refused on an ordinary API key, which makes it the worker/automation discriminator.

Quotas

Next