API quickstart - PolyAI Platform

This guide builds an agent from scratch through the API alone — no flow-building in the Agent Studio UI. By the end you’ll have created an agent, given it a behavior and a knowledge base topic, held a test conversation with it, and promoted it to production. Every step below has a curl and a Python tab. The Python snippets run top to bottom as one script — each reuses variables (agent_id, branch_id, …) set by the step before — so copy them in order. For an overview of the API families, see the API overview. This page uses the Agents API to build and ship, and the Debug Chat API to test — the same API key and host work for both.

What you’ll build

1. Create

Stand up a new agent with a greeting.

2. Configure

Branch, add a behavior and a knowledge base topic, then merge.

3. Test

Hold a live conversation with it in Sandbox.

4. Deploy

Promote through Pre-release into Live traffic.

5. Observe

Pull back the conversations it has.

Prerequisites

Get access to a PolyAI workspace

You build agents inside a PolyAI workspace, so you need access to one first.

Enterprise customers — PolyAI provisions your workspace during onboarding; your PolyAI representative sets it up and grants you access. Enterprise workspaces are region-specific (US, UK, or EU).
Getting started via the website — sign up at poly.ai to create a self-serve workspace, which lives in the Studio region.

Get an API key

Create a workspace-scoped API key from the API Keys tab on your workspace homepage in Agent Studio (see API keys). Copy the value when it’s shown — the full key only appears once. The same key authenticates the Agents API and the Data API’s debug chat — everything through step 4 of this guide.

Step 5 (pulling call data back out) uses the Conversations v3 API, which needs a separate project-scoped key. The Chat API needs its own connector token too. Request either only once you’re integrating a real channel or data pipeline — you don’t need them for steps 1–4.

Treat the key like a password. Don’t commit it or put it in client-side code.

Find your account ID

Open Agent Studio. Your account ID is the first path segment in the URL:

https://studio.{region}.poly.ai/{account_id}/{project_id}/agent

For example, https://studio.uk.poly.ai/acme-uk/acme-team-4/agent → account_id=acme-uk.

“Account ID” and “Workspace ID” are the same thing. Agent Studio’s UI calls this the Workspace ID and shows it in a prefixed form (ws-xxxxxxxx). The API parameter is named accountId (Agents and Data APIs) or account_id (Conversations, Chat, Webhooks, and most other APIs) — same value, different casing convention depending on which API family you’re calling. Both the slug form from the URL (acme-uk) and the prefixed form (ws-xxxxxxxx) work in API calls.

Pick the right base URL

The Agents and Data APIs — everything in steps 1–4 of this guide — share one regional host family:

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

The Conversations v3 API (used in step 5) is on a different host — api.{region}-1.platform.polyai.app, with a -1 suffix. Mixing these up is the most common cause of 404s. See base URLs for the full table across every API family.

Set environment variables

export POLYAI_API_KEY="your_api_key_here"
export POLYAI_BASE_URL="https://api.us.poly.ai"
export POLYAI_ACCOUNT_ID="ws-xxxxxxxx"

All examples below assume these are set.

Step 1: Create an agent

curl -X POST "$POLYAI_BASE_URL/v1/accounts/$POLYAI_ACCOUNT_ID/agents" \
  -H "x-api-key: $POLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "responseSettings": {
      "greeting": "Hi, thanks for calling Acme Corp. How can I help?"
    }
  }'

import os
import requests

base_url = os.environ["POLYAI_BASE_URL"]
account_id = os.environ["POLYAI_ACCOUNT_ID"]
headers = {"x-api-key": os.environ["POLYAI_API_KEY"]}

response = requests.post(
    f"{base_url}/v1/accounts/{account_id}/agents",
    headers=headers,
    json={
        "name": "Support Agent",
        "responseSettings": {
            "greeting": "Hi, thanks for calling Acme Corp. How can I help?",
        },
    },
)
response.raise_for_status()
agent_id = response.json()["agentId"]
print(agent_id)

