{ "openapi": "3.0.2", "info": { "title": "Klaviyo API (Beta)", "version": "2026-07-15.pre", "description": "The Klaviyo REST API. Please visit https://developers.klaviyo.com for more details.", "contact": { "name": "Klaviyo Developer Experience Team", "email": "developers@klaviyo.com", "url": "https://developers.klaviyo.com" }, "termsOfService": "https://www.klaviyo.com/legal/api-terms", "license": { "name": "License", "url": "https://www.klaviyo.com/legal" } }, "servers": [ { "url": "https://a.klaviyo.com", "description": "Production" } ], "security": [ { "Klaviyo-API-Key": [] } ], "paths": { "/api/customer-agent-conversation-contexts": { "post": { "operationId": "create_customer_agent_conversation_context_beta", "summary": "Create Conversation Context", "description": "\n > \ud83d\udea7 This endpoint is in beta and subject to change.\n >\n > A beta revision header (2026-07-15.pre) is required to use our beta APIs. Klaviyo APIs in beta are not intended for use in production. See our [versioning and deprecation policy](https://developers.klaviyo.com/en/docs/api_versioning_and_deprecation_policy) for more information.\n\nAttach background the caller already has to an existing conversation.\n\nUnlike `POST /api/customer-agent-responses`, this never runs the agent or produces a reply -- it only records the context. Requires an open `conversation`, created via `POST /api/customer-agent-conversations`.

*Rate limits*:
Burst: `10/s`
Steady: `150/m`\n\n**Scopes:**\n`agents:write`\n\n[OpenAPI Spec](https://raw.githubusercontent.com/klaviyo/openapi/main/openapi/beta/apis/create_customer_agent_conversation_context_beta.json)", "parameters": [ { "name": "fields[customer-agent-conversation-context]", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-07-15.pre/reference/api-overview#sparse-fieldsets", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "entries", "event_type", "id" ] } }, "explode": false }, { "name": "revision", "in": "header", "description": "API endpoint revision (format: YYYY-MM-DD[.suffix])", "required": true, "schema": { "type": "string", "default": "2026-07-15.pre" } } ], "requestBody": { "description": "JSON:API request to attach a survey-response context to an existing conversation.\n\nUnlike ``POST /api/customer-agent-responses``, this never produces a reply -- it only records background the caller already has.", "required": true, "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/SurveyResponseContextCreateRequestRequestDataWrapper" } } } }, "responses": { "201": { "description": "Success", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ConversationContextCreateResponseDataWrapper" } } } }, "4XX": { "$ref": "#/components/responses/ClientError" }, "5XX": { "$ref": "#/components/responses/ServerError" } }, "tags": [ "Beta APIs" ], "x-klaviyo-pre-release": "BETA", "x-klaviyo-ratelimit": { "burst": "10/s", "steady": "150/m" }, "x-klaviyo-scopes": [ "agents:write" ], "x-klaviyo-subtag": "Customer Agent" } } }, "components": { "responses": { "ClientError": { "description": "Client Error", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "required": [ "id", "code", "title", "detail" ], "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" } } } } } } }, "required": [ "errors" ] } } } }, "ServerError": { "description": "Server Error", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "required": [ "id", "code", "title", "detail" ], "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" } } } } } } }, "required": [ "errors" ] } } } } }, "schemas": { "ConversationContextCreateResponse": { "type": "object", "properties": { "event_type": { "$ref": "#/components/schemas/SurveyResponseEnum" }, "entries": { "description": "Question/answer pairs already collected from the customer.", "type": "array", "items": { "$ref": "#/components/schemas/SurveyResponseEntry" } } }, "required": [ "event_type", "entries" ] }, "ConversationContextCreateResponseData": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/CustomerAgentConversationContextResourceName" }, "id": { "description": "Conversation context id, unique per submission.", "type": "string" }, "attributes": { "$ref": "#/components/schemas/ConversationContextCreateResponse" }, "relationships": { "type": "object", "properties": { "conversation": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/CustomerAgentConversationResourceName" }, "id": { "description": "Conversation this context was attached to.", "type": "string" } }, "required": [ "type", "id" ] }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } } }, "required": [ "conversation" ] }, "links": { "$ref": "#/components/schemas/ObjectLinks" } }, "required": [ "type", "id", "attributes", "relationships", "links" ] }, "ConversationContextCreateResponseDataWrapper": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversationContextCreateResponseData" }, "links": { "$ref": "#/components/schemas/ObjectLinks" } }, "required": [ "data" ] }, "CustomerAgentConversationContextResourceName": { "type": "string", "enum": [ "customer-agent-conversation-context" ] }, "CustomerAgentConversationResourceName": { "type": "string", "enum": [ "customer-agent-conversation" ] }, "ObjectLinks": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" } }, "required": [ "self" ] }, "RelationshipLinks": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "related": { "type": "string", "format": "uri" } }, "required": [ "self", "related" ] }, "SurveyResponseContextCreateRequestRequest": { "type": "object", "properties": { "event_type": { "$ref": "#/components/schemas/SurveyResponseEnum" }, "entries": { "description": "Question/answer pairs already collected from the customer.", "type": "array", "items": { "$ref": "#/components/schemas/SurveyResponseEntryRequest" } } }, "required": [ "event_type", "entries" ] }, "SurveyResponseContextCreateRequestRequestData": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/CustomerAgentConversationContextResourceName" }, "attributes": { "$ref": "#/components/schemas/SurveyResponseContextCreateRequestRequest" }, "relationships": { "type": "object", "properties": { "conversation": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/CustomerAgentConversationResourceName" }, "id": { "description": "Conversation to attach this context to. Create one first via `POST /api/customer-agent-conversations`.", "type": "string" } }, "required": [ "type", "id" ] } } } }, "required": [ "conversation" ] } }, "required": [ "type", "attributes", "relationships" ] }, "SurveyResponseContextCreateRequestRequestDataWrapper": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SurveyResponseContextCreateRequestRequestData" } }, "required": [ "data" ] }, "SurveyResponseEntry": { "type": "object", "properties": { "question": { "description": "The question asked.", "type": "string", "example": "What's your budget?" }, "answer": { "description": "The customer's answer.", "type": "string", "example": "Under $50" } }, "required": [ "question", "answer" ] }, "SurveyResponseEntryRequest": { "type": "object", "properties": { "question": { "description": "The question asked.", "type": "string", "example": "What's your budget?" }, "answer": { "description": "The customer's answer.", "type": "string", "example": "Under $50" } }, "required": [ "question", "answer" ] }, "SurveyResponseEnum": { "type": "string", "enum": [ "survey-response" ] } }, "securitySchemes": { "Klaviyo-API-Key": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Private key authentication for /api/ endpoints is performed by setting the `Authorization` header to `Klaviyo-API-Key your-private-api-key`
For more information please visit https://developers.klaviyo.com/en/v2026-07-15.pre/reference/api-overview#authentication", "x-default": "Klaviyo-API-Key your-private-api-key" } } }, "tags": [ { "name": "Beta APIs", "description": "beta apis" } ] }