s46.apiv1

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

MethodRoutePurpose
POST/v1/worker/registerOperator-only provisioning; returns a worker credential.
POST/v1/worker/heartbeatReport liveness and current state.
POST/v1/worker/jobs/leaseLease the next compatible job.
POST/v1/internal/leases/ackAcknowledge a lease before starting work.
POST/v1/worker/jobs/completeReport success or failure for a job.
·/v1/internal/*Operator-only controls for the worker/job runtime.

Lease lifecycle

Register

POST/v1/worker/register→ 201 / 403

Auth · configured operator token

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 scopeValidation and leasing boundary
team suppliedTeam must exist; its organization is derived. An explicit organizationSlug must match. Leasing stays within both organization and team.
Only organizationSlug suppliedOrganization must exist. Leasing stays within that organization.
Both empty/omittedIntentionally 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

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", "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 work
res = 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 work

200 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

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