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

# List AI Agents in Your Workspace — ChatbotX REST API

> Use GET /api/v1/ai-agents to list all AI agents configured in your ChatbotX workspace, including model settings, system prompts, and enabled tools.

AI agents in ChatbotX are configurable LLM-powered assistants that can handle conversations autonomously. Each agent has a system prompt, a set of AI models, tools it can use (such as web search), and temperature and token settings that control its behaviour. Use this endpoint to retrieve all AI agents in your workspace for inspection, synchronisation, or configuration auditing.

<Info>
  **GET** `/api/v1/ai-agents`
</Info>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://app.chatbotx.io/api/v1/ai-agents \
    --header 'Authorization: Bearer <token>'
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.chatbotx.io/api/v1/ai-agents"

  headers = {"Authorization": "Bearer <token>"}

  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const options = {
    method: 'GET',
    headers: { Authorization: 'Bearer <token>' }
  };

  fetch('https://app.chatbotx.io/api/v1/ai-agents', options)
    .then(res => res.json())
    .then(res => console.log(res))
    .catch(err => console.error(err));
  ```
</CodeGroup>

## Response

Returns `200 OK` with a `data` array of AI agent objects and a `pageCount`.

### Response Fields

<ResponseField name="data" type="array" required>
  Array of AI agent objects configured in the workspace.

  <Expandable title="data item fields">
    <ResponseField name="id" type="string" required>
      Unique identifier for the AI agent.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      The display name of the AI agent.
    </ResponseField>

    <ResponseField name="prompt" type="string" required>
      The system prompt that defines the agent's persona, goals, and constraints.
    </ResponseField>

    <ResponseField name="models" type="array" required>
      List of AI model identifiers this agent can use (e.g., `gpt-4o`, `claude-3-5-sonnet`).
    </ResponseField>

    <ResponseField name="tools" type="array" required>
      List of tool identifiers enabled for this agent (e.g., `web_search`, `contact_lookup`).
    </ResponseField>

    <ResponseField name="webSearchAuthorizedDomains" type="array" required>
      List of domains the agent is permitted to search when the web search tool is enabled.
    </ResponseField>

    <ResponseField name="messages" type="array" required>
      Initial conversation messages (few-shot examples) pre-loaded into the agent's context.
    </ResponseField>

    <ResponseField name="isDefault" type="boolean" required>
      When `true`, this agent is the default AI agent for the workspace.
    </ResponseField>

    <ResponseField name="temperature" type="number" required>
      The sampling temperature controlling response creativity. Lower values produce more deterministic outputs.
    </ResponseField>

    <ResponseField name="maxOutputTokens" type="integer" required>
      The maximum number of tokens the agent can generate in a single response.
    </ResponseField>

    <ResponseField name="workspaceId" type="string" required>
      The ID of the workspace this agent belongs to.
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      ISO 8601 timestamp for when the agent was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      ISO 8601 timestamp for when the agent was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pageCount" type="integer" required>
  The total number of pages available.
</ResponseField>

### Example Response

```json theme={null}
{
  "data": [
    {
      "id": "agent_001",
      "name": "Support Bot",
      "prompt": "You are a helpful customer support agent for Acme Corp. Answer questions about products and orders. Escalate to a human if the user is frustrated.",
      "models": ["gpt-4o"],
      "tools": ["web_search", "contact_lookup"],
      "webSearchAuthorizedDomains": ["acme.com", "docs.acme.com"],
      "messages": [],
      "isDefault": true,
      "temperature": 0.3,
      "maxOutputTokens": 1024,
      "workspaceId": "42",
      "createdAt": "2024-01-05T10:00:00Z",
      "updatedAt": "2024-04-20T14:30:00Z"
    }
  ],
  "pageCount": 1
}
```