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.

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

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.

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.

Agent skills

You can read prebuilt and custom skills. Only custom skills can be updated or deleted. Set a custom skill’s status to draft to stage or pause it, or live to activate it.

Agent tools

Only custom tools can be updated or deleted. After creating an external HTTP tool, bind it to a custom skill through the skill’s agent-tools relationship. A tool is not available to that skill until it is bound.

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.

Agent secrets

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

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.

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.

Run the agent

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 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. Bind new tools to the skills that use them and set custom 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.

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.

Related articles