---
title: "Customer Agent APIs (Beta)"
description: "Use Klaviyo’s Customer Agent APIs (beta) to configure your agent, inspect conversations, pull performance reports, and run the agent for one turn over HTTP, all using JSON:API conventions and a single `agents`-scoped private API key."
canonical_url: "https://help.klaviyo.com/hc/en-us/articles/50972372091163"
markdown_url: "https://help.klaviyo.com/hc/en-us/articles/50972372091163.md"
locale: "en-us"
category: "Customer Agent"
section: "Settings"
updated: "2026-11-12"
---

# Customer Agent APIs (Beta)

## You will learn

What the Customer Agent APIs are, what each endpoint group does, and how to start calling them. The APIs let you configure your Customer Agent, read what it's doing in production, and run it programmatically — directly over HTTP, alongside the rest of Klaviyo's public API.

🎬 [Watch video on YouTube](https://www.youtube.com/watch?v=XkSEZ92kszg)

> **Note:** The Customer Agent APIs are in beta. Endpoints and schemas may change before general availability. Beta APIs aren't intended for production use — see [Klaviyo's versioning and deprecation policy](https://developers.klaviyo.com/en/docs/api_versioning_and_deprecation_policy) for details.

## What the APIs let you do

The Customer Agent APIs cover 4 jobs:

1. **Configure the agent** — read or update the agent itself, plus its skills, tools, knowledge sources, and secrets.

2. **Read production conversations** — list and inspect Customer Agent conversations.

3. **Report on performance** — pull volume, resolution rate, and per-skill metrics.

4. **Run the agent for one turn** — send a conversation turn and get the agent's response back. This is the headless primitive — useful for embedding the agent into your own surface.



Because these four jobs all live behind one API, you can wire them into a **continuous training loop**: pull what happened, diagnose what worked and what didn't, then ship configuration changes back. With a securely configured API integration or MCP connection, an AI assistant like Claude or ChatGPT can help read conversations, find patterns in failures, and propose changes to your skills, tools, knowledge, and guidance.

## Authentication and access

Use a Klaviyo private API key with the **agents** scope to call these endpoints. Customer Agent must already be enabled for your account.

When you create the key, you choose the access level for the `agents` scope:

| **Access level** | **Grants** |
| --- | --- |
| **Read Access** | agents:read — GET endpoints for configuration and conversations, plus POST endpoints for reports. Secret values are not returned. |
| **Full Access** | agents:read and agents:write — everything above, plus supported configuration changes, conversation creation and updates, and running the agent for a turn. |

Pick read-only if your integration only needs to observe the agent (e.g., a reporting dashboard). Pick read/write if it needs to configure the agent or run conversation turns.

1. Navigate to **Settings > API keys** and click **Create Private API Key**.

2. Enter a **Private API Key Name** and select **Custom Key**.

3. In the **Agents** row, select **Read Access** or **Full Access** for your integration, using the table above.

4. Click **Create**, then click the copy icon and store the key securely. You cannot view the key again after leaving the confirmation page.



For more details, see [how to create or clone a private API key](https://help.klaviyo.com/hc/en-us/articles/7423954176283.md).

Send API requests from your server to `https://a.klaviyo.com` and include this authorization header. Keep the private key out of browser code and shopper-facing apps:

`Authorization: Klaviyo-API-Key your-private-api-key`

Every request must also include the beta revision header:

`revision: 2026-10-15.pre`

Without the beta revision header, the request will be rejected.

## Rate limits

Rate limits depend on the endpoint group:

- **Agent, skills, tools, knowledge, secrets, and responses:** burst limit of 10 requests per second and steady limit of 150 requests per minute.

- **Conversations, conversation messages, and reports:** burst limit of 3 requests per second and steady limit of 60 requests per minute.



## Request format

Use Klaviyo's JSON:API request conventions, with a separate format for file uploads:

- Content type: `application/vnd.api+json` for JSON requests. Use `multipart/form-data` for `POST /api/agent-knowledge-files`.

- Paginated collections use `page[cursor]` and `page[size]` (default 50, max 100, forward-only). Follow links.next until it is empty to retrieve the remaining pages.

- Filtering uses the supported fields and operators listed in each endpoint's reference. Sort order is endpoint-specific: conversations are newest first, messages are oldest first, and skills and tools are sorted by ID.



## Endpoint groups

### Agent

There is at most 1 Customer Agent per company. Call GET /api/customer-agents to find its ID, then use that ID in the GET or PATCH URL. The list is empty if Customer Agent is not enabled for the account.

| **Method** | **Path** | **What it does** |
| --- | --- | --- |
| `GET` | [`/api/customer-agents`](https://developers.klaviyo.com/en/reference/get_customer_agents_beta) | Find the agent and its ID |
| `GET` | [`/api/customer-agents/{id}`](https://developers.klaviyo.com/en/reference/get_customer_agent_beta) | Retrieve the agent's name, tone of voice, escalation rules, and communication styles |
| `PATCH` | [`/api/customer-agents/{id}`](https://developers.klaviyo.com/en/reference/update_customer_agent_beta) | Update the agent's top-level fields |

### Agent skills

You can read the skills that remain in your account, including custom skills and previously customized defaults. Untouched default skills and the default skill template library have been removed. Only custom skills can be updated or deleted through these endpoints. Set a custom skill’s `status` to `draft` to stage or pause it, or `live` to activate it.

| **Method** | **Path** | **What it does** |
| --- | --- | --- |
| `GET` | [`/api/agent-skills`](https://developers.klaviyo.com/en/reference/get_agent_skills_beta) | List all skills |
| `POST` | [`/api/agent-skills`](https://developers.klaviyo.com/en/reference/create_agent_skill_beta) | Create a skill |
| `GET` | [`/api/agent-skills/{id}`](https://developers.klaviyo.com/en/reference/get_agent_skill_beta) | Get one skill |
| `PATCH` | [`/api/agent-skills/{id}`](https://developers.klaviyo.com/en/reference/update_agent_skill_beta) | Update a skill |
| `DELETE` | [`/api/agent-skills/{id}`](https://developers.klaviyo.com/en/reference/delete_agent_skill_beta) | Delete a skill |

### Agent tools

Only custom tools can be updated or deleted. To use a tool within a custom skill, bind it through the skill’s `agent-tools` relationship. Direct use is controlled by tool permissions in Customer Agent > Connectors; a tool does not need a skill when set to Always allow. A tool set to Only in skills must be included in a skill, and Blocked prevents use through either route.

[For tool permission behavior, see Understanding Tools.](https://help.klaviyo.com/hc/en-us/articles/49994508239131.md)

| **Method** | **Path** | **What it does** |
| --- | --- | --- |
| `GET` | [`/api/agent-tools`](https://developers.klaviyo.com/en/reference/get_agent_tools_beta) | List tools visible to the company |
| `POST` | [`/api/agent-tools`](https://developers.klaviyo.com/en/reference/create_agent_tool_beta) | Create an external HTTP tool |
| `GET` | [`/api/agent-tools/{id}`](https://developers.klaviyo.com/en/reference/get_agent_tool_beta) | Get one tool |
| `PATCH` | [`/api/agent-tools/{id}`](https://developers.klaviyo.com/en/reference/update_agent_tool_beta) | Update a tool |
| `DELETE` | [`/api/agent-tools/{id}`](https://developers.klaviyo.com/en/reference/delete_agent_tool_beta) | Delete a tool |

### Agent knowledge

Create text snippets, webpages, Q&A pairs, or folders by setting `source.source_type` to `snippet`, `webpage`, `qa`, or `folder`. To add a `file`, use the separate file-upload endpoint.

| **Method** | **Path** | **What it does** |
| --- | --- | --- |
| `GET` | [`/api/agent-knowledge`](https://developers.klaviyo.com/en/reference/list_agent_knowledge_beta) | List top-level knowledge items, newest first; filter by folder_id to list a folder’s contents |
| `POST` | [`/api/agent-knowledge`](https://developers.klaviyo.com/en/reference/create_agent_knowledge_beta) | Create a snippet, webpage, Q&A pair, or folder |
| `POST` | [`/api/agent-knowledge-files`](https://developers.klaviyo.com/en/reference/create_agent_knowledge_file_beta) | Upload a file as a knowledge source (multipart) |
| `GET` | [`/api/agent-knowledge/{id}`](https://developers.klaviyo.com/en/reference/get_agent_knowledge_beta) | Get one knowledge source |
| `PATCH` | [`/api/agent-knowledge/{id}`](https://developers.klaviyo.com/en/reference/update_agent_knowledge_beta) | Update a snippet’s title or content, or a Q&A pair’s question or answer |
| `DELETE` | [`/api/agent-knowledge/{id}`](https://developers.klaviyo.com/en/reference/delete_agent_knowledge_beta) | Delete a knowledge source |

### Agent secrets

Encrypted secrets used by custom tools. The list endpoint returns safe metadata only — the secret value itself is never returned.

| **Method** | **Path** | **What it does** |
| --- | --- | --- |
| `GET` | [`/api/agent-secrets`](https://developers.klaviyo.com/en/reference/get_agent_secrets_beta) | List secrets (metadata only) |
| `POST` | [`/api/agent-secrets`](https://developers.klaviyo.com/en/reference/create_agent_secret_beta) | Create a secret |
| `PATCH` | [`/api/agent-secrets/{id}`](https://developers.klaviyo.com/en/reference/update_agent_secret_beta) | Update a secret |
| `DELETE` | [`/api/agent-secrets/{id}`](https://developers.klaviyo.com/en/reference/delete_agent_secret_beta) | Delete a secret |

### Conversations

Read conversations the agent has had with shoppers, or create a conversation to run through the API. One conversation can span many messages over a long period. The list can include live and preview conversations; use filter=equals(mode,"live") to limit it to live conversations.

| **Method** | **Path** | **What it does** |
| --- | --- | --- |
| `GET` | [`/api/customer-agent-conversations`](https://developers.klaviyo.com/en/reference/list_customer_agent_conversations_beta) | List conversations |
| `GET` | [`/api/customer-agent-conversations/{id}`](https://developers.klaviyo.com/en/reference/retrieve_customer_agent_conversation_beta) | Get one conversation by ID, including references to its messages |
| `GET` | [`/api/customer-agent-conversations/{id}/customer-agent-messages`](https://developers.klaviyo.com/en/reference/get_agent_messages_for_customer_agent_conversation_beta) | Read message content, oldest first, with pagination |
| `POST` | [`/api/customer-agent-conversations`](https://developers.klaviyo.com/en/reference/create_customer_agent_conversation_beta) | Create an empty conversation before running the agent |

### Reports

Aggregate metrics, scoped to the requesting company. Both reports below are POST endpoints: pass the report parameters in the body. They require agents:read, so a read-only key can run them.

| **Method** | **Path** | **What it does** |
| --- | --- | --- |
| `POST` | [`/api/customer-agent-values-reports`](https://developers.klaviyo.com/en/reference/query_customer_agent_values_beta) | Conversation-level metrics: volume and resolution rate |
| `POST` | [`/api/customer-agent-skill-values-reports`](https://developers.klaviyo.com/en/reference/query_customer_agent_skill_values_beta) | Per-skill volume report |

### Run the agent

| **Method** | **Path** | **What it does** |
| --- | --- | --- |
| `POST` | [`/api/customer-agent-responses`](https://developers.klaviyo.com/en/reference/create_customer_agent_response_beta) | Run the Customer Agent for one conversation turn — pass the shopper input, get the agent's response back |

This is the primitive for embedding Customer Agent into your own surface (your app, your help center, a partner-built support panel).

Create an open conversation with `POST /api/customer-agent-conversations` before running a turn. The response endpoint only accepts conversations created through the API. A closed conversation, or one already routed to your team, cannot accept more responses.

## What still requires the Klaviyo UI

Some setup steps don't live in the API yet:

- **Channel configuration** (web chat, email, SMS, WhatsApp) — channel setup lives in Klaviyo platform settings.

- **Going live on each channel** — the on/off switch per channel stays in the UI.

- **Helpdesk selection** — in Customer Agent, open a channel under **Channels** and configure its **Handoff** section. See [Managing Customer Agent settings](https://help.klaviyo.com/hc/en-us/articles/37659474656027.md) for details.



## Typical workflows

### Configure once, then maintain

1. **Create a private API key** with the `agents` scope and read/write access in Klaviyo.

2. **Pull current state** — GET /api/customer-agents to find the agent ID, then retrieve the agent and the skill, tool, and knowledge lists. Follow pagination links to read all pages.

3. **Make changes** — create or update custom skills, tools, knowledge, and secrets as needed. Review tool permissions in Connectors. Bind tools to any custom skills that use them and set those skills to status: live when ready to activate them.

4. **Check production** — list recent conversations and pull a values report to see how the agent is performing.

5. **Iterate.**



### Train your agent in a loop

The APIs are designed to close the loop between what your agent did in production and how it's configured. A typical loop:

1. **Pull recent conversations** — GET conversations filtered by created_at and status, adding equals(mode,"live") to the filter for production conversations. Fetch each conversation’s customer-agent-messages and follow links.next to read every page.

2. **Diagnose** — for each conversation, classify it as a success or a failure. Look for patterns: are escalations clustered around a topic? Are certain skills being routed when they shouldn't? Is the agent missing knowledge it needs?

3. **Pull metrics** — values report for volume and resolution rate, plus skill-values report for per-skill breakdowns. Confirm the patterns hold in aggregate.

4. **Propose changes** — based on the failure patterns, decide what to change: edit a skill's instructions, add a knowledge snippet, create a new custom tool, tighten a tone rule, add an escalation trigger.

5. **Apply changes** — PATCH the affected skills, POST new knowledge sources, etc.

6. **Loop.** Repeat against the next window of conversations.



You can use an AI assistant such as Claude, ChatGPT, or Cursor to pull conversations, find gaps, propose specific edits, and apply changes with your approval. Connect it through the Klaviyo MCP server or your own API integration, and keep private API keys in secure configuration rather than in prompts. The MCP server supports many of these tasks, but creating or updating secrets and uploading knowledge files require direct API calls.

### Embed the agent in your own surface

Use `mode: preview` for testing without billing or production metrics. `mode: live` is for real shopper interactions and counts toward billing and production metrics. The beta-use warning above still applies.

1. **Create a key** with the agents scope (read/write).

2. **Create a conversation** — from your server, POST to `/api/customer-agent-conversations` with the chosen `mode`. Save the returned conversation ID.

3. **Open a conversation in your UI** — collect the shopper's input.

4. **Run a turn** — from your server, POST to /api/customer-agent-responses with mode, messages, and the saved ID in data.relationships.conversation.data.id. Use relationship type customer-agent-conversation. Include the conversation history in messages, ending with the shopper’s latest message with role: user.

5. **Render the response** — process the returned events in order and display the agent’s messages and any supported structured data in your interface. Handle handoff events in your integration. The API returns events together without streaming; it does not deliver them through a channel.

6. **Repeat for each turn** using the same conversation ID and mode while the conversation is open. After a hard or silent handoff, stop requesting agent responses and route the shopper to your support team.



## FAQ

**Is there an MCP server?**

Yes. The remote-hosted Klaviyo MCP server includes Customer Agent tools for skills, tools, knowledge, secret metadata, conversations, reports, and running the agent. Creating a conversation, creating or updating secrets, and uploading knowledge files require direct API calls. See [Klaviyo MCP server](https://developers.klaviyo.com/en/docs/klaviyo_mcp_server).

**Is this stable enough to build on?**

Beta means the schema may change. The endpoints are fully callable, but we don't yet commit to long-term stability. Don't ship production-critical integrations against the beta revision.

**Where do I find the full schema?**

The full reference lives in the Klaviyo developer portal at https://developers.klaviyo.com/en/reference/. The Customer Agent endpoints appear under Beta APIs in the 2026-10-15.pre revision.
