Poll & Heartbeat

Once registered, a worker runs a continuous loop: it sends a heartbeat to report its health and polls for new work. This page describes both endpoints and the full structure of the poll response, including batch work items and git credentials.

Heartbeat

Send a heartbeat on the interval provided by the registration response (heartbeatInterval, in milliseconds). A missed heartbeat causes the platform to mark the worker as unhealthy and eventually stop dispatching new sessions to it.

Corrected 2026-08-08. A previous revision of this page documented a "daemon-native" POST /v1/daemon/heartbeat endpoint. That route was hard-deleted on 2026-06-10 alongside /v1/daemon/register - see the note on Worker Registration. POST /api/workers/{workerId}/heartbeat below is the one and only heartbeat endpoint.

POST /api/workers/{workerId}/heartbeat
Authorization: Bearer <runtimeToken>
Content-Type: application/json

Request body

{
  "status": "idle",
  "activeCount": 0,
  "maxSessions": 4
}

Field	Type	Required	Description
`status`	string	No	Daemon-reported state: `idle`, `busy`, `draining` (also accepts the synonyms `ready`/`active`/`online`, `drain`, `unhealthy`/`degraded`/`error`, `offline`/`stopped`). An unrecognized or omitted value is ignored - the platform keeps the worker's previously stored status rather than acting on it.
`activeCount`	number	Yes	Current number of active sessions. Rejected with `400` if missing, non-numeric, or negative.
`maxSessions`	number	No	Maximum concurrent session capacity

Success response (200)

{
  "acknowledged": true,
  "serverTime": "2026-08-08T00:00:00.000Z",
  "pendingWorkCount": 0,
  "hostStatus": { "status": "ok" },
  "pendingMutations": []
}

hostStatus and pendingMutations are always present. hostStatus.status is ok on a healthy beat, or one of pool_deleted / pool_disabled when the host's pool was removed or disabled (accompanied by recommendedAction and, where applicable, candidatePoolIds). pendingMutations carries any daemon-config mutations queued for this host since the last beat, each shaped { id, op, params, requestedAt, requestedBy }.

Poll for work

Poll returns any sessions queued for this worker, plus inbox messages and optional batch work items.

GET /api/workers/{workerId}/poll
Authorization: Bearer <runtimeJwt>

The platform enforces that the JWT sub claim matches the {workerId} URL parameter. A mismatched token returns 403 Forbidden.

Poll response

{
  "work": [
    {
      "sessionId": "sess_01abc...",
      "issueId": "linear:abc123",
      "projectId": "proj_01abc...",
      "workType": "feature",
      "agentCard": { "... agent card object ..." },
      "systemPromptOverride": null,
      "gitCredentials": {
        "token": "ghp_...",
        "host": "github.com",
        "expiresAt": "2026-06-02T13:00:00Z"
      }
    }
  ],
  "inboxMessages": [],
  "hasInboxMessages": false,
  "preClaimed": true,
  "claimedSessionIds": ["sess_01abc..."],
  "batchWork": []
}

Work item fields

Field	Type	Description
`sessionId`	string	Unique session ID. Use in all session lifecycle calls.
`issueId`	string	Provider-namespaced issue identifier (e.g. `linear:ABC-123`)
`projectId`	string	Platform project ID
`workType`	string	SDLC work type: `feature`, `bug_fix`, `refactor`, `research`, etc.
`agentCard`	object	Resolved agent card for this session (includes system prompt, capabilities, tool config)
`systemPromptOverride`	string \| null	Override system prompt, if set on the session (takes precedence over agent card)
`gitCredentials`	object \| null	Short-lived git credentials for repo access
`authMode`	string	Auth mode for this session: `byok`, `metered`, `shared`, `host-session`, `local`

gitCredentials

When the session requires repository access, gitCredentials provides a short-lived token:

{
  "token": "ghs_...",
  "host": "github.com",
  "username": "x-access-token",
  "expiresAt": "2026-06-02T13:00:00Z"
}

Configure git to use it:

git config --global credential.helper store
echo "https://x-access-token:${GIT_TOKEN}@github.com" > ~/.git-credentials

Batch work items

Workers that advertise the code-survival-scan capability receive batchWork[] items in addition to session-based work. These are code survival analysis tasks dispatched in bulk.

{
  "batchWork": [
    {
      "batchItemId": "batch_01abc...",
      "type": "code-survival-scan",
      "payload": {
        "repository": "github.com/my-org/my-repo",
        "pool": "RW3",
        "commitRange": "abc123..def456"
      }
    }
  ]
}

Declare the capability at registration to receive these items:

{
  "registrationToken": "rsk_live_...",
  "capabilities": ["code-execution", "code-survival-scan"]
}

Inbox messages

The inboxMessages array carries out-of-band signals for the worker - for example, a user's nudge prompt sent via the Public Sessions API or a stop signal.

{
  "inboxMessages": [
    {
      "messageId": "msg_01abc...",
      "type": "prompt",
      "payload": { "text": "Focus on the error handling in the login flow." }
    }
  ],
  "hasInboxMessages": true
}

ACK inbox messages after processing them:

curl -X POST "https://app.rensei.ai/api/sessions/sess_01abc.../inbox/ack" \
  -H "Authorization: Bearer <runtimeJwt>" \
  -H "Content-Type: application/json" \
  -d '{"messageId": "msg_01abc..."}'

Pre-claim semantics

When preClaimed is true, the platform has atomically reserved the returned sessions for this worker. The worker must either begin execution or explicitly return the session. There is no separate "claim" step - sessions returned in a poll response are already owned by the calling worker.

Worker loop example (TypeScript)

async function workerLoop(workerId: string, jwt: string) {
  while (true) {
    // Heartbeat
    await fetch(`https://app.rensei.ai/api/workers/${workerId}/heartbeat`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${jwt}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ status: 'idle', activeCount: 0, maxSessions: 4 }),
    });

    // Poll
    const pollRes = await fetch(
      `https://app.rensei.ai/api/workers/${workerId}/poll`,
      { headers: { Authorization: `Bearer ${jwt}` } }
    );
    const { work, inboxMessages } = await pollRes.json();

    for (const session of work) {
      // dispatch session to agent subprocess
    }

    await sleep(5000); // use pollInterval (ms) from registration
  }
}

Worker Registration - obtain a workerId and runtimeToken
Session Lifecycle - status transitions after picking up work
Worker Credentials - credential snapshot and rotate-stream SSE

On this page