Rensei docs
API ReferenceDispatch

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.

POST
/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}$

Request Body

application/json
  1. body
kind*string
Value in"decision""handoff""checkpoint""note"
title*string
Length1 <= length <= 512
body*string
Length1 <= length <= 65536
refs?
recipients?array<>
Items1 <= items <= 16
replyToRecordId?string
Match^prec_[0-9a-f]{32}$
supersedesRecordId?string
Match^prec_[0-9a-f]{32}$
idempotencyKey?string
Length1 <= length <= 256

Response Body

An idempotency key replayed the record already written.

application/json
  1. response
ledgerVersion*string
programVersion*string
record*
created*boolean
Example Request
curl -X POST 'https://app.rensei.ai/api/cli/programs/string/records' \  -H 'Content-Type: application/json' \  -d '{  "kind": "decision",  "title": "string",  "body": "string"}'
Example Response
{  "ledgerVersion": "rensei.session-ledger/v1alpha1",  "programVersion": "rensei.session-ledger.program/v1alpha1",  "record": {    "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"  },  "created": true}

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.

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.