Skip to main content
The Agents API is a set of REST endpoints for building and shipping PolyAI agents without the UI. It covers the full agent lifecycle: create the agent, branch for parallel work, edit behavior and knowledge, provision telephony, publish through environments, and tweak runtime values after launch. Use it when you want to automate agent setup from your own tooling — CRM workflows, CCaaS provisioning, internal platforms, or coding agents — instead of clicking through Agent Studio.
Also known as the builder APIs or Agent Studio APIs. This reference covers the same surface area.

​
How it differs from the Conversations API

The Agents API is the build and deploy layer. The Conversations API is the read and analyze layer. They’re separate services with separate base URLs, auth, and audiences.
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
If you want to ship an agent change, use the Agents API. If you want to know what happened in a call, use the Conversations API. See Getting started for the full distinction across all API families.

​
Resource model

The Agents API is organized around a small set of nested resources: 
agent
 ├── branch                 # isolated working copy
 │    ├── behavior          # system prompt and interaction rules
 │    ├── knowledge-base    # topics and RAG
 │    ├── attributes        # variant dimensions
 │    └── variants          # site-specific overrides
 ├── deployment             # published version per environment
 ├── telephony
 │    ├── connector         # voice-infra binding
 │    └── phone-number      # E.164 number routed to a connector
 └── real-time-config       # runtime values editable without publishing
Everything except deployments, telephony, and real-time configs is scoped to a branch. The default branch is main; create additional branches for parallel development and merge them back.

​
Base URL

The Agents API uses the same regional base URL family as Alerts and Webhooks:
RegionBase URL
UShttps://api.us.poly.ai
UKhttps://api.uk.poly.ai
EUhttps://api.eu.poly.ai
All Agents API paths are prefixed with /v1/agents.
Do not use https://api.poly.ai without a region prefix — it returns an error. Always include the region.

​
Authentication

All endpoints authenticate with an API key sent in the x-api-key header. Keys are scoped to a workspace. 
curl https://api.us.poly.ai/v1/agents \
  -H "x-api-key: YOUR_API_KEY"
API keys for the Agents API are not yet available through self-service. Email developers@poly.ai to request access.

​
Quick start

​
1. Create an agent

curl -X POST https://api.us.poly.ai/v1/agents \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "description": "Handles Tier 1 support for the US market"
  }'
The response includes an agentId and a default main branch.

​
2. Update the agent’s behavior

curl -X PATCH https://api.us.poly.ai/v1/agents/AGENT_ID/branches/main/behavior \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "behavior": "You are a friendly, concise support agent..."
  }'

​
3. Add a knowledge base topic

curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/branches/main/knowledge-base/topics \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Password reset",
    "content": "Users can reset their password by..."
  }'

​
4. Publish to sandbox

curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/deployments/publish \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "environment": "sandbox" }'

​
5. Promote to pre-release, then live

curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/deployments/DEPLOYMENT_ID/promote \
  -H "x-api-key: YOUR_API_KEY"

​
Environments

Deployments run in one of three environments:
EnvironmentPurpose
sandboxSafe space for testing without affecting production calls
pre-releaseStaging for final validation before going live
liveProduction — serves real customer traffic
Use publish to push a draft into sandbox, then promote to move through pre-release and live. Use rollback to revert a deployment. See Environments and versions for the full model.

​
Branches

Branches are isolated working copies of an agent. Create a branch for any non-trivial change: 
curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/branches \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "experiment-new-greeting" }'
Merge back to main when you’re ready: 
curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/branches/BRANCH_ID/merge \
  -H "x-api-key: YOUR_API_KEY"

​
Real-time configs

Real-time configs let you change runtime values (opening hours, seasonal messaging, holiday flags) without a publish cycle. Updates take effect immediately. Define a JSON Schema for a config page, then PATCH variables against it: 
curl -X PATCH https://api.us.poly.ai/v1/agents/AGENT_ID/real-time-configs/live/variables \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "variables": { "open_hour": 8, "close_hour": 22 } }'

​
Variants

Variants let you run one agent across many sites — hotel chains, restaurant groups, franchises — with site-specific values (phone number, address, hours). Define attributes (dimensions), then create variants (combinations). See Variant management for the conceptual model.

​
Error responses

StatusDescription
400Validation error - check request body or parameters
401Missing or invalid API key
403API key lacks permission for the workspace or resource
404Resource not found
409Conflict - e.g. merging a branch with diverged state
422Malformed ID or schema validation error
500Internal server error

​
Example error response

{
  "message": "Validation failed",
  "errors": [
    {
      "field": "name",
      "message": "must be between 1 and 128 characters"
    }
  ]
}

Environments and versions

How sandbox, pre-release, and live environments fit together.

Variant management

Run one agent across many sites with attribute-driven variants.

Telephony

Provision phone numbers and route them to connectors.

Managed topics

How knowledge base topics power retrieval and actions.
Last modified on April 22, 2026