Worker control

The protocol infrastructure implements to run work: register a worker, heartbeat, lease jobs, acknowledge the lease, and report completion. For building clients you do not need this — it is for operators running the fleet. API-backed model certification uses the same worker lease path with kind: "model" jobs and capability gates (model_certification, model_registry_publish).

Route inventory

Method	Route	Purpose
`POST`	`/v1/worker/register`	Register a worker and its capabilities; receive a worker credential.
`POST`	`/v1/worker/heartbeat`	Report liveness and current state.
`POST`	`/v1/worker/jobs/lease`	Lease the next compatible job.
`POST`	`/v1/internal/leases/ack`	Acknowledge a lease before starting work.
`POST`	`/v1/worker/jobs/complete`	Report success or failure for a job.
`·`	`/v1/internal/*`	Operator-only controls for the worker/job runtime.

Lease lifecycle

Register

POST capabilities (models, kinds, region). The control plane returns a worker credential used on subsequent calls.

Heartbeat

Periodically report liveness and state so the scheduler can route work and mark stale workers unavailable.

Lease

Ask for the next compatible job. When none is available — or the worker cannot lease yet — the API returns 428 authorization_pending; retry on backoff.

Acknowledge

Ack the lease to take ownership before starting. Unacknowledged leases expire and return to the queue.

Complete

Report success or failure. Failures may be retried by the scheduler depending on job policy. For model.certify, completion includes green evidence and threshold signatures; for model.publish it includes registry publication metadata; for model.yank it completes the signed yank log step.

Lease a job

POST/v1/worker/jobs/lease→ 200 / 428

Returns a job to run, or 428 authorization_pending when no compatible work is available. Branch on endpoint context — here, authorization_pending means "nothing to lease right now."

Auth · worker credential · Schema · illustrative

curl -X POST https://api.s46.dev/v1/worker/jobs/lease \
  -H "Authorization: Bearer $S46_WORKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "workerId": "worker_01", "capabilities": ["chat", "code"] }'

const res = await fetch("https://api.s46.dev/v1/worker/jobs/lease", {
  method: "POST",
  headers: { Authorization: `Bearer ${workerToken}`, "Content-Type": "application/json" },
  body: JSON.stringify({ workerId: "worker_01", capabilities: ["chat", "code"] }),
});
const job = res.status === 200 ? await res.json() : null; // 428 = no work

res = requests.post("https://api.s46.dev/v1/worker/jobs/lease",
                    headers={"Authorization": f"Bearer {worker_token}"},
                    json={"workerId": "worker_01", "capabilities": ["chat", "code"]})
job = res.json() if res.status_code == 200 else None  # 428 = no work

{
  "jobId": "job_01J...",
  "sessionId": "@dscape/auth-redirect-fix",
  "team": "@s46/engineering",
  "region": "EU-OPO",
  "model": "s46/devstral-small-2-24b",
  "leaseExpiresAt": "2030-01-01T12:05:00Z"
}

{ "error": { "code": "authorization_pending", "message": "no compatible work" } }

Complete a job

POST/v1/worker/jobs/complete→ 200

Report the outcome with workerId, jobId, leaseId, and completion in the JSON body.

Auth · worker credential · Schema · illustrative

curl -X POST https://api.s46.dev/v1/worker/jobs/complete \
  -H "Authorization: Bearer $S46_WORKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workerId":"worker_01","jobId":"job_01J...","leaseId":"lease_01J...","completion":{"state":"succeeded","payload":{"ok":true}}}'

await fetch("https://api.s46.dev/v1/worker/jobs/complete", {
  method: "POST",
  headers: { Authorization: `Bearer ${workerToken}`, "Content-Type": "application/json" },
  body: JSON.stringify({ workerId: "worker_01", jobId, leaseId, completion: { state: "succeeded", payload: { ok: true } } }),
});

requests.post("https://api.s46.dev/v1/worker/jobs/complete",
              headers={"Authorization": f"Bearer {worker_token}"},
              json={"workerId": "worker_01", "jobId": job_id, "leaseId": lease_id, "completion": {"state": "succeeded", "payload": {"ok": True}}})

{
  "workerId": "worker_01",
  "jobId": "job_01J...",
  "leaseId": "lease_01J...",
  "completion": {"state": "succeeded", "payload": {"ok": true}}
}

On this page