Rensei docs
API ReferenceWorker Protocol

AF-compatible worker registration

AF-compatible registration endpoint. Accepts three auth modes: 1. `Authorization: Bearer rsk_live_*` or `rsp_live_*` (registration token in header). 2. Legacy `WORKER_API_KEY` (transitional; being removed). 3. User session cookie / `rsk_` API key with `projectId` in body (new-user onboarding). `projectAdmissionVersion: 2` makes `projectIds` authoritative, including explicit empty = serve none. When the version is absent, the platform uses the bounded legacy projection. Returns a `runtimeToken` (and `runtimeTokenExpiresAt`) for runtime-JWT-capable callers; legacy callers receive `null` for these fields.

POST
/api/workers/register

Authorization

headerAuthorizationBearer <rsp_live_* or project-scoped rsk_live_*>

Project-scoped worker registration token. Current handlers accept this only where explicitly listed.

Request Body

application/json
  1. body
hostname*string
capacity?integer

Max concurrent sessions. Hosted session-shim registration requires exactly 0 for auth-only recovery; legacy registration requires a positive value. Alias maxAgents also accepted.

Range0 <= value
maxAgents?integer

Alias for capacity (legacy field).

version?string
region?string
machineId?string
capabilities?array<string>

Advertised capability tags (e.g. code-survival-scan).

sessionShimSupported?boolean

Explicit hosted session-shim capability advertisement. True enables sticky stable-host recovery; false or absent remains legacy only when that host was never enabled.

sessionShimControllerId?string

Actual per-process daemon/controller identity. Required with sessionShimSupported=true and must differ from workerId.

Length1 <= length <= 256
sessionShimProtocolMin?integer

Required with sessionShimSupported=true; overlap remains anchored at v1 while hosted durable-carrier eligibility requires selected v3.

sessionShimProtocolMax?integer

Required with sessionShimSupported=true. Hosted durable carrier eligibility requires actual selected protocol 3 exactly; max 3 alone is not evidence.

Range3 <= value <= 4294967295
sessionShimCapabilities?array<>

Required with sessionShimSupported=true and must equal the exact closed four-token set in canonical order. Hosted activation remains default-off.

Items4 <= items <= 4
activeAgentCount?integer
Default0
projects?array<string>

Legacy project filter (overwritten for runtime-JWT callers).

projectId?string

Required when registering via user-auth (session/rsk_ key/WorkOS JWT).

projectAdmissionVersion?2

When present as 2, projectIds is authoritative and an empty set means serve no projects. Absence selects the legacy projection.

Value in2
projectIds?array<string>

Required when projectAdmissionVersion is 2. This is the exact applied project set and is never unioned with daemonProjects or the authentication anchor; an explicit empty array means serve none.

daemonProjects?array<>

Daemon-reported allowlist entries.

workareaExecutors?array<>

Per-harness workarea capability attestations. Each entry binds one harness adapter (harnessId) to the protocols it speaks (multiRepositoryWorkareaProtocols, e.g. session-root-v1) and the repository-authority enforcement it upholds (repositoryAuthorityEnforcement, e.g. isolated-read-only-v1). Registration records each attested capability as a harness-scoped tag on the worker; the retired top-level protocol/enforcement fields are not read.

hostInfo?

Optional host metadata reported by the daemon at registration.

executionSecurityEnforcement?

Host embedder-attested execution-security levels, per substrate dimension. Known dimensions and levels only; malformed is refused with 400. Absent leaves the host's stored attestation unchanged.

Response Body

Worker registered.

application/json
  1. response
workerId*string
heartbeatInterval*integer

Milliseconds between heartbeats.

pollInterval*integer

Milliseconds between polls.

runtimeToken?|

Runtime JWT for all subsequent calls (null for legacy auth).

runtimeTokenExpiresAt?|
Formatdate-time
projectAdmissionVersion?2

Present for versioned project-admission registrations.

Value in2
appliedProjectIds?array<string>

Exact project set acknowledged for this worker registration when projectAdmissionVersion is 2. An empty array means the worker serves no projects.

sessionShim?

Exact non-secret stable-host credential receipt. Adoption revision 0 is valid only while recovering. Hosted activation remains default-off until the relay durable full-host-frame path is deployed.

Example Request
curl -X POST 'https://app.rensei.ai/api/workers/register' \  -H 'Content-Type: application/json' \  -d '{  "hostname": "string"}'
Example Response
{  "workerId": "string",  "heartbeatInterval": 0,  "pollInterval": 0,  "runtimeToken": "string",  "runtimeTokenExpiresAt": "2019-08-24T14:15:22Z",  "projectAdmissionVersion": 2,  "appliedProjectIds": [    "string"  ],  "sessionShim": {    "enabled": true,    "state": "recovering",    "workerHostId": "string",    "adoptionRevision": "string",    "controllerId": "string",    "protocolMin": 1,    "protocolMax": 3,    "capabilities": [      "authoritative_snapshot_v2",      "authoritative_snapshot_v2",      "authoritative_snapshot_v2",      "authoritative_snapshot_v2"    ]  }}

Refresh expired runtime JWT

Refresh expired runtime JWT - Rensei REST API operation reference.

Persist an exact host-level session restart fence.

Runtime-worker-JWT-only planned-restart coordination mutation. The JWT must remain unrevoked and bound to the named organization and live host; its worker registration may already be deregistered, because a restart fence conserves an existing host rather than granting new work authority. One fence id accepts one exact ordered session set: exact replay returns the same durable revision, while changed bytes are refused. Fence expiry is never release authority.