VOISA AI REST API Reference

Complete reference documentation for the VOISA AI REST API, enabling programmatic control of agents, conversations, and platform features.

🌐 API Overview

Base URL

Production: https://api.voisa.ai/v1
Staging: https://staging-api.voisa.ai/v1

Authentication

All API requests require authentication via Bearer token:

Authorization: Bearer YOUR_API_KEY

Content Type

Content-Type: application/json
Accept: application/json

Rate Limiting

Standard: 100 requests/minute
Pro: 500 requests/minute
Enterprise: Custom limits

Response Format

{
  "success": true,
  "data": {},
  "message": "Operation successful",
  "timestamp": "2025-01-15T10:30:00Z"
}

Error Format

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Detailed error message",
    "field": "specific_field"
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

🔐 Authentication

Get API Key

Endpoint: POST /api/get-api-key

Request:

{
  "email": "user@example.com",
  "password": "secure_password"
}

Response:

{
  "success": true,
  "data": {
    "api_key": "vsa_live_abc123...",
    "expires_at": "2025-12-31T23:59:59Z",
    "permissions": ["read", "write", "delete"]
  }
}

Verify API Key

Endpoint: GET /api/verify

Headers:

Authorization: Bearer YOUR_API_KEY

Response:

{
  "success": true,
  "data": {
    "valid": true,
    "account_id": "acc_123",
    "permissions": ["read", "write"]
  }
}

🤖 Agent Management

List Agents

Endpoint: GET /api/agents/list

Query Parameters:

status: "active" | "inactive" | "training"
industry: Industry filter
page: Page number (default: 1)
limit: Items per page (default: 20)

Response:

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "agt_123",
        "name": "Restaurant Assistant",
        "description": "Handles reservations and inquiries",
        "status": "active",
        "industry": "restaurant",
        "created_at": "2025-01-01T00:00:00Z",
        "stats": {
          "total_calls": 1543,
          "success_rate": 0.92
        }
      }
    ],
    "pagination": {
      "total": 45,
      "page": 1,
      "pages": 3
    }
  }
}

Get Agent Details

Endpoint: GET /api/agents/{id}

Response:

{
  "success": true,
  "data": {
    "id": "agt_123",
    "name": "Restaurant Assistant",
    "description": "Full service restaurant agent",
    "status": "active",
    "config": {
      "voice": {
        "provider": "elevenlabs",
        "voice_id": "voice_abc",
        "settings": {
          "stability": 0.75,
          "speed": 1.0
        }
      },
      "conversation": {
        "first_message": "Hello, welcome to...",
        "system_prompt": "You are a helpful...",
        "model": "gpt-4o",
        "temperature": 0.5
      },
      "turn_detection": {
        "mode": "silence",
        "timeout": 7
      }
    },
    "knowledge_base": {
      "items": 23,
      "last_updated": "2025-01-14T12:00:00Z"
    },
    "tools": ["bookAppointment", "checkAvailability"],
    "analytics": {
      "total_calls": 1543,
      "success_rate": 0.92,
      "avg_duration": 180
    }
  }
}

Create Agent

Endpoint: POST /api/agents/create

Request:

{
  "name": "Medical Assistant",
  "description": "Handles patient inquiries",
  "industry": "healthcare",
  "config": {
    "voice": {
      "voice_id": "voice_123",
      "settings": {
        "stability": 0.8,
        "speed": 1.0
      }
    },
    "conversation": {
      "first_message": "Hello, Dr. Smith's office...",
      "system_prompt": "You are a medical receptionist...",
      "model": "claude-3-5-sonnet",
      "temperature": 0.3
    },
    "turn_detection": {
      "mode": "silence",
      "timeout": 7,
      "end_call_on_silence": 60
    },
    "privacy": {
      "retention_days": 30,
      "zero_retention": false,
      "delete_audio": true
    }
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "agt_456",
    "name": "Medical Assistant",
    "status": "training",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Update Agent

Endpoint: PUT /api/agents/{id}/update

Request:

{
  "name": "Updated Assistant Name",
  "config": {
    "conversation": {
      "system_prompt": "Updated prompt...",
      "temperature": 0.4
    }
  }
}

Delete Agent

Endpoint: DELETE /api/agents/{id}

Response:

{
  "success": true,
  "message": "Agent deleted successfully"
}

Agent Chat (Test)

Endpoint: POST /api/agents/{id}/chat

Request:

{
  "message": "What are your hours?",
  "session_id": "sess_123",
  "context": {
    "user_name": "John Doe",
    "location": "Berlin"
  }
}

Response:

{
  "success": true,
  "data": {
    "response": "We're open Monday through Friday from 9 AM to 6 PM...",
    "session_id": "sess_123",
    "tools_used": [],
    "confidence": 0.95
  }
}

📝 Knowledge Base

List Knowledge Base Items

Endpoint: GET /api/knowledge-base/list

Query Parameters:

agent_id: Filter by agent
type: "document" | "url" | "text"

Response:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "kb_123",
        "agent_id": "agt_123",
        "type": "document",
        "name": "Menu.pdf",
        "created_at": "2025-01-10T00:00:00Z"
      }
    ]
  }
}

