List Agents
curl --request GET \
--url https://api.talkifai.dev/v1/agents \
--header 'x-api-key: <api-key>'import requests
url = "https://api.talkifai.dev/v1/agents"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.talkifai.dev/v1/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.talkifai.dev/v1/agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.talkifai.dev/v1/agents"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.talkifai.dev/v1/agents")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.talkifai.dev/v1/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"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
}
}Agents
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.
GET
/
v1
/
agents
List Agents
curl --request GET \
--url https://api.talkifai.dev/v1/agents \
--header 'x-api-key: <api-key>'import requests
url = "https://api.talkifai.dev/v1/agents"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.talkifai.dev/v1/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.talkifai.dev/v1/agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.talkifai.dev/v1/agents"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.talkifai.dev/v1/agents")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.talkifai.dev/v1/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"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
Request
Headers:Authorization: Bearer YOUR_SESSION_TOKEN
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
| 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
// 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();
}
Related Endpoints
- Create Agent — Create a new agent
- Get Agent — Get single agent details
- Update Agent — Update agent configuration
- List All Agents — Agents across all organizations
⌘I