API Reference

Sidekick exposes 4 REST endpoints on Cloudflare edge. Server-to-server calls use a Bearer secret key. Browser/widget calls use a public key as query param.

Authentication

Each operator gets two keys:

pk_xxx — public key, safe to ship in the browser. Used by the widget via ?pk= query string.
sk_xxx — secret key, never exposed to the browser. Used server-to-server via Authorization: Bearer sk_xxx.

Endpoints

POST/api/v1/events

🔐 Authorization: Bearer sk_xxx

Ingest player events. The mission engine processes them, advances missions, grants rewards, awards XP.

Request body

{
  "userId": "player_xyz",         // operator's player ID
  "event": "bet_placed",          // event key
  "amount": 20,                   // optional, currency amount
  "currency": "EUR",              // optional, defaults to EUR
  "data": { "category": "sport", "legs": 4 },  // arbitrary metadata
  "externalId": "ev_12345",       // optional, for idempotency
  "user": {                       // optional, updates the user record
    "name": "Liam", "country": "UK", "ageRange": "25-34"
  }
}

Response

{
  "ok": true,
  "user": { "xp": 250, "level": 3 },
  "advanced": [ { "missionSlug": "three_slots", "progressBefore": 2, "progressAfter": 3 } ],
  "completed": [ { "missionSlug": "three_slots" } ],
  "rewards": [ { "id": "...", "reward_type": "free_spins", "amount": 10 } ],
  "xpGained": 100
}

Supported event keys

bet_placed, bet_settled, deposit_made, withdrawal_made, session_start, session_end, slot_played, live_played, sport_played, game_opened, kyc_completed

GET/api/v1/users/:id?pk=pk_xxx

🔓 Public (query param key)

Returns the full state of a player: XP, level, mission progress, granted rewards.

Response

{
  "user": { "externalId": "...", "name": "Liam", "xp": 250, "level": 3, "levelLabel": "MADE MEMBER" },
  "missions": [ { "slug": "...", "name": "...", "threshold": 3, "progress": 2, "completed": false, "reward": {...} } ],
  "rewards": [ { "id": "...", "reward_type": "free_spins", "amount": 10, "status": "granted" } ]
}

GET/api/v1/config?pk=pk_xxx&skin=optional

🔓 Public

Bootstrap config for the widget: operator info + character skin manifest (palette, characters, voice prompt).

POST/api/v1/redeem?pk=pk_xxx

🔓 Public

Mark a reward as redeemed. Sidekick fires a reward_redeemed webhook to your configured webhook URL.

Body

{ "userId": "player_xyz", "rewardId": "uuid-here" }

Webhooks (Sidekick → operator)

When a reward is redeemed, Sidekick POSTs to your configured webhook URL:

POST https://your-operator.com/sidekick-webhook
X-Sidekick-Signature: sha256=...

{
  "event": "reward_redeemed",
  "userId": "player_xyz",
  "reward": { "id": "...", "reward_type": "free_spins", "amount": 10 }
}

Verify the HMAC signature, then credit the player's wallet in your backend. Respond 200.

Rate limits

Free tier: 100k requests/day across all operators. Beyond that, scaling tiers apply (see pricing).