> ## 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. # List what narya has been taught > Cursor-paginated list of this owner's refinements, newest first, paged on (createdAt, id) — two facts consented in the same second would otherwise repeat one and lose the other across a page boundary. Rolled-back rows are in it: walking backwards from a strange behaviour to the fact that caused it is what the row is for. Each row carries its provenance, its state, how often it has fired and — for a capability that executes — its script's HASH. Not the script's text, which is on getRefinement: a listing that carried every authored program's source is a listing nobody can page. ## OpenAPI ````yaml /pt/openapi/v3-current/narya.yaml get /v1/refinements 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 serves this API over a Unix socket in your Narya home. The terminal client and the one-shot command that Lerian ships drive this API, and a client you write drives the same one. Requests authenticate with a bearer token issued by the identity provider the host is configured with. An operation that declares another security scheme also accepts that credential. A request without a valid credential gets 401 with NRY-0011. A caller whose role lacks the permission an operation needs gets 403 with NRY-0028. 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 and message. Codes are NRY- followed by four digits. Cursors are opaque. servers: [] security: - bearerAuth: [] 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: extensions description: >- Host-side extensions and the operations each exposes over the wire. This is the generic lane a host extension uses to serve its own client half (a TUI component, a web panel) or any API-only consumer, without adding routes to this contract. - 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: environments description: >- Where a session's code lives and its commands run — this machine, or a container narya operates. A session that names none runs here. - 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. - name: sharing description: >- Publishing a session from a developer's own home to the organisation's, and what is held back before a byte leaves the machine. - name: refinements description: >- What this owner has taught narya and allowed it to keep — distilled facts, and the skills, agents and commands the model wrote for itself. Propose, read, consent, roll back. Nothing here fires until a person answers. - name: platform description: >- Calls Lerian's control plane made to a home it hosts, as this home recorded them. paths: /v1/refinements: get: tags: - refinements summary: List what narya has been taught description: >- Cursor-paginated list of this owner's refinements, newest first, paged on (createdAt, id) — two facts consented in the same second would otherwise repeat one and lose the other across a page boundary. Rolled-back rows are in it: walking backwards from a strange behaviour to the fact that caused it is what the row is for. Each row carries its provenance, its state, how often it has fired and — for a capability that executes — its script's HASH. Not the script's text, which is on getRefinement: a listing that carried every authored program's source is a listing nobody can page. operationId: listRefinements parameters: - name: scope in: query required: false description: Only refinements kept at this reach. schema: $ref: '#/components/schemas/RefinementScope' - name: kind in: query required: false description: Only refinements of this kind. schema: $ref: '#/components/schemas/RefinementKind' - name: state in: query required: false description: Only refinements in this state. schema: $ref: '#/components/schemas/RefinementState' - name: repository in: query required: false description: >- Only refinements kept for this checkout. It narrows repository scope and never widens it: the owner's global facts are not in a repository and are therefore not in this answer. schema: type: string maxLength: 4096 - $ref: '#/components/parameters/CursorParam' - $ref: '#/components/parameters/LimitParam' responses: '200': description: One page of refinements. content: application/json: schema: $ref: '#/components/schemas/RefinementPage' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalServerError' components: schemas: RefinementScope: type: string enum: - repository - global x-enum-varnames: - RefinementScopeRepository - RefinementScopeGlobal description: >- How far a refinement reaches. `repository` is keyed on the canonical checkout path, the same key a trust answer uses; `global` is the owner's. There is no `session` here and the absence is a decision: a session-scoped fact lives exactly as long as the conversation that gave it, so it is never a stored row at all. RefinementKind: type: string enum: - memory - skill - agent - command x-enum-varnames: - RefinementKindMemory - RefinementKindSkill - RefinementKindAgent - RefinementKindCommand description: >- What a refinement IS. Four values and no more — one vocabulary is what makes "everything this repository taught narya" one question. RefinementState: type: string enum: - pending - active - rolled-back - unverifiable x-enum-varnames: - RefinementStatePending - RefinementStateActive - RefinementStateRolledBack - RefinementStateUnverifiable description: >- Where a refinement stands. `pending` is proposed and nothing else — never rendered, never executed, never on a ladder. `active` is consented and firing. `rolled-back` is kept for the record. `unverifiable` is the one that surprises: such a fact is STILL FIRING and says so. Every session it cited has been purged, which is a person deleting a transcript rather than a person retracting a belief. RefinementPage: type: object description: One page of refinements. required: - items - limit properties: items: type: array items: $ref: '#/components/schemas/Refinement' limit: type: integer minimum: 1 nextCursor: type: string prevCursor: type: string examples: - items: - id: 7d1e3a5c-9b2f-4e6a-8c0d-2f4a6c8e0b2d kind: memory scope: repository repository: /Users/dana/repos/midaz owner: local title: Migrations and the schema document are one change body: A new migration without its schema block fails two tests. state: active origin: loop createdAt: '2026-09-07T09:12:00.000Z' hits: 4 limit: 25 Refinement: type: object description: >- One thing the harness learned and a person allowed: a distilled memory, or a skill, agent or command definition the model authored. The owner is never something a caller names. `script` and `events` are present on getRefinement and absent from the listing. A page carrying every authored program's source is a page nobody can read; the hash is on both, which is what "what was consented to is what runs" is checked against. required: - id - kind - scope - owner - title - body - state - origin - createdAt - hits properties: id: type: string format: uuid kind: $ref: '#/components/schemas/RefinementKind' scope: $ref: '#/components/schemas/RefinementScope' repository: type: string description: The canonical checkout path, absent at the owner's global scope. owner: type: string description: Whose learning this is. name: type: string description: >- The ladder identity of the three definition kinds, absent on a memory. maxLength: 128 title: type: string maxLength: 200 body: type: string description: The fact's text, or the definition's prompt or description. script: type: string description: >- The program the model wrote, IN FULL — never a digest and never a path. A person cannot consent to what they were not shown, and what they consented to is what the confined runtime later runs, byte for byte. Present on getRefinement only. scriptSha256: type: string description: >- The hash of that program, on the listing as well as the read. It is what the runtime checks the text against before running it. pattern: ^[0-9a-f]{64}$ state: $ref: '#/components/schemas/RefinementState' origin: $ref: '#/components/schemas/RefinementOrigin' originSessionId: type: string description: >- The conversation this was learned from. It may name a session that has since been purged, which is what `unverifiable` reads from. originEntryId: type: string description: The turn this was learned in. originActor: type: string description: Who was acting when this came in over the contract. citations: type: array description: The turns this stands on, in the order they were written. items: $ref: '#/components/schemas/RefinementCitation' events: type: array description: >- Everything that has happened to this refinement, newest first. Present on getRefinement only. items: $ref: '#/components/schemas/RefinementEventEntry' createdAt: type: string format: date-time activatedAt: type: string format: date-time description: When a person consented. Absent while pending. lastUsedAt: type: string format: date-time description: >- When this last fired into a prompt. It is what eviction is ordered by — a fact that fires often is a fact that earned its place — and it is deliberately never rewound by a rollback. hits: type: integer format: int32 minimum: 0 description: How many turns this has fired into. supersededBy: type: string format: uuid description: The row that replaced this one, if any. examples: - id: 7d1e3a5c-9b2f-4e6a-8c0d-2f4a6c8e0b2d kind: memory scope: repository repository: /Users/dana/repos/midaz owner: local title: Migrations and the schema document are one change body: >- A new migration file without the matching block in schema.sql fails two tests the moment it lands. state: active origin: loop originSessionId: 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d originEntryId: 8a1d3f5b-7c9e-4a2b-8d6f-0c2e4a6b8d0f citations: - sessionId: 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d entryId: 8a1d3f5b-7c9e-4a2b-8d6f-0c2e4a6b8d0f createdAt: '2026-09-07T09:12:00.000Z' activatedAt: '2026-09-07T09:12:00.000Z' hits: 4 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. 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. 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. RefinementOrigin: type: string enum: - loop - api - import x-enum-varnames: - RefinementOriginLoop - RefinementOriginApi - RefinementOriginImport description: >- Which road a refinement came in on: narya's own review of a conversation, a client teaching it through this contract, or an import. Both roads land pending and pass the same consent. RefinementCitation: type: object description: >- One pointer into the transcript that justifies a refinement. The admitted user entry's id IS the turn id, so citing the turns needs no second identifier. THE POINTER MAY DANGLE, and that is the design: nothing cascades from a purged session to a fact learned in it, because a person deleting one noisy conversation must not silently lose weeks of learning. A fact whose evidence is gone becomes `unverifiable` and keeps firing. required: - sessionId - entryId properties: sessionId: type: string format: uuid entryId: type: string format: uuid note: type: string description: What the review said about this turn. maxLength: 2000 examples: - sessionId: 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d entryId: 8a1d3f5b-7c9e-4a2b-8d6f-0c2e4a6b8d0f note: the third attempt at the same import cycle RefinementEventEntry: type: object description: >- One thing that happened to one refinement. The log is APPEND-ONLY: nothing in it is ever updated or deleted, because "who taught narya this, and who took it away" has to be answerable from the log alone. required: - id - action - at properties: id: type: string format: uuid action: $ref: '#/components/schemas/RefinementAction' actor: type: string description: Who acted. Empty when narya's own loop did. at: type: string format: date-time causedByEventId: type: string format: uuid description: >- The event this one inverts, absent when it inverts nothing. It is what makes a rollback of a rollback readable as a redo. examples: - id: 5c7e9a1b-3d5f-4a7c-9e1b-3d5f7a9c1e3b action: activated actor: local at: '2026-09-07T09:12:00.000Z' RefinementAction: type: string enum: - created - activated - updated - promoted - demoted - rolled-back - deleted x-enum-varnames: - RefinementActionCreated - RefinementActionActivated - RefinementActionUpdated - RefinementActionPromoted - RefinementActionDemoted - RefinementActionRolledBack - RefinementActionDeleted description: >- What happened to a refinement. There is no `restored`: restoring what somebody undid is a rollback OF a rollback, so undo and redo are one verb aimed at different events and the log nests instead of branching. parameters: CursorParam: name: cursor in: query required: false description: >- Opaque pagination cursor from a previous page's nextCursor or prevCursor. schema: type: string maxLength: 1024 LimitParam: name: limit in: query required: false description: Maximum items per page. schema: type: integer minimum: 1 maximum: 100 default: 25 responses: BadRequest: description: Malformed request — invalid parameter, cursor, or JSON body. 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' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- 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. ````