Add Text Content

Endpoint: POST /api/knowledge-base/text

Request:

{
  "agent_id": "agt_123",
  "title": "Business Hours",
  "content": "We are open Monday-Friday 9am-6pm",
  "category": "general"
}

Add URL Content

Endpoint: POST /api/knowledge-base/url

Request:

{
  "agent_id": "agt_123",
  "url": "https://example.com/about",
  "refresh_interval": 86400
}

Upload Document

Endpoint: POST /api/knowledge-base/file

Request: Multipart form data

agent_id: agt_123
file: [Binary data]
category: policies

Delete Knowledge Item

Endpoint: DELETE /api/knowledge-base/{id}

💬 Conversations

List Conversations

Endpoint: GET /api/conversations/list

Query Parameters:

agent_id: Filter by agent
status: "success" | "failed" | "ongoing"
date_from: ISO date string
date_to: ISO date string
page: Page number
limit: Items per page

Response:

{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "conv_123",
        "agent_id": "agt_123",
        "phone_number": "+49123456789",
        "duration": 180,
        "status": "success",
        "started_at": "2025-01-15T10:00:00Z",
        "ended_at": "2025-01-15T10:03:00Z",
        "sentiment": "positive",
        "summary": "Customer booked appointment"
      }
    ]
  }
}

Get Conversation Details

Endpoint: GET /api/conversations/{id}

Response:

{
  "success": true,
  "data": {
    "id": "conv_123",
    "agent_id": "agt_123",
    "transcript": [
      {
        "speaker": "agent",
        "text": "Hello, how can I help you?",
        "timestamp": "00:00:01"
      },
      {
        "speaker": "user",
        "text": "I'd like to make a reservation",
        "timestamp": "00:00:03"
      }
    ],
    "metadata": {
      "tools_used": ["bookAppointment"],
      "data_collected": {
        "customer_name": "John Doe",
        "appointment_date": "2025-01-20"
      }
    },
    "audio_url": "https://storage.voisa.ai/audio/conv_123.mp3"
  }
}

Get Conversation Audio

Endpoint: GET /api/conversations/{id}/audio

Response: Audio file stream

🛠️ MCP Tools

List MCP Servers

Endpoint: GET /api/mcp-servers

Response:

{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "mcp_123",
        "name": "Calendar Server",
        "url": "https://mcp.example.com",
        "status": "connected",
        "tools_count": 5
      }
    ]
  }
}

Get MCP Server Tools

Endpoint: GET /api/mcp-servers/{id}/tools

Response:

{
  "success": true,
  "data": {
    "tools": [
      {
        "name": "bookAppointment",
        "description": "Books calendar appointments",
        "parameters": {
          "date": "string",
          "time": "string",
          "duration": "integer"
        }
      }
    ]
  }
}

Assign Tools to Agent

Endpoint: POST /api/agents/{id}/assign-tools

Request:

{
  "tools": ["bookAppointment", "checkAvailability"]
}

📊 Analytics

Get Agent Analytics

Endpoint: GET /api/analytics/agent/{id}

Query Parameters:

period: "day" | "week" | "month" | "year"
date_from: ISO date
date_to: ISO date

Response:

{
  "success": true,
  "data": {
    "overview": {
      "total_calls": 1543,
      "success_rate": 0.92,
      "avg_duration": 180,
      "total_duration": 277740
    },
    "timeline": [
      {
        "date": "2025-01-15",
        "calls": 45,
        "success_rate": 0.93
      }
    ],
    "top_intents": [
      {
        "intent": "booking",
        "count": 523,
        "percentage": 0.34
      }
    ],
    "sentiment": {
      "positive": 0.72,
      "neutral": 0.23,
      "negative": 0.05
    }
  }
}

Sentiment Analysis Batch

