PolyAI Platform · API Reference

Build voice agents from code.

Three REST API families cover the full lifecycle — ship agents, run conversations, and observe everything in production. No SDK required.

Quickstart →

Browse APIs

Error codes

API families

< 300ms

Median agent latency

24+

Languages

Regions: US · UK · EU

The three API families

Pick the family that matches your job. Each has its own base URL, key, and audience.

🛠️

Build & deploy

Agents API

Programmatically create agents, edit behavior and knowledge, branch, and ship through environments.

api.{region}.poly.ai

⚡

Runtime & data

Conversations, Chat, Handoff…

Interact with running agents and read post-call data. Transcripts, audio, metrics, sessions.

api.{region}-1.platform.polyai.app

📡

Monitoring

Alerts & Webhooks

Receive real-time events when calls complete, alerts fire, or handoffs happen. Stop polling.

api.{region}.poly.ai

I want to…

Task-oriented entry points. Jump straight to a working example.

Make my first API call

Full walkthrough: key → list conversations → fetch transcript → audio → webhooks.

Pull conversation data

Query transcripts, metrics, and audio for analytics and compliance pipelines.

Build & deploy an agent

Create agents, edit behavior and knowledge, promote sandbox → pre-release → live.

Get notified on events

Send a chat message

Drive a text-based conversation programmatically with create, respond, close.

Trigger an outbound call

Place a programmatic outbound call to a target number and track its status.

Pick your region

Your key is provisioned to a region. The host differs by API family — the platform.polyai.app host carries a -1 suffix, the poly.ai host doesn’t.

🇺🇸US

Runtime · data

api.us-1.platform.polyai.app

Build · monitoring

api.us.poly.ai

🇬🇧UK

Runtime · data

api.uk-1.platform.polyai.app

Build · monitoring

api.uk.poly.ai

🇪🇺EU

Runtime · data

api.euw-1.platform.polyai.app

Build · monitoring

api.eu.poly.ai

Do not use https://api.poly.ai without a region prefix — it returns an error. Always include the region.

Finding your `account_id` and `project_id`

Your account_id and project_id are the first two path segments of your Agent Studio URL:

https://studio.<region>.poly.ai/<account_id>/<project_id>/...

Agent Studio is region-specific. Each Studio host serves one region and is paired with the matching API host. Replace <region> with the subdomain for your tenant:

Studio URL	API host
`https://studio.us.poly.ai`	`https://api.us-1.platform.polyai.app`
`https://studio.uk.poly.ai`	`https://api.uk-1.platform.polyai.app`
`https://studio.eu.poly.ai`	`https://api.euw-1.platform.polyai.app`
`https://studio.poly.ai`	`https://api.studio.poly.ai` (self-serve / Studio region)

A workspace lives in exactly one region — use the Studio host you log in to, and the matching API host for calls.

For example, if your Studio URL is https://studio.uk.poly.ai/acme-uk/acme-team-4/agent, then account_id is acme-uk and project_id is acme-team-4.

Both the slug form (visible in the URL) and the prefixed form are accepted in API paths:

Path parameter	Slug form (from URL)	Prefixed form
`account_id`	`acme-uk`	`ws-xxxxxxxx`
`project_id`	`acme-team-4`	`PROJECT-xxxxxxxx`

The account_id path parameter corresponds to the workspace in Agent Studio. Its prefixed form starts with ws- (for example ws-fd112d8f) — not ACCOUNT-. Older docs may still refer to the prefixed form as ACCOUNT-xxxxxxx; the value you see in Agent Studio (prefixed with ws-) is the correct one to use.

Authenticate

Every PolyAI API uses an API key sent in the x-api-key header. Keys are provisioned by PolyAI — runtime and build keys are separate.

curl -X GET \
  "https://api.<region>.platform.polyai.app/v3/ws-xxxxxxxx/PROJECT-xxx/conversations" \
  -H "x-api-key: YOUR_API_KEY"

Key hygiene. Treat keys as secrets. Never commit or embed in client-side code. If a key leaks, contact PolyAI to rotate immediately.

Agents API vs. Conversations API

These two get confused most often. Use this table to pick the right one.

	Agents API	Conversations API
Purpose	Build and deploy agents	Read call data and transcripts
Direction	Write (create, update, deploy)	Read (query, retrieve)
Base URL	`api.{region}.poly.ai/v1/agents/…`	`api.{region}.platform.polyai.app/v3/…`
Auth	API key (workspace-scoped)	API key (project-scoped)
Who uses it	Developers automating agent builds	Analysts, integrations pulling call data