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

# Agents

> List your AI voice agents, read one agent, and update its name and description.

An agent is the AI voice assistant that makes or answers your calls. These endpoints let you read your agents and rename or re-describe them from your own systems.

| Endpoint | Request |
| - | - |
| [List agents](https://docs.olimi.ai/api-reference/endpoint/agent/list-agents.md) | `GET /api/v2/agents` |
| [Get an agent](https://docs.olimi.ai/api-reference/endpoint/agent/get-agent.md) | `GET /api/v2/agents/{id}` |
| [Update an agent](https://docs.olimi.ai/api-reference/endpoint/agent/update-agent.md) | `PATCH /api/v2/agents/{id}` |

## Authentication

Send your API key in the `X-API-KEY` header on every request, to the base URL `https://api-eg.olimi.ai`. See [API Authentication](https://docs.olimi.ai/api-auth.md).

You only ever see and change the agents that belong to the company your API key is issued to.

## Agent fields

Every endpoint returns agents with these fields:

| Field | Type | Meaning |
| - | - | - |
| `id` | UUID | The agent's ID. Use it in the URL of the other endpoints. |
| `organizationId` | UUID | Your company's ID. |
| `name` | string | The agent's display name. |
| `description` | string \| null | A short description of what the agent does. |
| `callType` | string | How the agent talks to people. See [Call types](#call-types). |
| `isActive` | boolean | Whether the agent is switched on. |
| `languageId` | UUID \| null | The language the agent speaks. |
| `voiceId` | UUID \| null | The voice the agent speaks with. |
| `voice` | object \| null | The voice the agent speaks with. See [Voice object](#voice-object). |
| `createdAt` | string | When the agent was created (ISO 8601, UTC). |
| `updatedAt` | string | When the agent was last changed (ISO 8601, UTC). |

### Call types

| Value | Meaning |
| - | - |
| `inbound` | Answers calls to your phone numbers. |
| `outbound` | Makes calls, for example in campaigns. |
| `web` | Talks to visitors in a website widget. |

### Voice object

| Field | Type | Meaning |
| - | - | - |
| `id` | UUID | The voice's ID. Same as the agent's `voiceId`. |
| `name` | string | The voice's display name. |
| `gender` | string \| null | The voice's gender, for example `female`. |
| `language` | object \| null | The voice's language. `null` for voices not tied to one language. |
| `language.id` | UUID | The language's ID. |
| `language.name` | string | The language's display name, for example `Arabic - Egyptian`. |
| `language.code` | string | The language code, for example `ar-EG`. |

> [!NOTE]
>
> Responses also carry the agent's detailed configuration, such as its prompt, knowledge base and call behaviour settings. Those fields are managed in the Dashboard and may change without notice, so rely only on the fields listed above.

## Errors

Always branch on `statusCode` first. Most errors also carry a machine-readable `errorCode`:

```json theme={null}
{
  "statusCode": 404,
  "errorCode": "agent_not_found",
  "message": "Agent not found"
}
```

| Status | `errorCode` | When |
| - | - | - |
| `400` | none | The `id` in the URL isn't a valid UUID. |
| `400` | varies | Update only. The agent's current voice setup is no longer valid, so any update is refused. Fix the agent's voice in the Dashboard, then retry. |
| `401` | `unauthenticated` | The `X-API-KEY` header is missing or the key isn't valid. |
| `404` | `agent_not_found` | No agent with that `id` belongs to your company, or it was deleted. |
| `422` | none | The request didn't pass validation. |

Validation errors (`422`) have a different body. `message` is a list of what went wrong, and there's no `errorCode`:

```json theme={null}
{
  "statusCode": 422,
  "message": ["name must be shorter than or equal to 100 characters"],
  "error": "Unprocessable Entity"
}
```

The `message` text is for humans and may change, so don't match on it.


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