Response

{
  "accountId": "ws-xxxxxxxx",
  "agentId": "PROJECT-58RP822I",
  "agentName": "Support Agent",
  "createdAt": "2026-07-02T10:00:00.000Z",
  "updatedAt": "2026-07-02T10:00:00.000Z",
  "branchCount": 1
}

Save agentId — every remaining call in this guide uses it. The agent starts with one branch, main.

export POLYAI_AGENT_ID="PROJECT-58RP822I"  # use the agentId from your response

Step 2: Configure it

You can’t edit main directly — the API rejects writes to it with 422 Cannot directly update main branch. Instead, create a working branch, make your edits there, then merge it back into main. This is the same branch-and-merge model Agent Studio and Studio Assistant use. Create a working branch:

curl -X POST "$POLYAI_BASE_URL/v1/agents/$POLYAI_AGENT_ID/branches" \
  -H "x-api-key: $POLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "branchName": "quickstart" }'

response = requests.post(
    f"{base_url}/v1/agents/{agent_id}/branches",
    headers=headers,
    json={"branchName": "quickstart"},
)
response.raise_for_status()
branch_id = response.json()["branchId"]
print(branch_id)

The response returns the branch’s ID — save it, every edit below targets it:

{ "branchId": "BRANCH-F9F1WNN8", "sequenceId": "1" }

export POLYAI_BRANCH_ID="BRANCH-F9F1WNN8"  # use the branchId from your response

Set the behavior

The behavior is the system prompt that governs how the agent responds.

curl -X PATCH "$POLYAI_BASE_URL/v1/agents/$POLYAI_AGENT_ID/branches/$POLYAI_BRANCH_ID/behavior" \
  -H "x-api-key: $POLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "behavior": "You are a friendly, concise support agent for Acme Corp. Answer questions using the knowledge base. If you cannot help, offer to hand off to a human agent."
  }'

requests.patch(
    f"{base_url}/v1/agents/{agent_id}/branches/{branch_id}/behavior",
    headers=headers,
    json={
        "behavior": "You are a friendly, concise support agent for Acme Corp. "
        "Answer questions using the knowledge base. If you cannot help, "
        "offer to hand off to a human agent.",
    },
).raise_for_status()

Add a knowledge base topic

Topics are what the agent draws on to answer questions — each one pairs content with example queries that should trigger it.

curl -X POST "$POLYAI_BASE_URL/v1/agents/$POLYAI_AGENT_ID/branches/$POLYAI_BRANCH_ID/knowledge-base/topics" \
  -H "x-api-key: $POLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Password reset",
    "content": "Users can reset their password at acme.com/reset. Resets take effect immediately and any active sessions are logged out.",
    "exampleQueries": {
      "queries": ["How do I reset my password?", "I forgot my password"]
    }
  }'

requests.post(
    f"{base_url}/v1/agents/{agent_id}/branches/{branch_id}/knowledge-base/topics",
    headers=headers,
    json={
        "name": "Password reset",
        "content": "Users can reset their password at acme.com/reset. Resets take "
        "effect immediately and any active sessions are logged out.",
        "exampleQueries": {
            "queries": ["How do I reset my password?", "I forgot my password"],
        },
    },
).raise_for_status()

See Knowledge base for the full schema, including actions and isActive.

Merge the branch into `main`

Merging applies the branch’s edits to main and publishes them to Sandbox in one step — there’s no separate publish call.

curl -X POST "$POLYAI_BASE_URL/v1/agents/$POLYAI_AGENT_ID/branches/$POLYAI_BRANCH_ID/merge" \
  -H "x-api-key: $POLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "deploymentMessage": "Initial support agent" }'

response = requests.post(
    f"{base_url}/v1/agents/{agent_id}/branches/{branch_id}/merge",
    headers=headers,
    json={"deploymentMessage": "Initial support agent"},
)
response.raise_for_status()
print(response.json()["message"])

