> ## 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 permission asks > Lists permission asks, by default the pending ones — actions waiting on a human decision. Pending asks also arrive as permission-asked events; this list is the poll/recovery path for clients that reconnect. ## OpenAPI ````yaml /pt/openapi/v3-current/narya.yaml get /v1/permissions openapi: 3.1.0 info: title: Narya Host API version: 1.0.0 description: >- The contract between the Narya host and every client. On your own machine, 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. On your own machine, the host also accepts a request with no token from your own operating system user. Once signed-in work has claimed the home for an organization, it does so only while this machine is signed in to that organization. Such a request gets 401 with NRY-0011 on work that reaches your organization beyond the machine. An operation that declares another security scheme also accepts that credential. Any other 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/permissions: get: tags: - permissions summary: List permission asks description: >- Lists permission asks, by default the pending ones — actions waiting on a human decision. Pending asks also arrive as permission-asked events; this list is the poll/recovery path for clients that reconnect. operationId: listPermissions parameters: - $ref: '#/components/parameters/CursorParam' - $ref: '#/components/parameters/LimitParam' - name: status in: query required: false description: Filter by ask status. schema: type: string enum: - pending - decided - expired default: pending responses: '200': description: One page of permission asks. content: application/json: schema: $ref: '#/components/schemas/PermissionPage' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalServerError' components: 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 schemas: PermissionPage: type: object description: One page of permission asks. required: - items - limit - lastEventId properties: items: type: array items: $ref: '#/components/schemas/Permission' limit: type: integer minimum: 1 nextCursor: type: string prevCursor: type: string lastEventId: type: string description: >- The event-stream position this page was read at — the id of the newest event the host had recorded, in the same database snapshot as the asks. Every permission-asked and permission-decided event at or before it is already reflected in the page, and one just past it may be too, because an ask is stored before the event announcing it; so a client holding the page applies the stream's events past this id. "0" when the host has recorded no events. examples: - items: - id: 7e5d3c1b-9a8f-4e6d-b2c4-0f1a3b5c7d9e sessionId: 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d action: shell resource: git push origin main status: pending requestedAt: '2026-08-08T12:20:00.000Z' limit: 25 lastEventId: '4211' Permission: type: object description: >- A permission ask — a sensitive action waiting on a decision. Pending asks also arrive as permission-asked events. required: - id - sessionId - action - resource - status - requestedAt properties: id: type: string format: uuid sessionId: type: string format: uuid laneId: type: string format: uuid description: The lane whose work triggered the ask, when not the main lane. action: type: string maxLength: 128 description: The kind of action, for example shell, write, network. resource: type: string maxLength: 4096 description: What the action targets — a parsed command, a path, a host. detail: type: string maxLength: 4096 description: >- Human-readable presentation of the ask: what is being asked, the exact rule a remembered allow would grant, and the rules that matched in evaluation order. Newline-separated, and truncated with a marker if it would exceed the length below — the gate matched the full text either way. status: type: string enum: - pending - decided - expired description: >- `pending` also covers a product write its person approved whose outcome is unknown (approvedAt set): for 15 minutes from its approval it waits on them to be sent again, under its own key. requestedAt: type: string format: date-time productCall: $ref: '#/components/schemas/ProductCall' approvedAt: type: string format: date-time description: >- When the person approved a product write whose outcome is unknown: no answer arrived, the product answered 5xx without X-Idempotency-Fenced, or it held the key (X-Idempotency-Held). For 15 minutes from that approval it can only be sent again, under its own key, and the product's key makes the re-send apply at most once while it keeps the key; it is never declined, and a message does not close it. Meanwhile its owner's other writes to the same endpoint are not stored, and its conversation is not archived. Past those minutes it ends as a change that may have applied. Absent on every other ask. entered: type: array items: type: string description: >- On a write with approvedAt whose send outcome was recorded, the credentials that send was given on the card, by property name and sorted, never their values; [] when it was given none. A re-send carries exactly these names. Absent when no send was recorded, and the re-send then takes the card's credentials as on a first send. Absent on every other ask. examples: - id: 7e5d3c1b-9a8f-4e6d-b2c4-0f1a3b5c7d9e sessionId: 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d action: shell resource: git push origin main detail: >- Allow shell: git push origin main Remembering this answer would grant the rule: allow shell — for exactly the text above, nothing broader. Rules that matched, in order (the last one decides): ask shell git push* — rule 4 in defaults.toml status: pending requestedAt: '2026-08-08T12:20:00.000Z' 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. ProductCall: type: object description: >- The exact request a product write sends, on an ask with action `product`, stored when the model proposed it and never truncated: its person confirms this call and nothing else, and a confirmed send is these bytes. Absent on every other ask. required: - product - operationId - method - path properties: product: type: string description: The product tree the call goes to. operationId: type: string summary: type: string description: The product specification's summary of the operation, verbatim. method: type: string path: type: string description: The resolved path with its query, as the request line carries it. body: type: string description: >- The model's request body as stored, JSON text; the typed credentials in `secrets` are added to a copy of it at send time. Absent when the call has none. secrets: type: array description: >- The credentials the card asks its person for, sorted by name: the body-root properties the product's specification marks `x-lerian-secret`, never one the model filled. Names and the specification's words only; the values are typed with the allow (`PermissionDecisionRequest.secrets`). Absent when there are none. items: $ref: '#/components/schemas/ProductCallSecret' ProductCallSecret: type: object required: - name properties: name: type: string description: The body property. description: type: string description: The product specification's description of the property, verbatim. required: type: boolean description: The body requires it, so the allow carries it. maxLength: type: integer format: int64 description: >- The longest value the specification allows. Absent when it sets none. 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 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 — except a request with no token on a laptop's socket from the OS user the kernel names as the host's own, which is that machine's user. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.