> ## 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, sub-300ms calls in production.

<div
  style={{
position: 'relative',
margin: '0 0 2.5rem',
padding: '2.5rem 2rem',
borderRadius: '20px',
background: 'linear-gradient(135deg, #4a7c10 0%, #3a6b08 55%, #1f3a04 100%)',
color: '#f9faf3',
overflow: 'hidden',
boxShadow: '0 24px 60px -28px rgba(74, 124, 16, 0.45)',
}}
>
  <div
    style={{
position: 'absolute',
top: '-40%',
right: '-10%',
width: '420px',
height: '420px',
background: 'radial-gradient(closest-side, rgba(217, 238, 80, 0.35), transparent 70%)',
pointerEvents: 'none',
}}
  />

  <div
    style={{
position: 'absolute',
bottom: '-50%',
left: '-10%',
width: '380px',
height: '380px',
background: 'radial-gradient(closest-side, rgba(217, 238, 80, 0.18), transparent 70%)',
pointerEvents: 'none',
}}
  />

  <div style={{ position: 'relative', maxWidth: '780px' }}>
    <div
      style={{
  display: 'inline-flex',
  alignItems: 'center',
  gap: '0.5rem',
  padding: '0.35rem 0.8rem',
  borderRadius: '999px',
  background: 'rgba(217, 238, 80, 0.18)',
  border: '1px solid rgba(217, 238, 80, 0.35)',
  fontSize: '0.8rem',
  fontWeight: 500,
  letterSpacing: '0.04em',
  textTransform: 'uppercase',
  color: '#d9ee50',
}}
    >
      <span
        style={{
    width: '8px',
    height: '8px',
    borderRadius: '50%',
    background: '#d9ee50',
    boxShadow: '0 0 12px #d9ee50',
  }}
      />

      PolyAI Platform · API Reference
    </div>

    <h1
      style={{
  margin: '1rem 0 0.6rem',
  fontSize: '2.6rem',
  lineHeight: 1.1,
  fontWeight: 700,
  color: '#fff',
}}
    >
      Build voice agents from code.
    </h1>

    <p
      style={{
  margin: '0 0 1.6rem',
  fontSize: '1.1rem',
  lineHeight: 1.5,
  color: 'rgba(255, 255, 255, 0.85)',
  maxWidth: '640px',
}}
    >
      Three REST API families cover the full lifecycle — ship agents, run conversations, and observe everything in production. No SDK required.
    </p>

    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem' }}>
      <a
        href="/api-reference/quickstart"
        style={{
    display: 'inline-flex',
    alignItems: 'center',
    gap: '0.5rem',
    padding: '0.7rem 1.2rem',
    borderRadius: '12px',
    background: '#d9ee50',
    color: '#1f3a04',
    fontWeight: 600,
    textDecoration: 'none',
    boxShadow: '0 8px 24px -8px rgba(217, 238, 80, 0.55)',
  }}
      >
        Quickstart →
      </a>

      <a
        href="#api-families"
        style={{
    display: 'inline-flex',
    alignItems: 'center',
    gap: '0.5rem',
    padding: '0.7rem 1.2rem',
    borderRadius: '12px',
    background: 'rgba(255, 255, 255, 0.08)',
    border: '1px solid rgba(255, 255, 255, 0.18)',
    color: '#fff',
    fontWeight: 500,
    textDecoration: 'none',
  }}
      >
        Browse APIs
      </a>

      <a
        href="/api-reference/error-codes"
        style={{
    display: 'inline-flex',
    alignItems: 'center',
    gap: '0.5rem',
    padding: '0.7rem 1.2rem',
    borderRadius: '12px',
    background: 'transparent',
    border: '1px solid rgba(255, 255, 255, 0.18)',
    color: 'rgba(255, 255, 255, 0.85)',
    fontWeight: 500,
    textDecoration: 'none',
  }}
      >
        Error codes
      </a>
    </div>
  </div>

  {/* Stat strip */}

  <div
    style={{
position: 'relative',
marginTop: '2rem',
paddingTop: '1.4rem',
borderTop: '1px solid rgba(255, 255, 255, 0.12)',
display: 'grid',
gridTemplateColumns: 'repeat(auto-fit, minmax(140px, 1fr))',
gap: '1.2rem',
}}
  >
    {[
            { value: '3', label: 'API families' },
            { value: '< 300ms', label: 'Median agent latency' },
            { 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>
          ))}
  </div>
</div>

