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

# API reference

> Build, run, and observe PolyAI agents from your own systems. Three API families, one platform, 99.994% uptime in production.

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 →](https://docs.poly.ai/api-reference/quickstart.md)

[Browse APIs](#api-families)

[Error codes](https://docs.poly.ai/api-reference/error-codes.md)

{[
        { value: '3', label: 'API families' },
        { value: '99.994%', label: 'Uptime, trailing 12mo' },
        { value: '24+', label: 'Languages' },
        { value: '3', label: 'Regions: US · UK · EU' },
      ].map((s) => (
        <div key={s.label}>
          <div style={{ fontSize: '1.6rem', fontWeight: 700, color: '#d9ee50' }}>{s.value}</div>
          <div style={{ fontSize: '0.85rem', color: 'rgba(255, 255, 255, 0.7)', marginTop: '0.15rem' }}>{s.label}</div>
        </div>
      ))}

## The three API families

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

Build & deploy

### [Agents API](https://docs.poly.ai/api-reference/agents/introduction.md)

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

`api.{region}.poly.ai`

Runtime & data

### [Conversations, Chat, Handoff…](https://docs.poly.ai/api-reference/conversations/introduction.md)

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

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

Monitoring

### [Alerts & Webhooks](https://docs.poly.ai/api-reference/webhooks/introduction.md)

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.

> [card] [Build an agent from the API](https://docs.poly.ai/api-reference/quickstart.md)
>
> Full walkthrough: create → branch and configure → merge to Sandbox → test → promote to live.

> [card] [Pull conversation data](https://docs.poly.ai/api-reference/conversations/introduction.md)
>
> Query transcripts, metrics, and audio for analytics and compliance pipelines.

> [card] [Build & deploy an agent](https://docs.poly.ai/api-reference/agents/introduction.md)
>
> Create agents, edit behavior and knowledge, promote sandbox → pre-release → live.

> [card] [Get notified on events](https://docs.poly.ai/api-reference/webhooks/introduction.md)
>
> Register a webhook endpoint and receive signed POSTs on conversation and handoff events.

> [card] [Send a chat message](https://docs.poly.ai/api-reference/chat/introduction.md)
>
> Drive a text-based conversation programmatically with create, respond, close.

> [card] [Trigger an outbound call](https://docs.poly.ai/api-reference/outbound/introduction.md)
>
> 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.

{[
    { region: 'US', runtime: 'api.us-1.platform.polyai.app', build: 'api.us.poly.ai' },
    { region: 'UK', runtime: 'api.uk-1.platform.polyai.app', build: 'api.uk.poly.ai' },
    { region: 'EU', runtime: 'api.euw-1.platform.polyai.app', build: 'api.eu.poly.ai' },
    { region: 'Studio', runtime: 'api.studio.poly.ai', build: 'api.studio.poly.ai' },
  ].map((r) => (
    <div key={r.region} style={{
      padding: '1.1rem 1.2rem',
      borderRadius: '14px',
      border: '1px solid rgba(0,0,0,0.08)',
      background: 'rgba(217, 238, 80, 0.04)',
    }}>
      <div style={{ display: 'flex', alignItems: 'center', gap: '0.5rem', marginBottom: '0.6rem' }}>
        <Icon icon="location-dot" iconType="solid" size={18} color="#4a7c10" />
        <span style={{ fontWeight: 600, fontSize: '1rem' }}>{r.region}</span>
      </div>
      <div style={{ fontSize: '0.7rem', textTransform: 'uppercase', letterSpacing: '0.05em', color: '#386dbf', fontWeight: 600 }}>Runtime · data</div>
      <code style={{ display: 'block', fontSize: '0.8rem', marginBottom: '0.6rem', wordBreak: 'break-all' }}>{r.runtime}</code>
      <div style={{ fontSize: '0.7rem', textTransform: 'uppercase', letterSpacing: '0.05em', color: '#4a7c10', fontWeight: 600 }}>Build · monitoring</div>
      <code style={{ display: 'block', fontSize: '0.8rem', wordBreak: 'break-all' }}>{r.build}</code>
    </div>
  ))}

> [!WARNING]
>
> 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>/...
```

> [!NOTE]
>
> **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` |

> [!NOTE]
>
> 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](https://docs.poly.ai/secrets/api-keys.md)) — runtime and build keys are separate.

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X GET \
  "https://api.<region>.platform.polyai.app/v3/ws-xxxxxxxx/PROJECT-xxx/conversations" \
  -H "x-api-key: YOUR_API_KEY"
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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()
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

**v3**
Recommended

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

**v2**

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

**v1**
Sunsetting

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

## Browse the catalog

Every endpoint, grouped by API.

> [card] [Agents](https://docs.poly.ai/api-reference/agents/introduction.md)

> [card] [Conversations](https://docs.poly.ai/api-reference/conversations/introduction.md)

> [card] [Chat](https://docs.poly.ai/api-reference/chat/introduction.md)

> [card] [Debug Chat](https://docs.poly.ai/api-reference/debug-chat/introduction.md)

> [card] [Dialog-RSN-1](https://docs.poly.ai/api-reference/dialog-rsn-1/reference.md)

> [card] [Handoff](https://docs.poly.ai/api-reference/handoff/introduction.md)

> [card] [Outbound calling](https://docs.poly.ai/api-reference/outbound/introduction.md)

> [card] [Concurrent calls](https://docs.poly.ai/api-reference/concurrent-calls/introduction.md)

> [card] [DNI](https://docs.poly.ai/api-reference/dni/introduction.md)

> [card] [External events](https://docs.poly.ai/api-reference/external-events/introduction.md)

> [card] [Messaging](https://docs.poly.ai/api-reference/messaging/introduction.md)

> [card] [WebRTC gateway](https://docs.poly.ai/api-reference/webrtc-gateway/introduction.md)

> [card] [Alerts](https://docs.poly.ai/api-reference/alerts/introduction.md)

> [card] [Webhooks](https://docs.poly.ai/api-reference/webhooks/introduction.md)

> [card] [Error codes](https://docs.poly.ai/api-reference/error-codes.md)

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 →](https://docs.poly.ai/api-reference/quickstart.md)