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

# List Agents

> Returns all agents in your current organization. Access is scoped by user role — owners/admins see all agents, members see public agents plus their own private agents.

## Overview

Lists all agents within your active organization. The response is filtered based on your user role:

* **Owners/Admins:** See all agents (public + private)
* **Members:** See public agents + their own private agents only

**Authentication:** Session-based (Better Auth)
**Scope:** Active organization from session

## Request

**Headers:**

```
Authorization: Bearer YOUR_SESSION_TOKEN
```

**Query Parameters:** None

## Response

**Status:** `200 OK`

```json theme={null}
{
  "agents": [
    {
      "id": "agent_abc123",
      "name": "Customer Support Bot",
      "description": "Handles customer inquiries and support tickets",
      "agentArchitecture": "pipeline",
      "mode": "public",
      "model": "gpt_4o_mini",
      "stt": "deepgram",
      "voiceId": "cartesia-voice-123",
      "functionCallingEnabled": true,
      "enabledFunctions": ["web_search", "end_call"],
      "enabledCustomFunctions": [],
      "temperature": 0.7,
      "inactivityTimeout": 30,
      "greetingType": "agentFirst",
      "greetingMessage": "Hello! How can I help you today?",
      "lastMessage": "Thank you for calling!",
      "createdAt": "2024-01-10T09:00:00Z",
      "updatedAt": "2024-01-15T14:30:00Z",
      "userId": "user_xyz789",
      "languages": [
        {
          "id": "lang_123",
          "language": "english"
        }
      ],
      "VoiceOption": {
        "voiceId": "cartesia-voice-123",
        "voiceName": "Sonic English",
        "provider": "cartesia",
        "providerVoiceId": "sonic-english",
        "gender": "neutral",
        "accent": "American",
        "age": "adult",
        "description": "Clear, professional voice",
        "language": "en-US",
        "model": "sonic"
      },
      "user": {
        "id": "user_xyz789",
        "name": "John Doe",
        "email": "john@example.com"
      },
      "organization": {
        "id": "org_123",
        "name": "Acme Corp",
        "slug": "acme-corp"
      }
    }
  ]
}
```

## Response Fields

| Field                             | Type    | Description                          |
| --------------------------------- | ------- | ------------------------------------ |
| `agents`                          | array   | List of agent objects                |
| `agents[].id`                     | string  | Agent ID (ULID format)               |
| `agents[].name`                   | string  | Agent display name                   |
| `agents[].description`            | string  | Internal description                 |
| `agents[].agentArchitecture`      | string  | `pipeline`, `realtime`, or `text`    |
| `agents[].mode`                   | string  | `public`, `private`, or `commercial` |
| `agents[].model`                  | string  | LLM model (pipeline/text only)       |
| `agents[].stt`                    | string  | STT provider (pipeline only)         |
| `agents[].voiceId`                | string  | Voice ID (pipeline/realtime only)    |
| `agents[].realtimeProvider`       | string  | `openai` or `gemini` (realtime only) |
| `agents[].functionCallingEnabled` | boolean | Functions enabled                    |
| `agents[].enabledFunctions`       | array   | Built-in function IDs                |
| `agents[].enabledCustomFunctions` | array   | Custom function IDs                  |
| `agents[].temperature`            | number  | 0.1–1.0                              |
| `agents[].inactivityTimeout`      | number  | 10–60 seconds                        |
| `agents[].greetingType`           | string  | `agentFirst` or `userFirst`          |
| `agents[].greetingMessage`        | string  | Custom greeting                      |
| `agents[].lastMessage`            | string  | Farewell message                     |
| `agents[].languages`              | array   | Language objects                     |
| `agents[].VoiceOption`            | object  | Voice details                        |
| `agents[].user`                   | object  | Creator info                         |
| `agents[].organization`           | object  | Organization info                    |

## Access Control

### Owners/Admins

```json theme={null}
// See ALL agents in organization
{
  "mode": { "in": ["public", "private"] }
}
```

### Members

```json theme={null}
// See public + own private agents only
{
  "OR": [
    { "mode": "public" },
    { "mode": "private", "userId": "current_user_id" }
  ]
}
```

## Error Responses

### 401 Unauthorized

```json theme={null}
{
  "error": "Unauthorized"
}
```

### 400 Bad Request

```json theme={null}
{
  "error": "Please select an organization first"
}
```

### 403 Forbidden

```json theme={null}
{
  "error": "You are not a member of the selected organization"
}
```

### 500 Server Error

```json theme={null}
{
  "error": "Server error"
}
```

## Examples

### cURL

```bash theme={null}
curl -X GET "https://studio.talkifai.dev/api/agents" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"
```

### JavaScript (Fetch)

```javascript theme={null}
const response = await fetch('/api/agents', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${sessionToken}`
  }
});

