Complete CRUD API for Voisnap voice agents — create, configure, activate, publish, version, and analyze agents.

Agents

Agents are the core resource in Voisnap. An agent defines the AI persona, voice, language model, transcription settings, channel configuration, and all behavioral parameters for a voice AI interaction.

Base path: /api/v1/agents

Agent object

{
  "id": "agt_01HXK8Z3MNPQRS",
  "name": "Aria – Support Agent",
  "description": "Front-line customer support for Acme Corp",
  "status": "active",
  "version": 3,
  "publishedVersion": 2,
  "persona": {
    "name": "Aria",
    "personality": "friendly, concise, professional",
    "role": "customer support specialist"
  },
  "voice": {
    "provider": "elevenlabs",
    "voiceId": "EXAVITQu4vr4xnSDxMaL",
    "stability": 0.5,
    "similarityBoost": 0.75,
    "style": 0.0,
    "useSpeakerBoost": true,
    "speed": 1.0
  },
  "llm": {
    "provider": "openai",
    "model": "gpt-4o",
    "temperature": 0.7,
    "maxTokens": 300,
    "topP": 1.0,
    "frequencyPenalty": 0.0,
    "presencePenalty": 0.0
  },
  "transcription": {
    "provider": "deepgram",
    "model": "nova-2",
    "language": "en-US",
    "smartFormat": true,
    "punctuate": true,
    "profanityFilter": false
  },
  "systemPromptTemplate": "You are Aria, a friendly customer support agent...",
  "firstMessage": "Hello! Thanks for calling. How can I help you today?",
  "firstMessageMode": "assistant_speaks_first",
  "endCallPhrases": ["goodbye", "have a good day", "thank you, bye"],
  "maxDurationSeconds": 600,
  "maxIdleTimeSeconds": 15,
  "dtmfEnabled": true,
  "hipaaCompliant": false,
  "aiDisclosureMessage": "Just so you know, you're speaking with an AI assistant.",
  "silenceDetection": {
    "enabled": true,
    "timeoutSeconds": 8,
    "message": "Are you still there?"
  },
  "endpointing": {
    "provider": "vad",
    "silenceDurationMs": 700,
    "utteranceEndMs": 1000
  },
  "interruption": {
    "enabled": true,
    "sensitivity": "medium"
  },
  "voicemailDetection": {
    "enabled": true,
    "action": "leave_message",
    "message": "Hi, this is Aria calling on behalf of Acme. Please call us back at 1-800-ACME."
  },
  "recording": {
    "enabled": true,
    "format": "mp3",
    "storageRetentionDays": 90,
    "stereo": false
  },
  "costTracking": {
    "enabled": true,
    "currency": "USD"
  },
  "analysisConfig": {
    "enabled": true,
    "sentimentAnalysis": true,
    "intentDetection": true,
    "summaryEnabled": true,
    "customFields": [
      {
        "name": "resolution_status",
        "type": "enum",
        "options": ["resolved", "escalated", "callback_scheduled", "unresolved"]
      },
      {
        "name": "issue_category",
        "type": "string"
      }
    ]
  },
  "knowledgeBaseIds": ["kb_01HXK9ABCDEF"],
  "tags": ["support", "tier-1"],
  "createdAt": "2025-06-15T10:00:00Z",
  "updatedAt": "2025-06-16T09:30:00Z"
}

Create an agent

POST /api/v1/agents

Request body:

