> ## 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.

# 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
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.

## 1. Sign up

<Steps>
  <Step title="Open the playground">
    Visit [playground.kaireonai.com](https://playground.kaireonai.com) and
    register. No email verification needed for the playground tier.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 2. Get your API key

<Steps>
  <Step title="Open the API Explorer">
    In the playground, click **Settings → API Explorer → Create**. Copy the key
    when shown — it is displayed only once.
  </Step>

  <Step title="Save it for the curl examples below">
    ```bash theme={null}
    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.

    <Note>
      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](/api-reference/api-keys).
    </Note>
  </Step>
</Steps>

<Note>
  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.
</Note>

## 3. Make your first recommendation

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="UI">
    <Steps>
      <Step title="Open the Decision Trace explorer">
        In the playground studio, navigate to **Studio → Decision Traces**.
      </Step>

      <Step title="Click 'New decision'">
        Pick customer **SBX-000042**, channel **email**, and click **Run**.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="MCP">
    Make sure the [Kaireon MCP server](/integrations/mcp) 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.
  </Tab>
</Tabs>

## 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:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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"
    }
    ```
  </Tab>

  <Tab title="UI">
    <Steps>
      <Step title="Open the Decision Trace from step 3">
        Click into the trace you just produced.
      </Step>

      <Step title="Click 'Record outcome'">
        Pick **click** as the outcome type. The studio writes the
        outcome event for you.
      </Step>
    </Steps>
  </Tab>

  <Tab title="MCP">
    > "Record a click outcome for the last interaction you generated."

    The assistant calls `recordOutcome` with the matching
    `interactionId` and the outcome type.
  </Tab>
</Tabs>

## 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.

<Tabs>
  <Tab title="curl">
    <Note>
      `/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](/api-reference/api-keys)). The UI and MCP tabs work without
      one.
    </Note>

    ```bash theme={null}
    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`.
  </Tab>

  <Tab title="UI">
    <Steps>
      <Step title="Open the trace">
        From **Studio → Decision Traces**, click the trace from step 3.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="MCP">
    > "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.
  </Tab>
</Tabs>

## 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

<CardGroup cols={2}>
  <Card title="Build a custom Decision Flow" icon="diagram-project" href="/decisioning/decision-flows">
    Replace the Base NBA Flow with one you designed for your offers, channels, and policies.
  </Card>

  <Card title="Try the SDK" icon="code" href="/tutorials/sdk-quickstart">
    Same flow as above, in TypeScript or Python.
  </Card>

  <Card title="Wire the MCP server" icon="robot" href="/integrations/mcp">
    Drive Kaireon from your AI assistant — Claude Desktop, Cursor, or any MCP-aware client.
  </Card>

  <Card title="Deployment options" icon="server" href="/self-host/deploy/options">
    Compare Cloud, Dedicated, and Enterprise on-prem plans as you move from trial to production.
  </Card>
</CardGroup>