const data = await response.json();
console.log(data.agents);
```

### Next.js (Server Component)

```tsx theme={null}
import { auth } from "@/src/lib/auth";
import { headers } from "next/headers";

async function getAgents() {
  const session = await auth.api.getSession({
    headers: await headers()
  });

  const response = await fetch(`${process.env.NEXT_PUBLIC_BASE_URL}/api/agents`, {
    headers: {
      cookie: headers().get("cookie") ?? ""
    },
    cache: "no-store"
  });

  return response.json();
}
```

## Related Endpoints

* [Create Agent](/api-reference/endpoint/create-agent) — Create a new agent
* [Get Agent](/api-reference/endpoint/get-agent) — Get single agent details
* [Update Agent](/api-reference/endpoint/update-agent) — Update agent configuration
* [List All Agents](/api-reference/endpoint/list-all-agents) — Agents across all organizations


## OpenAPI

````yaml GET /v1/agents
openapi: 3.1.0
info:
  title: TalkifAI API
  version: 1.0.0
  description: Build and manage AI voice and chat agents programmatically.
servers:
  - url: https://api.talkifai.dev
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Agents
    description: Create and manage voice and chat agents
  - name: Voice Calls
    description: Initiate outbound calls and retrieve call data
  - name: Text Chat
    description: Text chat sessions via REST + SSE
  - name: Batch Calling
    description: Run large-scale outbound call campaigns
paths:
  /v1/agents:
    get:
      tags:
        - Agents
      summary: List Agents
      description: >-
        Returns all agents (public and private) in the organization associated
        with the API key.
      operationId: listAgents
      responses:
        '200':
          description: List of agents
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      agents:
                        type: array
                        items:
                          $ref: '#/components/schemas/Agent'
                      count:
                        type: integer
        '401':
          description: Invalid or missing API key
        '403':
          description: API key disabled, expired, or no active organization
      security:
        - apiKeyHeader: []
components:
  schemas:
    Agent:
      type: object
      properties:
        id:
          type: string
          example: 5b710eca-ee67-4c3a-aeb6-8b541f451b40
        name:
          type: string
          example: Customer Support Bot
        description:
          type: string
          nullable: true
          example: Handles tier-1 support queries
        agentArchitecture:
          type: string
          enum:
            - pipeline
            - realtime
            - text
          example: pipeline
        model:
          type: string
          nullable: true
          example: gpt_4o_mini
          description: >-
            LLM model. Set for pipeline and text architectures; null for
            realtime.
        stt:
          type: string
          nullable: true
          example: deepgram
          description: >-
            Speech-to-text provider. Set for pipeline; null for realtime and
            text.
        voiceId:
          type: string
          nullable: true
          example: gemini-leda-en
          description: >-
            TTS voice ID. Required for pipeline; optional for realtime (used
            only when greetingType is agentFirst).
        realtimeProvider:
          type: string
          nullable: true
          example: openai
          description: >-
            Realtime provider. Set for realtime architecture; null for pipeline
            and text.
        sysMsg:
          type: string
          nullable: true
          example: >-
            You are a helpful customer support agent for Acme Corp. Be concise
            and friendly.
        greetingType:
          type: string
          enum:
            - agentFirst
            - userFirst
          example: agentFirst
          description: Controls who speaks first when the call connects.
        greetingMessage:
          type: string
          nullable: true
          example: Hello! How can I help you today?
          description: >-
            Opening message spoken by the agent. Only used when greetingType is
            agentFirst.
        temperature:
          type: number
          example: 0.7
          description: LLM sampling temperature (0–2).
        inactivityTimeout:
          type: integer
          example: 30
          description: >-
            Seconds of user silence before the agent ends the call. Range:
            10–60.
        lastMessage:
          type: string
          nullable: true
          example: Is there anything else I can help you with?
          description: Final message spoken by the agent before ending the call.
        mode:
          type: string
          enum:
            - public
            - private
            - commercial
          example: public
          description: >-
            Visibility mode. public: all org members. private: creator +
            admins/owners only. commercial: globally accessible.
        functionCallingEnabled:
          type: boolean
          example: false
        enabledFunctions:
          type: array
          items:
            type: string
          description: IDs of built-in functions enabled for this agent.
        enabledCustomFunctions:
          type: array
          items:
            type: string
          description: IDs of custom (webhook) functions enabled for this agent.
        languages:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              language:
                type: string
                example: en
          description: Languages the agent is configured to support.
        userId:
          type: string
          description: ID of the user who created this agent.
        organizationId:
          type: string
          description: ID of the organization this agent belongs to.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: tk_live_...
      description: Your TalkifAI API key. Get it from Studio → Settings → API Keys.
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your TalkifAI API key. Generate from Studio → Settings → API Keys.
        Format: `tk_live_...`

````