{ "sequence": "2", "message": "Branch merged to main and deployed to sandbox", "testRunIds": [] }

Step 3: Test it

Your merge in step 2 already published to Sandbox, so the agent is live there and ready to talk. Hold a test conversation using the Debug Chat API — it authenticates with the same key and host as the Agents API, so there’s no extra credential to request.

Edits reach an environment only when you merge or promote into it. If debug chat replies with stale behavior, you edited the branch but haven’t merged it to main. Merge again to push the change into Sandbox.

Prefer a UI? Agent Studio has a built-in Test panel that talks to a branch directly, no merge required — see Test your agent.

Start a session:

curl -X POST "$POLYAI_BASE_URL/v1/agents/$POLYAI_AGENT_ID/debug-chat" \
  -H "x-api-key: $POLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "clientEnv": "sandbox" }'

response = requests.post(
    f"{base_url}/v1/agents/{agent_id}/debug-chat",
    headers=headers,
    json={"clientEnv": "sandbox"},
)
response.raise_for_status()
conversation_id = response.json()["conversationId"]
print(response.json()["response"])  # the greeting

{
  "conversationId": "AS_CHAT_106b4f9a-2541-4924-9ea1-fe5ced3c1eec",
  "userInput": "",
  "response": "Hi, thanks for calling Acme Corp. How can I help?",
  "metadata": { "citedTopic": "", "retrievedTopics": [], "nodeTrace": [] },
  "conversationEnded": false,
  "delayedResponse": false
}

(metadata has more fields than shown — trimmed here for readability. The conversationId is an AS_CHAT_… string; the curl examples below hard-code the one from this response — swap in your own.) Send a message — try the knowledge base topic you just added:

curl -X POST "$POLYAI_BASE_URL/v1/agents/$POLYAI_AGENT_ID/debug-chat/AS_CHAT_106b4f9a-2541-4924-9ea1-fe5ced3c1eec" \
  -H "x-api-key: $POLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientEnv": "sandbox",
    "message": "I forgot my password"
  }'

response = requests.post(
    f"{base_url}/v1/agents/{agent_id}/debug-chat/{conversation_id}",
    headers=headers,
    json={"clientEnv": "sandbox", "message": "I forgot my password"},
)
response.raise_for_status()
body = response.json()
print(body["response"])
print(body["metadata"]["retrievedTopics"])  # ['Password reset']

The agent answers from the topic you added:

{
  "conversationId": "AS_CHAT_106b4f9a-2541-4924-9ea1-fe5ced3c1eec",
  "response": "No problem — you can reset your password at acme.com/reset. It takes effect immediately and any active sessions are logged out.",
  "metadata": { "retrievedTopics": ["Password reset"] },
  "conversationEnded": false
}

To confirm the topic was actually used, check metadata.retrievedTopics — it lists the knowledge base topics the agent pulled in (["Password reset"] here), a more reliable signal than scanning the reply text for acme.com/reset. Keep sending messages against the same conversationId to continue the conversation, matching clientEnv to whichever environment you’re checking.

Building a real webchat, SMS, or in-app integration instead of a one-off test? Use the Chat API — it’s built for driving conversations from an end-user-facing client and requires its own connector token.

Step 4: Deploy it

Sandbox is for testing, not customer traffic. Promote the Sandbox deployment through Pre-release and into Live — that’s what real callers hit. See Environments for the full model. Promotion works on a deployment ID, and the merge in step 2 didn’t return one — so fetch the active Sandbox deployment first:

curl -X GET "$POLYAI_BASE_URL/v1/agents/$POLYAI_AGENT_ID/deployments/active" \
  -H "x-api-key: $POLYAI_API_KEY"

response = requests.get(
    f"{base_url}/v1/agents/{agent_id}/deployments/active",
    headers=headers,
)
response.raise_for_status()
deployment_id = response.json()["activeDeployments"]["sandbox"]["id"]
print(deployment_id)

