Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This tutorial covers everything you need to integrate with KaireonAI’s two core APIs:
  • Recommend API — Get personalized offer recommendations for a customer
  • Respond API — Record customer interactions (impressions, clicks, conversions)

​
Prerequisites

Before starting, ensure you have:
  • A running KaireonAI instance (local or https://playground.kaireonai.com)
  • At least one active Decision Flow with Offers, channels, and Creatives configured
  • Your tenant ID (found in Settings > General)
  • An API key (generated in Settings > API Keys)

​
Authentication

All API requests require two headers:
HeaderDescription
x-tenant-idYour tenant identifier
x-api-keyYour API key (hashed with HMAC-SHA256 on the server)
curl -H "x-tenant-id: your-tenant-id" \
     -H "x-api-key: your-api-key" \
     https://your-instance.com/api/v1/recommend
API keys are hashed on the server using HMAC-SHA256 with the API_KEY_PEPPER environment variable. Store your API key securely — it cannot be retrieved after creation.

​
Base URL

EnvironmentBase URL
Local developmenthttp://localhost:3000/api/v1
Playgroundhttps://playground.kaireonai.com/api/v1
ProductionYour custom domain + /api/v1

​
Recommend API

The Recommend API is the primary decisioning endpoint. It executes a Decision Flow for a specific customer and returns ranked, personalized offers.

​
Endpoint

POST /api/v1/recommend

​
Request Body

{
  "customerId": "SBX-000042",
  "decisionFlowKey": "starbucks-decision-pipeline",
  "limit": 3,
  "channel": "email",
  "placement": "hero_offer",
  "attributes": {
    "tier": "gold",
    "source": "campaign_q1"
  },
  "debug": true
}
FieldTypeRequiredDescription
customerIdstringYesThe customer to generate recommendations for
decisionFlowKeystringNoDecision flow key to execute (uses default flow if omitted)
limitnumberNoMaximum offers to return (default: 5)
channelstringNoFilter by delivery channel
placementstringNoNamed placement slot within the channel
attributesobjectNoRequest-time attributes available as attributes.* in formulas
debugbooleanNoIf true, includes pipeline funnel counts in meta

​
Response

{
  "recommendationId": "rec_abc123",
  "customerId": "SBX-000042",
  "decisionFlowKey": "starbucks-decision-pipeline",
  "count": 3,
  "decisions": [
    {
      "offerId": "...",
      "offerName": "Starbucks: Discount — 10 Day High",
      "rank": 1,
      "score": 0.89,
      "creativeId": "...",
      "channelType": "email",
      "content": {
        "subject": "Special offer just for you",
        "body": "<p>Save on your next visit</p>"
      },
      "personalization": {}
    },
    {
      "offerId": "...",
      "offerName": "Starbucks: BOGO — 5 Day Hard",
      "rank": 2,
      "score": 0.74,
      "creativeId": "...",
      "channelType": "email",
      "content": {
        "subject": "Buy one, get one free",
        "body": "<p>Bring a friend this weekend</p>"
      },
      "personalization": {}
    }
  ],
  "meta": {
    "totalCandidates": 60,
    "afterQualification": 45,
    "afterContactPolicy": 42,
    "degradedScoring": false
  },
  "timestamp": "2026-03-10T14:30:00Z"
}

​
Response Fields

FieldDescription
decisions[]Ordered array of recommended offers (highest score first)
decisions[].scoreFinal composite score after arbitration
decisions[].contentRendered creative content with personalization variables resolved
decisions[].personalizationComputed values from the Compute stage
recommendationIdDecision trace ID (only when debug: true in request)
Once you receive recommendations, record how customers interact with them using the Respond API.

​
Respond API

The Respond API records customer interactions with recommendations. KaireonAI feeds this data back into behavioral metrics, contact policies, and experiment analysis.

​
Endpoint

POST /api/v1/respond

​
Request Body

{
  "customerId": "cust_12345",
  "creativeId": "treat_platinum_email",
  "channelId": "ch_email",
  "outcome": "click",
  "recommendationId": "trace_abc123",
  "idempotencyKey": "idem_click_cust12345_abc123",
  "metadata": {
    "clickPosition": "hero_banner",
    "deviceType": "mobile"
  }
}
FieldTypeRequiredDescription
customerIdstringYesThe customer who interacted
creativeIdstringYesThe creative they interacted with
channelIdstringYesThe channel the interaction occurred on
outcomestringYesThe type of interaction (see Outcome Types)
idempotencyKeystringYesUnique key to prevent duplicate recordings
recommendationIdstringNoLinks this interaction back to the original recommendation
metadataobjectNoArbitrary key-value data attached to the interaction

​
Response

{
  "interactionId": "int_xyz789",
  "customerId": "cust_12345",
  "creativeId": "treat_platinum_email",
  "channelId": "ch_email",
  "classification": "click",
  "status": "recorded",
  "recommendationId": "trace_abc123",
  "recordedAt": "2026-03-10T15:45:00Z"
}

​
Common Outcome Types

TypeWhen to Record
impressionCustomer was shown the recommendation
clickCustomer clicked/tapped the recommendation
conversionCustomer completed the desired action (purchase, application, etc.)
dismissCustomer explicitly dismissed the recommendation
not_interestedCustomer indicated disinterest
opt_outCustomer opted out of this type of communication

​
Advanced Topics

​
Decision Traces

When you set debug: true in the Recommend request, KaireonAI records a forensic trace of the entire decision process. Retrieve it with: 
GET /api/v1/decision-traces/:recommendationId
Trace response: 
{
  "recommendationId": "trace_abc123",
  "customerId": "cust_12345",
  "decisionFlowId": "df_credit_cards",
  "stages": [
    {
      "name": "enrich",
      "duration": 12,
      "input": { "customerId": "cust_12345" },
      "output": { "customer.loyalty_score": 85, "customer.credit_score": 720 }
    },
    {
      "name": "compute",
      "duration": 3,
      "computed": {
        "act_platinum_cc": { "personalized_rate": 17.49 },
        "act_cashback": { "personalized_rate": 18.24 }
      }
    },
    {
      "name": "filter",
      "duration": 5,
      "candidatesIn": 15,
      "candidatesOut": 8,
      "filtered": ["act_home_loan (segment_required)", "act_auto_loan (propensity < 0.4)"]
    },
    {
      "name": "score",
      "duration": 8,
      "scores": {
        "act_platinum_cc": 0.89,
        "act_cashback": 0.74
      }
    },
    {
      "name": "rank",
      "duration": 2,
      "finalOrder": ["act_platinum_cc", "act_cashback"]
    }
  ],
  "totalDuration": 30,
  "processedAt": "2026-03-10T14:30:00Z"
}
Decision traces are invaluable for debugging why a specific offer was or was not recommended. Enable tracing in staging environments and at a sample rate in production (configurable in Settings > Tracing).

​
Experiments

When an A/B experiment is active, KaireonAI automatically assigns customers to control or variant groups based on creative weights. The response includes experiment metadata: 
{
  "recommendations": [
    {
      "offerId": "act_platinum_cc",
      "creativeId": "treat_platinum_email_variant_a",
      "experiment": {
        "experimentId": "exp_cc_cta_test",
        "variant": "variant_a",
        "weight": 30
      }
    }
  ]
}
Track experiment results in Algorithms > Experiments, where KaireonAI calculates:
  • Conversion rate per variant
  • Uplift (percentage improvement over control)
  • Statistical significance (z-test)
  • Confidence interval

​
Computed Values in Responses

The personalization field in each recommendation contains the evaluated computed values from the Decision Flow’s Compute stage. These values are calculated per customer using:
  • Offer custom fields — base_rate, annual_fee, etc.
  • Enriched customer data — customer.loyalty_score, customer.credit_score
  • Request-time attributes — attributes.tier, attributes.device
{
  "personalization": {
    "personalized_rate": 17.49,
    "annual_fee_waiver": true,
    "bonus_points": 5000
  }
}
See Computed Values for formula syntax and configuration details.

​
Error Handling

​
Common Error Responses

StatusCodeDescription
400VALIDATION_ERRORInvalid request body (missing required fields, wrong types)
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENTenant does not have access to the requested resource
404NOT_FOUNDDecision Flow, customer, or Offer not found
429PLAYGROUND_QUOTA_EXCEEDEDPlayground decision limit reached (see Open-Source Model)
500INTERNAL_ERRORServer error — contact support
Error response format: 
{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": [
    { "field": "customerId", "message": "customerId is required" }
  ]
}

​
Rate Limiting

KaireonAI protects the platform with a sliding-window rate limit of 1,000 requests per minute per tenant. When rate-limited, the API returns: 
HTTP 429 Too Many Requests
Retry-After: 12
Rate limits apply per tenant, not per API key. Multiple API keys for the same tenant share the same rate limit window.

​
What’s Next?

Platform Walkthrough

Follow the end-to-end setup guide with hands-on examples.

Decision Flows

Learn how the decisioning pipeline works under the hood.

Formula Reference

Complete syntax reference for computed value formulas.

Behavioral Metrics

Build dynamic rules from interaction history.

Sample Data

Load demo data to test the APIs with realistic content.

MCP Quickstart

Connect your AI IDE to query and configure KaireonAI.