Worker control
Operator-only worker provisioning, then credentialed heartbeat and job leasing.
Operators provision workers; workers use the returned credentials to heartbeat, lease jobs, acknowledge leases, and report completion. The API represents model certification/publication as kind: "model" jobs with capability checks (model_certification, model_registry_publish); provisioning does not implement or attest those workloads.
The API checks worker credentials, lease eligibility/capacity, job compatibility, and assigned job/lease identifiers. Stored harness policy is separate: these routes do not establish a signed per-job sandbox policy or CLI drift enforcement.
Route inventory
| Method | Route | Purpose |
|---|---|---|
POST | /v1/worker/register | Operator-only provisioning; returns 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
Production requires the configured S46_ADMIN_TOKEN, sent as Authorization: Bearer <operator-token> or X-S46-Admin-Token. Use one transport; a supplied bearer credential takes precedence. Tenant owner/admin/team-admin/viewer tokens and worker credentials return 403 forbidden for every scope and worker ID, including replacement of an existing ID. Do not expose the operator token in tenant clients.
Non-production keeps bootstrap access only when no operator token is configured; otherwise the same operator check applies. This exception is not tenant provisioning authority.
Send worker metadata (kind, region, capacity, capabilities, and models). 201 returns { worker, token }; that token is for subsequent worker calls, not registration. Same-ID replacement rotates that worker's credential. Making provisioning operator-only does not retroactively revoke other issued credentials: operators must inventory and rotate/revoke them explicitly. Provisioning and reported capabilities are not VM isolation, loaded-model verification, or certification attestation.
| Registration scope | Validation and leasing boundary |
|---|---|
team supplied | Team must exist; its organization is derived. An explicit organizationSlug must match. Leasing stays within both organization and team. |
Only organizationSlug supplied | Organization must exist. Leasing stays within that organization. |
| Both empty/omitted | Intentionally global, cross-organization operator pool; other job eligibility checks still apply. |
Invalid or conflicting scope returns 400 invalid_request; unknown teams/organizations return 404 not_found. Scope is stored at provisioning, not selected by later lease requests. Worker details/logs/drain/revoke authorize against that stored team, else organization; global workers require operator credentials.
Heartbeat
Periodically report liveness and state so the scheduler can route work and mark stale workers unavailable.
Lease
Ask for the next compatible job. Leasing uses current stored worker fields and rechecks the credential under the lease lock, so a previously authorized request cannot retain old scope/capabilities after rotation or revocation. When no eligible job is available, the API returns 428 authorization_pending.
Model lifecycle jobs require model_certification for model.certify, or model_registry_publish for model.publish/model.yank; advertising the model ID alone is insufficient. These are scheduling checks, not evidence of workload execution.
Acknowledge
Acknowledge the assigned job and lease before starting. The API validates the worker credential and matching leased job/worker/lease IDs, then records the acknowledgement; it does not load or execute a stored harness policy.
Complete
Report success or failure. Model lifecycle completion payloads carry certification evidence or publication/yank results for API validation; registration alone does not prove a worker performed those workloads.
Lease a job
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."
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", "leaseSeconds": 60 }'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", leaseSeconds: 60 }),
});
const job = res.status === 200 ? await res.json() : null; // 428 = no workres = requests.post("https://api.s46.dev/v1/worker/jobs/lease",
headers={"Authorization": f"Bearer {worker_token}"},
json={"workerId": "worker_01", "leaseSeconds": 60})
job = res.json() if res.status_code == 200 else None # 428 = no work200 returns { job, lease }. Use job.id and lease.id for acknowledgement and completion; scope and capabilities are not lease-request overrides.
{ "error": { "code": "authorization_pending", "message": "no compatible work" } }Complete a job
Report the outcome with workerId, jobId, leaseId, and completion in the JSON body.
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}}
}