Endpoint: POST /api/analytics/sentiment-batch

Request:

{
  "texts": [
    "Great service, very helpful!",
    "Could be better",
    "Terrible experience"
  ]
}

Response:

{
  "success": true,
  "data": {
    "results": [
      {"text": "Great service...", "sentiment": "positive", "score": 0.95},
      {"text": "Could be better", "sentiment": "neutral", "score": 0.45},
      {"text": "Terrible...", "sentiment": "negative", "score": 0.15}
    ]
  }
}

📞 Phone Operations

Make Test Call

Endpoint: POST /api/make-call

Request:

{
  "agent_id": "agt_123",
  "phone_number": "+49123456789"
}

Response:

{
  "success": true,
  "data": {
    "call_id": "call_123",
    "status": "initiated"
  }
}

🔧 Voice Management

List Voices

Endpoint: GET /api/voices/list

Response:

{
  "success": true,
  "data": {
    "voices": [
      {
        "id": "voice_123",
        "name": "Professional German Male",
        "language": "de-DE",
        "gender": "male",
        "preview_url": "https://..."
      }
    ]
  }
}

Create Custom Voice

Endpoint: POST /api/voice/create

Request: Multipart form data

name: Custom Voice
audio_samples: [Binary audio files]
description: Professional voice for medical practice

🔄 Webhooks

Webhook Events

Configure webhooks to receive real-time updates:

Available Events:

conversation.started
conversation.ended
conversation.failed
agent.created
agent.updated
tool.executed
tool.failed

Webhook Payload

{
  "event": "conversation.ended",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "conversation_id": "conv_123",
    "agent_id": "agt_123",
    "duration": 180,
    "status": "success"
  }
}

Configure Webhook

Endpoint: POST /api/webhooks

Request:

{
  "url": "https://your-app.com/webhook",
  "events": ["conversation.ended", "tool.executed"],
  "secret": "webhook_secret_key"
}

🚨 Error Codes

HTTP Status Codes

200: Success
201: Created
400: Bad Request
401: Unauthorized
403: Forbidden
404: Not Found
429: Rate Limited
500: Server Error

Error Code Reference

Code	Description	Resolution
`INVALID_API_KEY`	API key invalid or expired	Generate new key
`RATE_LIMIT_EXCEEDED`	Too many requests	Wait and retry
`AGENT_NOT_FOUND`	Agent doesn't exist	Check agent ID
`INSUFFICIENT_PERMISSIONS`	Lacking required permission	Update API key permissions
`INVALID_REQUEST`	Malformed request	Check request format
`RESOURCE_LOCKED`	Resource being modified	Retry later

📝 Code Examples

Node.js

const axios = require('axios');

const voisaAPI = axios.create({
  baseURL: 'https://api.voisa.ai/v1',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

// List agents
async function listAgents() {
  try {
    const response = await voisaAPI.get('/api/agents/list');
    return response.data.data.agents;
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

// Create agent
async function createAgent(agentData) {
  try {
    const response = await voisaAPI.post('/api/agents/create', agentData);
    return response.data.data;
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

Python

import requests

class VoisaAPI:
    def __init__(self, api_key):
        self.base_url = 'https://api.voisa.ai/v1'
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }

    def list_agents(self):
        response = requests.get(
            f'{self.base_url}/api/agents/list',
            headers=self.headers
        )
        return response.json()

    def create_agent(self, agent_data):
        response = requests.post(
            f'{self.base_url}/api/agents/create',
            json=agent_data,
            headers=self.headers
        )
        return response.json()

# Usage
api = VoisaAPI('YOUR_API_KEY')
agents = api.list_agents()

cURL

# List agents
curl -X GET https://api.voisa.ai/v1/api/agents/list \
  -H "Authorization: Bearer YOUR_API_KEY"

# Create agent
curl -X POST https://api.voisa.ai/v1/api/agents/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Agent",
    "description": "Test description",
    "industry": "restaurant"
  }'

🔒 Security Best Practices

API Key Security
- Never expose keys in client-side code
- Use environment variables
- Rotate keys regularly
Request Validation
- Validate all inputs
- Use HTTPS only
- Implement request signing
Rate Limiting
- Implement exponential backoff
- Cache responses when possible
- Use webhooks for real-time updates

📚 Resources

🆘 Support

API Issues: api@voisa.ai
Documentation: docs@voisa.ai
Community: community.voisa.ai

Build powerful integrations with VOISA AI! 🚀