Developers / Agents
Create an agent
https://api.echonova.ai/v1/agentsCreates an active agent in this key's workspace with a name, instructions, 1 to 4 voices and a language model. It has no channel yet, so it takes no calls until you connect one. Send an Idempotency-Key to retry safely. Free. Needs the agents:write scope on the key.
Headers
Bearer, a space, then your API key, which starts with ek_. Create keys in the portal under Developers, API Keys.
Optional. Repeat the same key within 24 hours to retry safely: the first result comes back and nothing is made twice. A new request needs a new key.
Request body
application/json
The agent name.
What the agent is for.
The instructions the agent follows in every conversation.
What the agent says first when a conversation starts.
The voices the agent speaks with, 1 to 4.
A model id from GET /v1/llm/models.
Response
200 application/json Every response uses this envelope.
The result.
The agent id.
The agent name.
What the agent is for, or null.
active, or archived once deleted in the portal.
The agent's default voice, or null if it has none.
The voice id, as GET /v1/text-to-speech/voices shows it.
The voice name in English, or null if the voice is gone.
The default voice's dialect, or null.
The language model the agent thinks with.
Who serves the language model.
The model id. Pass it as model to GET /v1/llm/estimate for its price.
How many channels the agent is connected to.
How many conversations the agent has had.
When the agent last changed, as an ISO 8601 date-time.
What the agent says first, or null if none is set and the agent writes its own opening line.
The agent's instructions.
Call settings.
Whether voice calls are recorded.
Whether numbers, dates and amounts are spoken the way the dialect says them.
How many knowledge folders and sources the agent uses.
How many workspace tools are attached to the agent.
When the agent was created, as an ISO 8601 date-time.
true for a successful call.
Repeats the HTTP status.
null on success.
Errors
Same envelope, with success false and data null. All errors
When. name is over 100 characters.
Fix. Send a shorter name.
When. name is an empty string.
Fix. Send a name, or leave the field out where it is optional.
When. description is over 500 characters.
Fix. Send a shorter description.
When. systemPrompt is over 8000 characters.
Fix. Shorten the instructions; long reference text belongs in knowledge.
When. firstMessage is over 500 characters.
Fix. Send a shorter first message.
When. voices is an empty list.
Fix. Send 1 to 4 voices.
When. voices lists more than 4 voices.
Fix. Send 1 to 4 voices.
When. A voiceId is not a 24-character hexadecimal id; the message names its place in voices.
Fix. Use an id from GET /v1/agent-voices.
When. A voice language is not ar or en; the message names its place in voices.
Fix. Send ar or en.
When. llmModel is over 100 characters.
Fix. Send a model id from GET /v1/llm/models.
When. A new voiceId names a voice that has been retired.
Fix. Pick another voice from GET /v1/agent-voices.
When. voices lists the same voiceId twice; the message names it.
Fix. List each voice once.
When. More than one voice has isDefault true.
Fix. Mark at most one voice as the default.
When. llmModel is not a model this workspace can use.
Fix. Use a model id from GET /v1/llm/models.
When. llmModel is missing on create; every rule on the field fails at once.
Fix. Send a model id from GET /v1/llm/models.
When. The workspace already has as many active agents as its plan allows. Create, duplicate and restore check it.
Fix. Archive an agent with POST /v1/agents/{agentId}/archive, or upgrade the plan.
When. The Idempotency-Key header is longer than 200 characters, or holds a space or a character outside printable ASCII.
Fix. Send 1 to 200 printable ASCII characters, such as a UUID.
When. The body or query carries a field the endpoint does not define.
Fix. Remove the field.
When. The Authorization header is missing or is not Bearer ek_..., no key matches the token, or the key is deleted, disabled, expired or its account is closed.
Fix. Send Authorization: Bearer ek_... with an enabled key from this environment.
When. The workspace that owns the key has no subscription.
Fix. Check the workspace's plan in the portal.
When. The subscription is in a state other than active or trial.
Fix. Renew the subscription.
When. The key does not have the agents:write scope.
Fix. Edit the key and give it the agents:write scope, or use another key.
When. The member who created the key has left the workspace, or no longer has both the Manage agents and Manage developer API permissions. It is checked on every call.
Fix. Give that member both permissions again, or create a key as a member who has them.
When. A voiceId is unknown, or is a cloned voice of another workspace.
Fix. Use an id from GET /v1/agent-voices.
When. This key sent the same Idempotency-Key in the last 24 hours with a different body or agent.
Fix. Use a new Idempotency-Key for a new request.
When. The first request with this Idempotency-Key has not finished yet.
Fix. Wait a moment, then retry with the same key to get its result.
When. The JSON body of an agent write is over 512 KB; the request is rejected before the API key is checked, so it has no Activity row.
Fix. Send a smaller body; split long knowledge text into several sources.
When. The request has a body whose Content-Type is not application/json.
Fix. Send Content-Type: application/json.
When. The key made more than 100 requests to one endpoint in 60 seconds, or one IP address made more than 100 requests to one endpoint in 60 seconds (the IP limit is counted before the key is checked, so it can answer with no key at all); a Retry-After header carries the seconds to wait.
Fix. Wait Retry-After seconds, then retry.
When. An error the API did not classify.
Fix. Check the request, then retry after a short wait; contact support if it persists.
When. A transient outage inside the API.
Fix. Retry after a short wait.
When. A transient timeout inside the API.
Fix. Retry after a short wait.
curl -X POST "https://api.echonova.ai/v1/agents" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Sales assistant","systemPrompt":"You are a friendly sales assistant. Answer in the caller language.","voices":"string","llmModel":"gpt-4o"}'{
"data": {
"id": "6650a1b2c3d4e5f6a7b8c9d0",
"name": "Sales assistant",
"description": "Answers questions about plans and prices.",
"status": "active",
"voice": {
"id": "6640a1b2c3d4e5f6a7b8c9d0",
"name": "Huda"
},
"dialect": "emirati",
"llm": {
"provider": "openai",
"model": "gpt-4o"
},
"channelsCount": 2,
"sessionsCount": 128,
"updatedAt": "2026-11-01T10:00:00.000Z",
"firstMessage": "Hello, how can I help you today?",
"systemPrompt": "You are a friendly sales assistant for EchoNova.",
"settings": {
"recordCalls": true,
"normalizeNumbers": true
},
"knowledgeCount": 3,
"toolsCount": 2,
"createdAt": "2026-10-01T10:00:00.000Z"
},
"success": true,
"statusCode": 200,
"errorMessage": null
}