Create Agent

Creates a new AI voice agent with specified configuration.

Endpoint

POST https://api.ayra.ai/v1/agents

Authentication

Requires API key with agents:write permission.

Request Parameters

Required Parameters:

Optional Parameters:

Request Examples

cURL Example:

curl -X POST https://api.ayra.ai/v1/agents \
  -H "Authorization: Bearer sk_live_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "voice_platform": "vapi",
    "voice_id": "voice_professional_female_1",
    "language": "en",
    "system_prompt": "You are a helpful customer support agent for Acme Corporation. You help customers with order inquiries, shipping questions, and general product information. Be friendly, professional, and concise. If you cannot answer a question, offer to transfer to a human agent.",
    "welcome_message": "Thank you for calling Acme Corporation. How can I help you today?",
    "transfer_number": "+15559876543",
    "business_hours": {
      "timezone": "America/New_York",
      "schedule": [
        { "day": "monday", "open": "09:00", "close": "17:00" },
        { "day": "tuesday", "open": "09:00", "close": "17:00" },
        { "day": "wednesday", "open": "09:00", "close": "17:00" },
        { "day": "thursday", "open": "09:00", "close": "17:00" },
        { "day": "friday", "open": "09:00", "close": "17:00" }
      ]
    },
    "recording_enabled": true,
    "transcription_enabled": true,
    "metadata": {
      "client_id": "client_789",
      "department": "support",
      "version": "1.0"
    }
  }'

JavaScript Example:

const axios = require('axios');

async function createAgent() {
  try {
    const response = await axios.post('https://api.ayra.ai/v1/agents', {
      name: 'Customer Support Agent',
      voice_platform: 'vapi',
      voice_id: 'voice_professional_female_1',
      language: 'en',
      system_prompt: 'You are a helpful customer support agent...',
      welcome_message: 'Thank you for calling Acme Corporation. How can I help you today?',
      transfer_number: '+15559876543',
      recording_enabled: true,
      transcription_enabled: true,
      metadata: {
        client_id: 'client_789',
        department: 'support'
      }
    }, {
      headers: {
        'Authorization': 'Bearer sk_live_abc123xyz789',
        'Content-Type': 'application/json'
      }
    });
    
    console.log('Agent created:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error creating agent:', error.response.data);
    throw error;
  }
}

createAgent();

Python Example:

import requests

def create_agent():
    url = 'https://api.ayra.ai/v1/agents'
    headers = {
        'Authorization': 'Bearer sk_live_abc123xyz789',
        'Content-Type': 'application/json'
    }
    
    data = {
        'name': 'Customer Support Agent',
        'voice_platform': 'vapi',
        'voice_id': 'voice_professional_female_1',
        'language': 'en',
        'system_prompt': 'You are a helpful customer support agent...',
        'welcome_message': 'Thank you for calling Acme Corporation. How can I help you today?',
        'transfer_number': '+15559876543',
        'recording_enabled': True,
        'transcription_enabled': True,
        'metadata': {
            'client_id': 'client_789',
            'department': 'support'
        }
    }
    
    response = requests.post(url, json=data, headers=headers)
    
    if response.status_code == 201:
        print('Agent created:', response.json())
        return response.json()
    else:
        print('Error:', response.json())
        raise Exception(f'Failed to create agent: {response.status_code}')

create_agent()

Response

Success Response (201 Created):

{
  "data": {
    "id": "agent_abc123xyz789",
    "name": "Customer Support Agent",
    "phone_number": "+15551234567",
    "voice_platform": "vapi",
    "voice_id": "voice_professional_female_1",
    "language": "en",
    "system_prompt": "You are a helpful customer support agent for Acme Corporation...",
    "welcome_message": "Thank you for calling Acme Corporation. How can I help you today?",
    "transfer_number": "+15559876543",
    "business_hours": {
      "timezone": "America/New_York",
      "schedule": [
        { "day": "monday", "open": "09:00", "close": "17:00" },
        { "day": "tuesday", "open": "09:00", "close": "17:00" },
        { "day": "wednesday", "open": "09:00", "close": "17:00" },
        { "day": "thursday", "open": "09:00", "close": "17:00" },
        { "day": "friday", "open": "09:00", "close": "17:00" }
      ]
    },
    "recording_enabled": true,
    "transcription_enabled": true,
    "status": "active",
    "metadata": {
      "client_id": "client_789",
      "department": "support",
      "version": "1.0"
    },
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_create_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Error Responses

{
  "error": {
    "type": "invalid_request",
    "message": "The 'name' field is required",
    "code": "missing_required_field",
    "field": "name"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "Invalid voice_platform. Must be 'vapi' or 'retell'",
    "code": "invalid_parameter",
    "field": "voice_platform"
  }
}

{
  "error": {
    "type": "validation_error",
    "message": "An agent with this name already exists",
    "code": "duplicate_name",
    "field": "name"
  }
}

{
  "error": {
    "type": "permission_error",
    "message": "Agent limit exceeded for your plan. Upgrade to create more agents.",
    "code": "quota_exceeded",
    "limit": 5,
    "current": 5
  }
}

Notes

• • Agent creation is typically fast (under 1 second) but phone number provisioning may take a few seconds if auto-provisioning is used
• • The agent_id returned should be stored for future agent management operations
• • Agents are created in active status by default and immediately begin answering calls to their assigned phone number
• • Voice platform integration must be configured in your account before creating agents for that platform
• • System prompts are critical for agent behavior - invest time in crafting effective prompts