curl https://api.telzino.com/v1/agents/123e4567-e89b-12d3-a456-426614174000 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const agentId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(`https://api.telzino.com/v1/agents/${agentId}`, {
headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' }
});
const { data } = await response.json();
console.log(data.name, data.status);
import requests
agent_id = '123e4567-e89b-12d3-a456-426614174000'
response = requests.get(
f'https://api.telzino.com/v1/agents/{agent_id}',
headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
)
agent = response.json()['data']
print(f"Agent: {agent['name']} - Status: {agent['status']}")
{
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "987fcdeb-51a2-3bc4-d567-890123456789",
"name": "Customer Support Agent",
"description": "Handles customer inquiries and support requests",
"greeting_message": "Hello! Thank you for calling. How can I help you today?",
"system_prompt": "You are a helpful customer support agent for Acme Corp. Be friendly, professional, and concise.",
"agent_type": "simple",
"model": "gpt-4.1",
"voice_model": "gpt-4o-realtime-preview",
"stt_model": "deepgram",
"tts_model": "cartesia",
"voice_settings": {
"voice_id": "f786b574-daa5-4673-aa0c-cbe3e8534c02",
"speed": 1.0
},
"config": {
"enable_recording": true,
"user_timezone": "America/New_York",
"inactivity_timeout": 15
},
"extensions": {
"tools": [
{
"type": "webhook",
"name": "check_order",
"description": "Check order status",
"url": "https://api.example.com/orders",
"method": "GET"
}
],
"mcp_servers": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"connection_name": "Example MCP",
"mcp_endpoint_url": "https://mcp.example.com/mcp",
"transport_type": "http",
"auth_headers": {
"Authorization": "Bearer YOUR_TOKEN"
},
"initialization_options": {},
"fingerprint": "sha256:abc123",
"tools": [
{
"name": "get_order_status",
"description": "Look up order status by order id"
}
]
}
]
},
"integrations": {
"googleCalendar": {
"email": "[email protected]",
"expires_at": "2026-06-13T10:30:00Z",
"selected_calendar_name": "Bookings",
"timezone": "America/New_York"
}
},
"transfer_enabled": true,
"transfer_rules": "Transfer to +15551234567 if the caller asks for billing support",
"language": "en-US",
"timezone": "America/New_York",
"enable_recording": true,
"echo_detection": false,
"call_detection": false,
"knowledgebase_links": ["https://example.com/faq"],
"email": ["[email protected]"],
"email_tool_enabled": false,
"email_tool_instructions": null,
"status": "active",
"is_active": true,
"sip_registration_data": null,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
{
"error": "not_found",
"error_description": "Agent not found or access denied"
}
Agents
Get Agent
Retrieves details of a specific agent by ID
GET
/
v1
/
agents
/
{agentId}
curl https://api.telzino.com/v1/agents/123e4567-e89b-12d3-a456-426614174000 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const agentId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(`https://api.telzino.com/v1/agents/${agentId}`, {
headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' }
});
const { data } = await response.json();
console.log(data.name, data.status);
import requests
agent_id = '123e4567-e89b-12d3-a456-426614174000'
response = requests.get(
f'https://api.telzino.com/v1/agents/{agent_id}',
headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
)
agent = response.json()['data']
print(f"Agent: {agent['name']} - Status: {agent['status']}")
{
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "987fcdeb-51a2-3bc4-d567-890123456789",
"name": "Customer Support Agent",
"description": "Handles customer inquiries and support requests",
"greeting_message": "Hello! Thank you for calling. How can I help you today?",
"system_prompt": "You are a helpful customer support agent for Acme Corp. Be friendly, professional, and concise.",
"agent_type": "simple",
"model": "gpt-4.1",
"voice_model": "gpt-4o-realtime-preview",
"stt_model": "deepgram",
"tts_model": "cartesia",
"voice_settings": {
"voice_id": "f786b574-daa5-4673-aa0c-cbe3e8534c02",
"speed": 1.0
},
"config": {
"enable_recording": true,
"user_timezone": "America/New_York",
"inactivity_timeout": 15
},
"extensions": {
"tools": [
{
"type": "webhook",
"name": "check_order",
"description": "Check order status",
"url": "https://api.example.com/orders",
"method": "GET"
}
],
"mcp_servers": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"connection_name": "Example MCP",
"mcp_endpoint_url": "https://mcp.example.com/mcp",
"transport_type": "http",
"auth_headers": {
"Authorization": "Bearer YOUR_TOKEN"
},
"initialization_options": {},
"fingerprint": "sha256:abc123",
"tools": [
{
"name": "get_order_status",
"description": "Look up order status by order id"
}
]
}
]
},
"integrations": {
"googleCalendar": {
"email": "[email protected]",
"expires_at": "2026-06-13T10:30:00Z",
"selected_calendar_name": "Bookings",
"timezone": "America/New_York"
}
},
"transfer_enabled": true,
"transfer_rules": "Transfer to +15551234567 if the caller asks for billing support",
"language": "en-US",
"timezone": "America/New_York",
"enable_recording": true,
"echo_detection": false,
"call_detection": false,
"knowledgebase_links": ["https://example.com/faq"],
"email": ["[email protected]"],
"email_tool_enabled": false,
"email_tool_instructions": null,
"status": "active",
"is_active": true,
"sip_registration_data": null,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
{
"error": "not_found",
"error_description": "Agent not found or access denied"
}
Path Parameters
string
required
The unique identifier of the agent (UUID format)
curl https://api.telzino.com/v1/agents/123e4567-e89b-12d3-a456-426614174000 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const agentId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(`https://api.telzino.com/v1/agents/${agentId}`, {
headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' }
});
const { data } = await response.json();
console.log(data.name, data.status);
import requests
agent_id = '123e4567-e89b-12d3-a456-426614174000'
response = requests.get(
f'https://api.telzino.com/v1/agents/{agent_id}',
headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
)
agent = response.json()['data']
print(f"Agent: {agent['name']} - Status: {agent['status']}")
{
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "987fcdeb-51a2-3bc4-d567-890123456789",
"name": "Customer Support Agent",
"description": "Handles customer inquiries and support requests",
"greeting_message": "Hello! Thank you for calling. How can I help you today?",
"system_prompt": "You are a helpful customer support agent for Acme Corp. Be friendly, professional, and concise.",
"agent_type": "simple",
"model": "gpt-4.1",
"voice_model": "gpt-4o-realtime-preview",
"stt_model": "deepgram",
"tts_model": "cartesia",
"voice_settings": {
"voice_id": "f786b574-daa5-4673-aa0c-cbe3e8534c02",
"speed": 1.0
},
"config": {
"enable_recording": true,
"user_timezone": "America/New_York",
"inactivity_timeout": 15
},
"extensions": {
"tools": [
{
"type": "webhook",
"name": "check_order",
"description": "Check order status",
"url": "https://api.example.com/orders",
"method": "GET"
}
],
"mcp_servers": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"connection_name": "Example MCP",
"mcp_endpoint_url": "https://mcp.example.com/mcp",
"transport_type": "http",
"auth_headers": {
"Authorization": "Bearer YOUR_TOKEN"
},
"initialization_options": {},
"fingerprint": "sha256:abc123",
"tools": [
{
"name": "get_order_status",
"description": "Look up order status by order id"
}
]
}
]
},
"integrations": {
"googleCalendar": {
"email": "[email protected]",
"expires_at": "2026-06-13T10:30:00Z",
"selected_calendar_name": "Bookings",
"timezone": "America/New_York"
}
},
"transfer_enabled": true,
"transfer_rules": "Transfer to +15551234567 if the caller asks for billing support",
"language": "en-US",
"timezone": "America/New_York",
"enable_recording": true,
"echo_detection": false,
"call_detection": false,
"knowledgebase_links": ["https://example.com/faq"],
"email": ["[email protected]"],
"email_tool_enabled": false,
"email_tool_instructions": null,
"status": "active",
"is_active": true,
"sip_registration_data": null,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
{
"error": "not_found",
"error_description": "Agent not found or access denied"
}
Response Fields
Core Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique agent identifier (UUID) |
organization_id | string | Organization the agent belongs to |
name | string | Display name of the agent |
description | string | What the agent does |
status | string | active, inactive, cancelled, or pending |
is_active | boolean | Computed from status (true if status is active) |
Conversation Configuration
| Field | Type | Description |
|---|---|---|
greeting_message | string | First message spoken when call connects |
outbound_greeting_message | string | Greeting spoken when the agent places an outbound call |
system_prompt | string | AI instructions defining behavior |
agent_type | string | simple, advanced, custom, or appointment_scheduler |
AI/Voice Models
| Field | Type | Description |
|---|---|---|
model | string | LLM model: gpt-4.1, gpt-4.1-mini, gpt-4o-mini, grok-3-fast, moonshotai/Kimi-K2.6, claude-sonnet-4-6 (see List LLM Models) |
voice_model | string | Voice model for realtime speech |
stt_model | string | Speech-to-text: deepgram |
tts_model | string | Text-to-speech: cartesia, minimax, deepgram |
voice_settings | object | TTS-specific voice configuration |
Configuration Objects
| Field | Type | Description |
|---|---|---|
config | object | General settings (enable_recording, user_timezone, etc.) |
extensions | object | Webhook tools (tools) and MCP connections (mcp_servers) — see below |
integrations | object | Third-party integrations keyed by provider (modmed, googleCalendar, outlookCalendar, twilio, netsapiens). Secret fields are never returned — see below |
Secrets are redacted from all agent responses. Integration secret fields — passwords,
twilio.authToken, netsapiens.client_secret, and calendar access/refresh tokens — and the SIP password inside sip_registration_data are omitted (not masked) from this and every other agent endpoint. Non-secret metadata (provider keys, usernames, accountSid, connected_at, calendar names) is still returned. Secrets are write-only: set them via Update Agent, whose field-level merge means a GET → modify → PUT round-trip won’t wipe stored secrets.Stored MCP Connection Shape
Each item inextensions.mcp_servers is returned exactly as stored — no field remapping occurs on GET. After saving via the Dashboard or the API, each entry uses the snake_case shape documented below.
Both "sse" and "http" transports use the same field set. transport_type is always stored lowercase. For "http", provide your streamable HTTP MCP endpoint in mcp_endpoint_url; for "sse" provide your SSE endpoint URL. The mcp_endpoint_url field accepts https:// (production) or http:// (e.g. local dev) as the URL scheme.
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Present once the connection has been saved |
connection_name | string | Human-readable connection label |
mcp_endpoint_url | string | Full MCP endpoint URL. Use your SSE endpoint when transport_type is "sse", or your streamable HTTP endpoint when transport_type is "http". Accepts https:// or http:// scheme |
transport_type | string | "sse" or "http", lowercase only |
auth_headers | object | Optional. Object of header names to string values, sent to the MCP server |
initialization_options | object | Optional. Arbitrary JSON passed at MCP client initialization |
fingerprint | string | Present only after the connection has been tested (via Dashboard or API test). Absent for connections created via the API that have never been tested from the Portal. |
tools | array | Cached list of tools discovered during the last connection test. Each item has name and description only — full JSON schemas are not stored. Empty for API-created connections that have not yet been tested. |
extensions on POST or PUT, the API validates a different request shape. See Create Agent — MCP Servers Request Body for the accepted fields. Do not paste a GET mcp_servers array into a create or update body without transforming the entries.
Call Features
| Field | Type | Description |
|---|---|---|
transfer_enabled | boolean | Whether call transfer function is available |
transfer_rules | string | Rules/conditions for call transfers |
enable_recording | boolean | Whether call recording is enabled |
echo_detection | boolean | Whether echo detection is enabled |
call_detection | boolean | Whether answering machine detection is enabled |
email_tool_enabled | boolean | Whether the email tool is enabled |
email_tool_instructions | string | Instructions for email tool usage |
email | array | Email addresses for notifications and email tool |
sip_registration_data | object | SIP registration configuration (if set) |
Localization
| Field | Type | Description |
|---|---|---|
language | string | Agent language (en-US, es-US, or multi) |
timezone | string | Agent timezone in IANA format (e.g., America/New_York) |
Knowledge Base
| Field | Type | Description |
|---|---|---|
knowledgebase_links | array | URLs the agent references for knowledge |
Business (Google Place)
| Field | Type | Description |
|---|---|---|
google_place_id | string | Linked Google Business Profile listing. Set via googlePlaceId on Create / Update |
google_place_data | object | Raw listing details from Google (service-managed, read-only) |
google_place_context | string | Curated business facts the agent uses on calls (service-managed, read-only) |
google_place_fetched_at | string | When the listing was last fetched. Data older than 30 days is never used on calls |
Timestamps
| Field | Type | Description |
|---|---|---|
created_at | datetime | When the agent was created |
updated_at | datetime | When the agent was last modified |
⌘I
