> ## 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.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.poly.ai/feedback
```json
{
"path": "/api-reference/introduction",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Getting started
> The three PolyAI API families, regional base URLs, authentication with API keys, and Conversations API versioning.
Set up your API integration with PolyAI. Learn which API family to use, how to authenticate, and which version to pick for each integration.
## API families at a glance
PolyAI exposes three distinct API families, each with its own base URL pattern, auth model, and audience.
| Family | What it's for | Base URL pattern | Examples |
| ------------------ | --------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Build & deploy** | Programmatically build, configure, and ship agents | `api.{region}.poly.ai/v1/agents/…` | [Agents API](/api-reference/agents/introduction) |
| **Runtime & data** | Runtime interaction with an agent and post-call data | `api.{region}.platform.polyai.app/{version}/…` | [Chat](/api-reference/chat/introduction), [Conversations](/api-reference/conversations/introduction), [Handoff](/api-reference/handoff/introduction), [Concurrent Calls](/api-reference/concurrent-calls/introduction), [DNI](/api-reference/dni/introduction), [External Events](/api-reference/external-events/introduction), [Outbound Calling](/api-reference/outbound/introduction) |
| **Monitoring** | Observe, alert on, and receive events from running agents | `api.{region}.poly.ai/v1/…` | [Alerts](/api-reference/alerts/introduction), [Webhooks](/api-reference/webhooks/introduction) |
The **build & deploy** and **monitoring** families share the `poly.ai` host. The **runtime & data** family lives on `platform.polyai.app`. They are separate services with separate API keys.
### Agents API vs Conversations API
The two are frequently confused. 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.**
## Base URLs
### Runtime and data APIs (regional)
The Conversations, Chat, Handoff, Concurrent Calls, DNI, External Events, and Outbound Calling APIs use regional base URLs:
| Region | Base URL |
| ------ | --------------------------------------- |
| US | `https://api.us-1.platform.polyai.app` |
| UK | `https://api.uk-1.platform.polyai.app` |
| EUW | `https://api.euw-1.platform.polyai.app` |
Most endpoints follow this pattern:
`https://api.{region}.platform.polyai.app/{version}/{account_id}/{project_id}/…`
### Agents API, Alerts, and Webhooks
The [Agents API](/api-reference/agents/introduction), [Alerts API](/api-reference/alerts/introduction), and [Webhooks API](/api-reference/webhooks/introduction) use a separate set of regional base URLs:
| Region | Base URL |
| ------ | ------------------------ |
| US | `https://api.us.poly.ai` |
| UK | `https://api.uk.poly.ai` |
| EU | `https://api.eu.poly.ai` |
Endpoint patterns:
* Agents API: `https://api.{region}.poly.ai/v1/agents/…`
* Alerts, Webhooks: `https://api.{region}.poly.ai/v1/…`
Do not use `https://api.poly.ai` without a region prefix – it will return an error. Always include the region (e.g. `api.us.poly.ai`).
## Conversations API versions
Only the Conversations API is versioned. All other APIs are currently unversioned.
### v3 – current and recommended
v3 is the fully supported release of the Conversations API.
It runs on PolyAI's event-sourced data platform and improves on v1 by offering:
* reliable ingestion and querying at scale
* empty strings ("") instead of `null` for empty text fields
* additional turn-level fields such as `latency`, `translated_user_input` and `english_agent_response`
* consistent ISO8601 timestamps across conversations, turns, and metrics
Endpoint pattern:
`https://api.{region}.platform.polyai.app/v3/{account_id}/{project_id}/conversations`
Most customers should use v3, the latest most performant version.
Authentication for v3 is managed by PolyAI.
Ask your PolyAI representative to provision a v3 key and confirm the project and region it is scoped to.
### v2
v2 has the same schema as v3 but differs in authentication methods. Customers on v2 can continue using v2. New customers should use v3.
### v1 – legacy
v1 uses an earlier, less scalable data pipeline and the legacy auth model.
Endpoint pattern:
`https://api.{region}.platform.polyai.app/v1/{account_id}/{project_id}/conversations`
#### Deprecation plan
**v1 Conversations API is scheduled for deprecation.**
* **2 March 2026**: v1 moves to best-effort support (no SLA guarantees).
* **31 August 2026**: v1 remains available but no support will be provided.
Plan your migration to v3 before these dates.
### Which version should I use?
* All new integrations should use v3.
* Customers on v1 should plan their migration before support ends.
* v2 is only relevant for maintaining existing legacy integrations.
## Authentication
PolyAI uses API keys for all externally exposed endpoints.
Include your key using the `x-api-key` header:
```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X GET \
"https://api.us-1.platform.polyai.app/v3/ACCOUNT-xxx/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.us-1.platform.polyai.app/v3/ACCOUNT-xxx/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.us-1.platform.polyai.app/v3/ACCOUNT-xxx/PROJECT-xxx/conversations",
{
headers: { "x-api-key": "YOUR_API_KEY" },
}
);
const data = await response.json();
```
### API key provisioning
* Legacy (v1/v2) keys
May already exist and follow a legacy authentication model.
* Conversations API v3 keys
Keys are provisioned by PolyAI.
### Security notes
* Treat API keys as secrets.
* Never embed keys in client-side code or commit them to source control.
* If a key is exposed, contact PolyAI immediately so it can be rotated.