<h2 id="api-families" style={{ marginTop: '2.5rem', marginBottom: '0.25rem' }}>The three API families</h2>

<p style={{ color: 'var(--tw-prose-body, #4b5563)', margin: '0 0 1.5rem' }}>
  Pick the family that matches your job. Each has its own base URL, key, and audience.
</p>

<div
  style={{
display: 'grid',
gridTemplateColumns: 'repeat(auto-fit, minmax(280px, 1fr))',
gap: '1.2rem',
marginBottom: '2.5rem',
}}
>
  <a
    href="/api-reference/agents/introduction"
    style={{
display: 'block',
padding: '1.5rem',
borderRadius: '16px',
background: 'linear-gradient(160deg, rgba(74, 124, 16, 0.06), rgba(74, 124, 16, 0.01))',
border: '1px solid rgba(74, 124, 16, 0.18)',
textDecoration: 'none',
color: 'inherit',
transition: 'transform 160ms ease, box-shadow 160ms ease',
}}
  >
    <div style={{
          width: '44px',
          height: '44px',
          borderRadius: '12px',
          background: '#4a7c10',
          color: '#d9ee50',
          display: 'inline-flex',
          alignItems: 'center',
          justifyContent: 'center',
          fontSize: '1.3rem',
          marginBottom: '0.9rem',
        }}>🛠️</div>

    <div style={{ fontSize: '0.75rem', fontWeight: 600, letterSpacing: '0.06em', textTransform: 'uppercase', color: '#4a7c10' }}>
      Build & deploy
    </div>

    <h3 style={{ margin: '0.3rem 0 0.5rem', fontSize: '1.25rem' }}>Agents API</h3>

    <p style={{ margin: '0 0 0.8rem', fontSize: '0.95rem', color: '#4b5563', lineHeight: 1.5 }}>
      Programmatically create agents, edit behavior and knowledge, branch, and ship through environments.
    </p>

    <code style={{ fontSize: '0.78rem', color: '#3a6b08', background: 'rgba(74, 124, 16, 0.08)', padding: '0.2rem 0.5rem', borderRadius: '6px' }}>
      api.{`{region}`}.poly.ai
    </code>
  </a>

  <a
    href="/api-reference/conversations/introduction"
    style={{
display: 'block',
padding: '1.5rem',
borderRadius: '16px',
background: 'linear-gradient(160deg, rgba(56, 109, 191, 0.06), rgba(56, 109, 191, 0.01))',
border: '1px solid rgba(56, 109, 191, 0.2)',
textDecoration: 'none',
color: 'inherit',
}}
  >
    <div style={{
          width: '44px',
          height: '44px',
          borderRadius: '12px',
          background: '#386dbf',
          color: '#fff',
          display: 'inline-flex',
          alignItems: 'center',
          justifyContent: 'center',
          fontSize: '1.3rem',
          marginBottom: '0.9rem',
        }}>⚡</div>

    <div style={{ fontSize: '0.75rem', fontWeight: 600, letterSpacing: '0.06em', textTransform: 'uppercase', color: '#386dbf' }}>
      Runtime & data
    </div>

    <h3 style={{ margin: '0.3rem 0 0.5rem', fontSize: '1.25rem' }}>Conversations, Chat, Handoff…</h3>

    <p style={{ margin: '0 0 0.8rem', fontSize: '0.95rem', color: '#4b5563', lineHeight: 1.5 }}>
      Interact with running agents and read post-call data. Transcripts, audio, metrics, sessions.
    </p>

    <code style={{ fontSize: '0.78rem', color: '#244a86', background: 'rgba(56, 109, 191, 0.08)', padding: '0.2rem 0.5rem', borderRadius: '6px' }}>
      api.{`{region}`}-1.platform.polyai.app
    </code>
  </a>

  <a
    href="/api-reference/webhooks/introduction"
    style={{
display: 'block',
padding: '1.5rem',
borderRadius: '16px',
background: 'linear-gradient(160deg, rgba(180, 90, 30, 0.07), rgba(180, 90, 30, 0.01))',
border: '1px solid rgba(180, 90, 30, 0.2)',
textDecoration: 'none',
color: 'inherit',
}}
  >
    <div style={{
          width: '44px',
          height: '44px',
          borderRadius: '12px',
          background: '#b45a1e',
          color: '#fff',
          display: 'inline-flex',
          alignItems: 'center',
          justifyContent: 'center',
          fontSize: '1.3rem',
          marginBottom: '0.9rem',
        }}>📡</div>

    <div style={{ fontSize: '0.75rem', fontWeight: 600, letterSpacing: '0.06em', textTransform: 'uppercase', color: '#b45a1e' }}>
      Monitoring
    </div>

    <h3 style={{ margin: '0.3rem 0 0.5rem', fontSize: '1.25rem' }}>Alerts & Webhooks</h3>

    <p style={{ margin: '0 0 0.8rem', fontSize: '0.95rem', color: '#4b5563', lineHeight: 1.5 }}>
      Receive real-time events when calls complete, alerts fire, or handoffs happen. Stop polling.
    </p>

    <code style={{ fontSize: '0.78rem', color: '#7a3a10', background: 'rgba(180, 90, 30, 0.08)', padding: '0.2rem 0.5rem', borderRadius: '6px' }}>
      api.{`{region}`}.poly.ai
    </code>
  </a>
