> ## 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.

# Get Agent

> Returns full configuration details for a specific agent. Returns 403 if the agent is private and the caller is not its creator or an org admin/owner.

## 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:**

| Parameter | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `agentId` | string | ✅        | Agent ID (ULID format) |

**Headers:**

```
Authorization: Bearer YOUR_SESSION_TOKEN
```

## Response

**Status:** `200 OK`

```json theme={null}
{
  "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

| Field                          | Type    | Description                          |
| ------------------------------ | ------- | ------------------------------------ |
| `agent`                        | object  | Agent configuration object           |
| `agent.id`                     | string  | Agent ID (ULID)                      |
| `agent.name`                   | string  | Display name                         |
| `agent.description`            | string  | Internal description (max 200 chars) |
| `agent.agentArchitecture`      | string  | `pipeline`, `realtime`, or `text`    |
| `agent.mode`                   | string  | `public`, `private`, or `commercial` |
| `agent.model`                  | string  | LLM model (pipeline/text only)       |
| `agent.stt`                    | string  | STT provider (pipeline only)         |
| `agent.voiceId`                | string  | Voice ID (pipeline/realtime only)    |
| `agent.realtimeProvider`       | string  | `openai` or `gemini` (realtime only) |
| `agent.sysMsg`                 | string  | System prompt (max 5000 chars)       |
| `agent.functionCallingEnabled` | boolean | Functions enabled flag               |
| `agent.enabledFunctions`       | array   | Built-in function IDs                |
| `agent.enabledCustomFunctions` | array   | Custom function IDs                  |
| `agent.temperature`            | number  | 0.1–1.0 (default: 0.7)               |
| `agent.inactivityTimeout`      | number  | 10–60 seconds (default: 30)          |
| `agent.greetingType`           | string  | `agentFirst` or `userFirst`          |
| `agent.greetingMessage`        | string  | Custom greeting message              |
| `agent.lastMessage`            | string  | Farewell message                     |
| `agent.languages`              | array   | Language configurations              |
| `agent.VoiceOption`            | object  | Voice configuration details          |
| `agent.user`                   | object  | Agent creator information            |
| `agent.organization`           | object  | Organization information             |

## Access Control

| User Role                | Can 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:**

```json theme={null}
{
  "error": "You don't have permission to access this agent"
}
```

## Error Responses

### 401 Unauthorized

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

### 403 Forbidden

```json theme={null}
{
  "error": "You don't have permission to access this agent"
}
```

### 404 Not Found

```json theme={null}
{
  "error": "Agent not found"
}
```

### 500 Server Error

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

## Examples

### cURL

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

### JavaScript (Fetch)

```javascript theme={null}
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)

```tsx theme={null}
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

```tsx theme={null}
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

```javascript theme={null}
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;
}
```

## Related Endpoints

* [List Agents](/api-reference/endpoint/list-agents) — List all agents in organization
* [Create Agent](/api-reference/endpoint/create-agent) — Create a new agent
* [Update Agent](/api-reference/endpoint/update-agent) — Update agent configuration
* [Delete Agent](/api-reference/endpoint/delete-agent) — Delete an agent


## OpenAPI

````yaml GET /v1/agents/{agentId}
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/{agentId}:
    get:
      tags:
        - Agents
      summary: Get Agent
      description: >-
        Returns full configuration for a specific agent. The agent must belong
        to your organization.
      operationId: getAgent
      parameters:
        - name: agentId
          in: path
          required: true
          schema:
            type: string
          example: 01JK5XYZ...
      responses:
        '200':
          description: Agent details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      agent:
                        $ref: '#/components/schemas/Agent'
        '401':
          description: Invalid or missing API key
        '404':
          description: Agent not found
      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_...`

````