Agents

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	`GET /api/v2/agents`
Get an agent	`GET /api/v2/agents/{id}`
Update an agent	`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. 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.
`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.
`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`.

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:

{
  "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:

{
  "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.

Getting Started

API Overview

Agents & Campaigns

Speech

Authentication

Agent fields

Call types

Voice object

Errors

​Authentication

​Agent fields

​Call types

​Voice object

​Errors

Authentication

Agent fields

Call types

Voice object

Errors