> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lokutor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents API

> Create, read, change and delete voice agents, read their calls, and check the balance, with an API key

Everything the dashboard does with agents is also an API call. Authenticate as for any request (`Authorization: Bearer <key>` or `X-API-Key`); every call sees only your account. The [MCP server](https://docs.lokutor.com/guides/mcp-server.md) exposes the same operations as tools.

## Agents

### `GET /v1/agents`

Your agents, newest first: `id`, `name`, `description`, `voice`, `language`, `first_message`, `created_at`, `updated_at`.

### `POST /v1/agents`

Creates an agent. It can take web calls at once; [assign a phone number](https://docs.lokutor.com/api-reference/call-center.md) to give it a line.

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| `name` | string | Yes | 1–100 characters. |
| `prompt` | string | Yes | The agent's instructions: who it is, who it talks to, what to get done, what never to do. Up to 50,000 characters. |
| `description` | string | No | A note on what it is for, up to 500 characters. |
| `voice` | string | No | A slot `F1`–`F5` / `M1`–`M5`, a built-in voice name, or one of your `clone_…` ids ([voices](https://docs.lokutor.com/voices-languages-models.md)). |
| `language` | string | No | The language it speaks and listens in, e.g. `es`. Default `en`. |
| `first_message` | string | No | Said word for word when a call starts. Empty: the agent opens in its own words. |
| `settings` | object | No | See below. |

**Settings**, merged into the agent's configuration (a setting sent as `null` goes back to its default):

| Setting | Type | Description |
| :- | :- | :- |
| `dictionary_ids` | string\[] | [Dictionaries](https://docs.lokutor.com/api-reference/pronunciation.md) for how the agent says and hears your terms (your default one always applies). |
| `keyterms` | string\[] | The agent's own [custom words](https://docs.lokutor.com/guides/custom-vocabulary.md), up to 100 of 40 characters. |
| `recording_enabled` | bool | Record calls. Free accounts always record. |
| `webhook_url` | string | An `https` URL called after each conversation ([webhook](https://docs.lokutor.com/api-reference/conversation-webhook)). |
| `timezone` | string | IANA name, e.g. `Europe/Madrid`, for dates and calendar slots. |
| `web_search` | bool | Let the agent search the web during a call. |
| `temperature` | number | 0.1–1.0: how varied the voice's delivery is. Default 0.3. |
| `data_fields` | object\[] | `[{"name": "email", "description": "the caller's email address"}]`: what to extract from each call. |
| `speculative_llm` | bool | Start the reply while the caller may still be finishing (faster answers, more model tokens). |

Tools, integrations (CRM, calendar, call transfer) and the language model are set in the dashboard; `GET` shows them in `config` and the API leaves them as they are. An unknown setting answers `400` with the list above.

```bash theme={null}
curl -X POST https://api.lokutor.com/v1/agents \
  -H "Authorization: Bearer sk_your_key" -H "Content-Type: application/json" \
  -d '{"name": "Sofía", "language": "es", "voice": "F2",
       "prompt": "Eres la recepcionista de la Clínica Sol. Das citas y respondes dudas sobre horarios y precios.",
       "first_message": "Clínica Sol, buenos días, ¿en qué puedo ayudarle?",
       "settings": {"timezone": "Europe/Madrid", "data_fields": [{"name": "nombre", "description": "nombre del paciente"}]}}'
```

Returns `201` with the agent.

### `GET /v1/agents/{id}`

One agent in full, with its `prompt` and its whole `config` (your own language-model key, if set, shows as `"(set)"`).

### `PATCH /v1/agents/{id}`

Changes the fields you send, with the same fields and settings as `POST`; settings are merged, never replacing the rest of the configuration. Takes effect from the agent's next call.

### `DELETE /v1/agents/{id}?confirm_name=<name>`

Deletes the agent **with its conversations, knowledge documents and evaluation rules**; its phone numbers stay yours, unassigned. `confirm_name` must be the agent's exact name. Cannot be undone.

## Conversations

### `GET /v1/conversations`

Your calls, newest first. Query: `agent_id` (one agent's), `limit` (1–100, default 20), `before` (RFC 3339 time, to page back).

Each: `id`, `agent_id`, `agent_name`, `created_at`, `duration_seconds`, `channel` (`web` or `phone`), `caller` (phone), `summary`, `sentiment` (−1 to 1), `flagged` (failed an evaluation rule), `has_recording`.

### `GET /v1/conversations/{id}`

One call, adding the `transcript`, the `evaluation` results and the `data_fields` extracted from it.

## Balance

### `GET /v1/account/balance`

`{"balance_usd": 18.42, "billing_mode": "wallet", "top_up": "https://app.lokutor.com/billing", "prices": "https://api.lokutor.com/v1/pricing"}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.