Agents API

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 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 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).
`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 for how the agent says and hears your terms (your default one always applies).
`keyterms`	string[]	The agent’s own custom words, 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).
`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.

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

Get Started

SDK

API Reference

Resources

Agents

`GET /v1/agents`

`POST /v1/agents`

`GET /v1/agents/{id}`

`PATCH /v1/agents/{id}`

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

Conversations

`GET /v1/conversations`

`GET /v1/conversations/{id}`

Balance

`GET /v1/account/balance`

​Agents

​GET /v1/agents

​POST /v1/agents

​GET /v1/agents/{id}

​PATCH /v1/agents/{id}

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

​Conversations

​GET /v1/conversations

​GET /v1/conversations/{id}

​Balance

​GET /v1/account/balance

Agents

`GET /v1/agents`

`POST /v1/agents`

`GET /v1/agents/{id}`

`PATCH /v1/agents/{id}`

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

Conversations

`GET /v1/conversations`

`GET /v1/conversations/{id}`

Balance

`GET /v1/account/balance`