Skip to main content
This guide gets you from zero to a working decisioning platform with sample data and a live API call. By the end, you will have KaireonAI running locally with 10 Starbucks offers, 6 channels, scoring models, and a complete Decision Flow — and you will have called the Recommend API to get personalized results.

​
Prerequisites

Docker Compose (Recommended)

Just Docker Desktop installed. Everything else (PostgreSQL, Redis) runs in containers.

Local Development

Node.js 22+, PostgreSQL 15+, and optionally Redis. For contributors or if you want Turbopack hot-reload.

​
Setup

Choose your path — both get you to the same result.
No setup needed. Use the hosted playground to explore KaireonAI instantly.
1

Create an account

Go to playground.kaireonai.com and create an account with your email and a password. No email verification needed — you can sign in immediately.
2

Sign in

Go to playground.kaireonai.com/login and sign in with your credentials. You can also use Continue with Google for one-click access.
3

Explore

Your playground comes pre-loaded with sample data (Starbucks dataset) — 10 offers, 6 channels, scoring models, and a complete Decision Flow. You are ready to make your first recommendation.
Playground accounts have usage limits: 100 API requests/minute, 5,000 lifetime decisions, and entity caps (50 offers, 10 schemas, 5 pipelines). Self-host for unlimited usage.

​
Load Sample Data

With the platform running, load the Starbucks dataset to see everything in action. Playground users already have sample data pre-loaded — skip to Run Your First Recommendation.
1

Navigate to Settings > Sample Data

Click Settings in the sidebar, then select Sample Data.
2

Load the Starbucks dataset

Click Load next to the Starbucks dataset. This creates:
EntityCountExamples
Offers10BOGO Frappuccino, 25% Off Merchandise, Earn 3x Stars
Channels6Web, Email, Mobile Push, Social, Batch Email, Manual Outreach
Creatives60Content variants per offer per channel
Scoring Models3Scorecard, Bayesian, Thompson Bandit
Decision Flow1Complete pipeline with qualification, scoring, and ranking
Qualification RulesYesEligibility gates based on customer attributes
Contact PoliciesYesFrequency caps to prevent over-contact
3

Verify on the Home page

Go to the Home page. You should see entity counts populated: 1 Decision Flow, 10 Offers, 6 Channels, 3 Models.
The Starbucks dataset is designed as a complete learning environment. Every entity is connected — offers have creatives linked to channels, qualification rules reference customer attributes, and the Decision Flow ties it all together.

​
Run Your First Recommendation

Call the Recommend API to see the decision engine evaluate, score, and rank offers for a specific customer. 
curl -s -X POST https://playground.kaireonai.com/api/v1/recommend \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: YOUR_TENANT_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Requested-With: XMLHttpRequest" \
  -d '{
    "customerId": "SBX-000042",
    "limit": 3
  }' | python3 -m json.tool
Find your Tenant ID and API Key in Settings > API Explorer. Both are auto-populated from your session. Click Manage Keys to create additional keys or revoke existing ones. On the playground, a default API key is created automatically when you register.
Expected response (trimmed): 
{
  "interactionId": "095baa57-...",
  "recommendationId": "095baa57-...",
  "customerId": "SBX-000042",
  "decisionFlowKey": "starbucks-offers",
  "decisionFlowVersion": 1,
  "experimentVariant": null,
  "controlGroup": false,
  "timestamp": "2026-04-14T12:00:00.000Z",
  "channel": "all",
  "placement": "all",
  "count": 3,
  "decisions": [
    {
      "offerId": "92a89bed-...",
      "offerName": "Starbucks: Discount — 10 Day Low",
      "creativeName": "Starbucks: Discount Low — Social",
      "channelName": "Starbucks: Social",
      "categoryName": "Starbucks: Retention",
      "score": 1,
      "rank": 1,
      "content": {
        "post": "Treat yourself to our Discount Low offer!",
        "hashtags": ["#Starbucks", "#StarbucksRewards"]
      },
      "scoreExplanation": {
        "method": "priority_weighted",
        "priority": 85,
        "finalScore": 1
      }
    }
  ],
  "meta": {
    "totalCandidates": 60,
    "afterQualification": 60,
    "afterSuppression": 60,
    "afterContactPolicy": 57,
    "degradedScoring": false
  }
}
The exact offers and scores depend on the scoring model and the customer attributes you pass. Try changing income to 120000 or age to 55 to see different results — the model adapts to each customer profile.

​
What Just Happened?

Behind that single API call, the decision engine ran a complete pipeline:
  1. Inventory — Loaded all 10 offers with their 60 creatives
  2. Qualification — Filtered out offers the customer is not eligible for based on rules
  3. Contact Policy — Removed offers that would violate frequency caps
  4. Scoring — Evaluated remaining candidates using the Starbucks scorecard model
  5. Ranking — Sorted by score and returned the top 3
This entire process completed in under 50ms. In production, you would call this API from your app, website, or email system whenever you need to decide what to show a customer.

​
What’s Next?

Starbucks Tutorial

Build the entire Starbucks pipeline from scratch — step by step, entity by entity. The best way to learn KaireonAI.

Try the AI Assistant

Ask the AI assistant about your data: “How many offers do I have?” or “Create a new email channel.”

Decision Flows

Learn how the composable pipeline works — 16 node types, visual canvas editor, PRIE scoring.

API Reference

Full Recommend and Respond API documentation with request/response schemas.