Create Agent

Creates a new AI voice agent for your organization. Phone number and prompt are optional at creation time.

Endpoint

POST https://www.tabbly.io/api/create-agent

Authentication

See Introduction. Send your API key in one of:

"api_key": "YOUR_API_KEY" in the JSON request body (recommended)
X-API-Key: YOUR_API_KEY header (body api_key can be omitted)

Request body

Parameter	Type	Required	Description
`api_key`	string	Yes*	Your organization API key (omit if using `X-API-Key` header)
`agent_name`	string	Yes	Name of the voice agent
`custom_first_line`	string	Yes	Initial greeting when the agent answers
`stt_language`	string	Yes	Language the agent listens in (e.g. `en`, `hi`)
`voice_id`	integer	Conditional	Prefer this. Voice library ID from Get Voices. Use this or the three voice fields below
`voice_name`	string	Conditional	Required with `language_code` and `tts_library` when `voice_id` is omitted
`language_code`	string	Conditional	Voice language code when not using `voice_id`
`tts_library`	string	Conditional	TTS provider when not using `voice_id`
`phone_number`	string	No	E.164 number — must belong to your org if provided
`prompt_text`	string	No	Agent behavior instructions
`agent_type`	string	No	Leave empty for a normal voice agent. Use `video` only for video agents

Example request

curl -X POST "https://www.tabbly.io/api/create-agent" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "agent_name": "My Voice Agent",
    "custom_first_line": "Hello, how can I help you today?",
    "stt_language": "en",
    "voice_id": 125,
    "prompt_text": "You are a helpful assistant."
  }'

Response

Success (200)

{
  "status": "success",
  "data": {
    "agent_id": 6580,
    "message": "Voice agent created successfully"
  }
}

Error responses

{
  "status": "error",
  "message": "Human-readable error description"
}

HTTP status	When
400	Missing required fields, invalid voice, invalid phone for org, invalid `agent_type`
401	Missing or invalid API key
405	Method not POST
500	Server or database error

Notes

Use Get Voices to find a voice_id, or pass voice_name, language_code, and tts_library directly.
If phone_number is provided, it must already be purchased and registered for your organization.