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 four 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. Point an AI assistant like Claude or ChatGPT at the API key and it can run the loop end-to-end on your behalf — read conversations, find patterns in failures, and propose (or apply) changes to your skills, tools, knowledge, and guidance.

Authentication and access

The Customer Agent APIs are called with a Klaviyo private API key. Generate the key from Settings > API keys in Klaviyo, and grant it the agents scope.

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.

Every request must also include the beta revision header:

revision: 2026-07-15.pre

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

Rate limits

All endpoints share the same limits:

• Burst: 10 requests / second
• Steady: 150 requests / minute

Request format

All endpoints follow the JSON:API conventions used elsewhere in Klaviyo's APIs:

• Content type: application/vnd.api+json
• Pagination via page[cursor] and page[size] (default 50, max 100, forward-only)
• Filtering and sorting follow Klaviyo's standard filter syntax

Endpoint groups

Agent

There is one Customer Agent per company. The agent is a singleton — the ID in the URL is resolved from your auth token.

Agent Skills

Agent Tools

Agent Knowledge

Knowledge sources come in three types, set by source_type on create: snippet, webpage, or file.

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. Conversations are ticket-shaped — one conversation can span many messages over a long period.

Reports

Aggregate metrics, scoped to the requesting company. Both reports are POST endpoints — you pass the report parameters in the body.

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

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 — which helpdesk takes escalations is set in the helpdesk integration setup, not on the agent.

Typical workflows

Configure once, then maintain

1. Create a private API key with the agents scope in Klaviyo.
2. Pull current state — GET the agent and the skill / tool / knowledge lists.
3. Make changes — create or update skills, tools, knowledge, and secrets as needed.
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. Pull the messages from each.
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.

This is a strong fit for AI-assisted operation. Hand the API key and a brief to Claude, ChatGPT, or Cursor and let it pull conversations, find the gaps, propose specific edits, and (with your approval) apply them. The MCP- or coding-agent-friendly shape of these endpoints — JSON:API, predictable resource paths, full CRUD — is intentional.

Embed the agent in your own surface

1. Create a key with the agents scope (read/write).
2. Open a conversation in your UI — collect the shopper's input.
3. Run a turn — POST to /api/customer-agent-responses, passing the shopper input and any conversation context.
4. Render the response in your surface.
5. Repeat for each turn of the conversation.

FAQ

Is there an MCP server?

Not in this beta. The APIs are REST-only.

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 current revision (2026-07-15.pre).

Related articles