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:

Access level	Grants
Read-only	All GET endpoints — read the agent, skills, tools, knowledge, secrets; list conversations; pull reports
Read/write	All endpoints — everything above, plus create/update/delete on configuration, 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.

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.

Method	Path	What it does
GET	/api/customer-agents/{id}	Retrieve the agent (name, handoff message, top-level state)
PATCH	/api/customer-agents/{id}	Update the agent's top-level fields

Agent Skills

Method	Path	What it does
GET	/api/agent-skills	List all skills
POST	/api/agent-skills	Create a skill
GET	/api/agent-skills/{id}	Get one skill
PATCH	/api/agent-skills/{id}	Update a skill
DELETE	/api/agent-skills/{id}	Delete a skill

Agent Tools

Method	Path	What it does
GET	/api/agent-tools	List tools visible to the company
POST	/api/agent-tools	Create an external HTTP tool
GET	/api/agent-tools/{id}	Get one tool
PATCH	/api/agent-tools/{id}	Update a tool
DELETE	/api/agent-tools/{id}	Delete a tool

Agent Knowledge

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

Method	Path	What it does
GET	/api/agent-knowledge	List knowledge sources, newest first
POST	/api/agent-knowledge	Create a snippet or webpage knowledge source
POST	/api/agent-knowledge-files	Upload a file as a knowledge source (multipart)
GET	/api/agent-knowledge/{id}	Get one knowledge source
PATCH	/api/agent-knowledge/{id}	Update a snippet's title or content
DELETE	/api/agent-knowledge/{id}	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	List secrets (metadata only)
POST	/api/agent-secrets	Create a secret
PATCH	/api/agent-secrets/{id}	Update a secret
DELETE	/api/agent-secrets/{id}	Delete a secret

Conversations

Read conversations the agent has had with shoppers. Conversations are ticket-shaped — one conversation can span many messages over a long period.

Method	Path	What it does
GET	/api/customer-agent-conversations	List conversations
GET	/api/customer-agent-conversations/{id}	Get one conversation by ticket ID, including all messages

Reports

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

Method	Path	What it does
POST	/api/customer-agent-values-reports	Conversation-level metrics: volume and resolution rate
POST	/api/customer-agent-skill-values-reports	Per-skill volume report

Run the agent

Method	Path	What it does
POST	/api/customer-agent-responses	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).

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