Rensei docs
API ReferenceDispatch

Read the append-only decision and handoff records for one program.

Keyset-paginated, newest first. Records carry the markdown a coordinator wrote and typed references to the issues, commits and sessions the record concerns. Addressed records (recipients) are the mailbox between sessions; addressedOnly (true/false or 1/0) narrows to them, and unreadOnlyFor to the unread mail of one reader: broadcasts plus records addressed to that reader or to one of its comma-separated roles, never mail addressed to another reader. Visibility matches the program itself: an invisible program is reported as not found rather than forbidden.

GET
/api/cli/programs/{programId}/records

Authorization

headerAuthorizationBearer <rsk_live_*>

Rensei API key presented as Authorization: Bearer rsk_live_. Required API-key scopes are recorded per operation in x-rensei-required-scopes.

Path Parameters

programId*string
Match^prog_[0-9a-f]{32}$

Query Parameters

kind?string
Value in"decision""handoff""checkpoint""note"
addressedOnly?string
Value in"0""1""true""false"
unreadOnlyFor?string
Length1 <= length <= 256
roles?string
Lengthlength <= 1024
limit?integer
Range1 <= value <= 200
cursor?string
Length1 <= length <= 2048

Response Body

One page of program records, newest first.

application/json
  1. response
ledgerVersion*string
programVersion*string
programId*string
Match^prog_[0-9a-f]{32}$
records*array<>
Itemsitems <= 200
nextCursor?
Example Request
curl -X GET 'https://app.rensei.ai/api/cli/programs/string/records'
Example Response
{  "ledgerVersion": "rensei.session-ledger/v1alpha1",  "programVersion": "rensei.session-ledger.program/v1alpha1",  "programId": "string",  "records": [    {      "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"    }  ],  "nextCursor": {    "createdAt": "2019-08-24T14:15:22Z",    "recordId": "string"  }}

Mark program records read for one reader session.

Idempotent: re-marking an already-read record marks nothing new. Record ids outside the program are ignored so a caller cannot probe record existence across programs. The reader attribution is derived from the authenticating principal; readerSessionId is the opaque session cookie being marked.

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.