AI

Get ai details.

Changed on

Retrieves detailed information for a specific ai by its ID.

get/ais/{id}

Request

  • Base URL
    https://api.voipbin.net/v1.0
  • URL
    https://api.voipbin.net/v1.0/ais/{id}
  • Auth
    none declared

Path parameters

idstring required

The ID of the ai.

Response

Details of the requested ai.

idstring uuid

The unique identifier of the AI.

customer_idstring uuid

The unique identifier of the associated customer. Returned from the GET /customers response.

namestring

Name of the AI.

detailstring

Detailed information about the AI.

type'normal' | 'insight'

AI type. normal (default) is a general-purpose AI. insight limits the AI's built-in tools to the Insight tool set, adds the tools of the MCP servers in its own mcp_server_ids, and uses a dedicated system prompt for analyzing existing contact/conversation data.

is_insight_activeboolean required

Whether this is the customer's active Insight AI, i.e. the one the Case Insight Assistant panel auto-attaches to a case. Only meaningful when type is insight. A customer may hold any number of Insight AIs but at most one may be active. Newly created AIs are always inactive; use POST /ais/{id}/activate_insight to activate one. When no Insight AI is active, the most recently created one is used.

engine_modelstring

Model of the AI engine. Uses target.model format (e.g., openai.gpt-5). The target prefix identifies the provider, and the model name follows after the dot. The list of selectable models is returned by GET /ai_models. A value in the form openrouter.<author>/<slug> is also accepted (custom OpenRouter model, see model_id_prefix in GET /ai_models); in that case engine_key is required. A value in the form customendpoint.<model-id> selects an OpenAI-compatible server that you host; in that case engine_base_url is required and engine_base_key is optional. The customendpoint. model is not listed in GET /ai_models.

parameterobject

Custom key-value configuration data specific to the AI engine type.

has_engine_keyboolean

Whether the AI holds an engine key (engine_key). A key kept on a platform model counts, although it is not used. The key itself is write-only and is never returned in responses.

engine_base_urlstring

Base URL of the customer-hosted OpenAI-compatible server. Set only when engine_model starts with customendpoint.. The key for that server (engine_base_key) is write-only and is never returned.

rag_idstring uuid

The knowledge base ID for the search_knowledge tool. Returned from the id field of the GET /rags response. When set, the AI assistant can search this knowledge base during voice calls.

init_promptstring

Initial prompt to configure the AI's behavior.

current_prompt_history_idstring uuid

UUID of the most-recent prompt history entry. Zero UUID means no versioned history has been recorded yet.

tts_type'' | 'async' | 'aws' | 'azure' | 'cartesia' | 'deepgram' | 'elevenlabs' | 'fish' | 'google' | 'groq' | 'hume' | 'inworld' | 'lmnt' | 'minimax' | 'neuphonic' | 'nvidia-riva' | 'openai' | 'piper' | 'playht' | 'rime' | 'sarvam' | 'xtts'

Text-to-speech provider type.

tts_voice_idstring

Text-to-speech voice identifier.

stt_type'' | 'cartesia' | 'deepgram' | 'elevenlabs'

Speech-to-text provider type.

stt_languagestring

STT language in BCP-47 format (e.g., ko-KR, en-US). Empty for auto-detect.

smart_turn_enabledboolean

Enable smart turn detection using Pipecat's LocalSmartTurnAnalyzerV3. When enabled, forces VAD stop_secs to 0.2 for optimal turn-taking.

auto_aicall_audit_enabledboolean

When true, any finished AICall involving this AI is audited automatically.

tool_namesAIManagerToolName[]

List of tool names enabled for this AI. Use ["all"] to enable all tools. See the Tool Functions documentation for detailed descriptions of each tool.

mcp_server_idsstring[]

List of customer-registered MCP server IDs whitelisted for this AI. Each ID must reference an MCP server owned by the same customer, returned from the id field of the POST /mcpservers or GET /mcpservers response. Tool use scope: a whitelisted server's tools are presented to this AI's single-AI sessions, including those of type=insight AIs; team-typed AI calls never receive MCP tools regardless of this list. Sessions that do discover and advertise include chat, voice calls, ai_task flow actions and API-created single-AI sessions, so expect tools/list (and, on a tool call, tools/call) requests authenticated per the server's auth_type in its logs. Of what is discovered, the tool names are stored on the AI session record and outlive the request, while the input schemas and descriptions are not stored. A usable server's tools are namespaced mcp_<server_id_prefix>_<tool_name> when presented to the model, up to 256 tools per session across this AI's whitelisted servers.

direct_hashstring

The direct hash for direct access via SIP URI sip:<direct_hash>@sip.voipbin.net (the "direct." prefix is already included in the value, e.g. "direct.a1b2c3d4e5f6"). Returned from the resource's direct_hash field.

tm_createstring date-time

Timestamp when the AI was created.

tm_updatestring date-time

Timestamp when the AI was last updated.

tm_deletestring date-time

Timestamp when the AI was deleted.

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_id": "7c4d2f3a-1b8e-4f5c-9a6d-3e2f1a0b4c5d",
  "name": "Customer Support Bot",
  "detail": "AI assistant for handling customer inquiries",
  "type": "normal",
  "engine_model": "openai.gpt-5",
  "has_engine_key": true,
  "engine_base_url": "https://llm.example.com/v1",
  "rag_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "init_prompt": "You are a helpful customer support assistant.",
  "current_prompt_history_id": "00000000-0000-0000-0000-000000000000",
  "tts_type": "elevenlabs",
  "tts_voice_id": "en-US-Neural2-F",
  "stt_type": "deepgram",
  "stt_language": "en-US",
  "vad_config": {
    "confidence": 0.7,
    "start_secs": 0.2,
    "stop_secs": 0.5,
    "min_volume": 0.6
  },
  "tool_names": [
    "all"
  ],
  "mcp_server_ids": [],
  "direct_hash": "direct.a1b2c3d4e5f6",
  "tm_create": "2026-01-15T09:30:00.000000Z",
  "tm_update": "2026-01-15T09:30:00.000000Z",
  "tm_delete": "2026-01-15T09:30:00.000000Z"
}

Changes