Quickstart

By the end of this guide you will have a live KaireonAI tenant with seeded sample retail demo data, made one recommendation, recorded one outcome, and inspected the full decision trace. No install required — everything runs against the hosted Playground, the free trial that lets you evaluate the platform before you buy.

Open the playground

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

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

Open the API Explorer

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

Save it for the curl examples below

export KAIREON_API_KEY="krn_..."
export KAIREON_TENANT_ID="<your-tenant-id-from-the-Settings-page>"
export KAIREON_BASE_URL="https://playground.kaireonai.com"

Every key starts with the krn_ prefix. The key is bound to the tenant that created it, so X-Tenant-Id is optional on API-key requests — it is ignored in favor of the key’s own tenant. We keep it in the examples below for clarity.

A freshly minted key is data-plane-only by default: it can call /recommend, /respond, /respond/bulk, and /capture — everything this quickstart’s recommend and respond steps need. Management endpoints (including the decision-traces curl in step 5) require a key minted with the control-plane scope; see API Keys.

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
UI
MCP

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": "SBX-000042",
    "channel": "email",
    "limit": 3
  }'

The response ranks the top 3 offers for customer SBX-000042. Each entry in decisions includes a score, a 1-based rank, and the offer metadata you need to render to the customer. Field values depend on your seeded data; the shape is exactly as shown:

{
  "interactionId": "5aca955f-5570-4b41-8537-fed15051e9be",
  "recommendationId": "5aca955f-5570-4b41-8537-fed15051e9be",
  "customerId": "SBX-000042",
  "decisionFlowKey": "base-nba-flow",
  "decisionFlowVersion": 1,
  "timestamp": "2026-07-02T10:08:01.270Z",
  "channel": "email",
  "count": 3,
  "decisions": [
    {
      "offerId": "96c9eba5-1c8f-4881-937f-576be9719110",
      "offerName": "Retail Rewards: Discount — 10 Day Low",
      "creativeId": "3f2a1b4c-8e7d-4c2a-9f1e-2b3c4d5e6f70",
      "channelName": "Email",
      "categoryName": "Retail Rewards: Retention",
      "score": 0.8,
      "rank": 1,
      "personalization": {}
    }
    // …two more decisions, each with the same fields, at rank 2 and 3
  ],
  "meta": {
    "totalCandidates": 10,
    "afterQualification": 8,
    "afterSuppression": 8,
    "afterContactPolicy": 8,
    "degradedScoring": false
  }
}

Save the recommendationId (it equals interactionId on a single-flow recommendation) — together with a decision’s rank, it is how you record the outcome in step 4.

Open the Decision Trace explorer

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

Click 'New decision'

Pick customer SBX-000042, channel email, and click Run.

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.

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 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
UI
MCP

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 '{
    "customerId": "SBX-000042",
    "recommendationId": "5aca955f-5570-4b41-8537-fed15051e9be",
    "rank": 1,
    "outcome": "click",
    "idempotencyKey": "click-SBX-000042-rank1-20260702"
  }'

Replace recommendationId with the value from step 3 and rank with the position of the offer the customer acted on. idempotencyKey is required — it stops the same outcome being counted twice, so use a stable value per real interaction. outcome must be a registered outcome type (click, accept, convert, …). The response echoes the resolved offer and confirms the outcome fed the online learners:

{
  "interactionId": "5b00991f-3eb6-43f7-8c1e-2389e323c94a",
  "recommendationId": "5aca955f-5570-4b41-8537-fed15051e9be",
  "customerId": "SBX-000042",
  "outcome": "click",
  "classification": "positive",
  "rank": 1,
  "offerName": "Retail Rewards: Discount — 10 Day Low",
  "status": "recorded",
  "timestamp": "2026-07-02T10:08:18.259Z"
}

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

The assistant calls recordOutcome 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
UI
MCP

/decision-traces is a control-plane (management) endpoint. A default data-plane-only key gets 403 here — this curl needs an API key minted with the control-plane scope (admin only; see API Keys). The UI and MCP tabs work without one.

curl "$KAIREON_BASE_URL/api/v1/decision-traces?customerId=SBX-000042&limit=1" \
  -H "X-API-Key: $KAIREON_API_KEY" \
  -H "X-Tenant-Id: $KAIREON_TENANT_ID"

Decision traces are looked up by customerId (or requestId), not by a trace id returned from /recommend. The response is { traces, total, limit, offset }; each trace carries per-stage counts (candidateCount, afterQualification, afterSuppression, afterContactPolicy, afterScoring, finalCount), the qualificationResults, contactPolicyResults, and scoringResults breakdowns, the rankingWeights, and the selectedOffers.

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

The assistant calls 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.

Deployment options

Compare Cloud, Dedicated, and Enterprise on-prem plans as you move from trial to production.

Get Started

Tutorials

Use Cases

Decisioning

Studio

Data Pipelines

AI & ML

Operations & Reporting

Governance & Security

Integrations

Reference

2. Get your API key

3. Make your first recommendation

4. Record the outcome

5. See the decision trace

What just happened

Where to go next

Build a custom Decision Flow

Try the SDK

Wire the MCP server

Deployment options

​1. Sign up

​2. Get your API key

​3. Make your first recommendation

​4. Record the outcome

​5. See the decision trace

​What just happened

​Where to go next

Build a custom Decision Flow

Try the SDK

Wire the MCP server

Deployment options

1. Sign up

2. Get your API key

3. Make your first recommendation

4. Record the outcome

5. See the decision trace

What just happened

Where to go next