Quickstart

Sign up, make your first recommendation, record an outcome, and see the decision trace — all in 5 minutes.

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

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.

UI

1. Open the Decision Trace explorer

   In the playground studio, navigate to Studio → Decision Traces.

2. Click 'New decision'

   Pick customer C001, channel email, and click Run.

3. See the result inline

   The studio shows the ranked offers and the decision trace side-by-side. Note the interactionId shown at the top — you need it to record the outcome in step 4.

MCP

Make sure the Kaireon MCP server is wired into your AI client (Claude Desktop, Cursor, etc.). Then ask your assistant:

“Make a recommendation for customer C001 on the email channel and show me the top 3 offers.”

The assistant calls the kaireon.recommend MCP tool with the right parameters and reports back the ranked results plus the interactionId you’ll use next.

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

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.

UI

1. Open the Decision Trace from step 3

   Click into the trace you just produced.

2. Click 'Record outcome'

   Pick click as the outcome type. The studio writes the outcome event for you.

MCP

“Record a click outcome for the last interaction you generated.”

The assistant calls kaireon.respond with the matching interactionId and the outcome type.

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

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.

UI

1. Open the trace

   From Studio → Decision Traces, click the trace from step 3.

2. Walk the stages

   The studio renders the trace as a flow chart: every offer’s path through eligibility → fit → match → ranking is shown with the exact rule and score that decided each step.

MCP

“Explain why the top offer was ranked first for the last interaction.”

The assistant calls kaireon.explainDecision and walks through the decisioning gates, fit filters, scoring contributions, and final rank.

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.