</div>

<h2 style={{ marginTop: '2rem', marginBottom: '0.25rem' }}>I want to...</h2>

<p style={{ color: 'var(--tw-prose-body, #4b5563)', margin: '0 0 1.5rem' }}>
  Task-oriented entry points. Jump straight to a working example.
</p>

<CardGroup cols={2}>
  <Card title="Make my first API call" icon="rocket" href="/api-reference/quickstart">
    Full walkthrough: key → list conversations → fetch transcript → audio → webhooks.
  </Card>

  <Card title="Pull conversation data" icon="database" href="/api-reference/conversations/introduction">
    Query transcripts, metrics, and audio for analytics and compliance pipelines.
  </Card>

  <Card title="Build & deploy an agent" icon="hammer" href="/api-reference/agents/introduction">
    Create agents, edit behavior and knowledge, promote sandbox → pre-release → live.
  </Card>

  <Card title="Get notified on events" icon="bell" href="/api-reference/webhooks/introduction">
    Register a webhook endpoint and receive signed POSTs on conversation and handoff events.
  </Card>

  <Card title="Send a chat message" icon="comments" href="/api-reference/chat/introduction">
    Drive a text-based conversation programmatically with create, respond, close.
  </Card>

  <Card title="Trigger an outbound call" icon="phone-arrow-up-right" href="/api-reference/outbound/introduction">
    Place a programmatic outbound call to a target number and track its status.
  </Card>
</CardGroup>

<h2 style={{ marginTop: '2.5rem' }}>Pick your region</h2>

<p style={{ color: 'var(--tw-prose-body, #4b5563)', margin: '0 0 1.25rem' }}>
  Your key is provisioned to a region. The host differs by API family — the platform.polyai.app host carries a <code>-1</code> suffix, the poly.ai host doesn't.
</p>

<div
  style={{
display: 'grid',
gridTemplateColumns: 'repeat(auto-fit, minmax(260px, 1fr))',
gap: '1rem',
marginBottom: '1.5rem',
}}
>
  {[
      { flag: '🇺🇸', region: 'US', runtime: 'api.us-1.platform.polyai.app', build: 'api.us.poly.ai' },
      { flag: '🇬🇧', region: 'UK', runtime: 'api.uk-1.platform.polyai.app', build: 'api.uk.poly.ai' },
      { flag: '🇪🇺', region: 'EU', runtime: 'api.euw-1.platform.polyai.app', build: 'api.eu.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' }}>
          <span style={{ fontSize: '1.4rem' }}>{r.flag}</span>
          <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>
    ))}
</div>

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

### 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.
</Note>

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.
</Note>

<h2 style={{ marginTop: '2.5rem' }}>Authenticate</h2>

<p style={{ color: 'var(--tw-prose-body, #4b5563)', margin: '0 0 1rem' }}>
  Every PolyAI API uses an API key sent in the <code>x-api-key</code> header. Keys are provisioned by PolyAI — runtime and build keys are separate.
</p>

<CodeGroup>
  ```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();
  ```
</CodeGroup>

<div
  style={{
marginTop: '1rem',
padding: '1rem 1.25rem',
borderRadius: '12px',
background: 'rgba(217, 238, 80, 0.12)',
border: '1px solid rgba(74, 124, 16, 0.2)',
fontSize: '0.92rem',
}}
>
  <strong>Key hygiene.</strong> Treat keys as secrets. Never commit or embed in client-side code. If a key leaks, contact PolyAI to rotate immediately.
</div>

<h2 style={{ marginTop: '2.5rem' }}>Agents API vs. Conversations API</h2>

