Skip to main content
Welcome to the PolyAI API documentation. This page gives you the minimum you need before wiring anything up: regions, API surface, versions, and authentication.

​
Regional API endpoints

PolyAI provides regional API endpoints to keep latency low and meet data residency requirements. Use the base URL that matches your deployment region:
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}/… Check each API’s page for exact paths and parameters.

​
API surface

The externally documented APIs are:
  • Chat API – drive chat channels programmatically (WhatsApp, in-app widgets, email, and more).
  • Conversations API – fetch full conversation records for analytics and data pipelines.
  • Handoff API – query handoff state for live-agent integrations.
  • Concurrent Calls API – retrieve concurrency statistics over time windows.
  • DNI API – reserve numbers for Dynamic Number Insertion journeys.
  • External Events API – allow external providers to POST results into active conversations.
All APIs share the same regional base URLs; each has its own path and authentication model described on its page.

​
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 internally 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

Notice: v1 Conversations API is scheduled for deprecation. On 2 March 2026, v1 will move to best-effort support (no SLA guarantees). On 31 August 2026, v1 will remain available but no support will be provided.

​
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 internal integrations.

​
Authentication

PolyAI uses API keys for all externally exposed endpoints. Include your key using the x-api-key header: 
GET /polyai-endpoint HTTP/1.1
Host: api.{region}.platform.polyai.app
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.