Create a new agent
curl --request POST \
--url https://api.inya.ai/platform/v1/agents \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"botName": "Support Agent"
}
'import requests
url = "https://api.inya.ai/platform/v1/agents"
payload = { "botName": "Support Agent" }
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({botName: 'Support Agent'})
};
fetch('https://api.inya.ai/platform/v1/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"status": "success",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "Agent created successfully.",
"response": {
"botId": "fb79920229d144608ebf665a10e50275",
"botName": "Support Agent"
}
}{
"status": "failure",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "<string>"
}{
"status": "failure",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "An agent named 'Support Agent' already exists in your organization"
}{
"status": "failure",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "<string>"
}Agents API
Create Agent
Create a new voice agent and get a botId
POST
/
v1
/
agents
Create a new agent
curl --request POST \
--url https://api.inya.ai/platform/v1/agents \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"botName": "Support Agent"
}
'import requests
url = "https://api.inya.ai/platform/v1/agents"
payload = { "botName": "Support Agent" }
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({botName: 'Support Agent'})
};
fetch('https://api.inya.ai/platform/v1/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"status": "success",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "Agent created successfully.",
"response": {
"botId": "fb79920229d144608ebf665a10e50275",
"botName": "Support Agent"
}
}{
"status": "failure",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "<string>"
}{
"status": "failure",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "An agent named 'Support Agent' already exists in your organization"
}{
"status": "failure",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "<string>"
}What it does: Creates a new voice agent and returns a
Save the
403 Forbidden — insufficient permissions
botId. The agent starts with dashboard defaults — you configure voice, prompt, and integrations in a follow-up Update Agent call.
1. POST /v1/agents → get botId (this page)
2. PUT /v1/agents/{botId} → set prompt, voice, webhook
3. POST /v1/agents/{botId}/trigger_call → test a call
Required Permission
agents
Minimum working example
curl -X POST "https://api.inya.ai/platform/v1/agents" \
-H "x-api-key: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"botName": "Support Agent",
"description": "Handles inbound customer support calls.",
"region": "asia",
"timeZone": "Asia/Kolkata"
}'
botId from the response — you need it for every other Agents API call.
Success (201)
{
"status": "success",
"message": "Agent created successfully.",
"response": {
"botId": "fb79920229d144608ebf665a10e50275",
"botName": "Support Agent"
},
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
Request body
| Field | Required | Default | Description |
|---|---|---|---|
botName | Yes | — | Unique name within your organization. |
description | No | "" | Short description of the agent’s purpose. |
region | No | "asia" | Deployment region — asia, america, or europe. See Get Regions. |
timeZone | No | "Asia/Kolkata" | IANA timezone. See Get Timezones. |
New agents inherit sensible defaults: barge-in enabled, TTS caching on, LLM temperature
0.5, max tokens 300. Override any setting via Update Agent.What to do next
| Step | Endpoint | Why |
|---|---|---|
| Configure voice and prompt | Update Agent | Set ASR, LLM, TTS, system prompt, webhook |
| Validate prompt syntax | Validate Prompt | Check Jinja2 variables before saving |
| Pick compatible ASR/TTS | Get Transcriber Config | Ensure models support your languages |
| Place a test call | Trigger Call | Requires whitelisted phone number |
| Review the call | Get Conversation Logs → Stats | Read disposition and transcript |
Edge cases
| Scenario | What happens |
|---|---|
Duplicate botName | HTTP 409 — pick a unique name |
| QA role without create permission | HTTP 403 |
Invalid region or timeZone | HTTP 400 — validate via Config API first |
Errors
409 Conflict — name already taken{
"status": "failure",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "An agent named 'Support Agent' already exists in your organization"
}
{
"status": "failure",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "QA role does not have permission to create/update agents"
}
Call Get Regions and Get Timezones before your first create request so you use valid values.
Save the
requestId from every response. You will need it if you contact Gnani support to trace a specific request.Authorizations
API key with 'agents' permission
Body
application/json
Was this page helpful?