> This page is for Voice AI Platform.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.hams.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.hams.ai/_mcp/server.

# Overview

> What the Voice AI Platform API covers, where it runs, and which key each part takes.

The Voice AI Platform is the service behind the Hams dashboard. It holds your AI agents, runs their
chat sessions, and dials outbound calling batches through your telephony extensions. Everything
documented here you can do from your own systems with an API key created in the dashboard.

## Base URL

All requests go to `https://api.hams.ai`; paths in these docs are relative to it. There is no
version prefix, with one exception: the endpoints meant for browsers and embedded widgets live under
`/v1/` and take a public key.

## What you can do

#### [API keys](/platform/api-keys)

Get a secret key for your servers or a public key for your web pages in the dashboard, and
restrict it by IP, domain and scope.

#### [AI agents](/platform/ai-agents)

Build and update agents in the platform, then integrate them by ID: chat sessions, the widget,
calls and outbound batches.

#### [Chat sessions and widget](/platform/chat)

Start a chat with an agent, stream its replies, rate and end the session; configure the
embeddable widget.

#### [Outbound batches](/platform/outbound-batches)

Upload leads, schedule a batch, publish it and follow every lead to its outcome.

#### [Outbound dialer](/platform/outbound-dialer)

How the platform turns a published batch into calls, and what each lead status means.

#### [API Reference](/platform/reference)

Every endpoint with its request and response schema, generated from the service itself.

## Which key to use

| Area                                                                                       | Key                           |
| ------------------------------------------------------------------------------------------ | ----------------------------- |
| `/ai-agents/{agent_id}/chat/…`, `/ai-agents/{agent_id}/widget-config`, `/outbound-batch/…` | Secret key, in `X-Secret-Key` |
| `/v1/ai-agents/…`                                                                          | Public key, in `X-Public-Key` |

Secret keys need the `WRITER` role for anything that creates, changes or deletes. See
[Authentication](/platform/authentication) for the headers and [API conventions](/platform/conventions)
for pagination, errors and rate limits.

> **Note**
>
> Identifiers are opaque strings and timestamps are ISO 8601 in UTC. Every resource belongs to one
> entity, the workspace you see in the dashboard; a key reaches only the entity it was created in.