Catalog authoring

Your catalog is the set of events and missions that drive progression for your players. You build it in three steps:

1. Register an event in the event registry and publish it (gamification-config:mutate).
2. Author a mission that reacts to that event (gamification-catalog:author).
3. Approve the mission with a different key (gamification-catalog:approve). Approval is the only way a mission is published to players.

Administrators can do the same from the dashboard; see Missions in the dashboard.

The event registryCopy Anchor Link

An event declares a key, a display name, and the payload fields a mission may test.

curl -X POST "$GAMIFICATION_API_URL/v1/gamification/event-registry" \
  -H "Authorization: Bearer $TANITAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventKey": "match:won",
    "displayName": "Match won",
    "status": "published",
    "fields": [
      { "field": "mode", "primitiveType": "string", "allowedOperators": ["eq", "in"], "required": true },
      { "field": "kills", "primitiveType": "number", "allowedOperators": ["gte", "gt"] }
    ]
  }'

An event that an active mission references cannot be archived, deleted, moved back to draft, or re-registered without one of its fields: each answers 409 GAMIFICATION_EVENT_IN_USE. Disable the missions first.

Platform fields and built-in eventsCopy Anchor Link

Every event may also carry these platform fields, which you do not declare:

A condition on levelKey, currencyKey or gameSlug is checked against the owning registry when the mission is written. A reference that does not exist is refused with 422 GAMIFICATION_REGISTRY_REFERENCE_INVALID; if the registry cannot be reached the write answers 503 GAMIFICATION_REGISTRY_UNAVAILABLE, which you can retry.

Tanitar also defines built-in events that missions can use without registering them: player:game-won and tournament:completed (field gameSlug), gamification:chest-opened (field chestType) and reward:granted (field currencyKey).

MissionsCopy Anchor Link

curl -X POST "$GAMIFICATION_API_URL/v1/gamification/catalog/missions" \
  -H "Authorization: Bearer $TANITAR_AUTHOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "missionKey": "win-three-ranked",
    "displayName": "Win three ranked matches",
    "eventKey": "match:won",
    "conditions": [{ "field": "mode", "operator": "eq", "value": "ranked" }],
    "rewards": [
      { "rewardType": "xp", "amount": 150 },
      { "rewardType": "currency", "amount": 25, "key": "gems" },
      { "rewardType": "chest", "key": "rare" }
    ],
    "cadence": "daily",
    "targetCount": 3,
    "authorType": "human"
  }'

The approval state, the publication flag and the author are never taken from the body. Every create or update stores the mission as pending and unpublished, so an approval never carries over to terms nobody approved. A write that fails a rule is refused whole with a 422; nothing is stored.

The response is the stored mission, including approvalState, active, published and a revision that increases on every change.

Your catalog starts with one mission provided by Tanitar, core-win-valorant, which reacts to player:game-won for the valorant game. It appears the first time you read your catalog or send an event; you can disable it like any other mission.

ApprovalCopy Anchor Link

curl -X POST "$GAMIFICATION_API_URL/v1/gamification/catalog/approvals" -d '{ "missionKey": "win-three-ranked" }' \
  -H "Authorization: Bearer $TANITAR_APPROVER_KEY" \
  -H "Content-Type: application/json"

Approval sets the mission to approved and publishes it in one step. It is refused when:

Level curveCopy Anchor Link

The level curve sets how much XP each level costs. Until you author one, a default curve applies (revision 0). Every change appends a new revision; earlier revisions stay readable because a player's stored level records the revision it was earned under.

curl -X PUT "$GAMIFICATION_API_URL/v1/gamification/levels/curve" \
  -H "Authorization: Bearer $TANITAR_API_KEY" \
  -H "If-Match: \"3\"" \
  -H "Content-Type: application/json" \
  -d '{
    "levels": [
      { "level": 1, "xpRequired": 100 },
      { "level": 2, "xpRequired": 250 },
      { "level": 3, "xpRequired": 500 }
    ],
    "levelCap": null
  }'

• xpRequired is the XP a player must earn to leave that level.
• Levels start at 1 and increase by one with no gaps; each costs more than the one before; at most 200 levels and 1,000,000 XP per level. levelCap is optional, between 2 and the highest level the table reaches; null removes a cap. A breach is 422 GAMIFICATION_LEVEL_CURVE_INVALID.
• Once you have stored a curve, If-Match must carry its current revision. A missing header is 400 GAMIFICATION_PRECONDITION_REQUIRED; a stale one is 409 GAMIFICATION_LEVEL_CURVE_REVISION_MISMATCH: read the curve again and retry.
• A change applies forward only: levels players already hold stand, and the new curve prices their next level.

Membership-tier settingsCopy Anchor Link

Tier settings decide which of your membership tiers unlock the premium battle-pass track.

The body is premiumLevelKeys: up to 20 tier keys you have published. An empty list means no tier is premium. If you never store settings, the tiers premium and pro unlock the premium track.

Chest drop tables and the chest currency are configured with the same scope; see Seasons and chests.