Overview | Hams AI Docs

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

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

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

Chat sessions and widget

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

Outbound batches

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

Outbound dialer

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

API 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 for the headers and API conventions for pagination, errors and rate limits.

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.