Agents

Create an agent

POSThttps://voxa.abhinavyadav.in/api/v1/agents

Only name is required; every other setting has a sensible default. {variables} in the welcome message or prompt are filled from user_data when a call is placed.

The agent may only use providers your workspace can use (see List providers); anything else returns 422. Creating an agent also records version 1.

Authorization

An API key (X-API-Key or Authorization: Bearer), or a signed-in member with the agents.edit permission.

X-API-KeyAuthorization: Beareragents.edit

Query parameters

timezonestringdefault: "Asia/Kolkata"

IANA time zone for every timestamp in the response (at, date, timestamp and *_at fields), as ISO 8601 with the offset. The X-Timezone header works too; the zone used comes back in the X-Timezone response header. An unknown zone is a 400.

Body application/json

namestringrequired

Shown in the console and on calls.

1 to 120 characters

welcome_messagestring

The first thing the agent says. May use {variables}.

system_promptstring

How the agent behaves: role, tone, what it may do. May use {variables} filled from user_data.

llmobject

The language model.

Show child attributes

providerstringdefault: "gemini"

modelstringdefault: "gemini-3.5-flash-lite"

An id from Get the catalog (llm_models).

temperaturenumberdefault: 0.4

Higher is more varied, lower is more predictable.

0 to 2

max_tokensintegerdefault: 300

The longest reply, in tokens.

16 to 4096

voiceobject

Text to speech.

Show child attributes

providerstringdefault: "cartesia"

modelstringdefault: "sonic-3.6"

A text-to-speech model from the catalog (tts_models).

voice_idstring

A voice from List voices.

voice_namestring

The voice's name, for display.

languagestringdefault: "hi"

The language the agent speaks.

speednumberdefault: 1

Speaking rate; 1 is normal.

0.6 to 1.5

transcriberobject

Speech to text.

Show child attributes

providerenum<string>default: "cartesia"

cartesia (ink-2, detects language and end of turn) or deepgram (nova-3).

One of:cartesiadeepgram

modelstringdefault: "ink-2"

Set to match the provider automatically.

turn_detectionenum<string>default: "balanced"

Cartesia: how quickly the agent answers once the caller pauses.

One of:responsivebalancedpatient

languagestringdefault: "hi"

Deepgram only: the caller's language.

endpointing_msintegerdefault: 300

Deepgram only: silence that ends a turn.

10 to 3000

keytermsstring[]

Words the recogniser should expect, such as doctor or product names.

at most 100 items

callobject

Call length, silence, interruptions, calling hours and recording.

Show child attributes

max_duration_secondsintegerdefault: 600

The call ends after this long.

30 to 3600

hangup_after_silence_secondsintegerdefault: 15

The call ends after this much silence from the caller.

5 to 120

allow_interruptionsbooleandefault: true

The caller can talk over the agent, which stops speaking.

interruption_min_wordsintegerdefault: 2

Words the caller must say to interrupt.

1 to 10

call_start_hourintegerdefault: 9

Outbound calls start no earlier than this hour (in timezone).

0 to 23

call_end_hourintegerdefault: 21

Outbound calls start before this hour (in timezone).

1 to 24

timezonestringdefault: "Asia/Kolkata"

IANA time zone for the calling hours.

recordbooleandefault: true

Keep a stereo recording of the call.

hangup_messagestring

Said before the agent hangs up when the conversation is over.

hangup_on_promptbooleandefault: false

After each reply, ask the model (with hangup_prompt) whether the conversation is over.

hangup_promptstring

The question for hangup_on_prompt; it must answer Yes or No.

at most 4000 characters

hangup_interruptiblebooleandefault: false

check_user_onlinebooleandefault: false

When the caller goes quiet, ask once whether they're still there.

user_online_messagestringdefault: "Are you still there?"

What to ask.

user_online_after_secondsintegerdefault: 9

Silence before asking.

3 to 60

analyticsobject

Post-call analysis, saved on the call and sent in call.completed.

Show child attributes

summarizebooleandefault: false

Write a short summary of the call.

extractionsobject[]

at most 50 items

Show item attributes

keystringrequired

the JSON key, e.g. lead_status

matches ^[a-z][a-z0-9_]{0,39}$

labelstring

at most 80 characters

typeenum<string>default: "text"

One of:textnumberbooleanchoicedatelist

descriptionstring

what to extract and how

at most 600 characters

choicesobject[]

at most 20 items

Show item attributes

valuestringrequired

1 to 60 characters

whenstring

at most 300 characters

extraction_promptstring

What to pull out of the transcript, in plain words; saved as JSON in extracted.

at most 4000 characters

toolsobject[]

HTTP tools the agent can call mid-conversation. Names are unique; end_call is built in.

