---
title: "List Agents"
method: GET
path: "/agents"
tags: ["agents"]
---

# List Agents

`GET /agents`

List the agents the organization may run, or the full catalog.

The single authoritative source of agent availability for clients (extension,
Console, integrations). By default the returned list already reflects every
per-org gate — labs access, style-agent mode, per-agent on/off, and the
no-LLM flag — so clients must not re-derive availability; the `no_llm` flag is
returned alongside so they can render the Style-Agent-only state directly.
Pass `include_unavailable=true` for the full catalog (per-org gates skipped),
e.g. an internal tool resolving an agent id regardless of org config.

## Query parameters

- `page` integer
- `page_size` integer
- `category` string, nullable
- `include_unavailable` boolean

## Headers

- `Authorization` string, required

## Response `200`

Successful Response

- AgentListResponse — Paginated agent list plus the org-level no-LLM signal. Returned by ``GET /agents``. Extends the shared :class:`AgentListResult` (agents + pagination) with ``no_llm``, which only the HTTP boundary can compute — the shared ``AgentLoader`` that builds ``AgentListResult`` has no organization context. By default the returned list already reflects every per-org gate (labs access, style-agent mode, per-agent on/off, and the no-LLM flag), so clients must not re-derive availability; ``no_llm`` lets them render the Style-Agent-only state without doing so. With ``include_unavailable=true`` the list is the full catalog while ``no_llm`` still reports the org's flag.
  - `agents` AgentMetadata[], required — Agents for the current page
    - `id` string, required — Stable agent ID (ag_<nanoid>) used for API routing
    - `description` string, nullable — Agent description
    - `labs` boolean — Whether this agent is in labs
    - `input_schema` object, nullable — Input JSON schema
    - `name` string, required — Agent name
    - `output_schema` object, nullable — Output JSON schema
    - `categories` string[] — Category IDs for discovery and filtering
    - `cadence` 'per_chunk' | 'per_fragment' | 'doc_wide' | 'on_demand' — §2.4 session routing cadence (configured in agents.yaml)
    - `ui` AgentUIMetadata — UI presentation metadata for an agent.
      - `title` string, nullable — Display name override
      - `description` string, nullable — Description override for UI
      - `icon` string — Lucide icon key (e.g. 'spell-check')
  - `total` integer, required — Total number of agents matching filters
  - `page` integer, required — Current page number (1-based)
  - `page_size` integer, required — Number of items per page
  - `total_pages` integer, required — Total number of pages
  - `no_llm` boolean, required — When true, the organization has disabled all LLM-powered agents; only the deterministic Style Agent is available and, unless `include_unavailable` is set, `agents` contains it alone (Style-Agent-only).

## Other responses

- `401` — Authentication failed or no valid API key provided.
- `403` — Forbidden
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.dev/markup/apis/api-reference.md) · [All operations](https://skmtc.dev/markup/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/markup/api-reference/revisions/65e1214d0bbf/schema)