<p style={{ color: 'var(--tw-prose-body, #4b5563)', margin: '0 0 1rem' }}>
  These two get confused most often. Use this table to pick the right one.
</p>

|                 | 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.**

<h2 style={{ marginTop: '2.5rem' }}>Versioning</h2>

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

<div
  style={{
display: 'grid',
gridTemplateColumns: 'repeat(auto-fit, minmax(220px, 1fr))',
gap: '1rem',
margin: '1rem 0 1.5rem',
}}
>
  <div
    style={{
padding: '1rem 1.2rem',
borderRadius: '14px',
border: '2px solid #4a7c10',
background: 'rgba(74, 124, 16, 0.05)',
}}
  >
    <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', marginBottom: '0.5rem' }}>
      <strong style={{ fontSize: '1.1rem' }}>v3</strong>
      <span style={{ fontSize: '0.7rem', fontWeight: 600, padding: '0.15rem 0.5rem', borderRadius: '999px', background: '#4a7c10', color: '#fff' }}>Recommended</span>
    </div>

    <p style={{ margin: 0, fontSize: '0.9rem', color: '#374151' }}>
      Event-sourced, scalable, full schema with latency and translation fields. Use for all new integrations.
    </p>
  </div>

  <div
    style={{
padding: '1rem 1.2rem',
borderRadius: '14px',
border: '1px solid rgba(0,0,0,0.1)',
}}
  >
    <strong style={{ fontSize: '1.1rem' }}>v2</strong>

    <p style={{ margin: '0.5rem 0 0', fontSize: '0.9rem', color: '#374151' }}>
      Same schema as v3, legacy auth model. Continue if already integrated.
    </p>
  </div>

  <div
    style={{
padding: '1rem 1.2rem',
borderRadius: '14px',
border: '1px solid rgba(180, 90, 30, 0.3)',
background: 'rgba(180, 90, 30, 0.04)',
}}
  >
    <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', marginBottom: '0.5rem' }}>
      <strong style={{ fontSize: '1.1rem' }}>v1</strong>
      <span style={{ fontSize: '0.7rem', fontWeight: 600, padding: '0.15rem 0.5rem', borderRadius: '999px', background: '#b45a1e', color: '#fff' }}>Sunsetting</span>
    </div>

    <p style={{ margin: 0, fontSize: '0.9rem', color: '#374151' }}>
      Best-effort from 2 Mar 2026 · unsupported from 31 Aug 2026. Migrate to v3.
    </p>
  </div>
</div>

<h2 style={{ marginTop: '2.5rem' }}>Browse the catalog</h2>

<p style={{ color: 'var(--tw-prose-body, #4b5563)', margin: '0 0 1rem' }}>
  Every endpoint, grouped by API.
</p>

<CardGroup cols={3}>
  <Card title="Agents" icon="hammer" href="/api-reference/agents/introduction" />

  <Card title="Conversations v3" icon="comments" href="/api-reference/conversations/introduction" />

  <Card title="Chat" icon="message" href="/api-reference/chat/introduction" />

  <Card title="Data" icon="database" href="/api-reference/data/introduction" />

  <Card title="Handoff" icon="people-arrows" href="/api-reference/handoff/introduction" />

  <Card title="Outbound calling" icon="phone-arrow-up-right" href="/api-reference/outbound/introduction" />

  <Card title="Concurrent calls" icon="gauge-high" href="/api-reference/concurrent-calls/introduction" />

  <Card title="DNI" icon="hashtag" href="/api-reference/dni/introduction" />

  <Card title="External events" icon="bolt" href="/api-reference/external-events/introduction" />

  <Card title="Messaging" icon="paper-plane" href="/api-reference/messaging/introduction" />

  <Card title="WebRTC gateway" icon="signal" href="/api-reference/webrtc-gateway/introduction" />

  <Card title="Alerts" icon="bell" href="/api-reference/alerts/introduction" />

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks/introduction" />

  <Card title="Error codes" icon="circle-exclamation" href="/api-reference/error-codes" />
</CardGroup>

<div
  style={{
marginTop: '2.5rem',
padding: '1.5rem 1.75rem',
borderRadius: '16px',
background: 'linear-gradient(135deg, rgba(74, 124, 16, 0.08), rgba(217, 238, 80, 0.12))',
border: '1px solid rgba(74, 124, 16, 0.15)',
display: 'flex',
flexWrap: 'wrap',
gap: '1.2rem',
alignItems: 'center',
justifyContent: 'space-between',
}}
/>