Read the current resumable topology for one program ledger.
One authoritative read joins the immutable program event stream to current session-ledger edges and nodes, and inlines the most recent program records so a cold session needs one call rather than three. Terminal children are absent even when no later program event was appended. mailbox counts one reader's unread mail (broadcasts plus records addressed to it or to one of the comma-separated roles it claims): the authenticated principal by default, or readerSessionId when named. It is null when no reader can be attributed.
AuthorizationBearer <rsk_live_*>Rensei API key presented as Authorization: Bearer rsk_live_. Required API-key scopes are recorded per operation in x-rensei-required-scopes.
programId*string^prog_[0-9a-f]{32}$readerSessionId?string1 <= length <= 256roles?stringlength <= 1024Program resume projection.
application/json- response
ledgerVersion*stringprogramVersion*stringprogram*resumeCursor*lastEvent*||||||nullopenWaves*array<>inFlightChildren*array<>latestRecords*array<>items <= 50latestByKind*state*array<>items <= 100stateTruncated*booleanstateKeyCount*integer0 <= value <= 9007199254740991mailbox*|nullcurl -X GET 'https://app.rensei.ai/api/cli/programs/string/resume'{ "ledgerVersion": "rensei.session-ledger/v1alpha1", "programVersion": "rensei.session-ledger.program/v1alpha1", "program": { "ledgerVersion": "rensei.session-ledger/v1alpha1", "programVersion": "rensei.session-ledger.program/v1alpha1", "programId": "string", "externalKey": "string", "title": "string", "scope": { "kind": "project", "projectId": "string" }, "origin": { "sessionId": "string", "graphId": "string", "projectId": "string", "phase": "string", "stateVersion": 1 }, "createdByPrincipalRef": "string", "author": { "kind": "human", "id": "string" }, "createdAt": "2019-08-24T14:15:22Z" }, "resumeCursor": { "afterSeq": "string" }, "lastEvent": { "ledgerVersion": "rensei.session-ledger/v1alpha1", "programVersion": "rensei.session-ledger.program/v1alpha1", "programId": "string", "eventId": "string", "seq": "string", "actor": { "kind": "user", "ref": "string" }, "source": { "kind": "session", "ref": "string" }, "projectId": "string", "repositoryId": "string", "waveId": "string", "occurredAt": "2019-08-24T14:15:22Z", "recordedAt": "2019-08-24T14:15:22Z", "type": "issue_created", "issue": { "provider": "string", "ref": "string" } }, "openWaves": [ { "waveId": "string", "openedEventId": "string", "openedSeq": "string", "openedAt": "2019-08-24T14:15:22Z" } ], "inFlightChildren": [ { "edgeId": "string", "sessionId": "string", "projectId": "string", "transport": "string", "edgeState": "string", "phase": "string", "stateVersion": 1, "dispatchedEventId": "string", "dispatchedSeq": "string", "waveId": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" } ], "latestRecords": [ { "ledgerVersion": "rensei.session-ledger/v1alpha1", "programVersion": "rensei.session-ledger.program/v1alpha1", "programId": "string", "recordId": "string", "kind": "decision", "title": "string", "body": "string", "refs": { "issues": [ "string" ], "commits": [ "string" ], "sessions": [ "string" ] }, "recipients": [ { "kind": "session", "id": "string" } ], "replyToRecordId": "string", "supersedesRecordId": "string", "author": { "kind": "human", "id": "string" }, "idempotencyKey": "string", "createdAt": "2019-08-24T14:15:22Z" } ], "latestByKind": { "decision": { "ledgerVersion": "rensei.session-ledger/v1alpha1", "programVersion": "rensei.session-ledger.program/v1alpha1", "programId": "string", "recordId": "string", "kind": "decision", "title": "string", "body": "string", "refs": { "issues": [ "string" ], "commits": [ "string" ], "sessions": [ "string" ] }, "recipients": [ { "kind": "session", "id": "string" } ], "replyToRecordId": "string", "supersedesRecordId": "string", "author": { "kind": "human", "id": "string" }, "idempotencyKey": "string", "createdAt": "2019-08-24T14:15:22Z" }, "handoff": { "ledgerVersion": "rensei.session-ledger/v1alpha1", "programVersion": "rensei.session-ledger.program/v1alpha1", "programId": "string", "recordId": "string", "kind": "decision", "title": "string", "body": "string", "refs": { "issues": [ "string" ], "commits": [ "string" ], "sessions": [ "string" ] }, "recipients": [ { "kind": "session", "id": "string" } ], "replyToRecordId": "string", "supersedesRecordId": "string", "author": { "kind": "human", "id": "string" }, "idempotencyKey": "string", "createdAt": "2019-08-24T14:15:22Z" }, "checkpoint": { "ledgerVersion": "rensei.session-ledger/v1alpha1", "programVersion": "rensei.session-ledger.program/v1alpha1", "programId": "string", "recordId": "string", "kind": "decision", "title": "string", "body": "string", "refs": { "issues": [ "string" ], "commits": [ "string" ], "sessions": [ "string" ] }, "recipients": [ { "kind": "session", "id": "string" } ], "replyToRecordId": "string", "supersedesRecordId": "string", "author": { "kind": "human", "id": "string" }, "idempotencyKey": "string", "createdAt": "2019-08-24T14:15:22Z" }, "note": { "ledgerVersion": "rensei.session-ledger/v1alpha1", "programVersion": "rensei.session-ledger.program/v1alpha1", "programId": "string", "recordId": "string", "kind": "decision", "title": "string", "body": "string", "refs": { "issues": [ "string" ], "commits": [ "string" ], "sessions": [ "string" ] }, "recipients": [ { "kind": "session", "id": "string" } ], "replyToRecordId": "string", "supersedesRecordId": "string", "author": { "kind": "human", "id": "string" }, "idempotencyKey": "string", "createdAt": "2019-08-24T14:15:22Z" } }, "state": [ { "ledgerVersion": "rensei.session-ledger/v1alpha1", "programVersion": "rensei.session-ledger.program/v1alpha1", "programId": "string", "key": "string", "version": 1, "value": null, "author": { "kind": "human", "id": "string" }, "createdAt": "2019-08-24T14:15:22Z" } ], "stateTruncated": true, "stateKeyCount": 0, "mailbox": { "readerSessionId": "string", "unreadCount": 0, "unreadAddressedCount": 0, "newestUnreadRecordIds": [ "string" ] }}Append one decision, handoff, checkpoint or note to a program.
Append-only: there is no update and no delete. A later record supersedes an earlier one by being later. The author is derived from the authenticating principal - a session or user token records as a human, an OAuth agent as an agent, an API key as api_key - and is never read from the body. An optional idempotency key, unique within the program, makes a retry return the record it already wrote. Optional recipients address the record to named sessions or handoff roles (the mailbox between sessions); replyToRecordId threads a reply and supersedesRecordId retires the named record for this record's own readers only: its recipients, or every reader when it is a broadcast. A reader never loses mail to a replacement it cannot see.
Read the structured program state, latest-wins per key.
The queryable half of the ledger: one JSON value per key with its version, author and timestamp. With ?key=<key> reads that key append history newest-first (use limit to bound it); without it reads the latest value of the 500 most recently written keys (sorted by key), with truncated and the total keyCount when the program holds more. Visibility matches the program itself.