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

# Voice AI overview

> How voice agents, versions, and conversations fit together, and what you can automate with the Voice API.

Clarity voice agents answer and place phone calls for you. An agent listens to the caller, reasons with a language model, uses your tools (look up an order, book a slot, transfer to a person), and speaks back. Every call is recorded, transcribed, and kept as a **conversation** you can read back from the API.

## Where calls come from

| Channel | How it starts |
| - | - |
| Inbound phone | A caller dials one of your project's numbers. The number's routing sends the call to an agent. |
| Outbound phone | You ask an agent to call a number, one call at a time ([dispatch a call](/voice/outbound-calls.md)) or as a list ([campaigns](/voice/campaigns.md)). |
| Web | **Try it** in Clarity, or the agent's public demo page, connects a browser to the agent. |
| Evals | A synthetic caller talks to the agent to test it ([evals](/voice/evals.md)). |

You set up numbers, routing and agents in Clarity at [support.onclarity.com](https://support.onclarity.com). The API covers the parts teams usually automate.

## The model

**1. A project holds your agents**

Every path in the Voice API starts with a project: `/v1/projects/{projectId}/…`. List the projects your key can reach with `GET /v1/projects`.

**2. An agent has versions**

Only the **published** version takes live calls. Edits go to a **draft**, which you publish when it is ready. Older published versions stay in the history and can be republished. See [Manage agents](/voice/agents.md).

**3. A call is a conversation**

Each call creates a **conversation**. A conversation can have several call legs (`calls`), for example when a call is transferred.

**4. Conversations carry the record**

After the call ends you can read its transcript, a signed link to the recording, the tool calls the agent made, the summary and any fields the agent extracted. See [Conversations and recordings](/voice/conversations.md).

## Base URL and authentication

```bash theme={null}
curl https://voice-api.onclarity.com/v1/projects \
  -H "Authorization: Bearer $CLARITY_API_KEY"
```

```json theme={null}
{
  "projects": [
    { "id": "3f6c1a52-8e0b-4f6e-9a1d-2b7c4e9f0a11", "name": "Customer care" }
  ]
}
```

Every request uses your **organization API key** in the `Authorization` header. The key reaches every project of your organization. See [Authentication](/authentication.md).

Most errors come back as JSON with an `error` field. Some errors add a machine-readable `code`, for example `AGENT_NOT_PUBLISHED`.

## What you can automate

> **[Place outbound calls](/voice/outbound-calls.md)**
>
> Have an agent call a customer and get the conversation id back right away.

> **[Get notified when a call ends](/voice/call-ended-webhook.md)**
>
> Receive the call's transcript, parties and extracted fields as a vCon document at your HTTPS endpoint.

> **[Read conversations and recordings](/voice/conversations.md)**
>
> List calls, filter them, and pull transcripts, recordings and metrics.

> **[Run campaigns](/voice/campaigns.md)**
>
> Call a list of numbers with per-contact variables, retries and calling hours.

> **[Manage agents](/voice/agents.md)**
>
> Create and edit agents, publish drafts, and roll back to an earlier version.

> **[Test with evals](/voice/evals.md)**
>
> Run a suite of scripted test calls against an agent version and read the judge's verdicts.

The full list of endpoints, with request and response schemas, is in the [API reference](/api-reference/introduction.md).


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