Create agent

Provision a new conversational Voice AI prompt agent or rule-based static bot

POST /api/v1/agents

Python

import requests

url = "https://api.sayvy.ai/api/v1/agents"

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

payload = {
    "name": "Customer Support Concierge",
    "agent_type": "prompt",
    "timezone": "America/New_York",
    "agent_config": {
        "welcome_message": "Hello! Thank you for calling Sayvy AI support. How can I assist you today?",
        "system_prompt": "You are a professional customer support specialist for Sayvy AI. Answer inquiries politely and concisely.",
        "language": "en-US",
        "llm_provider": "openai",
        "llm_model": "gpt-4o-mini",
        "voice_settings": {
            "voice_id": "79a125e8-cd45-4c13-8a67-188112f4dd22",
            "name": "British Friendly Male",
            "provider": "cartesia"
        }
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.status_code)
print(response.json())

201 Created

{
  "id": "e4b2d184-7cf1-4560-a292-6284649bcf2e",
  "name": "Customer Support Concierge",
  "organization_id": "93f35dc2-5d46-4e58-a9ee-038c35d9bcf1",
  "timezone": "America/New_York",
  "agent_type": "prompt",
  "is_active": "active",
  "created_at": "2026-09-03T12:00:00Z",
  "updated_at": "2026-09-03T12:00:00Z"
}

Create a new Voice AI agent under your organization with customized voice synthesis, LLM parameters, system instructions, and real-time tool bindings.

---

Authentication

This endpoint requires Bearer token authentication.

Authorization: Bearer <token>

---

Input parameters

The following parameters are accepted in the request body.

Authorization · string · required

Bearer token for authentication. Format: Bearer <token>.

name · string · required

Descriptive name of the voice agent (e.g. Inbound Support Specialist).

agent_type · string · default: "prompt"

Architecture pattern of the agent:

• prompt: Autonomous LLM-driven voice agent.
• static: Deterministic rule-based decision bot.

timezone · string

Operational timezone for calendar and campaign calculations (e.g. America/New_York, UTC).

agent_config · object

Detailed runtime configurations and tool integrations:

Show agent_config attributes

welcome_message · string

Initial greeting spoken immediately as soon as the recipient answers.

system_prompt · string

Core directive and instructions establishing the agent’s persona and constraints.

language · string · default: "en-US"

Primary spoken language tag.

llm_provider · string · default: "openai"

Model hosting provider (openai, anthropic, groq).

llm_model · string · default: "gpt-4o-mini"

LLM model identifier (gpt-4o, gpt-4o-mini, claude-3-5-sonnet).

voice_settings · object

Voice synthesis engine parameters:

Show voice_settings

voice_id · string · required

Voice identifier from Cartesia or ElevenLabs.

name · string · required

Descriptive name of the voice.

provider · string · default: "cartesia"

TTS provider (cartesia, elevenlabs).

booking_config · object

Automated appointment scheduling settings:

Show booking_config

booking_enabled · boolean · default: "false"

Enable calendar slot queries and appointment creation.

provider · string · default: "google_calendar"

Calendar provider (google_calendar, calendly).

prompt · string

Instructions guiding the agent on when to initiate booking.

custom_tools · object[]

Array of dynamic REST API tools the agent can execute mid-call.

mcp_tools · object[]

Array of Model Context Protocol (MCP) server configurations.

---

Response Fields

id · string

Generated unique UUID identifier for the created agent.

name · string

Agent display name.

organization_id · string

UUID of the owning organization.

agent_type · string

Configured agent type (prompt or static).

is_active · string

Initial operational status (active or inactive).

created_at · string

Timestamp of creation in ISO 8601 format.

---

Python

import requests

url = "https://api.sayvy.ai/api/v1/agents"

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

payload = {
    "name": "Customer Support Concierge",
    "agent_type": "prompt",
    "timezone": "America/New_York",
    "agent_config": {
        "welcome_message": "Hello! Thank you for calling Sayvy AI support. How can I assist you today?",
        "system_prompt": "You are a professional customer support specialist for Sayvy AI. Answer inquiries politely and concisely.",
        "language": "en-US",
        "llm_provider": "openai",
        "llm_model": "gpt-4o-mini",
        "voice_settings": {
            "voice_id": "79a125e8-cd45-4c13-8a67-188112f4dd22",
            "name": "British Friendly Male",
            "provider": "cartesia"
        }
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.status_code)
print(response.json())

201 Created

{
  "id": "e4b2d184-7cf1-4560-a292-6284649bcf2e",
  "name": "Customer Support Concierge",
  "organization_id": "93f35dc2-5d46-4e58-a9ee-038c35d9bcf1",
  "timezone": "America/New_York",
  "agent_type": "prompt",
  "is_active": "active",
  "created_at": "2026-09-03T12:00:00Z",
  "updated_at": "2026-09-03T12:00:00Z"
}

---

‹ Previous

List agents

Retrieve all Voice AI agents for organization

Next ›