Show item attributes

namestringrequired

The function name the model calls: letters, digits and _.

matches ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$

descriptionstringrequired

When the model should use the tool.

3 to 1000 characters

parametersobject

JSON Schema of the arguments the model fills in.

methodenum<string>default: "POST"

GET sends the arguments as query parameters, POST as a JSON body.

One of:GETPOST

urlstringrequired

Where the request goes.

headersobject

Extra request headers, such as an authorization header.

pre_call_messagestring

Said while the request runs.

timeout_secondsnumberdefault: 8

The request is abandoned after this long.

1 to 30

knowledge_base_idsstring[]

at most 10 items

webhook_urlstring

Also receives this agent's call events, signed with the workspace's default secret.

phone_numberstring

The number (E.164) that answers inbound calls with this agent, and its default caller ID.

statusenum<string>default: "active"

paused agents don't take calls.

One of:activepaused

Response

201Success.

namestring

1 to 120 characters

welcome_messagestring

system_promptstring

llmobject

Show child attributes

providerstringdefault: "gemini"

modelstringdefault: "gemini-3.5-flash-lite"

An id from Get the catalog (llm_models).

temperaturenumberdefault: 0.4

Higher is more varied, lower is more predictable.

0 to 2

max_tokensintegerdefault: 300

The longest reply, in tokens.

16 to 4096

voiceobject

Text to speech.

Show child attributes

providerstringdefault: "cartesia"

modelstringdefault: "sonic-3.6"

A text-to-speech model from the catalog (tts_models).

voice_idstring

A voice from List voices.

voice_namestring

The voice's name, for display.

languagestringdefault: "hi"

The language the agent speaks.

speednumberdefault: 1

Speaking rate; 1 is normal.

0.6 to 1.5

transcriberobject

Speech to text.

Show child attributes

providerenum<string>default: "cartesia"

cartesia (ink-2, detects language and end of turn) or deepgram (nova-3).

One of:cartesiadeepgram

modelstringdefault: "ink-2"

Set to match the provider automatically.

turn_detectionenum<string>default: "balanced"

Cartesia: how quickly the agent answers once the caller pauses.

One of:responsivebalancedpatient

languagestringdefault: "hi"

Deepgram only: the caller's language.

endpointing_msintegerdefault: 300

Deepgram only: silence that ends a turn.

10 to 3000

keytermsstring[]

Words the recogniser should expect, such as doctor or product names.

at most 100 items

callobject

Show child attributes

max_duration_secondsintegerdefault: 600

The call ends after this long.

30 to 3600

hangup_after_silence_secondsintegerdefault: 15

The call ends after this much silence from the caller.

5 to 120

allow_interruptionsbooleandefault: true

The caller can talk over the agent, which stops speaking.

interruption_min_wordsintegerdefault: 2

Words the caller must say to interrupt.

1 to 10

call_start_hourintegerdefault: 9

Outbound calls start no earlier than this hour (in timezone).

0 to 23

call_end_hourintegerdefault: 21

Outbound calls start before this hour (in timezone).

1 to 24

timezonestringdefault: "Asia/Kolkata"

IANA time zone for the calling hours.

recordbooleandefault: true

Keep a stereo recording of the call.

hangup_messagestring

Said before the agent hangs up when the conversation is over.

hangup_on_promptbooleandefault: false

After each reply, ask the model (with hangup_prompt) whether the conversation is over.

hangup_promptstring

The question for hangup_on_prompt; it must answer Yes or No.

at most 4000 characters

hangup_interruptiblebooleandefault: false

check_user_onlinebooleandefault: false

When the caller goes quiet, ask once whether they're still there.

user_online_messagestringdefault: "Are you still there?"

What to ask.

user_online_after_secondsintegerdefault: 9

Silence before asking.

3 to 60

analyticsobject

Run once the call ends; the results are saved on the call and sent in call.completed.

Show child attributes

summarizebooleandefault: false

Write a short summary of the call.

extractionsobject[]

at most 50 items

Show item attributes

keystring

the JSON key, e.g. lead_status

matches ^[a-z][a-z0-9_]{0,39}$

labelstring

at most 80 characters

typeenum<string>default: "text"

One of:textnumberbooleanchoicedatelist

descriptionstring

what to extract and how

at most 600 characters

choicesobject[]

at most 20 items

Show item attributes

valuestring

1 to 60 characters

whenstring

at most 300 characters

extraction_promptstring

What to pull out of the transcript, in plain words; saved as JSON in extracted.

at most 4000 characters

toolsobject[]

Show item attributes

namestring

The function name the model calls: letters, digits and _.

matches ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$

descriptionstring

When the model should use the tool.

3 to 1000 characters

parametersobject

JSON Schema of the arguments the model fills in.

