Rensei docs
API ReferenceWorker Protocol

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.

POST
/api/sessions/{id}/status

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
status*AgentSessionStatus

FSM states for an agent session:

  • pending - queued, waiting for a worker
  • claimed - worker has claimed but not yet started
  • running - agent actively processing
  • finalizing - cleanup in progress
  • completed - finished successfully (terminal)
  • failed - encountered an error (terminal)
  • stopped - stopped by user (terminal)
Value in"pending""claimed""running""finalizing""completed""failed""stopped"
continuationOutcome?string

Typed rework outcome, stored only for completed status posts. Unknown values are ignored.

Value in"no_op""fixed_in_place"
providerSessionId?string
worktreePath?string
error?unknown

Error context (on failed status).

totalCostUsd?number
inputTokens?integer
outputTokens?integer
cacheReadTokens?integer

Cache-read tokens (disjoint from inputTokens).

cacheWriteTokens?integer

Cache-write tokens (disjoint from inputTokens).

reasoningTokens?integer

Reasoning tokens (a SUBSET of outputTokens — never added on top).

usageStatus?string

Usage completeness (always re-derived server-side from the token buckets; a runner-sent value is ignored): a zero-token crash reads untracked, not a measured $0.

Value in"tracked""partial""untracked"
commitSha?string

Head commit SHA at session end (used for CI gate correlation).

pullRequestUrl?string

PR URL opened during the session (used for CI gate correlation).

manifest?unknown

Turn-result manifest, routed through the hook chain on terminal transitions.

Response Body

Status updated.

application/json
  1. response
updated*boolean
session*

Full session state object stored in Redis.

Example Request
curl -X POST 'https://app.rensei.ai/api/sessions/string/status' \  -H 'Content-Type: application/json' \  -d '{  "workerId": "string",  "status": "pending"}'
Example Response
{  "updated": true,  "session": {    "linearSessionId": "string",    "trackerSessionId": "string",    "issueId": "string",    "issueIdentifier": "string",    "providerSessionId": "string",    "worktreePath": "string",    "status": "pending",    "createdAt": 0,    "updatedAt": 0,    "workerId": "string",    "queuedAt": 0,    "claimedAt": 0,    "priority": 0,    "promptContext": "string",    "organizationId": "string",    "workType": "research",    "agentId": "string",    "projectName": "string",    "provider": "string",    "totalCostUsd": 0,    "inputTokens": 0,    "outputTokens": 0,    "lastToolName": "string",    "lastToolCalledAt": 0,    "toolCallCount": 0  }}

Read session state

Read session state - Rensei REST API operation reference.

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).