> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trellis.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# List Agents

> List your organization's published agents

Returns the published agents in your organization. Use an agent's `id` as the `{agent_id}` in the chat WebSocket and REST turn URLs.

<Note>
  Only **published** agents are returned. An organization may have a single org-scoped published agent whose display label and `is_trellis_default` flag are historical metadata. Trellis supplies the assigned UUID during onboarding. Configure and use that exact `id`; do not infer the agent from its name, list position, or default flag.
</Note>

<ParamField header="Authorization" type="string" required>
  Bearer token obtained from the [authenticate](/api-reference/authentication/authenticate) endpoint.
</ParamField>

## Response

<ResponseField name="agents" type="array" required>
  List of published agents.

  <Expandable title="Agent object">
    <ResponseField name="id" type="string" required>
      Unique identifier for the agent — pass as `{agent_id}` in the WebSocket URL.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Display name of the agent.
    </ResponseField>

    <ResponseField name="description" type="string | null">
      Optional description of the agent's purpose.
    </ResponseField>

    <ResponseField name="is_trellis_default" type="boolean" required>
      `true` for the org's default agent (the one new chats bind to unless told otherwise).
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Publication status. Always `"published"` for agents returned here.
    </ResponseField>

    <ResponseField name="model_id" type="string" required>
      The model used when a turn does not provide a valid per-turn override.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET https://api.trellis.sh/v1/agents \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests

  response = requests.get(
      "https://api.trellis.sh/v1/agents",
      headers={"Authorization": "Bearer YOUR_TOKEN"},
  )
  agents = response.json()["agents"]
  assigned_agent_id = os.environ["TRELLIS_AGENT_ID"]
  agent = next((item for item in agents if item["id"] == assigned_agent_id), None)
  if agent is None:
      raise RuntimeError("The assigned agent is not published for this organization")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch("https://api.trellis.sh/v1/agents", {
    headers: { Authorization: "Bearer YOUR_TOKEN" },
  });
  const { agents } = await response.json();
  const assignedAgentId = process.env.TRELLIS_AGENT_ID;
  const agent = agents.find(({ id }) => id === assignedAgentId);
  if (!agent) throw new Error("The assigned agent is not published for this organization");
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "agents": [
      {
        "id": "44444444-4444-4444-8444-444444444444",
        "name": "Trellis Agent",
        "description": null,
        "is_trellis_default": true,
        "status": "published",
        "model_id": "claude-sonnet-5"
      }
    ]
  }
  ```
</ResponseExample>