Field	Type	Required	Description
`name`	string	Yes	Agent display name (max 100 chars)
`description`	string	No	Internal description
`persona.name`	string	Yes	The agent's spoken name
`persona.personality`	string	No	Personality descriptor (used in prompt)
`voice.provider`	string	Yes	`elevenlabs`, `google`, `aws`, `azure`
`voice.voiceId`	string	Yes	Provider-specific voice ID
`llm.provider`	string	Yes	`openai`, `anthropic`, `google`, `cohere`
`llm.model`	string	Yes	Model identifier (see AI Models)
`transcription.provider`	string	Yes	`deepgram`, `assemblyai`, `google`, `aws`, `azure`
`systemPromptTemplate`	string	Yes	System prompt (supports `{{variables}}`)
`firstMessage`	string	No	Opening message the agent speaks
`firstMessageMode`	string	No	`assistant_speaks_first` or `wait_for_user`
`endCallPhrases`	string[]	No	Phrases that trigger call end
`maxDurationSeconds`	integer	No	Max call duration (30–3600, default 600)
`maxIdleTimeSeconds`	integer	No	Silence timeout in seconds (5–60)

curl -X POST https://api.voisnap.ai/api/v1/agents \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aria – Support Agent",
    "persona": { "name": "Aria", "personality": "friendly, professional" },
    "voice": { "provider": "elevenlabs", "voiceId": "EXAVITQu4vr4xnSDxMaL" },
    "llm": { "provider": "openai", "model": "gpt-4o" },
    "transcription": { "provider": "deepgram", "model": "nova-2", "language": "en-US" },
    "systemPromptTemplate": "You are Aria, a support agent for Acme Corp...",
    "firstMessage": "Hello! How can I help you today?",
    "firstMessageMode": "assistant_speaks_first"
  }'

agent = client.agents.create(
    name="Aria – Support Agent",
    persona={"name": "Aria", "personality": "friendly, professional"},
    voice={"provider": "elevenlabs", "voice_id": "EXAVITQu4vr4xnSDxMaL"},
    llm={"provider": "openai", "model": "gpt-4o"},
    transcription={"provider": "deepgram", "model": "nova-2", "language": "en-US"},
    system_prompt_template="You are Aria, a support agent for Acme Corp...",
    first_message="Hello! How can I help you today?",
    first_message_mode="assistant_speaks_first",
)

const agent = await client.agents.create({
  name: 'Aria – Support Agent',
  persona: { name: 'Aria', personality: 'friendly, professional' },
  voice: { provider: 'elevenlabs', voiceId: 'EXAVITQu4vr4xnSDxMaL' },
  llm: { provider: 'openai', model: 'gpt-4o' },
  transcription: { provider: 'deepgram', model: 'nova-2', language: 'en-US' },
  systemPromptTemplate: 'You are Aria, a support agent for Acme Corp...',
  firstMessage: 'Hello! How can I help you today?',
  firstMessageMode: 'assistant_speaks_first',
});

List agents

GET /api/v1/agents

Query parameters:

Parameter	Type	Description
`page`	integer	Page number
`pageSize`	integer	Items per page (max 100)
`status`	string	Filter by `active`, `inactive`, `draft`
`search`	string	Search by name
`tags`	string	Comma-separated tags filter
`sortBy`	string	`name`, `createdAt`, `updatedAt`
`sortOrder`	string	`asc` or `desc`

curl "https://api.voisnap.ai/api/v1/agents?status=active&pageSize=50" \
  -H "Authorization: Bearer vsnp_live_..."

# Auto-paginated iterator
for agent in client.agents.list(status="active"):
    print(agent.name)

for await (const agent of client.agents.list({ status: 'active' })) {
  console.log(agent.name);
}

Get an agent

GET /api/v1/agents/{agentId}

curl https://api.voisnap.ai/api/v1/agents/agt_01HXK8Z3MNPQRS \
  -H "Authorization: Bearer vsnp_live_..."

Update an agent

PATCH /api/v1/agents/{agentId}

All fields are optional. Only provided fields are updated.

curl -X PATCH https://api.voisnap.ai/api/v1/agents/agt_01HXK8Z3MNPQRS \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "systemPromptTemplate": "You are Aria, updated prompt...",
    "llm": { "temperature": 0.5 },
    "maxDurationSeconds": 900
  }'

Delete an agent

DELETE /api/v1/agents/{agentId}

