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.

GET /v1/sessions/{sessionId}/tree

Read the branched family a session belongs to

cURL

curl --request GET \
  --url https://api.example.com/v1/sessions/{sessionId}/tree \
  --header 'Authorization: Bearer <token>'

200

{
  "rootSessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "nodes": [
    {
      "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"
      ]
    }
  ]
}

Authorizations

Authorization · string · header · required

Enforced on every transport, with no exempt operation. A person's request — over the default local unix socket exactly as over a TCP listener — must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011. The socket's file permissions are transport and are not an authorisation.

Path Parameters

sessionId · string<uuid> · required

The session's id.

Query Parameters

label · string

Keep only sessions carrying this exact entry label, plus their ancestors. Absent returns the whole family.

Maximum string length: 128

Response

200

application/json

The branched family this session belongs to.

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.

rootSessionId · string<uuid> · required

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 · object[] · required

The family's sessions, root first. Empty only when a label filter matched nothing.

Show child attributes