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

# List Available Agents

> Get a list of all available AI agents using API key authentication

## Use Cases

* Discover available agents before creating conversations
* Build agent selection interfaces in your application
* Understand agent capabilities and specializations
* Dynamically populate agent options for users
* Determine the right agent for specific tasks

## Authentication

This endpoint requires API key authentication via the `x-api-key` header.

```bash theme={null}
x-api-key: YOUR_API_KEY
```

#### Response

<ResponseField name="id" type="string">
  Unique agent identifier (use in conversation creation)
</ResponseField>

<ResponseField name="name" type="string">
  Human-readable agent name
</ResponseField>

<ResponseField name="description" type="string">
  What the agent specializes in
</ResponseField>

<ResponseField name="status" type="string">
  Agent status
</ResponseField>

<ResponseField name="visibility" type="string">
  Visibility of the agent. `null` for system agents; `private`, `shared`, or `public` for custom agents.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    The endpoint requires a valid API key for authentication.

    ```json theme={null}
    {
      "detail": "API key is required"
    }
    ```

    **Causes:**

    * Missing `x-api-key` header
    * Invalid or expired API key

    **Solution:** Include a valid API key in the request header.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    The endpoint returns this error when unexpected exceptions occur.

    ```json theme={null}
    {
      "detail": "Internal server error"
    }
    ```

    **Causes:**

    * Database connection failures
    * Service unavailability

    **Solution:** Retry the request after a brief delay. Contact support if the issue persists.
  </Accordion>
</AccordionGroup>

## Complete Workflow

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await fetch(
    'http://localhost:8001/api/v2/list-available-agents',
    {
      headers: {
        'x-api-key': 'YOUR_API_KEY'
      }
    }
  );

  const agents = await response.json();

  console.log('Available Agents:');
  agents.forEach(agent => {
    console.log(`\n${agent.name} (${agent.id})`);
    console.log(`  ${agent.description}`);
  });
  ```

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

  response = requests.get(
      'http://localhost:8001/api/v2/list-available-agents',
      headers={'x-api-key': 'YOUR_API_KEY'}
  )

  agents = response.json()

  print('Available Agents:')
  for agent in agents:
      print(f"\n{agent['name']} ({agent['id']})")
      print(f"  {agent['description']}")
  ```

  ```bash cURL theme={null}
  # List all agents
  curl -X GET \
    'http://localhost:8001/api/v2/list-available-agents' \
    -H 'x-api-key: YOUR_API_KEY'

  # Pretty print with jq
  curl -X GET \
    'http://localhost:8001/api/v2/list-available-agents' \
    -H 'x-api-key: YOUR_API_KEY' | jq '.'
  ```
</CodeGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Empty agent list">
    **Problem:** API returns an empty array `[]`.

    **Solution:**

    * This is unusual - system agents should always be available
    * Verify you're using the correct API endpoint
    * Check that your account is active and in good standing
    * Contact support if the list remains empty
  </Accordion>

  <Accordion title="Unknown agent ID">
    **Problem:** Agent ID from list doesn't work in conversations.

    **Solution:**

    * Verify you're using the exact `id` value from this endpoint
    * Refresh the agent list to get the latest data
    * Some agents may require specific permissions
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml GET /api/v2/list-available-agents
openapi: 3.1.0
info:
  title: Potpie API
  version: 2.0.0
  description: >-
    AI-powered codebase intelligence API. Build powerful integrations with
    Potpie's parsing, conversation, search, and agent capabilities.
  contact:
    name: Potpie Support
    email: hi@potpie.ai
    url: https://potpie.ai
  license:
    name: Proprietary
    url: https://potpie.ai/terms
servers:
  - url: http://localhost:8001
    description: Local server
security:
  - ApiKeyAuth: []
tags:
  - name: Parsing
    description: Repository parsing and status management
  - name: Projects
    description: Project management and listing
  - name: Conversations
    description: AI conversation management
  - name: Agents
    description: AI agent information and selection
  - name: Search
    description: Codebase semantic search
  - name: Integrations
    description: External service integrations
paths:
  /api/v2/list-available-agents:
    get:
      tags:
        - Agents
      summary: List Agents
      description: >-
        Get a list of all available AI agents. Each agent is specialized for
        different tasks like Q&A, debugging, and code generation.
      operationId: listAgents
      responses:
        '200':
          description: Agents retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentInfo'
              example:
                - id: codebase_qna_agent
                  name: Codebase Q&A Agent
                  description: >-
                    An agent specialized in answering questions about the
                    codebase using the knowledge graph and code analysis tools
                  status: active
                  visibility: public
                - id: debugging_agent
                  name: Debugging Agent
                  description: An agent specialized in debugging using knowledge graphs
                  status: active
                  visibility: public
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    AgentInfo:
      type: object
      properties:
        id:
          type: string
          description: Agent identifier
        name:
          type: string
          description: Agent display name
        description:
          type: string
          description: Agent capabilities and use cases
        status:
          type: string
          description: Agent availability status
        visibility:
          type: string
          description: Agent visibility (public/private)
  responses:
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
          example:
            detail: Invalid API key
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key authentication. Get your key from <a
        href="https://app.potpie.ai/settings" style="color: #60a5fa;
        font-weight: bold; text-decoration: none !important;">potpie settings
        page</a>

````