Skip to main content

​
Base URLs

EnvironmentBase URL
Playgroundhttps://playground.kaireonai.com/api/v1
Local devhttp://localhost:3000/api/v1
All paths in this reference are relative to the base URL. For example, POST /recommend means POST https://playground.kaireonai.com/api/v1/recommend.

​
Authentication

Every API request must identify a tenant. You can authenticate using any of the following methods. Pass your key in the Authorization header along with the tenant identifier: 
curl -X POST https://playground.kaireonai.com/api/v1/recommend \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "X-Tenant-Id: <your-tenant-id>" \
  -d '{"customerId": "CUST001"}'
Generate API keys in Settings > Integrations > API Keys. Each key is scoped to a single tenant. When using the KaireonAI platform UI, requests authenticate via session cookie automatically. The tenant is resolved from the JWT session. No additional headers are needed.
Keep your API key secret. Never expose it in client-side code or public repositories.

​
Common Headers

HeaderRequiredDescription
Content-TypeYes (POST/PUT)Must be application/json
X-Tenant-IdYesTenant identifier. Resolved from session JWT or passed explicitly with API key auth
AuthorizationConditionalBearer <api-key> for API key authentication
Idempotency-KeyConditionalPrevents duplicate processing on the Respond API. Can also be sent in the request body as idempotencyKey

​
Pagination

List endpoints that support pagination return a cursor-based response: 
{
  "data": [ ... ],
  "pagination": {
    "cursor": "eyJpZCI6IjEyMyJ9",
    "hasMore": true,
    "total": 247
  }
}
Query parameters:
ParameterTypeDefaultDescription
limitinteger20Number of items to return (max 100)
cursorstring—Opaque cursor from a previous response to fetch the next page

​
Error Response Format

All errors follow a consistent structure: 
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "customerId is required",
    "status": 400,
    "recommendationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2026-03-16T12:00:00.000Z"
  }
}
Validation errors from Zod schemas return a combined detail string: 
{
  "title": "Validation error",
  "detail": "customerId: Required; outcome: outcome (or interactionType) is required"
}

​
Status Codes

CodeMeaning
200Success
201Created (new resource)
204No content (successful delete)
400Bad request — invalid or missing fields
401Unauthorized — missing or invalid API key / session
403Forbidden — insufficient permissions for the requested action
404Not found — resource does not exist or belongs to another tenant
409Conflict — resource already exists (e.g., duplicate key)
415Unsupported Media Type — Content-Type must be application/json
429Rate limited — wait and retry after the Retry-After interval
500Internal server error — an unexpected error occurred

​
Rate Limiting

API requests are rate-limited per tenant on a sliding window basis. The default limit is 1,000 requests per 60-second window. When a request is rate-limited, the response includes these headers:
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining in the current window
Retry-AfterSeconds to wait before retrying
Example 429 response: 
{
  "error": "Too Many Requests",
  "retryAfter": 42
}
When you receive a 429, wait for the number of seconds in the Retry-After header before retrying.

​
Next Steps

Recommend API

Get personalized next-best-action recommendations for a customer.

Respond API

Record impressions, clicks, conversions, and other outcomes.

API Tutorial

End-to-end walkthrough with advanced features like Decision Flows and computed values.

MCP Server

Use the Recommend and Respond APIs as MCP tools from AI agents.