Skip to main content
GET
/
v1
/
agents
/
{agentId}
curl https://api.telzino.com/v1/agents/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "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"
  }
}

​
Path Parameters

​
agentId
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"

{
  "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"
  }
}

​
Response Fields

​
Core Fields

FieldTypeDescription
idstringUnique agent identifier (UUID)
organization_idstringOrganization the agent belongs to
namestringDisplay name of the agent
descriptionstringWhat the agent does
statusstringactive, inactive, cancelled, or pending
is_activebooleanComputed from status (true if status is active)

​
Conversation Configuration

FieldTypeDescription
greeting_messagestringFirst message spoken when call connects
system_promptstringAI instructions defining behavior
agent_typestringsimple, advanced, custom, or appointment_scheduler

​
AI/Voice Models

FieldTypeDescription
modelstringLLM model: gpt-4o, gpt-4o-mini
voice_modelstringVoice model for realtime speech
stt_modelstringSpeech-to-text: deepgram
tts_modelstringText-to-speech: cartesia, minimax, deepgram
voice_settingsobjectTTS-specific voice configuration

​
Configuration Objects

FieldTypeDescription
configobjectGeneral settings (enable_recording, user_timezone, etc.)
extensionsobjectWebhook tools (tools) and MCP connections (mcp_servers) — see below
integrationsobjectThird-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 in extensions.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.
FieldTypeDescription
idstring (UUID)Present once the connection has been saved
connection_namestringHuman-readable connection label
mcp_endpoint_urlstringFull 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_typestring"sse" or "http", lowercase only
auth_headersobjectOptional. Object of header names to string values, sent to the MCP server
initialization_optionsobjectOptional. Arbitrary JSON passed at MCP client initialization
fingerprintstringPresent 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.
toolsarrayCached 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.
To create or update MCP entries via 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

FieldTypeDescription
transfer_enabledbooleanWhether call transfer function is available
transfer_rulesstringRules/conditions for call transfers
enable_recordingbooleanWhether call recording is enabled
echo_detectionbooleanWhether echo detection is enabled
call_detectionbooleanWhether answering machine detection is enabled
email_tool_enabledbooleanWhether the email tool is enabled
email_tool_instructionsstringInstructions for email tool usage
emailarrayEmail addresses for notifications and email tool
sip_registration_dataobjectSIP registration configuration (if set)

​
Localization

FieldTypeDescription
languagestringAgent language (en-US, es-US, or multi)
timezonestringAgent timezone in IANA format (e.g., America/New_York)

​
Knowledge Base

FieldTypeDescription
knowledgebase_linksarrayURLs the agent references for knowledge

​
Business (Google Place)

FieldTypeDescription
google_place_idstringLinked Google Business Profile listing. Set via googlePlaceId on Create / Update
google_place_dataobjectRaw listing details from Google (service-managed, read-only)
google_place_contextstringCurated business facts the agent uses on calls (service-managed, read-only)
google_place_fetched_atstringWhen the listing was last fetched. Data older than 30 days is never used on calls

​
Timestamps

FieldTypeDescription
created_atdatetimeWhen the agent was created
updated_atdatetimeWhen the agent was last modified