Developers / Agents

Update an agent

PATCH https://api.echonova.ai/v1/agents/{agentId}

Changes the fields you send: name, description, systemPrompt, firstMessage, voices or llmModel. A voice the agent already has keeps its tuning. An archived agent answers 409. 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.

Path parameters

agentId string Required

The agent id, as GET /v1/agents returned it.

Request body

application/json

name string Optional

The agent name.

1 to 100 characters
description string Optional

What the agent is for. Send null or an empty string to clear it.

Up to 500 characters
systemPrompt string Optional

The instructions the agent follows in every conversation.

1 to 8000 characters
firstMessage string Optional

What the agent says first when a conversation starts. Send null or an empty string to clear it; the agent then writes its own opening line.

Up to 500 characters
voices array of objects Optional

The voices the agent speaks with, 1 to 4. A voice the agent already has keeps its tuning; a new one starts with the default tuning.

llmModel string Optional

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

PATCH /v1/agents/{agentId}

curl -X PATCH "https://api.echonova.ai/v1/agents/{agentId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "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
}