v51

latestOpenAPI 3.0.0raw.githubusercontent.com2026-08-014102371.0 MB

Create a new ai.

Creates a new ai and returns the created ai's details.

post/ais

Request body

namestring required

detailstring required

type'normal' | 'insight'

AI type. normal (default) is a general-purpose AI. insight restricts the AI to the Insight tool set and uses a dedicated system prompt.

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.

parameterobject required

Data associated with the ai's engine, can be dynamic and vary based on the engine type.

engine_keystring required

API key or credential for the AI engine.

rag_idstring

The knowledge base ID (UUID) for the search_knowledge tool. Returned from the id field of the GET /rags response. Send empty string or omit to clear.

init_promptstring required

tts_typestring required

Text-to-speech engine type.

tts_voice_idstring required

Voice ID for the text-to-speech engine.

stt_typestring required

Speech-to-text engine type.

stt_languagestring

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

tool_namesAIManagerToolName[]

List of tool names to enable for this AI. Use ["all"] to enable all available tools. For type=insight AIs, only Insight tool names are permitted (currently: get_contact_interactions, get_conversation_content); type=normal AIs may use any Normal tool name or ["all"]. Mismatched combinations are rejected with a 400.

auto_aicall_audit_enabledboolean

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

Example request

{
  "type": "normal",
  "engine_model": "openai.gpt-5",
  "stt_language": "en-US",
  "vad_config": {
    "confidence": 0.7,
    "start_secs": 0.2,
    "stop_secs": 0.5,
    "min_volume": 0.6
  },
  "tool_names": [
    "connect_call"
  ]
}

Response

Details of the created 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 restricts the AI to the Insight tool set 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.

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.

parameterobject

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

engine_keystring

API key or authentication key for the AI engine. Write-only; not returned in responses.

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.

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 available tools. See the Tool Functions documentation for detailed descriptions of each tool.

direct_hashstring

Hash for direct access via SIP URI sip:direct.<hash>@sip.voipbin.net. 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",
  "engine_key": "sk-...redacted...",
  "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"
  ],
  "direct_hash": "a8f3b2c1d4e5",
  "tm_create": "2026-01-15T09:30:00.000000Z",
  "tm_update": "2026-01-15T09:30:00.000000Z",
  "tm_delete": "2026-01-15T09:30:00.000000Z"
}