https://api.echonova.aiDevelopers
Agents API
Create, change, copy, archive and read voice agents over the v1 API, with the key permissions, paging, retry and archive rules, and a link to every endpoint.
The Agents API lets your server manage the voice agents of one workspace: list and read them, create, change, copy, archive and restore them, add knowledge and tools, and read their conversations. It is the same set of agents you see under Agents in the portal, so a change made here shows there and the other way round.
What you need
- An API key with agent access. See Give a key agent access.
- The base URL and the
Authorization: Bearer ek_...header from Authentication. - A member of the workspace who created the key and still has the permissions listed below.
Give a key agent access
A key reaches no agent route until you set agent access on it. On the key
form, under Agents, set the Agents row. Tools is covered in
Tools API. Agent sessions (agents:talk)
lets a key start, read and end live sessions with an agent, and nothing else.
See Live sessions.
The Agents row has three levels:
| Level | Scope | What the key may do |
|---|---|---|
| Read | agents:read |
List and read agents, knowledge, tools, conversations, transcripts, recordings and test runs. |
| Write | agents:write |
Everything Read allows, and create, change, copy, archive and restore agents, knowledge, tools. Write includes Read. |
A key can have agent rows and no speech access. The speech rows on the key do
not give agent access, even when the key allows every speech endpoint. A key without the scope gets 403 with
This API key cannot read agents. or This API key cannot change agents..
The key acts for the member who created it, and the check runs on every call:
- Reading needs that member to keep the permission to view agents and the permission to manage the developer API.
- Writing needs the permission to manage agents and the permission to manage the developer API.
- Attaching and detaching tools also needs the permission to manage tools.
To set Agents to Write on a key, you need the permission to manage
agents yourself. Without it the Write option is off on the key form, and
the API refuses it with 403 and
You cannot give a key scopes you cannot use: agents:write. A key that
already has Write keeps it when you edit its other rows.
A member who left the workspace or lost one of these takes the key's agent
access with them. The error then reads The member who created this API key cannot view agents.,
... cannot manage agents. or ... cannot manage tools.. Every text is on
Errors.
Paging
The lists that page take offset and limit. limit is 1 to 50 and
defaults to 20. offset is 0 to 10000 and defaults to 0. A page comes back
as an object with the page and the full count:
{
"data": { "items": [], "total": 0 },
"success": true,
"statusCode": 200,
"errorMessage": null
}A conversation's transcript pages by time instead: it returns the newest
messages first, 20 by default and 50 at most, and before takes the
createdAt of the oldest message you have to return the page before it.
The test runs list takes limit from 1 to 10 and defaults to 2.
Archived agents
Archiving takes an agent out of the default list, which shows every agent
that is not archived. An archived agent refuses every change with 409 and This agent is archived. Restore it before changing it.
The only calls that work on it are duplicate, archive and restore. Restore
it first, or duplicate it and change the copy.
Create, duplicate and restore count against the active agents your plan
allows, and fail with Workspace has reached the maximum number of agents allowed by the current plan
when the workspace is full.
Retry a create safely
POST /v1/agents and POST /v1/agents/{agentId}/duplicate accept an optional
Idempotency-Key header, so a retry after a lost response does not make a
second agent. The rules are on
Retry requests safely.
Every other write is not idempotent: repeating it applies it again.
Knowledge and credits
Adding knowledge indexes it, and indexing uses the workspace's credits. That usage is not counted against the key's Credit Limit. A key that can manage agents can therefore spend workspace credits on indexing, up to what the workspace balance covers, until you disable or delete the key. Each of the two knowledge-add routes accepts at most 20 calls a minute per key. Give Agents on Write only to keys you trust with that.
Webhooks
Creating, changing, archiving and restoring an agent, a finished agent build and a finished test run send webhook events. See Webhook events.
MCP uses sign-in, not keys
AI apps such as Claude reach the same agent actions over MCP. They sign in with an EchoNova account through OAuth and never take an API key. See Connect EchoNova to Claude.
Endpoints
Reads need Agents on Read or Write.
- List agents
- Get an agent
- Compare agents
- List an agent's knowledge
- List an agent's tools
- Get an agent's website widget
- List an agent's conversations
- Get a conversation
- Get a conversation's transcript
- Get a link to a call's recording
- List an agent's latest test runs
- Get a test run
- List voices an agent can use
- List language models
- Estimate the cost of a language model
Writes need Agents on Write.
- Create an agent
- Update an agent
- Duplicate an agent
- Attach tools to an agent
- Detach tools from an agent
- Add text knowledge to an agent
- Add a web page or site to an agent
- Set an agent's knowledge search
Test runs started from the portal can be read with List an agent's latest test runs and Get a test run. Starting a test run over the API is not available yet.
Archive and restore need Agents on Write and work on archived agents too.
FAQ
Can a key create an agent that takes calls?
A new agent has no channel, so it takes no calls until you connect one in the portal. The API does not connect channels.
Does the key see agents of other workspaces?
No. A key works for the workspace that owns it. An agent id from another
workspace answers 404 with Agent not found, the same as an unknown id.