{
  "activeDeployments": {
    "sandbox":     { "id": "019f380c-4235-7ea5-8426-1edf249cd6f3", "environment": "sandbox" },
    "pre-release": null,
    "live":        null
  }
}

export POLYAI_DEPLOYMENT_ID="019f380c-4235-7ea5-8426-1edf249cd6f3"  # activeDeployments.sandbox.id

Then promote it up the chain. Each promote returns a new deployment under deployment.id for the target environment — feed that into the next call:

# sandbox -> pre-release
curl -X POST "$POLYAI_BASE_URL/v1/agents/$POLYAI_AGENT_ID/deployments/$POLYAI_DEPLOYMENT_ID/promote" \
  -H "x-api-key: $POLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "targetEnvironment": "pre-release" }'

# take deployment.id from the response above:
export POLYAI_PRERELEASE_DEPLOYMENT_ID="..."

# pre-release -> live
curl -X POST "$POLYAI_BASE_URL/v1/agents/$POLYAI_AGENT_ID/deployments/$POLYAI_PRERELEASE_DEPLOYMENT_ID/promote" \
  -H "x-api-key: $POLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "targetEnvironment": "live" }'

# sandbox -> pre-release
response = requests.post(
    f"{base_url}/v1/agents/{agent_id}/deployments/{deployment_id}/promote",
    headers=headers,
    json={"targetEnvironment": "pre-release"},
)
response.raise_for_status()
pre_release_id = response.json()["deployment"]["id"]

# pre-release -> live
requests.post(
    f"{base_url}/v1/agents/{agent_id}/deployments/{pre_release_id}/promote",
    headers=headers,
    json={"targetEnvironment": "live"},
).raise_for_status()

Omit targetEnvironment and the promote defaults to the next stage in sequence (sandbox → pre-release → live). A Sandbox deployment can also promote straight to live — going through Pre-release first is a safety choice, not an API requirement. Made a mistake? Roll back to the previous deployment in any environment.

Step 5: Work with the calls it takes

Once your agent is live (or you’ve made test calls), pull the data back with the Conversations API. This uses a different host and a project-scoped key — see prerequisites above.

The project_id this API expects is the same value as the agentId you’ve used throughout this guide — “Agent” and “Project” are the current and legacy names for the same resource.

This is the one step on the -1.platform.polyai.app host with its own project-scoped key, so set that key first:

export POLYAI_CONVERSATIONS_API_KEY="your_conversations_api_key_here"

curl -X GET \
  "https://api.us-1.platform.polyai.app/v3/$POLYAI_ACCOUNT_ID/$POLYAI_AGENT_ID/conversations?limit=5" \
  -H "x-api-key: $POLYAI_CONVERSATIONS_API_KEY"

platform_url = "https://api.us-1.platform.polyai.app"
conversations_headers = {"x-api-key": os.environ["POLYAI_CONVERSATIONS_API_KEY"]}

response = requests.get(
    f"{platform_url}/v3/{account_id}/{agent_id}/conversations",
    headers=conversations_headers,
    params={"limit": 5},
)
response.raise_for_status()
conversations = response.json()["conversations"]

This returns a conversations array and a cursor for pagination. Fetch one by ID to get its full turn-by-turn transcript:

curl -X GET \
  "https://api.us-1.platform.polyai.app/v3/$POLYAI_ACCOUNT_ID/$POLYAI_AGENT_ID/conversations/CONVERSATION_ID" \
  -H "x-api-key: $POLYAI_CONVERSATIONS_API_KEY"

conversation_id = conversations[0]["id"]
response = requests.get(
    f"{platform_url}/v3/{account_id}/{agent_id}/conversations/{conversation_id}",
    headers=conversations_headers,
)
response.raise_for_status()
transcript = response.json()

From here:

Download call audio

