Skip to main content
GET
/
v1
/
agents
/
{agentId}
Get Agent
curl --request GET \
  --url https://api.talkifai.dev/v1/agents/{agentId} \
  --header 'x-api-key: <api-key>'
{
  "success": true,
  "data": {
    "agent": {
      "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"
    }
  }
}

Overview

Retrieves complete configuration for a single agent by ID. Includes all settings, languages, voice configuration, and related metadata. Authentication: Session-based (Better Auth) Scope: Active organization from session

Request

Path Parameters:
ParameterTypeRequiredDescription
agentIdstringAgent ID (ULID format)
Headers:
Authorization: Bearer YOUR_SESSION_TOKEN

Response

Status: 200 OK
{
  "agent": {
    "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",
    "realtimeProvider": null,
    "sysMsg": "You are a helpful customer support agent for Acme Corp. Your job is to resolve customer issues efficiently...",
    "functionCallingEnabled": true,
    "enabledFunctions": ["web_search", "end_call"],
    "enabledCustomFunctions": ["func_custom123"],
    "temperature": 0.7,
    "inactivityTimeout": 30,
    "greetingType": "agentFirst",
    "greetingMessage": "Hello! Thank you for calling Acme Corp. How can I help you today?",
    "lastMessage": "Thank you for calling! Have a great day.",
    "createdAt": "2024-01-10T09:00:00Z",
    "updatedAt": "2024-01-15T14:30:00Z",
    "userId": "user_xyz789",
    "organizationId": "org_123",
    "languages": [
      {
        "id": "lang_123",
        "agentId": "agent_abc123",
        "language": "english"
      },
      {
        "id": "lang_124",
        "agentId": "agent_abc123",
        "language": "urdu"
      }
    ],
    "VoiceOption": {
      "voiceId": "cartesia-voice-123",
      "voiceName": "Sonic English",
      "provider": "cartesia",
      "providerVoiceId": "sonic-english",
      "gender": "neutral",
      "accent": "American",
      "age": "adult",
      "description": "Clear, professional voice suitable for customer service",
      "previewAudioUrl": "https://storage.googleapis.com/.../preview.mp3",
      "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
agentobjectAgent configuration object
agent.idstringAgent ID (ULID)
agent.namestringDisplay name
agent.descriptionstringInternal description (max 200 chars)
agent.agentArchitecturestringpipeline, realtime, or text
agent.modestringpublic, private, or commercial
agent.modelstringLLM model (pipeline/text only)
agent.sttstringSTT provider (pipeline only)
agent.voiceIdstringVoice ID (pipeline/realtime only)
agent.realtimeProviderstringopenai or gemini (realtime only)
agent.sysMsgstringSystem prompt (max 5000 chars)
agent.functionCallingEnabledbooleanFunctions enabled flag
agent.enabledFunctionsarrayBuilt-in function IDs
agent.enabledCustomFunctionsarrayCustom function IDs
agent.temperaturenumber0.1–1.0 (default: 0.7)
agent.inactivityTimeoutnumber10–60 seconds (default: 30)
agent.greetingTypestringagentFirst or userFirst
agent.greetingMessagestringCustom greeting message
agent.lastMessagestringFarewell message
agent.languagesarrayLanguage configurations
agent.VoiceOptionobjectVoice configuration details
agent.userobjectAgent creator information
agent.organizationobjectOrganization information

Access Control

User RoleCan Access
Owner✅ Any agent in organization
Admin✅ Any agent in organization
Member (Creator)✅ Own agents (any mode)
Member (Not Creator)✅ Public agents only / ❌ Private agents (403)
External User❌ Commercial agents only
403 Response:
{
  "error": "You don't have permission to access this agent"
}

Error Responses

401 Unauthorized

{
  "error": "Unauthorized"
}

403 Forbidden

{
  "error": "You don't have permission to access this agent"
}

404 Not Found

{
  "error": "Agent not found"
}

500 Server Error

{
  "error": "Server error"
}

Examples

cURL

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

JavaScript (Fetch)

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

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

Next.js (Server Component)

import { auth } from "@/src/lib/auth";
import { headers } from "next/headers";

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

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

  if (!response.ok) {
    throw new Error("Failed to fetch agent");
  }

  return response.json();
}

Use Cases

Display Agent Configuration

function AgentConfigPage({ agentId }) {
  const { data: agentData, error } = useSWR(`/api/agents/${agentId}`);
  
  if (error) return <div>Failed to load agent</div>;
  if (!agentData) return <div>Loading...</div>;
  
  const agent = agentData.agent;
  
  return (
    <div>
      <h1>{agent.name}</h1>
      <p>{agent.description}</p>
      <div>Architecture: {agent.agentArchitecture}</div>
      <div>Model: {agent.model}</div>
      <div>Voice: {agent.VoiceOption?.voiceName}</div>
      <div>Languages: {agent.languages.map(l => l.language).join(", ")}</div>
    </div>
  );
}

Check Agent Permissions

function canEditAgent(agent, user) {
  // Owners/admins can always edit
  if (user.role === "owner" || user.role === "admin") {
    return true;
  }
  
  // Creators can edit their own agents (except commercial)
  if (agent.userId === user.id && agent.mode !== "commercial") {
    return true;
  }
  
  return false;
}

Authorizations

x-api-key
string
header
required

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

Path Parameters

agentId
string
required

Response

Agent details

success
boolean
data
object