Get an agent recipe

Returns one named agent recipe. For a session whose container cannot be read right now, a name none of the caller’s own recipes carries is refused 422 in words saying the clone’s recipes appear once it can be read.

GET /v1/agents/{name}

Get an agent recipe

cURL

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

200

{
  "name": "reviewer",
  "description": "Reviews diffs for correctness and style.",
  "model": "claude-sonnet-4-5",
  "tools": [
    "read",
    "grep",
    "shell"
  ],
  "permissionPolicy": "read-only",
  "mode": "subagent",
  "source": "package",
  "sourcePackage": "lerian/review-pack"
}

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

name · string · required

The agent recipe's name.

Maximum string length: 128

Pattern: ^[^\s/\\]+$

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.

Response

200

application/json

The agent recipe.

A named agent recipe — instructions, allowed tools, model and permission policy. Recipes come from configuration and packages; read-only through this API in v1.

name · string · required

Maximum string length: 128

Pattern: ^[^\s/\\]+$

description · string

Maximum string length: 1024

model · string

The model the recipe runs on; the session default when absent.

tools · string[]

Tool names the recipe may use.

permissionPolicy · string

Name of the permission policy the recipe runs under.

mode · enum<string>

Where the recipe may be used: primary is the session's own agent, subagent is a delegate, all is both. A client offering a primary-agent picker lists primary and all.

Available options: primary, subagent, all

source · enum<string>

Where the recipe was read from, nearest source winning a name collision: a built-in, the user's own narya or Claude Code directory, an installed package, or the repository's own .claude/.narya directory.

authored is the odd one and the only one with no file behind it: narya wrote the recipe and a person consented to it, so it is a row in the refinement ledger rather than something anybody can open. It sits between the built-ins and the user's own directory — a learned override of a shipped default is the point, and a model is not the user.

Available options: builtin, user, claude-user, package, project-claude, project-narya, authored

sourcePackage · string

The package that supplied the recipe; absent for built-ins and local configuration.