Voice calls have a recording available on a separate binary endpoint.

Subscribe to webhooks

Get a signed POST when a call completes instead of polling for it.

Clean up

Built this agent just to try the API? Delete it when you’re done — this removes the agent along with all its branches and deployments, and can’t be undone.

curl -X DELETE "$POLYAI_BASE_URL/v1/agents/$POLYAI_AGENT_ID" \
  -H "x-api-key: $POLYAI_API_KEY"

requests.delete(
    f"{base_url}/v1/agents/{agent_id}",
    headers=headers,
).raise_for_status()

A successful delete returns 204 No Content.

Troubleshooting

Symptom	Likely cause	Fix
`401 Unauthorized`	Missing or wrong `x-api-key`, or a key from the wrong region.	Confirm the key was issued for the region in your base URL — see region mismatches.
`403 Forbidden`	Key lacks permission for this account or agent.	Confirm the key was provisioned for the account ID / agent ID you’re using.
`400` on create agent	Missing `responseSettings.greeting`, which is required.	Include a non-empty `greeting` — it’s the agent’s opening line.
`422 Cannot directly update main branch`	You sent a behavior or knowledge base write to `branches/main`.	Create a working branch, make edits on it, then merge to `main` — see step 2. `main` is read-only.
Debug chat replies with the old behavior/topic	You edited a branch but haven’t merged it into `main` yet.	Merge the branch again — edits reach Sandbox only once they’re merged into `main`.
`404` on debug-chat message	Wrong or expired `conversationId`.	Start a new session with `POST /debug-chat` and use the returned `conversationId`.
`409 Deployments already published`	You called `publish` after a merge, which already deployed to Sandbox.	Skip the explicit publish — merging a branch publishes to Sandbox for you. Move on to promote.
`404` on promote	Wrong `deploymentId`.	Use the `deployment.id` from the most recent publish/promote response, not an old one.
`400` on promote	`targetEnvironment` isn’t a later stage than the deployment’s current one.	Sandbox can promote to `pre-release` or `live`; pre-release can only promote to `live`.
`404` on Conversations endpoint (step 5)	Wrong base URL — usually the build host (`api.us.poly.ai`) instead of the platform host.	Conversations v3 uses `api.{region}-1.platform.polyai.app`, with the `-1` suffix.
Empty `conversations` array	No calls yet in the time window, or wrong `client_env`.	Place a test call via debug chat, widen the window, or try `client_env=sandbox`.
`429 Too Many Requests`	Rate limit hit.	Back off per the `Retry-After` header; use cursor pagination for large pulls.

See Error codes for the full reference.

Next steps

Agents API

Branches, telephony, real-time configs, and variants for multi-site agents.

Chat API

Wire a real webchat, web SDK, or SMS integration into a live conversation.

Conversations API

Full schema, pagination, and retrieval modes for call data.

Webhooks API

Event types, retries, and signature verification.

Outbound Calling API

Have your new agent place a real call out — needs outbound enabled on the project first.

WebRTC Gateway

Talk to your agent by voice from a browser tab instead of typing.

​What you’ll build

1. Create

2. Configure

3. Test

4. Deploy

5. Observe

​Prerequisites

​Step 1: Create an agent

​Step 2: Configure it

​Set the behavior

​Add a knowledge base topic

​Merge the branch into main

​Step 3: Test it

​Step 4: Deploy it

​Step 5: Work with the calls it takes

Download call audio

Subscribe to webhooks

​Clean up

​Troubleshooting

​Next steps

Agents API

Chat API

Conversations API

Webhooks API

Outbound Calling API

WebRTC Gateway

What you’ll build

Prerequisites

Step 1: Create an agent

Step 2: Configure it

Set the behavior

Add a knowledge base topic

Merge the branch into `main`

Step 3: Test it

Step 4: Deploy it

Step 5: Work with the calls it takes

Clean up

Troubleshooting

Next steps