> ## Documentation Index > Fetch the complete documentation index at: https://docs.hq.zone/llms.txt > Use this file to discover all available pages before exploring further. # List agents > Returns every agent configured in the caller's workspace, including each agent's slug, display name, description, system-prompt instructions, personality settings (tone, verbosity, cautions, languages), aliases, runtime profile, selected model, default flag, status, and avatar URL. Results are scoped to the caller's own workspace and ordered with the default agent first, then enabled agents, then by slug. Requires the agents:read scope. ## OpenAPI ````yaml GET /v1/agents openapi: 3.1.0 info: title: HQ API description: >- Public HTTP API for HQ. Authenticate with a Personal Access Token (`Authorization: Bearer hq_pat_...`) for server-side integrations, or an OAuth 2.1 authorization-code + PKCE flow for browser apps acting on a user's behalf. Both grant from the same resource:action scope vocabulary; an endpoint's required scope is listed under its `security`. license: name: Apache-2.0 identifier: Apache-2.0 version: 1.0.0 servers: - url: https://api.hq.zone description: HQ API (production) security: [] tags: - name: me description: The signed-in user's own account - name: conversations description: Conversations and their messages - name: documents description: The content-addressed documents library - name: schedules description: Scheduled prompts and recurring tasks - name: agents description: Agents, their skills and integrations - name: memory description: What the assistant remembers (L5 governance) - name: tokens description: Personal Access Token management - name: billing description: Usage and billing - name: notifications description: In-app notification center - name: admin description: Workspace administration - name: integrations description: Workspace integrations (Slack, MCP, skills) - name: onboarding description: New-workspace onboarding wizard - name: auth description: Sign-in, sessions, and OAuth paths: /v1/agents: get: tags: - agents summary: List agents description: >- Returns every agent configured in the caller's workspace, including each agent's slug, display name, description, system-prompt instructions, personality settings (tone, verbosity, cautions, languages), aliases, runtime profile, selected model, default flag, status, and avatar URL. Results are scoped to the caller's own workspace and ordered with the default agent first, then enabled agents, then by slug. Requires the agents:read scope. operationId: list_agents responses: '200': description: This workspace's agents content: application/json: schema: $ref: '#/components/schemas/AgentsListResp' security: - bearer_pat: - agents:read - oauth2: - agents:read components: schemas: AgentsListResp: type: object required: - agents properties: agents: type: array items: $ref: '#/components/schemas/AgentRow' AgentRow: type: object required: - id - slug - display_name - instructions_is_default - cautions - languages - aliases - runtime_profile - delivery_mode - is_default - status - created_at properties: aliases: type: array items: type: string avatar_url: type: - string - 'null' description: |- Absolute URL of the avatar shown next to this agent's messages. NULL = use the Slack app's default icon for now (fine for legacy single-agent tenants). cautions: type: array items: type: string description: |- Free-form short phrases the agent should avoid talking about. Composed as "Be careful around: X, Y, Z" in the system prompt. Empty = no caution block. created_at: type: string format: date-time delivery_mode: type: string description: type: - string - 'null' display_name: type: string id: type: string format: uuid instructions: type: - string - 'null' description: |- Admin-editable system-prompt for this agent. NULL = use the platform baseline only (the legacy generalist behaviour). Plumbed through to `router_client::compose_system_prompt` which sandwiches it between the Slack-formatting baseline and the identity-pin footer. instructions_is_default: type: boolean description: |- True iff `instructions` is still the platform-seeded value (admin hasn't customised or tailored yet). The admin UI uses this to surface a "your agent is still on the default - click Tailor" banner. Any PATCH that writes instructions flips this false; the seed migrations set it true on creation. is_default: type: boolean languages: type: array items: type: string description: |- BCP-47 language codes. The first is the default; subsequent entries are explicit fallbacks. Empty = no language pin (LLM follows the user's language). model: type: - string - 'null' description: |- Selected model slug (e.g. `claude-opus-4-8`). NULL = the runtime's platform default. Must belong to `runtime_profile` (billing C). runtime_profile: type: string slug: type: string status: type: string tone: type: - string - 'null' description: |- One of `formal | friendly | direct | casual` (or NULL = unset → no tone pin in the system prompt). Orthogonal to role; admin choice, not inferrable from "you're a CFO". verbosity: type: - string - 'null' description: |- One of `concise | balanced | detailed` (or NULL = unset). Drives a canonical "Default to brief / balanced / detailed responses" sentence in the system prompt. securitySchemes: bearer_pat: type: http scheme: bearer bearerFormat: hq_pat description: 'Personal Access Token. Send as `Authorization: Bearer hq_pat_...`.' oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://app.hq.zone/v1/oauth/authorize tokenUrl: https://api.hq.zone/v1/oauth/token refreshUrl: https://api.hq.zone/v1/oauth/token scopes: admin: Administer the workspace (users, settings, integrations) agents:read: View the agents in your workspace agents:write: Create and configure agents billing:read: View usage and billing information conversations:read: Read your conversations and their messages conversations:write: Start conversations and send messages on your behalf documents:read: Read your documents library documents:write: Upload and manage documents in your library memory:read: Read what the assistant remembers about you memory:write: Correct or delete what the assistant remembers schedules:read: View your scheduled tasks schedules:write: Create and manage scheduled tasks tables:read: Read your tables and their rows tables:write: Create tables and add, edit, or delete rows ````