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

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..poly.ai

Runtime & data

Conversations, Chat, Handoff…

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

api.-1.platform.polyai.app

Monitoring

Alerts & Webhooks

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

api..poly.ai

I want to…

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

Build an agent from the API

Full walkthrough: create → branch and configure → merge to Sandbox → test → promote to live.

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.

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. Create keys from the API Keys tab in Agent Studio (see API keys) — 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"

import requests

response = requests.get(
    "https://api.<region>.platform.polyai.app/v3/ws-xxxxxxxx/PROJECT-xxx/conversations",
    headers={"x-api-key": "YOUR_API_KEY"},
)
data = response.json()

const response = await fetch(
  "https://api.<region>.platform.polyai.app/v3/ws-xxxxxxxx/PROJECT-xxx/conversations",
  { headers: { "x-api-key": "YOUR_API_KEY" } },
);
const data = await response.json();

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

In short: Agents API creates and ships agents. Conversations API tells you what those agents did on calls.

Versioning

Only the Conversations API is versioned today. Everything else is unversioned.

Recommended

Event-sourced, scalable, full schema with latency and translation fields. Use for all new integrations.

Same schema as v3, legacy auth model. Continue if already integrated.

Sunsetting

Best-effort from 2 Mar 2026 · unsupported from 31 Aug 2026. Migrate to v3.

Browse the catalog

Every endpoint, grouped by API.

Agents

Conversations

Chat

Debug Chat

Handoff

Outbound calling

Concurrent calls

DNI

External events

Messaging

WebRTC gateway

Alerts

Webhooks

Error codes

Need a hand getting started?

Walk through building an agent end-to-end, from your first API key to a live deployment.

Start the quickstart →

API reference

Build & deploy

Runtime & data

Monitoring

Legacy

API reference

Build voice agents from code.

The three API families

Agents API

Conversations, Chat, Handoff…

Alerts & Webhooks

I want to…

Build an agent from the API

Pull conversation data

Build & deploy an agent

Get notified on events

Send a chat message

Trigger an outbound call

Pick your region

Finding your `account_id` and `project_id`

Authenticate

Agents API vs. Conversations API

Versioning

Browse the catalog

Agents

Conversations

Chat

Debug Chat

Handoff

Outbound calling

Concurrent calls

DNI

External events

Messaging

WebRTC gateway

Alerts

Webhooks

Error codes

​Build voice agents from code.

​The three API families

​Agents API

​Conversations, Chat, Handoff…

​Alerts & Webhooks

​I want to…

Build an agent from the API

Pull conversation data

Build & deploy an agent

Get notified on events

Send a chat message

Trigger an outbound call

​Pick your region

​Finding your account_id and project_id

​Authenticate

​Agents API vs. Conversations API

​Versioning

​Browse the catalog

Agents

Conversations

Chat

Debug Chat

Handoff

Outbound calling

Concurrent calls

DNI

External events

Messaging

WebRTC gateway

Alerts

Webhooks

Error codes

Build voice agents from code.

The three API families

Agents API

Conversations, Chat, Handoff…

Alerts & Webhooks

I want to…

Pick your region

Finding your `account_id` and `project_id`

Authenticate

Agents API vs. Conversations API

Versioning

Browse the catalog