> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Data API

> Query conversations, recordings, annotations, notes, and debug chat sessions for your PolyAI agents.

The Data API provides programmatic access to conversation records, audio recordings, annotations, notes, and debug chat sessions generated by your PolyAI agents. Use it for analytics pipelines, QA workflows, compliance reporting, and interactive testing.

## What you can do

* List conversations for a project and retrieve full conversation detail by ID.
* Fetch the WAV audio recording for a conversation (with PII-redaction controls).
* Add turn-level annotations (`missing_topic`, `wrong_transcript`, `wrong_info`) to flag issues for review.
* Upsert free-form notes on a conversation.
* Create and exchange messages in debug chat sessions to test agent variants outside of production traffic.

## Regional base URLs

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

## Identifiers

Agent Studio labels and API parameters use different names for the same things. When you read an ID from Agent Studio, map it to the API parameter using this table:

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

<Note>**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. Use the value you see in Agent Studio as the `agentId` path parameter — no transformation needed.</Note>

## Authentication

The Data API uses API key authentication with the `X-API-KEY` header. API keys are scoped to account, project, and region. Issue keys from the API keys section of Agent Studio, or request one from your PolyAI representative.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request GET \
  --url "https://api.us.poly.ai/v1/agents/{agentId}/conversations" \
  --header "X-API-KEY: $POLYAI_API_KEY"
```

<Warning>
  **The Agent Studio instance and API region must match.** A key generated from `studio.poly.ai` only works against `api.studio.poly.ai`. To call `api.us.poly.ai`, you must generate the key from `studio.us.poly.ai` (and likewise for `eu` and `uk`). A mismatch returns `401 Unauthorized`.

  | Agent Studio URL            | API base URL                 |
  | --------------------------- | ---------------------------- |
  | `https://studio.poly.ai`    | `https://api.studio.poly.ai` |
  | `https://studio.us.poly.ai` | `https://api.us.poly.ai`     |
  | `https://studio.eu.poly.ai` | `https://api.eu.poly.ai`     |
  | `https://studio.uk.poly.ai` | `https://api.uk.poly.ai`     |
</Warning>