> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sayvyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create agent

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

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.

```http theme={null}
Authorization: Bearer <token>
```

***

### Input parameters

The following parameters are accepted in the request body.

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer <token>`.
</ParamField>

<ParamField body="name" type="string" required>
  Descriptive name of the voice agent (e.g. `Inbound Support Specialist`).
</ParamField>

<ParamField body="agent_type" type="string" default="prompt">
  Architecture pattern of the agent:

  * `prompt`: Autonomous LLM-driven voice agent.
  * `static`: Deterministic rule-based decision bot.
</ParamField>

<ParamField body="timezone" type="string">
  Operational timezone for calendar and campaign calculations (e.g. `America/New_York`, `UTC`).
</ParamField>

<ParamField body="agent_config" type="object">
  Detailed runtime configurations and tool integrations:

  <Expandable title="agent_config attributes">
    <ParamField body="welcome_message" type="string">
      Initial greeting spoken immediately as soon as the recipient answers.
    </ParamField>

    <ParamField body="system_prompt" type="string">
      Core directive and instructions establishing the agent's persona and constraints.
    </ParamField>

    <ParamField body="language" type="string" default="en-US">
      Primary spoken language tag.
    </ParamField>

    <ParamField body="llm_provider" type="string" default="openai">
      Model hosting provider (`openai`, `anthropic`, `groq`).
    </ParamField>

    <ParamField body="llm_model" type="string" default="gpt-4o-mini">
      LLM model identifier (`gpt-4o`, `gpt-4o-mini`, `claude-3-5-sonnet`).
    </ParamField>

    <ParamField body="voice_settings" type="object">
      Voice synthesis engine parameters:

      <Expandable title="voice_settings">
        <ParamField body="voice_id" type="string" required>
          Voice identifier from Cartesia or ElevenLabs.
        </ParamField>

        <ParamField body="name" type="string" required>
          Descriptive name of the voice.
        </ParamField>

        <ParamField body="provider" type="string" default="cartesia">
          TTS provider (`cartesia`, `elevenlabs`).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="booking_config" type="object">
      Automated appointment scheduling settings:

      <Expandable title="booking_config">
        <ParamField body="booking_enabled" type="boolean" default="false">
          Enable calendar slot queries and appointment creation.
        </ParamField>

        <ParamField body="provider" type="string" default="google_calendar">
          Calendar provider (`google_calendar`, `calendly`).
        </ParamField>

        <ParamField body="prompt" type="string">
          Instructions guiding the agent on when to initiate booking.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="custom_tools" type="object[]">
      Array of dynamic REST API tools the agent can execute mid-call.
    </ParamField>

    <ParamField body="mcp_tools" type="object[]">
      Array of Model Context Protocol (MCP) server configurations.
    </ParamField>
  </Expandable>
</ParamField>

***

### Response Fields

<ResponseField name="id" type="string">
  Generated unique UUID identifier for the created agent.
</ResponseField>

<ResponseField name="name" type="string">
  Agent display name.
</ResponseField>

<ResponseField name="organization_id" type="string">
  UUID of the owning organization.
</ResponseField>

<ResponseField name="agent_type" type="string">
  Configured agent type (`prompt` or `static`).
</ResponseField>

<ResponseField name="is_active" type="string">
  Initial operational status (`active` or `inactive`).
</ResponseField>

<ResponseField name="created_at" type="string">
  Timestamp of creation in ISO 8601 format.
</ResponseField>

***

<RequestExample>
  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.sayvy.ai/api/v1/agents", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      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"
        }
      }
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```java Java theme={null}
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.sayvy.ai/api/v1/agents"))
      .header("Authorization", "Bearer <token>")
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString("""
          {
            "name": "Customer Support Concierge",
            "agent_type": "prompt",
            "agent_config": {
              "welcome_message": "Hello! Thank you for calling Sayvy AI.",
              "language": "en-US",
              "llm_model": "gpt-4o-mini"
            }
          }
          """))
      .build();

  HttpResponse<String> response =
      HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.sayvy.ai/api/v1/agents" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Customer Support Concierge",
      "agent_type": "prompt",
      "timezone": "America/New_York",
      "agent_config": {
        "welcome_message": "Hello! Thank you for calling Sayvy AI support.",
        "language": "en-US",
        "llm_model": "gpt-4o-mini"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "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"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": 400,
    "message": "Validation error: agent 'name' is required and must not be empty"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": 401,
    "message": "Unauthorized"
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "error": 500,
    "message": "Internal server error"
  }
  ```
</ResponseExample>

***

<div
  style={{
display: "flex",
alignItems: "center",
justifyContent: "space-between",
backgroundColor: "rgba(255, 255, 255, 0.03)",
border: "1px solid rgba(255, 255, 255, 0.08)",
borderRadius: "16px",
padding: "10px 18px",
marginTop: "40px",
gap: "16px",
flexWrap: "wrap"
}}
>
  <a
    href="/api-reference/agents/get-agent"
    style={{
display: "inline-flex",
alignItems: "center",
gap: "6px",
color: "#94A3B8",
textDecoration: "none",
fontSize: "14px",
fontWeight: "500",
padding: "4px 8px"
}}
  >
    <span style={{ fontSize: "16px" }}>‹</span> Previous
  </a>

  <div
    style={{
display: "flex",
alignItems: "center",
gap: "16px",
backgroundColor: "rgba(255, 255, 255, 0.04)",
border: "1px solid rgba(255, 255, 255, 0.06)",
borderRadius: "12px",
padding: "8px 16px",
marginLeft: "auto"
}}
  >
    <div style={{ textAlign: "right" }}>
      <div style={{ fontSize: "13px", fontWeight: "700", color: "#F8FAFC" }}>List agents</div>

      <div style={{ fontSize: "11px", color: "#94A3B8", maxWidth: "260px", overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
        Retrieve all Voice AI agents for organization
      </div>
    </div>

    <div style={{ width: "1px", height: "24px", backgroundColor: "rgba(255, 255, 255, 0.1)" }} />

    <a
      href="/api-reference/agents/list-agents"
      style={{
  display: "inline-flex",
  alignItems: "center",
  gap: "6px",
  color: "#94A3B8",
  textDecoration: "none",
  fontSize: "14px",
  fontWeight: "500"
}}
    >
      Next <span style={{ fontSize: "16px" }}>›</span>
    </a>
  </div>
</div>