> For the full page index, fetch https://echonova.ai/llms.txt

# 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](#give-a-key-agent-access).
- The base URL and the `Authorization: Bearer ek_...` header from
  [Authentication](/docs/developers/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](/docs/developers/tools-api). **Agent sessions** (`agents:talk`)
lets a key start, read and end live sessions with an agent, and nothing else.
See [Live sessions](/docs/developers/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](/docs/developers/errors#agents).

## 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:

```json
{
  "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](/docs/developers/retries-and-idempotency#idempotency-key).
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](/docs/developers/webhooks-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](/docs/developers/connect-claude).

## Endpoints

Reads need **Agents** on **Read** or **Write**.

- [List agents](/docs/reference/agents-list-agents)
- [Get an agent](/docs/reference/agents-get-agent)
- [Compare agents](/docs/reference/agents-compare-agents)
- [List an agent's knowledge](/docs/reference/agents-list-knowledge)
- [List an agent's tools](/docs/reference/agents-get-agent-tools)
- [Get an agent's website widget](/docs/reference/agents-get-widget)
- [List an agent's conversations](/docs/reference/agents-list-conversations)
- [Get a conversation](/docs/reference/agents-get-conversation)
- [Get a conversation's transcript](/docs/reference/agents-get-transcript)
- [Get a link to a call's recording](/docs/reference/agents-get-recording-link)
- [List an agent's latest test runs](/docs/reference/agents-list-test-runs)
- [Get a test run](/docs/reference/agents-get-test-run)
- [List voices an agent can use](/docs/reference/agents-list-agent-voices)
- [List language models](/docs/reference/agents-list-llm-models)
- [Estimate the cost of a language model](/docs/reference/agents-estimate-llm)

Writes need **Agents** on **Write**.

- [Create an agent](/docs/reference/agents-create-agent)
- [Update an agent](/docs/reference/agents-update-agent)
- [Duplicate an agent](/docs/reference/agents-duplicate-agent)
- [Attach tools to an agent](/docs/reference/agents-attach-tools)
- [Detach tools from an agent](/docs/reference/agents-detach-tools)
- [Add text knowledge to an agent](/docs/reference/agents-add-text-knowledge)
- [Add a web page or site to an agent](/docs/reference/agents-add-web-knowledge)
- [Set an agent's knowledge search](/docs/reference/agents-set-rag)

Test runs started from the portal can be read with
[List an agent's latest test runs](/docs/reference/agents-list-test-runs) and
[Get a test run](/docs/reference/agents-get-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.

- [Archive an agent](/docs/reference/agents-archive-agent)
- [Restore an archived agent](/docs/reference/agents-restore-agent)

## 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.

## Related

- [Webhook events](/docs/developers/webhooks-events)
- [Retry requests safely](/docs/developers/retries-and-idempotency)
- [Errors](/docs/developers/errors)
- [Changelog](/docs/developers/changelog)
