Progress, XP and levels

Read a player's progressCopy Anchor Link

Set PLAYER_ID to your identifier for the player.

curl "$GAMIFICATION_API_URL/v1/gamification/players/$PLAYER_ID/progress" \
  -H "Authorization: Bearer $TANITAR_API_KEY"

{
  "playerId": "player-2231",
  "level": 4,
  "experience": 120,
  "totalExperience": 1320,
  "currentStreak": 3,
  "longestStreak": 9,
  "lastActivityDate": "2026-09-30",
  "curve": {
    "revision": 2,
    "earnedUnderRevision": 2,
    "source": "tenant",
    "maxLevel": 30,
    "atMaxLevel": false,
    "currentLevelXpRequired": 400,
    "nextLevelXpRequired": 550,
    "thresholds": [{ "level": 1, "xpRequired": 100 }]
  },
  "missions": [
    {
      "missionKey": "win-three-ranked",
      "currentCount": 2,
      "requiredCount": 3,
      "status": "active",
      "occurrence": 1,
      "periodStart": "2026-09-30T00:00:00.000Z",
      "completedAt": null
    }
  ]
}

A player you have never sent an event for reads as an empty progression (level 1, no XP, no missions); the read creates nothing. The read is always scoped to your tenant, so naming a player that belongs to another organizer returns your own empty record for that identifier, never theirs.

FieldsCopy Anchor Link

XP and levelsCopy Anchor Link

XP reaches a player from three places: an xp mission reward, an XP drop from a chest, and an xp reward on a battle-pass tier. Each grant adds to experience and totalExperience; when experience passes the current level's price the player levels up, possibly by several levels at once. Each grant publishes gamification.xp.granted with the amount, the new total, the previous and new level and the levels gained.

You set the prices with the level curve.

StreaksCopy Anchor Link

A player's streak advances on the first mission completion of each UTC day. Completing a mission on the next UTC day extends the streak; a gap of two days or more restarts it at 1 on the next completion. There is no nightly reset: a lapsed streak is noticed when the player next completes a mission. Each advance publishes gamification.streak.advanced.

Reaching a streak of 3, 7, 14 or 30 days is a milestone, recorded once per player. Each milestone pays a chest: common at 3 days, rare at 7, epic at 14 and legendary at 30.

Replay a player's historyCopy Anchor Link

When you publish a mission after the activity it counts has already happened, replay lets that activity count.

curl -X POST "$GAMIFICATION_API_URL/v1/gamification/replay" -d '{ "playerId": "player-2231" }' \
  -H "Authorization: Bearer $TANITAR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json"

{ "playerId": "player-2231", "replayed": 500, "completed": 2, "skipped": 0, "nextOffset": 500 }

Replay re-evaluates the player's events retained from the last 90 days, oldest first, through the same path as live ingestion, and can complete missions and pay their rewards.

• It is safe to repeat. An event that already counted toward a mission never counts again, so re-running a replay over the same history completes nothing and pays nothing twice.
• It is bounded. One call processes at most 500 events. When nextOffset is not null, call again with "offset": <nextOffset> under a new Idempotency-Key to continue.
• skipped counts events that are not replayable: built-in events, which are consequences of work Tanitar already did.
• Tier-restricted missions are not backfilled. A mission with allowedLevelKeys is never advanced by replay, because the tier a player held when the event happened cannot be reconstructed.

Replay is also the scope that authorizes granting a chest to a player, since both change a player's state directly.