methodenum<string>default: "POST"

GET sends the arguments as query parameters, POST as a JSON body.

One of:GETPOST

urlstring

Where the request goes.

headersobject

Extra request headers, such as an authorization header.

pre_call_messagestring

Said while the request runs.

timeout_secondsnumberdefault: 8

The request is abandoned after this long.

1 to 30

knowledge_base_idsstring[]

at most 10 items

webhook_urlstring

phone_numberstring

statusenum<string>default: "active"

One of:activepaused

idstring

The agent's id.

versionintegerdefault: 1

Increases with every saved change.

updated_bystring

Who made the last change.

created_atstring

date-time

updated_atstring

date-time

variablesstring[]

Every {variable} the welcome message and prompt use, in order.

401No credentials, or they are invalid or revoked.

detailstring

What went wrong, in plain words.

403Your role (or an API key) lacks the permission.

detailstring

What went wrong, in plain words.

422Validation Error

detailobject[]

Show item attributes

locstring | integer[]

msgstring

typestring

429Over the per-key rate limit; wait for Retry-After.

detailstring

What went wrong, in plain words.

curl --request POST \
  --url 'https://voxa.abhinavyadav.in/api/v1/agents?timezone=Asia/Kolkata' \
  --header 'X-API-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Front desk",
  "welcome_message": "Hello {caller_name}, thanks for calling City Clinic. How can I help?",
  "system_prompt": "You are the receptionist of City Clinic. Help the caller book a visit. Keep replies short.",
  "llm": {
    "model": "gemini-3.5-flash-lite",
    "temperature": 0.4,
    "max_tokens": 300
  },
  "voice": {
    "voice_id": "",
    "language": "en",
    "speed": 1
  },
  "transcriber": {
    "provider": "cartesia",
    "turn_detection": "balanced"
  },
  "call": {
    "max_duration_seconds": 600,
    "call_start_hour": 9,
    "call_end_hour": 21,
    "timezone": "Asia/Kolkata",
    "record": true
  },
  "analytics": {
    "summarize": true,
    "extraction_prompt": "The date and time the caller wants to visit"
  },
  "tools": [
    {
      "name": "check_availability",
      "description": "Free appointment slots for a date",
      "method": "POST",
      "url": "https://example.com/slots",
      "parameters": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string"
          }
        },
        "required": [
          "date"
        ]
      }
    }
  ],
  "status": "active"
}'

import requests

url = "https://voxa.abhinavyadav.in/api/v1/agents"
params = {
    "timezone": "Asia/Kolkata",
}
headers = {
    "X-API-Key": "<api-key>",
}
payload = {
    "name": "Front desk",
    "welcome_message": "Hello {caller_name}, thanks for calling City Clinic. How can I help?",
    "system_prompt": "You are the receptionist of City Clinic. Help the caller book a visit. Keep replies short.",
    "llm": {
        "model": "gemini-3.5-flash-lite",
        "temperature": 0.4,
        "max_tokens": 300,
    },
    "voice": {
        "voice_id": "",
        "language": "en",
        "speed": 1,
    },
    "transcriber": {
        "provider": "cartesia",
        "turn_detection": "balanced",
    },
    "call": {
        "max_duration_seconds": 600,
        "call_start_hour": 9,
        "call_end_hour": 21,
        "timezone": "Asia/Kolkata",
        "record": True,
    },
    "analytics": {
        "summarize": True,
        "extraction_prompt": "The date and time the caller wants to visit",
    },
    "tools": [
        {
            "name": "check_availability",
            "description": "Free appointment slots for a date",
            "method": "POST",
            "url": "https://example.com/slots",
            "parameters": {
                "type": "object",
                "properties": {
                    "date": {
                        "type": "string",
                    },
                },
                "required": [
                    "date",
                ],
            },
        },
    ],
    "status": "active",
}

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

const response = await fetch("https://voxa.abhinavyadav.in/api/v1/agents?timezone=Asia/Kolkata", {
  method: "POST",
  headers: {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Front desk",
    "welcome_message": "Hello {caller_name}, thanks for calling City Clinic. How can I help?",
    "system_prompt": "You are the receptionist of City Clinic. Help the caller book a visit. Keep replies short.",
    "llm": {
      "model": "gemini-3.5-flash-lite",
      "temperature": 0.4,
      "max_tokens": 300
    },
    "voice": {
      "voice_id": "",
      "language": "en",
      "speed": 1
    },
    "transcriber": {
      "provider": "cartesia",
      "turn_detection": "balanced"
    },
    "call": {
      "max_duration_seconds": 600,
      "call_start_hour": 9,
      "call_end_hour": 21,
      "timezone": "Asia/Kolkata",
      "record": true
    },
    "analytics": {
      "summarize": true,
      "extraction_prompt": "The date and time the caller wants to visit"
    },
    "tools": [
      {
        "name": "check_availability",
        "description": "Free appointment slots for a date",
        "method": "POST",
        "url": "https://example.com/slots",
        "parameters": {
          "type": "object",
          "properties": {
            "date": {
              "type": "string"
            }
          },
          "required": [
            "date"
          ]
        }
      }
    ],
    "status": "active"
  }),
})
const data = await response.json()
console.log(response.status, data)

