Skip to main content
GET
/
v1
/
agents
List Agents
curl --request GET \
  --url https://api.talkifai.dev/v1/agents \
  --header 'x-api-key: <api-key>'
{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "5b710eca-ee67-4c3a-aeb6-8b541f451b40",
        "name": "Customer Support Bot",
        "description": "Handles tier-1 support queries",
        "agentArchitecture": "pipeline",
        "model": "gpt_4o_mini",
        "stt": "deepgram",
        "voiceId": "gemini-leda-en",
        "realtimeProvider": "openai",
        "sysMsg": "You are a helpful customer support agent for Acme Corp. Be concise and friendly.",
        "greetingType": "agentFirst",
        "greetingMessage": "Hello! How can I help you today?",
        "temperature": 0.7,
        "inactivityTimeout": 30,
        "lastMessage": "Is there anything else I can help you with?",
        "mode": "public",
        "functionCallingEnabled": false,
        "enabledFunctions": [
          "<string>"
        ],
        "enabledCustomFunctions": [
          "<string>"
        ],
        "languages": [
          {
            "id": "<string>",
            "language": "en"
          }
        ],
        "userId": "<string>",
        "organizationId": "<string>",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z"
      }
    ],
    "count": 123
  }
}

​
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 
{
  "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

FieldTypeDescription
agentsarrayList of agent objects
agents[].idstringAgent ID (ULID format)
agents[].namestringAgent display name
agents[].descriptionstringInternal description
agents[].agentArchitecturestringpipeline, realtime, or text
agents[].modestringpublic, private, or commercial
agents[].modelstringLLM model (pipeline/text only)
agents[].sttstringSTT provider (pipeline only)
agents[].voiceIdstringVoice ID (pipeline/realtime only)
agents[].realtimeProviderstringopenai or gemini (realtime only)
agents[].functionCallingEnabledbooleanFunctions enabled
agents[].enabledFunctionsarrayBuilt-in function IDs
agents[].enabledCustomFunctionsarrayCustom function IDs
agents[].temperaturenumber0.1–1.0
agents[].inactivityTimeoutnumber10–60 seconds
agents[].greetingTypestringagentFirst or userFirst
agents[].greetingMessagestringCustom greeting
agents[].lastMessagestringFarewell message
agents[].languagesarrayLanguage objects
agents[].VoiceOptionobjectVoice details
agents[].userobjectCreator info
agents[].organizationobjectOrganization info

​
Access Control

​
Owners/Admins

// See ALL agents in organization
{
  "mode": { "in": ["public", "private"] }
}

​
Members

// See public + own private agents only
{
  "OR": [
    { "mode": "public" },
    { "mode": "private", "userId": "current_user_id" }
  ]
}

​
Error Responses

​
401 Unauthorized

{
  "error": "Unauthorized"
}

​
400 Bad Request

{
  "error": "Please select an organization first"
}

​
403 Forbidden

{
  "error": "You are not a member of the selected organization"
}

​
500 Server Error

{
  "error": "Server error"
}

​
Examples

​
cURL

curl -X GET "https://studio.talkifai.dev/api/agents" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

​
JavaScript (Fetch)

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)

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();
}

Authorizations

​
x-api-key
string
header
required

Your TalkifAI API key. Generate from Studio → Settings → API Keys. Format: tk_live_...

Response

List of agents

​
success
boolean
​
data
object