Update Agent

Overview

Updates an existing agent’s configuration. Send only the fields you want to modify — all other fields remain unchanged. 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
Content-Type: application/json

Request Body:

{
  "name": "Updated Agent Name",
  "description": "Updated description",
  "sysMsg": "Updated system prompt...",
  "languages": ["english", "urdu"],
  "agentArchitecture": "pipeline",
  "model": "gpt_4o_mini",
  "stt": "deepgram",
  "voiceId": "cartesia-voice-456",
  "realtimeProvider": "gemini",
  "greetingType": "agentFirst",
  "greetingMessage": "Hello! How can I assist you?",
  "lastMessage": "Goodbye!",
  "temperature": 0.7,
  "inactivityTimeout": 30,
  "mode": "public"
}

Optional Fields:

Field	Type	Validation	Description
`name`	string	2-50 chars	Agent display name
`description`	string	Max 200 chars	Internal description
`sysMsg`	string	Max 5000 chars	System prompt
`languages`	array	1+ items	Language codes (en, ur, sd)
`agentArchitecture`	string	Fixed after create	`pipeline`, `realtime`, or `text`
`model`	string	Required for pipeline/text	LLM model
`stt`	string	Required for pipeline	STT provider
`voiceId`	string	Required for pipeline	Voice ID
`realtimeProvider`	string	Required for realtime	`openai` or `gemini`
`greetingType`	string	`agentFirst` or `userFirst`	Who speaks first
`greetingMessage`	string	Optional	Greeting text
`lastMessage`	string	Max 100 chars	Farewell message
`temperature`	number	0.1–1.0	Response randomness
`inactivityTimeout`	number	10–60 seconds	Silence timeout
`mode`	string	`public`, `private`, `commercial`	Visibility mode

Response

Status: 200 OK

{
  "success": true,
  "agent": {
    "id": "agent_abc123",
    "name": "Updated Agent Name",
    "description": "Updated description",
    "agentArchitecture": "pipeline",
    "mode": "public",
    "model": "gpt_4o_mini",
    "stt": "deepgram",
    "voiceId": "cartesia-voice-456",
    "sysMsg": "Updated system prompt...",
    "functionCallingEnabled": true,
    "enabledFunctions": ["web_search", "end_call"],
    "enabledCustomFunctions": [],
    "greetingType": "agentFirst",
    "greetingMessage": "Hello! How can I assist you?",
    "lastMessage": "Goodbye!",
    "temperature": 0.7,
    "inactivityTimeout": 30,
    "createdAt": "2024-01-10T09:00:00Z",
    "updatedAt": "2024-01-15T14:30:00Z",
    "userId": "user_xyz789",
    "organizationId": "org_123",
    "languages": [
      {
        "id": "lang_123",
        "language": "english"
      },
      {
        "id": "lang_124",
        "language": "urdu"
      }
    ],
    "VoiceOption": {
      "voiceId": "cartesia-voice-456",
      "voiceName": "Sonic British",
      "provider": "cartesia"
    }
  }
}

Special Response (Missing API Keys):

{
  "success": true,
  "agent": { /* ... agent object ... */ },
  "missingKeys": ["openaiKey"],
  "usedDefaults": true,
  "finalModel": "gemini-2.0-flash",
  "finalStt": "gemini",
  "redirectUrl": "/organization?callbackUrl=/agents/create-agent/agent_abc123"
}

Access Control

User Role	Can Update
Owner	✅ Any agent in organization
Admin	✅ Any agent in organization
Member (Creator)	✅ Own agents (except commercial)
Member (Not Creator)	❌ Cannot update

Commercial Agent Restriction:

Only Owners/Admins can update commercial agents
Creators cannot modify their own commercial agents

Validation Rules

Architecture-Specific Validation

Pipeline:

{
  "agentArchitecture": "pipeline",
  "voiceId": "required",
  "model": "required",
  "stt": "required"
}

Realtime:

{
  "agentArchitecture": "realtime",
  "realtimeProvider": "required (openai or gemini)",
  "voiceId": "required if greetingType=agentFirst"
}

Text:

{
  "agentArchitecture": "text",
  "model": "required",
  "voiceId": "not applicable",
  "stt": "not applicable"
}

Field Validation

Field	Rule	Error Message
`inactivityTimeout`	10–60 seconds	”Inactivity timeout must be between 10 and 60 seconds”
`mode`	public/private/commercial	”Invalid agent mode”
`languages`	en/ur/sd only	”Invalid language: “
`name`	Required	”Name is required”
`description`	Required	”Description is required”
`sysMsg`	Required	”System message is required”

Mode Change Validation

Changing to Commercial:

{
  "mode": "commercial"
}

✅ Allowed for Owners/Admins
❌ Forbidden for Members
Error: “Only organization owners and admins can set agent as commercial”

Error Responses

401 Unauthorized

{
  "error": "Unauthorized"
}

403 Forbidden

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

400 Bad Request

{
  "error": "Inactivity timeout must be between 10 and 60 seconds"
}

{
  "error": "For pipeline architecture, voiceId, model, and STT are required"
}

{
  "error": "Invalid agent mode. Must be 'public', 'private', or 'commercial'"
}

404 Not Found

{
  "error": "Agent not found"
}

500 Server Error

