SDK Quickstart

X-Tenant-Id: <your-tenant-id>
X-API-Key: <your-api-key>
Content-Type: application/json

npm install node-fetch   # only needed for Node < 18

const BASE_URL = "https://playground.kaireonai.com";

const headers = {
  "Content-Type": "application/json",
  "X-Tenant-Id": "YOUR_TENANT_ID",
  "X-API-Key": "YOUR_API_KEY",
  "X-Requested-With": "XMLHttpRequest",
};

async function getRecommendations(customerId, limit = 3) {
  const response = await fetch(`${BASE_URL}/api/v1/recommend`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      customerId,
      limit,
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Recommend failed (${response.status}): ${error.error}`);
  }

  return response.json();
}

// Usage
const result = await getRecommendations("SBX-000100");
console.log("Decisions:", result.decisions);
console.log("Recommendation ID:", result.recommendationId);

{
  "recommendationId": "rec-uuid",
  "customerId": "SBX-000100",
  "count": 3,
  "decisions": [
    {
      "offerId": "offer-abc",
      "offerName": "Retail Rewards: Discount — 10 Day Low",
      "categoryName": "Retail Rewards: Retention",
      "channelName": "Retail Rewards: Email",
      "creativeId": "creative-xyz",
      "score": 0.85,
      "rank": 1,
      "content": { "subject": "Special offer", "body": "<p>Save today</p>" },
      "personalization": {}
    }
  ],
  "meta": { "totalCandidates": 60, "afterQualification": 60, "afterContactPolicy": 60, "degradedScoring": false }
}

async function recordOutcome(customerId, creativeId, outcome) {
  const response = await fetch(`${BASE_URL}/api/v1/respond`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      customerId,
      creativeId,  // from the recommend response decisions[].creativeId
      outcome,     // e.g. "impression", "click", "dismiss", "conversion"
      idempotencyKey: `${outcome}-${Date.now()}`,
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Respond failed (${response.status}): ${error.error}`);
  }

  return response.json();
}

// Usage — record a click on the first decision
const decision = result.decisions[0];
await recordOutcome("SBX-000100", decision.creativeId, "click");

{
  "interactionId": "interaction-uuid",
  "customerId": "SBX-000100",
  "outcome": "click",
  "classification": "positive",
  "offerName": "Retail Rewards: Discount — 10 Day Low",
  "status": "recorded"
}

try {
  const recs = await getRecommendations("cust-001");
} catch (err) {
  // 401 -- invalid API key or tenant ID
  // 404 -- customer not found or no active decision flow
  // 422 -- validation error (bad request body)
  // 429 -- rate limited
  // 500 -- server error
  console.error("API error:", err.message);
}

pip install requests

import requests

BASE_URL = "https://playground.kaireonai.com"

HEADERS = {
    "Content-Type": "application/json",
    "X-Tenant-Id": "YOUR_TENANT_ID",
    "X-API-Key": "YOUR_API_KEY",
    "X-Requested-With": "XMLHttpRequest",
}


def get_recommendations(customer_id: str, limit: int = 3) -> dict:
    response = requests.post(
        f"{BASE_URL}/api/v1/recommend",
        headers=HEADERS,
        json={
            "customerId": customer_id,
            "limit": limit,
        },
    )
    response.raise_for_status()
    return response.json()


# Usage
result = get_recommendations("SBX-000100")
print("Decisions:", result["decisions"])
print("Recommendation ID:", result["recommendationId"])

import time

def record_outcome(
    customer_id: str,
    creative_id: str,
    outcome: str,
) -> dict:
    response = requests.post(
        f"{BASE_URL}/api/v1/respond",
        headers=HEADERS,
        json={
            "customerId": customer_id,
            "creativeId": creative_id,   # from decisions[].creativeId
            "outcome": outcome,          # e.g. impression, click, dismiss, conversion
            "idempotencyKey": f"{outcome}-{int(time.time())}",
        },
    )
    response.raise_for_status()
    return response.json()


# Usage — record a click on the first decision
decision = result["decisions"][0]
record_outcome("SBX-000100", decision["creativeId"], "click")

from requests.exceptions import HTTPError

try:
    recs = get_recommendations("cust-001")
except HTTPError as err:
    status = err.response.status_code
    body = err.response.json()
    # 401 -- invalid API key or tenant ID
    # 404 -- customer not found or no active decision flow
    # 422 -- validation error (bad request body)
    # 429 -- rate limited
    # 500 -- server error
    print(f"API error ({status}): {body.get('error', 'Unknown')}")