> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Read the branched family a session belongs to > Every session joined to this one by branch provenance, root first, each node carrying the entry it branched at. A branch IS a session, so this is the shape listSessions cannot show: that flat list says which conversations exist and never that one continues another. It returns the WHOLE family, not the subtree below the named session. A person navigating a tree is standing on a branch, and the thing they most often want is the sibling they walked away from — which a subtree rooted where they stand would not contain. Each node carries the first and last thing said in it. That is how an unsummarised branch is recognised on sight, which is the point: no summary is ever produced because a branch was abandoned, so recognition has to work without one. Asking for a summary (summarizeSession) is one command away when it does not. A node whose parentSessionId is absent is a root. That includes a branch whose origin was purged: the provenance link is cleared rather than the branch taken away, so an orphaned branch becomes a root of its own family and stays fully readable. The label filter keeps a session carrying that label AND every ancestor of one, whether the ancestor carries it or not. A tree with holes in the middle is not a tree — dropping an unlabelled parent would draw its child hanging off a branch point that never existed. A family whose branch provenance runs deeper than the walk allows is refused (409) rather than answered with a tree that quietly stops partway. A truncated tree presented as whole would be missing exactly the branch the person is standing on. ## OpenAPI ````yaml /en/openapi/v3-current/narya.yaml get /v1/sessions/{sessionId}/tree openapi: 3.1.0 info: title: Narya Host API version: 1.0.0 description: >- The contract between the Narya host and every client. One long-lived host runs on your machine and serves this API over a Unix socket in your Narya home. Narya creates the socket owner-only, and file permissions are the whole authorization. There is no password, no token and no TLS. The terminal client and the one-shot command that Lerian ships drive this API, and a client you write drives the same one. Results never arrive on the response of the request that caused them. Submitting a message returns 202 with a turn id. Everything the turn produces streams over GET /v1/events as server-sent events with a typed envelope, and a stream resumes from a Last-Event-ID header. One error envelope: code, title, message, and fields on 422. Codes are NRY- followed by four digits. A paged list answers items, limit and a nextCursor when more remains. Cursors are opaque. servers: [] security: [] tags: - name: host description: The host process itself — version, uptime, mode, store. - name: sessions description: Durable conversation containers. Archive, never destroy. - name: messages description: Submitting work into a session and interrupting it. - name: events description: The server-sent event stream every client consumes. - name: lanes description: Parallel tracks inside a session — main, subagent, side. - name: agents description: Named recipes — instructions, tools, model, policy. Read-only in v1. - name: ladder description: >- What a person can type: the skills and command files in force for one repository, and expanding one into text. Five origins merged, nearest winning a name, the repository's own rungs gated on trust. - name: permissions description: Pending permission asks, decisions, and the decision audit. - name: intercom description: Sessions on one machine finding and messaging each other. - name: packages description: The one thing a user installs — resources, Go code, or both. - name: workflows description: Deterministic multi-agent orchestration runs. - name: providers description: Model suppliers, their auth state, and the model catalogue. - name: monitors description: >- Long-running watchers a session keeps beside its conversation — a test runner in watch mode, a build, a log being followed. Started by the model or by the person, always listed, always killable. - name: records description: The queryable local record of everything that happened. - name: schedules description: >- Work the host's own clock starts with nobody present — a repository, a prompt, a rule and what one fire may spend. Cancel, never destroy. paths: /v1/sessions/{sessionId}/tree: parameters: - $ref: '#/components/parameters/SessionIdParam' get: tags: - sessions summary: Read the branched family a session belongs to description: >- Every session joined to this one by branch provenance, root first, each node carrying the entry it branched at. A branch IS a session, so this is the shape listSessions cannot show: that flat list says which conversations exist and never that one continues another. It returns the WHOLE family, not the subtree below the named session. A person navigating a tree is standing on a branch, and the thing they most often want is the sibling they walked away from — which a subtree rooted where they stand would not contain. Each node carries the first and last thing said in it. That is how an unsummarised branch is recognised on sight, which is the point: no summary is ever produced because a branch was abandoned, so recognition has to work without one. Asking for a summary (summarizeSession) is one command away when it does not. A node whose parentSessionId is absent is a root. That includes a branch whose origin was purged: the provenance link is cleared rather than the branch taken away, so an orphaned branch becomes a root of its own family and stays fully readable. The label filter keeps a session carrying that label AND every ancestor of one, whether the ancestor carries it or not. A tree with holes in the middle is not a tree — dropping an unlabelled parent would draw its child hanging off a branch point that never existed. A family whose branch provenance runs deeper than the walk allows is refused (409) rather than answered with a tree that quietly stops partway. A truncated tree presented as whole would be missing exactly the branch the person is standing on. operationId: getSessionTree parameters: - name: label in: query required: false description: >- Keep only sessions carrying this exact entry label, plus their ancestors. Absent returns the whole family. schema: type: string maxLength: 128 responses: '200': description: The branched family this session belongs to. content: application/json: schema: $ref: '#/components/schemas/SessionTree' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalServerError' components: parameters: SessionIdParam: name: sessionId in: path required: true description: The session's id. schema: type: string format: uuid schemas: SessionTree: type: object description: >- One whole branched family: every session reachable from the one asked about through branch provenance, root first, parents always listed before the branches that came off them. required: - rootSessionId - nodes properties: rootSessionId: type: string format: uuid description: >- The family's root — the session nothing in this family branched from. It names which family was searched even when a label filter left no nodes at all. nodes: type: array description: >- The family's sessions, root first. Empty only when a label filter matched nothing. items: $ref: '#/components/schemas/SessionTreeNode' SessionTreeNode: type: object description: >- One session inside a branched family, with what it takes to recognise it without opening it. required: - sessionId - status - entryCount - createdAt - updatedAt properties: sessionId: type: string format: uuid parentSessionId: type: string format: uuid description: >- The session this one branched from. Absent on a root — including a branch whose origin was purged, which becomes a root of its own rather than being taken away with it. branchedFromEntryId: type: string format: uuid description: >- The entry this session branched at. It survives the origin being purged, so a branch can still say WHERE it came off even when it can no longer say what from. branchedFromSeq: type: integer format: int64 minimum: 1 description: >- That entry's position in the parent's transcript — the readable form of the branch point, since the id above is 36 characters nobody can place. Read against the parent node's entryCount it says how much of the parent this branch left behind: "branched at 6 of 14". This is what indentation cannot say. Indentation says WHICH session a branch came off; without a position, two rewinds off the same parent — one at its second message, one at its eighth — are siblings drawn identically, and every rewind is a branch, so "how far back did this one go" is the fact somebody opens the tree to decide on. Absent when the parent was purged: the id outlives that, the entry it names does not, so there is no transcript left to count it in. title: type: string maxLength: 512 status: type: string enum: - idle - running - waiting - archived entryCount: type: integer description: >- How many transcript entries this session holds — every lane of it, deliberately unlike the excerpts below, which are the main lane's alone. This answers how long the session is, and a delegation's rows are as much part of what it holds as the conversation's own. createdAt: type: string format: date-time updatedAt: type: string format: date-time firstMessageExcerpt: type: string maxLength: 512 description: >- The first thing said in this session's main lane, as one cleaned display line. A message — never a tool result, never a note about the session itself, and never a delegation's own track. Absent when nobody has said anything here yet. Every session of a family carries the SAME first line: branching copies the transcript from the start of the lane, so this discriminates nothing between siblings and narya's own clients draw lastMessageExcerpt instead. It is served for a client that wants the family's opening question, not as the way a branch is recognised. lastMessageExcerpt: type: string maxLength: 512 description: >- The last thing said in this session's main lane, as one cleaned display line, and a message on the same terms as the first. This is the excerpt that differs between siblings, so it is the one a tree row draws: no summary is ever produced because a branch was abandoned, so a shelf of retired branches has to be told apart by what was last said in them, and by branchedFromSeq, rather than by the epitaph retiring them wrote. summary: type: string maxLength: 4096 description: >- The summary somebody asked for (summarizeSession), trimmed to this length with a marker when the model answered past it. Absent until they do: nothing summarises a branch because a rewind happened. summaryAt: type: string format: date-time description: >- When that summary was taken, so a node can say its summary predates the last thing that happened in it. labels: type: array description: >- Every label set on this session's entries, in transcript order. This is what the label filter matches. items: type: string maxLength: 128 examples: - sessionId: 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d parentSessionId: 3a1c5e7f-9b2d-4e6a-8c0f-1d3b5a7c9e2f branchedFromEntryId: 9c2b7a10-3e4d-4f6a-8b1c-5d7e9f0a2b3c branchedFromSeq: 6 title: Retry with a different approach status: idle entryCount: 12 firstMessageExcerpt: where does the ledger validate an asset code? lastMessageExcerpt: it validates it in validate.go, line 88 labels: - the version that worked Error: type: object description: >- The single error envelope every operation returns. Codes are NRY- followed by four digits and are catalogued in the top-level x-error-catalog extension. fields appears only on 422 validation errors, mapping each offending property to its problem. required: - code - title - message properties: code: type: string pattern: ^NRY-[0-9]{4}$ description: Machine-readable error code from the NRY catalogue. title: type: string maxLength: 256 description: Short human-readable summary of the error class. message: type: string maxLength: 4096 description: Specific, actionable description of what went wrong. fields: type: object description: Per-field validation problems. Present on 422 only. additionalProperties: type: string examples: - code: NRY-0002 title: Session not found message: >- No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host. responses: BadRequest: description: Malformed request — invalid parameter, cursor, or JSON body. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The addressed resource does not exist on this host. content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: >- The resource's current state rejects the request — archived session, busy lane, slot conflict, failed build, already-final state. content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: The host failed — including a store that refuses writes (NRY-0012). content: application/json: schema: $ref: '#/components/schemas/Error' ````