Try it

POST/api/v1/agents

Base URL

Authorization

Kept in this browser tab only (sessionStorage), never in the code samples.

Query parameters

timezonestring

Body application/json

{
  "name": "Front desk",
  "welcome_message": "Hello {caller_name}, thanks for calling City Clinic. How can I help?",
  "system_prompt": "You are the receptionist of City Clinic. Help the caller book a visit. Keep replies short.",
  "llm": {
    "model": "gemini-3.5-flash-lite",
    "temperature": 0.4,
    "max_tokens": 300
  },
  "voice": {
    "voice_id": "",
    "language": "en",
    "speed": 1
  },
  "transcriber": {
    "provider": "cartesia",
    "turn_detection": "balanced"
  },
  "call": {
    "max_duration_seconds": 600,
    "call_start_hour": 9,
    "call_end_hour": 21,
    "timezone": "Asia/Kolkata",
    "record": true
  },
  "analytics": {
    "summarize": true,
    "extraction_prompt": "The date and time the caller wants to visit"
  },
  "tools": [
    {
      "name": "check_availability",
      "description": "Free appointment slots for a date",
      "method": "POST",
      "url": "https://example.com/slots",
      "parameters": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string"
          }
        },
        "required": [
          "date"
        ]
      }
    }
  ],
  "status": "active"
}

Sends a real request with your key.

Response

{
  "name": "Example",
  "welcome_message": "",
  "system_prompt": "",
  "llm": {
    "provider": "gemini",
    "model": "gemini-3.5-flash-lite",
    "temperature": 0.4,
    "max_tokens": 300
  },
  "voice": {
    "provider": "cartesia",
    "model": "sonic-3.6",
    "voice_id": "",
    "voice_name": "",
    "language": "hi",
    "speed": 1
  },
  "transcriber": {
    "provider": "cartesia",
    "model": "ink-2",
    "turn_detection": "balanced",
    "language": "hi",
    "endpointing_ms": 300,
    "keyterms": [
      "keyterms"
    ]
  },
  "call": {
    "max_duration_seconds": 600,
    "hangup_after_silence_seconds": 15,
    "allow_interruptions": true,
    "interruption_min_words": 2,
    "call_start_hour": 9,
    "call_end_hour": 21,
    "timezone": "Asia/Kolkata",
    "record": true,
    "hangup_message": "",
    "hangup_on_prompt": false,
    "hangup_prompt": "You are an AI assistant determining if a conversation is complete. A conversation is complete if:\n\n1. The user explicitly says they want to stop (e.g., \"That's all,\" \"I'm done,\" \"Goodbye,\" \"thank you\").\n2. The user seems satisfied, and their goal appears to be achieved.\n3. The user's goal appears achieved based on the conversation history, even without explicit confirmation.\n\nIf none of these apply, the conversation is not complete.",
    "hangup_interruptible": false,
    "check_user_online": false,
    "user_online_message": "Are you still there?",
    "user_online_after_seconds": 9
  },
  "analytics": {
    "summarize": false,
    "extractions": [
      {
        "key": "key",
        "label": "",
        "type": "text",
        "description": "",
        "choices": [
          {}
        ]
      }
    ],
    "extraction_prompt": ""
  },
  "tools": [
    {
      "name": "Example",
      "description": "description",
      "parameters": {},
      "method": "POST",
      "url": "https://example.com/hook",
      "headers": {},
      "pre_call_message": "",
      "timeout_seconds": 8
    }
  ],
  "knowledge_base_ids": [
    "knowledge_base_ids"
  ],
  "webhook_url": "",
  "phone_number": "",
  "status": "active",
  "id": "id",
  "version": 1,
  "updated_by": "",
  "created_at": "2026-10-01T15:30:00+05:30",
  "updated_at": "2026-10-01T15:30:00+05:30",
  "variables": [
    "variables"
  ]
}

{
  "detail": "sign in required"
}

{
  "detail": "your role cannot do this (agents.edit)"
}

{
  "detail": [
    {
      "type": "missing",
      "loc": [
        "body",
        "name"
      ],
      "msg": "Field required",
      "input": {}
    }
  ]
}

{
  "detail": "rate limit exceeded; slow down"
}