API Introduction

Base URLs, authentication, common headers, pagination, error handling, and rate limiting for the KaireonAI REST API.

Base URLs

Environment	Base URL
Playground	https://playground.kaireonai.com/api/v1
Local dev	http://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.

API Key (recommended for integrations)

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.

Session Cookie

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

Header	Required	Description
Content-Type	Yes (POST/PUT)	Must be application/json
X-Tenant-Id	Yes	Tenant identifier. Resolved from session JWT or passed explicitly with API key auth
Authorization	Conditional	Bearer <api-key> for API key authentication
Idempotency-Key	Conditional	Prevents 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:

Parameter	Type	Default	Description
limit	integer	20	Number of items to return (max 100)
cursor	string	—	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

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

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the current window
X-RateLimit-Remaining	Requests remaining in the current window
Retry-After	Seconds 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.