{
  "error": "Update failed"
}

Examples

cURL

curl -X PUT "https://studio.talkifai.dev/api/agents/agent_abc123" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Support Bot",
    "temperature": 0.5,
    "mode": "public"
  }'

JavaScript (Fetch)

const agentId = "agent_abc123";
const updateData = {
  name: "Updated Support Bot",
  temperature: 0.5,
  mode: "public"
};

const response = await fetch(`/api/agents/${agentId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${sessionToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(updateData)
});

const data = await response.json();
if (data.redirectUrl) {
  // Missing API keys - redirect to configure
  window.location.href = data.redirectUrl;
}

Next.js (Client Component)

async function updateAgent(agentId: string, updates: Partial<Agent>) {
  const response = await fetch(`/api/agents/${agentId}`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(updates)
  });

  const data = await response.json();
  
  if (!response.ok) {
    throw new Error(data.error || "Update failed");
  }
  
  // Handle missing keys redirect
  if (data.redirectUrl) {
    router.push(data.redirectUrl);
    return;
  }
  
  // Success - agent updated
  toast.success("Agent updated successfully!");
  return data.agent;
}

// Usage
await updateAgent("agent_abc123", {
  name: "New Name",
  temperature: 0.5
});

Update Languages

const response = await fetch(`/api/agents/${agentId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${sessionToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    languages: ["english", "urdu", "sindhi"]
  })
});

Change to Commercial Mode

// Only works for Owners/Admins
const response = await fetch(`/api/agents/${agentId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${sessionToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    mode: "commercial"
  })
});

if (response.status === 403) {
  console.error("Only owners/admins can create commercial agents");
}

Use Cases

Partial Update (Recommended)

// Only send fields you want to change
await updateAgent(agentId, {
  temperature: 0.5  // Only change temperature
});

Full Configuration Update

await updateAgent(agentId, {
  name: "New Name",
  description: "New description",
  sysMsg: "New system prompt...",
  languages: ["english"],
  model: "gpt_4o_mini",
  stt": "deepgram",
  voiceId: "cartesia-voice-123",
  greetingType: "agentFirst",
  greetingMessage: "Hello!",
  temperature: 0.7,
  inactivityTimeout: 30,
  mode: "public"
});

Architecture-Specific Update

// Pipeline agent update
await updateAgent(agentId, {
  agentArchitecture: "pipeline",
  voiceId: "cartesia-voice-456",
  model: "gpt_4o_mini",
  stt: "deepgram"
});

// Realtime agent update
await updateAgent(agentId, {
  agentArchitecture: "realtime",
  realtimeProvider: "gemini",
  voiceId: "gemini-leda-en"
});

// Text agent update
await updateAgent(agentId, {
  agentArchitecture: "text",
  model: "gpt_4o_mini"
});

List Agents — List all agents
Get Agent — Get agent details
Create Agent — Create new agent
Delete Agent — Delete agent

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

Body

application/json

name

string

description

string

sysMsg

string

model

string

stt

string

voiceId

string

realtimeProvider

enum<string>

Available options:

openai,

gemini

greetingType

enum<string>

Available options:

agentFirst,

userFirst

greetingMessage

string

lastMessage

string

temperature

number

inactivityTimeout

integer

Required range: 10 <= x <= 60

mode

enum<string>

Available options:

public,

private,

commercial

languages

string[]

functionCallingEnabled

boolean

enabledFunctions

string[]

enabledCustomFunctions

string[]

Response

Agent updated

success

boolean

data

object

Show child attributes

Overview

Agents

Voice Calls

Export

Text Chat

Batch Calling

Custom Functions

Webhooks

Overview

Request

Response

Access Control

Validation Rules

Architecture-Specific Validation

Field Validation

Mode Change Validation

Error Responses

401 Unauthorized

403 Forbidden

400 Bad Request

404 Not Found

500 Server Error

Examples

cURL

JavaScript (Fetch)

Next.js (Client Component)

Update Languages

Change to Commercial Mode

Use Cases

Partial Update (Recommended)

Full Configuration Update

Architecture-Specific Update

Authorizations

Path Parameters

Body

Response

Overview

Agents

Voice Calls

Export

Text Chat

Batch Calling

Custom Functions

Webhooks

​Overview

​Request

​Response

​Access Control

​Validation Rules

​Architecture-Specific Validation

​Field Validation

​Mode Change Validation

​Error Responses

​401 Unauthorized

​403 Forbidden

​400 Bad Request

​404 Not Found

​500 Server Error

​Examples

​cURL

​JavaScript (Fetch)

​Next.js (Client Component)

​Update Languages

​Change to Commercial Mode

​Use Cases

​Partial Update (Recommended)

​Full Configuration Update

​Architecture-Specific Update

​Related Endpoints

Authorizations

Path Parameters

Body

Response

Overview

Request

Response

Access Control

Validation Rules

Architecture-Specific Validation

Field Validation

Mode Change Validation

Error Responses

401 Unauthorized

403 Forbidden

400 Bad Request

404 Not Found

500 Server Error

Examples

cURL

JavaScript (Fetch)

Next.js (Client Component)

Update Languages

Change to Commercial Mode

Use Cases

Partial Update (Recommended)

Full Configuration Update

Architecture-Specific Update

Related Endpoints