List agent recipes

Lists the named agent recipes available on this host — name, description, model, allowed tools, permission policy and the package each came from. Recipes come from configuration and packages; read-only in v1, so there is no create or update operation.

GET /v1/agents

List agent recipes

cURL

curl --request GET \
  --url https://api.example.com/v1/agents \
  --header 'Authorization: Bearer <token>'

200

{
  "items": [
    {
      "name": "reviewer",
      "description": "Reviews diffs for correctness and style."
    }
  ],
  "limit": 25
}

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.

Query Parameters

repository · string

Absolute path of the repository to resolve recipes for. A repository's own .claude/agents and .narya/agents are read only when it is named here AND its instruction files have been trusted; with no repository named, the answer carries the built-ins, the user's own recipes and the installed packages' only. On a hosted home it resolves under the home's workspace, and a path outside it is refused 422.

Maximum string length: 4096

sessionId · string<uuid>

The session to resolve recipes for, in place of repository: its own checkout's recipes as repository would, or, for a session working in an environment, those of the repository that environment cloned, read on its machine, and never the host checkout's. A session whose environment cloned nothing gets none. The read never starts a container: one that cannot be read right now is answered without the clone's recipes, saying so in notices. Naming both sessionId and repository is refused 400; a session that does not exist is 404, and one the caller may not read 403.

cursor · string

Opaque pagination cursor from a previous page's nextCursor or prevCursor.

Maximum string length: 1024

limit · integer · default: 25

Maximum items per page.

Required range: 1 <= x <= 100

Response

200

application/json

One page of agent recipes.

One page of agent recipes.

items · object[] · required

Show child attributes

limit · integer · required

Required range: x >= 1

nextCursor · string

prevCursor · string

notices · string[]

What this listing could not include, in the words a person reads: the recipes of the repository a session's container cloned, while that container cannot be read.