Create Agent

curl -X POST https://api.voicy.co/functions/v1/agent-create \
  -H "Authorization: Bearer voicy_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment Booker",
    "language": "he",
    "prompt": "You are a friendly receptionist that books appointments.",
    "voice": "Ori",
    "welcome_message": "שלום, איך אפשר לעזור?",
    "variables_provided": [{ "name": "customer_name", "description": "The caller'\''s name" }],
    "variables_extracted": [{ "name": "appointment_date", "description": "The date the caller chose", "required": true }]
  }'

const agent = await (await fetch('https://api.voicy.co/functions/v1/agent-create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer voicy_sk_live_xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Appointment Booker',
    language: 'he',
    prompt: 'You are a friendly receptionist that books appointments.',
    voice: 'Ori',
    welcome_message: 'שלום, איך אפשר לעזור?',
  }),
})).json();

import requests
agent = requests.post(
    'https://api.voicy.co/functions/v1/agent-create',
    headers={'Authorization': 'Bearer voicy_sk_live_xxx'},
    json={
        'name': 'Appointment Booker',
        'language': 'he',
        'prompt': 'You are a friendly receptionist that books appointments.',
        'voice': 'Ori',
        'welcome_message': 'שלום, איך אפשר לעזור?',
    },
).json()

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Appointment Booker",
  "language": "he",
  "voice": "Ori",
  "agent_type": "singlePrompt",
  "active": true,
  "prompt": "You are a friendly receptionist that books appointments.",
  "welcome_message": "שלום, איך אפשר לעזור?",
  "variables_provided": [
    { "name": "customer_name", "description": "The caller's name" }
  ],
  "variables_extracted": [
    { "name": "appointment_date", "description": "The date the caller chose" }
  ],
  "created_at": "2026-06-06T10:00:00Z",
  "updated_at": "2026-06-06T10:00:00Z"
}

{
  "status": "error",
  "message": "Invalid voice \"Bob\". Valid voices: Sapir, Steve, Ori, Yael, Guy, Gefen, Gal, Gabriel"
}

POST

agent-create

curl -X POST https://api.voicy.co/functions/v1/agent-create \
  -H "Authorization: Bearer voicy_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment Booker",
    "language": "he",
    "prompt": "You are a friendly receptionist that books appointments.",
    "voice": "Ori",
    "welcome_message": "שלום, איך אפשר לעזור?",
    "variables_provided": [{ "name": "customer_name", "description": "The caller'\''s name" }],
    "variables_extracted": [{ "name": "appointment_date", "description": "The date the caller chose", "required": true }]
  }'

const agent = await (await fetch('https://api.voicy.co/functions/v1/agent-create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer voicy_sk_live_xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Appointment Booker',
    language: 'he',
    prompt: 'You are a friendly receptionist that books appointments.',
    voice: 'Ori',
    welcome_message: 'שלום, איך אפשר לעזור?',
  }),
})).json();

import requests
agent = requests.post(
    'https://api.voicy.co/functions/v1/agent-create',
    headers={'Authorization': 'Bearer voicy_sk_live_xxx'},
    json={
        'name': 'Appointment Booker',
        'language': 'he',
        'prompt': 'You are a friendly receptionist that books appointments.',
        'voice': 'Ori',
        'welcome_message': 'שלום, איך אפשר לעזור?',
    },
).json()

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Appointment Booker",
  "language": "he",
  "voice": "Ori",
  "agent_type": "singlePrompt",
  "active": true,
  "prompt": "You are a friendly receptionist that books appointments.",
  "welcome_message": "שלום, איך אפשר לעזור?",
  "variables_provided": [
    { "name": "customer_name", "description": "The caller's name" }
  ],
  "variables_extracted": [
    { "name": "appointment_date", "description": "The date the caller chose" }
  ],
  "created_at": "2026-06-06T10:00:00Z",
  "updated_at": "2026-06-06T10:00:00Z"
}

{
  "status": "error",
  "message": "Invalid voice \"Bob\". Valid voices: Sapir, Steve, Ori, Yael, Guy, Gefen, Gal, Gabriel"
}

Creates a prompt-based voice agent and deploys it immediately — the returned agent_id can be used right away as override_agent_id on Dial.

Only prompt-based agents can be created via the API. Flow agents (multi-step conversational flows with branching, function calls, and knowledge bases) are built in the dashboard.

Body Parameters

string

required

Agent display name.

string

required

System prompt that defines the agent’s behavior.

string

default:"he"

Language code, e.g. he or en.

string

default:"Ori"

Voice display name. One of Sapir, Steve, Ori, Yael, Guy, Gefen, Gal, Gabriel.

string

Message the agent speaks first when it answers. When empty, the agent opens the conversation from the prompt.

array

Variables to supply at call time (via vars_provided on Dial).

Show Variable properties

string

required

Variable name.

string

Human-readable description.

string

Default value if not supplied at call time.

array

Variables the agent should extract from the conversation after the call.

Show Variable properties

string

required

Variable name.

string

Human-readable description.

boolean

Whether extraction is required.

Response

The created Agent object.

curl -X POST https://api.voicy.co/functions/v1/agent-create \
  -H "Authorization: Bearer voicy_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment Booker",
    "language": "he",
    "prompt": "You are a friendly receptionist that books appointments.",
    "voice": "Ori",
    "welcome_message": "שלום, איך אפשר לעזור?",
    "variables_provided": [{ "name": "customer_name", "description": "The caller'\''s name" }],
    "variables_extracted": [{ "name": "appointment_date", "description": "The date the caller chose", "required": true }]
  }'

const agent = await (await fetch('https://api.voicy.co/functions/v1/agent-create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer voicy_sk_live_xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Appointment Booker',
    language: 'he',
    prompt: 'You are a friendly receptionist that books appointments.',
    voice: 'Ori',
    welcome_message: 'שלום, איך אפשר לעזור?',
  }),
})).json();

import requests
agent = requests.post(
    'https://api.voicy.co/functions/v1/agent-create',
    headers={'Authorization': 'Bearer voicy_sk_live_xxx'},
    json={
        'name': 'Appointment Booker',
        'language': 'he',
        'prompt': 'You are a friendly receptionist that books appointments.',
        'voice': 'Ori',
        'welcome_message': 'שלום, איך אפשר לעזור?',
    },
).json()

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Appointment Booker",
  "language": "he",
  "voice": "Ori",
  "agent_type": "singlePrompt",
  "active": true,
  "prompt": "You are a friendly receptionist that books appointments.",
  "welcome_message": "שלום, איך אפשר לעזור?",
  "variables_provided": [
    { "name": "customer_name", "description": "The caller's name" }
  ],
  "variables_extracted": [
    { "name": "appointment_date", "description": "The date the caller chose" }
  ],
  "created_at": "2026-06-06T10:00:00Z",
  "updated_at": "2026-06-06T10:00:00Z"
}

{
  "status": "error",
  "message": "Invalid voice \"Bob\". Valid voices: Sapir, Steve, Ori, Yael, Guy, Gefen, Gal, Gabriel"
}

Overview

Models

Calls

Agents

Body Parameters

Response

​Body Parameters

​Response

Body Parameters

Response