:::warning Deleting an agent is permanent. All associated phone number assignments are released. Conversation history is preserved and accessible via the Conversations API. :::

curl -X DELETE https://api.voisnap.ai/api/v1/agents/agt_01HXK8Z3MNPQRS \
  -H "Authorization: Bearer vsnp_live_..."

Activate / Deactivate

Agents must be active to receive inbound calls or initiate outbound calls.

POST /api/v1/agents/{agentId}/activate
POST /api/v1/agents/{agentId}/deactivate

curl -X POST https://api.voisnap.ai/api/v1/agents/agt_01HXK8Z3MNPQRS/activate \
  -H "Authorization: Bearer vsnp_live_..."

client.agents.activate("agt_01HXK8Z3MNPQRS")
client.agents.deactivate("agt_01HXK8Z3MNPQRS")

Duplicate an agent

Creates a copy of an agent with all settings cloned. The new agent starts in inactive status.

POST /api/v1/agents/{agentId}/duplicate

curl -X POST https://api.voisnap.ai/api/v1/agents/agt_01HXK8Z3MNPQRS/duplicate \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Aria – Support Agent (Copy)" }'

Agent versions

Every PATCH to an agent increments its version. You can retrieve and compare versions.

GET /api/v1/agents/{agentId}/versions
GET /api/v1/agents/{agentId}/versions/{versionNumber}

curl https://api.voisnap.ai/api/v1/agents/agt_01HXK8Z3MNPQRS/versions \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "data": [
    {
      "version": 3,
      "createdAt": "2025-06-16T09:30:00Z",
      "createdBy": "usr_01HXK8Z...",
      "changesSummary": "Updated system prompt and LLM temperature"
    },
    {
      "version": 2,
      "publishedAt": "2025-06-15T14:00:00Z",
      "createdAt": "2025-06-15T12:00:00Z",
      "createdBy": "usr_01HXK8Z...",
      "changesSummary": "Initial published version"
    }
  ]
}

Publish an agent version

Publishing locks the agent configuration for the current version and marks it as the stable production version.

POST /api/v1/agents/{agentId}/publish

curl -X POST https://api.voisnap.ai/api/v1/agents/agt_01HXK8Z3MNPQRS/publish \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Improved prompt for billing questions" }'

Agent stats

GET /api/v1/agents/{agentId}/stats

Query parameters: dateFrom, dateTo (ISO 8601)

curl "https://api.voisnap.ai/api/v1/agents/agt_01HXK8Z3MNPQRS/stats?dateFrom=2025-06-01&dateTo=2025-06-30" \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "agentId": "agt_01HXK8Z3MNPQRS",
  "period": { "from": "2025-06-01", "to": "2025-06-30" },
  "totalConversations": 1482,
  "totalDurationSeconds": 312840,
  "avgDurationSeconds": 211,
  "totalCostUsd": 127.43,
  "avgCostUsdPerConversation": 0.086,
  "channelBreakdown": {
    "phone": 1240,
    "webrtc": 180,
    "webchat": 62
  },
  "outcomeBreakdown": {
    "resolved": 1089,
    "escalated": 241,
    "abandoned": 152
  },
  "avgSentimentScore": 0.72
}

Test an agent

Sends a test call from the agent to a specified phone number or initiates a sandbox session.

POST /api/v1/agents/{agentId}/test

curl -X POST https://api.voisnap.ai/api/v1/agents/agt_01HXK8Z3MNPQRS/test \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "phone",
    "phoneNumber": "+14155550100",
    "metadata": { "testScenario": "billing-inquiry" }
  }'

Response:

{
  "testSessionId": "test_01HXMNZ...",
  "status": "initiated",
  "estimatedConnectSeconds": 5
}

Agents

Agents

Agent object

Create an agent

List agents

Get an agent

Update an agent

Delete an agent

Activate / Deactivate

Duplicate an agent

Agent versions

Publish an agent version

Agent stats

Test an agent

On this page