Agents API

Build, configure, and deploy PolyAI agents programmatically. Manage agents, branches, knowledge bases, telephony, and deployments from your own systems.

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

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:

account
 ├── agent                  # top-level agent resource (created/listed under account)
 └── voice-library          # account-scoped voice catalog (register, list, sample)

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

Agents and voice library entries are scoped to an account. Everything inside an agent 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:

Region	Base URL
US	https://api.us.poly.ai
EU	https://api.eu.poly.ai
UK	https://api.uk.poly.ai
Studio	https://api.studio.poly.ai

Most Agents API paths are prefixed with /v1/agents/{agentId}/…. Account-scoped endpoints (listing/creating agents, voice library) are prefixed with /v1/accounts/{accountId}/….

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/accounts/ACCOUNT_ID/agents \
  -H "x-api-key: YOUR_API_KEY"

Create a workspace-scoped key from the API Keys tab on your workspace homepage in Agent Studio — see API keys. Copy it when it’s shown; the full value only appears once.

Identifiers

Agent Studio labels and API parameters use different names for the same things. ACCOUNT_ID above is your account ID — Agent Studio’s UI calls it the Workspace ID and shows it prefixed (ws-xxxxxxxx):

Agent Studio label	API parameter	Example
Workspace ID	accountId	ws-fd112d8f
Project ID / Agent ID	agentId	PROJECT-58RP822I

Agent ID is the same value as Project ID. “Agent” is the current product name; “Project” is the legacy term still surfaced in some Agent Studio screens and URLs, and used by the Conversations and Chat APIs. Use the value you see in Agent Studio directly — no transformation needed.

Quick start

main is read-only — behavior and knowledge base writes go to a branch, which you then merge into main. Merging publishes to Sandbox automatically. For the full walkthrough (create → configure → test → deploy → observe), see the API quickstart.

1. Create an agent

curl -X POST https://api.us.poly.ai/v1/accounts/ACCOUNT_ID/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. Create a working branch

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 '{ "branchName": "quickstart" }'

The response returns a branchId — use it for the edits below.

3. Update the behavior and add a topic

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

curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/branches/BRANCH_ID/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. Merge to main (publishes to Sandbox)

curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/branches/BRANCH_ID/merge \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "deploymentMessage": "Initial support agent" }'

5. Promote to pre-release, then live

Fetch the active Sandbox deployment’s id (GET /v1/agents/AGENT_ID/deployments/active), then promote it. Each promote returns the next environment’s deployment.id:

curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/deployments/DEPLOYMENT_ID/promote \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "targetEnvironment": "pre-release" }'

Environments

Deployments run in one of three environments:

Environment	Purpose
sandbox	Safe space for testing without affecting production calls
pre-release	Staging for final validation before going live
live	Production — serves real customer traffic

Merging a branch into main publishes the result to sandbox; from there, promote moves it through pre-release and live, and rollback reverts a deployment. (The standalone publish endpoint deploys the current main draft to sandbox — redundant right after a merge, which already does this.) See Environments for the full model.

Branches

Branches are isolated working copies of an agent. Because main can’t be written to directly, every behavior, knowledge base, or variant change starts on a branch:

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 '{ "branchName": "experiment-new-greeting" }'

Merge back to main when you’re ready — this also publishes the result to Sandbox:

curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/branches/BRANCH_ID/merge \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "deploymentMessage": "Update greeting" }'

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 Variants for the conceptual model.

Error responses

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

Example error response

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

Related

Environments

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

Variants

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

Telephony

Provision phone numbers and route them to connectors.

FAQs

How knowledge base topics power retrieval and actions.