Rensei docs
API ReferenceWorker Protocol

Lightweight step-level heartbeat

Low-overhead heartbeat emitted at each agent step (tool call, turn, etc.) to signal liveness without the cost of a full status update. Updates the session's `lastToolCalledAt` timestamp in Redis. Auth failures and storage errors are swallowed (best-effort: never 5xx the caller).

POST
/api/sessions/{id}/step-heartbeat

Authorization

headerAuthorizationBearer <JWT>

Short-lived worker runtime JWT minted by the platform. Claims bind the worker, project, organization, registration, and scopes.

Path Parameters

id*string

Request Body

application/json
  1. body
workerId*string
emittedAt?string

RFC 3339 timestamp from the agent (optional; server uses now if absent).

Formatdate-time
progress?boolean

When true, also updates the session's progress indicator.

totalCostUsd?number

legacy top-level cumulative cost so far in USD (optional; prefer usage.totalCostUsd). Stored on the session Redis twin when strictly above the stored value.

Range0 <= value
inputTokens?integer

legacy top-level cumulative input tokens so far (optional; prefer usage.inputTokens).

Range0 <= value
outputTokens?integer

legacy top-level cumulative output tokens so far (optional; prefer usage.outputTokens).

Range0 <= value
usage?

runner cumulative usage so far (matches the runner step-heartbeat Usage payload). Nested wins over the legacy top-level fields when present.

Response Body

Heartbeat accepted.

application/json
  1. response
ok*true
Value intrue
Example Request
curl -X POST 'https://app.rensei.ai/api/sessions/string/step-heartbeat' \  -H 'Content-Type: application/json' \  -d '{  "workerId": "string"}'
Example Response200
{  "ok": true}

FSM status transition

Drives the session FSM: `pending → claimed → running → finalizing → completed | failed | stopped` Terminal transitions trigger side effects: cost persistence, fleet quota accounting, Linear `agentActivityCreate`, claim release, inbox archival, issue lock release, and next-pending-work promotion.

Ingest batched interview token-delta frames

Used by the interview runner to relay streamed assistant token deltas to the browser. Frames are batched (≤100ms or 20 tokens per flush) and published to `interviewTokenChannel(interviewId)` via Redis pub/sub, where `GET /api/interview/[id]/stream` picks them up for SSE re-delivery to the browser. Auth mirrors `/api/sessions/{id}/activity` (worker runtime JWT).