Skip to main content
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.
FamilyWhat it’s forBase URL patternExamples
Build & deployProgrammatically build, configure, and ship agentsapi.{region}.poly.ai/v1/agents/…Agents API
Runtime & dataRuntime interaction with an agent and post-call dataapi.{region}.platform.polyai.app/{version}/…Chat, Conversations, Handoff, Concurrent Calls, DNI, External Events, Outbound Calling
MonitoringObserve, alert on, and receive events from running agentsapi.{region}.poly.ai/v1/…Alerts, Webhooks
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 APIConversations API
PurposeBuild and deploy agentsRead call data and transcripts
DirectionWrite (create, update, deploy)Read (query, retrieve)
Base URLapi.{region}.poly.ai/v1/agents/…api.{region}.platform.polyai.app/v3/…
AuthAPI key (workspace-scoped)API key (project-scoped)
Who uses itDevelopers automating agent buildsAnalysts, 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:
RegionBase URL
UShttps://api.us-1.platform.polyai.app
UKhttps://api.uk-1.platform.polyai.app
EUWhttps://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, Alerts API, and Webhooks API use a separate set of regional base URLs:
RegionBase URL
UShttps://api.us.poly.ai
UKhttps://api.uk.poly.ai
EUhttps://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 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: 
curl -X GET \
  "https://api.us-1.platform.polyai.app/v3/ACCOUNT-xxx/PROJECT-xxx/conversations" \
  -H "x-api-key: YOUR_API_KEY"

​
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.
Last modified on April 22, 2026