Skip to main content
By the end of this guide you will have a live KaireonAI tenant with seeded Starbucks demo data, made one recommendation, recorded one outcome, and inspected the full decision trace. No install required — everything runs against the hosted playground.

​
1. Sign up

1

Open the playground

Visit playground.kaireonai.com and register. No email verification needed for the playground tier.
2

Demo data is auto-seeded

Your tenant ships with 10 offers, 6 channels, 100 customers, 3 scoring algorithms, and one Decision Flow named Base NBA Flow that wires them all together. Skip the setup; you have everything you need.

​
2. Get your API key

1

Open API Keys

In the playground, click Settings → API Keys → Create. Copy the key when shown — it is displayed only once.
2

Save it for the curl examples below

export KAIREON_API_KEY="kk_live_..."
export KAIREON_TENANT_ID="<your-tenant-id-from-the-Settings-page>"
export KAIREON_BASE_URL="https://playground.kaireonai.com"
The same KAIREON_API_KEY and KAIREON_TENANT_ID env vars also wire the MCP server. If you set up MCP later, you can copy these same values into your AI client’s MCP config.

​
3. Make your first recommendation

curl -X POST "$KAIREON_BASE_URL/api/v1/recommend" \
  -H "X-API-Key: $KAIREON_API_KEY" \
  -H "X-Tenant-Id: $KAIREON_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "C001",
    "channel": "email",
    "limit": 3
  }'
The response ranks the top 3 offers for customer C001 over email. Each result includes a score, interactionId, and the offer metadata you need to render to the customer:
{
  "decisionId": "dec_...",
  "interactionId": "int_...",
  "results": [
    { "offerId": "free-coffee", "score": 0.86, "creativeId": "...", "ranking": 1 },
    { "offerId": "buy-one-get-one", "score": 0.74, "creativeId": "...", "ranking": 2 },
    { "offerId": "double-stars", "score": 0.61, "creativeId": "...", "ranking": 3 }
  ],
  "decisionTraceId": "trace_..."
}
Save the interactionId — you need it for step 4.

​
4. Record the outcome

The customer saw your top recommendation. Whether they clicked, ignored, or converted, KaireonAI uses that signal to learn. Record one outcome: 
curl -X POST "$KAIREON_BASE_URL/api/v1/respond" \
  -H "X-API-Key: $KAIREON_API_KEY" \
  -H "X-Tenant-Id: $KAIREON_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "interactionId": "int_...",
    "outcome": "click",
    "timestamp": "2026-05-06T12:00:00Z"
  }'
Replace int_... with the interactionId from step 3. The response confirms the outcome was recorded and feeds the online learners.

​
5. See the decision trace

Every decision is fully explainable. Walk through eligibility, fit, match, and ranking to see exactly why each offer ranked where it did. 
curl "$KAIREON_BASE_URL/api/v1/decision-traces/<trace_id>" \
  -H "X-API-Key: $KAIREON_API_KEY" \
  -H "X-Tenant-Id: $KAIREON_TENANT_ID"
Replace <trace_id> with the decisionTraceId from step 3. The response includes per-stage gate results, fit-filter outcomes, scoring breakdowns per algorithm, and the final ranking math.

​
What just happened

You drove the entire KaireonAI decisioning loop end-to-end. In 5 minutes you used:
  • A Decision Flow — a configured pipeline that runs every recommendation through eligibility gates, fit filters, scoring algorithms, and ranking. The auto-seeded Base NBA Flow is what powered your /recommend call.
  • The Recommend API — the runtime entry point that returns ranked offers along with the interactionId that links the recommendation to its outcome.
  • The Respond API — closes the loop. Outcomes feed the online learners so the next recommendation for similar customers is better.
  • The Decision Trace — full transparency into every gate, filter, score, and ranking decision. Every decision is reproducible and auditable.

​
Where to go next

Build a custom Decision Flow

Replace the Base NBA Flow with one you designed for your offers, channels, and policies.

Try the SDK

Same flow as above, in TypeScript or Python.

Wire the MCP server

Drive Kaireon from your AI assistant — Claude Desktop, Cursor, or any MCP-aware client.

Self-host

Run the same stack on your own infrastructure.