Developers / Agents

Create an agent

POST https://api.echonova.ai/v1/agents

Creates 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

Authorization string Required

Bearer, a space, then your API key, which starts with ek_. Create keys in the portal under Developers, API Keys.

Idempotency-Key string Optional

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

name string Required

The agent name.

1 to 100 characters
description string Optional

What the agent is for.

Up to 500 characters
systemPrompt string Required

The instructions the agent follows in every conversation.

1 to 8000 characters
firstMessage string Optional

What the agent says first when a conversation starts.

Up to 500 characters
voices array of objects Required

The voices the agent speaks with, 1 to 4.

llmModel string Required

A model id from GET /v1/llm/models.

1 to 100 characters

Response

200 application/json Every response uses this envelope.

data object

The result.

success boolean

true for a successful call.

statusCode integer

Repeats the HTTP status.

errorMessage string or null

null on success.

Errors

Same envelope, with success false and data null. All errors

POST /v1/agents

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
}