Creating Leaderboards

Creating Leaderboards

This guide teaches you how to provision, update, and retire leaderboards via the Admin Gateway. It assumes you already understand the configuration model from Leaderboard Overview.

1. Authentication Recap

Admin endpoints require API Key or JWT authentication. Include either:

X-API-Key: <ADMIN_API_KEY>

or

Authorization: Bearer <ADMIN_API_KEY>

For tenant-scoped routes (/v1/tenants/{tenant_id}/...), the API key or JWT must have access to that tenant. Phoenix returns 403 if permissions are insufficient.

2. List Existing Leaderboards

Endpoint

GET /v1/leaderboards

Response

{
  "total": 2,
  "leaderboards": [
    {
      "leaderboard_id": "xp-weekly-global",
      "tenant_id": "tenant-prod-001",
      "name": "Global Weekly XP",
      "description": "Weekly XP race across all regions",
      "status": "active",
      "version": 3,
      "config": { "...": "..." },
      "created_at": "2025-08-01T12:00:00Z",
      "updated_at": "2025-11-18T09:15:42Z"
    }
  ]
}

Use GET /v1/leaderboards?tenant_id=${tenant_id} to list leaderboards for a specific tenant.

3. Create a Leaderboard

Endpoint

POST /v1/leaderboards?tenant_id=${tenant_id}

Request Body

{
  "leaderboard_id": "xp-weekly-global",
  "tenant_id": "tenant-prod-001",
  "name": "Global Weekly XP",
  "description": "Weekly XP race across all regions",
  "config": {
    "scope": {
      "filters": {
        "actor.metadata.region": { "in": ["na", "eu"] }
      }
    },
    "timeframe": {
      "type": "weekly",
      "timezone": "UTC",
      "reset_day": "monday",
      "reset_time": "00:00"
    },
    "scoring": {
      "rules": [
        {
          "event_type": "match.completed",
          "points_expression": "attrs.score",
          "conditions": {
            "attrs.victory": { "eq": true }
          }
        }
      ],
      "aggregation": "sum"
    },
    "ranking": {
      "method": "score_desc",
      "size": 1000,
      "min_score": 0
    }
  }
}

Validation highlights

• leaderboard_id must be alphanumeric with hyphens/underscores.
• tenant_id in the body must match the URL path.
• Config is validated server-side using the same rules documented in Leaderboard Overview. Errors return 400 with descriptive messages (e.g., "reset_day is required when type is 'weekly'").

cURL example

curl -X POST \
  "$ADMIN_BASE_URL/v1/leaderboards?tenant_id=${tenant_id}" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ADMIN_API_KEY" \
  -d @leaderboard.json

If successful, Phoenix returns the persisted record plus timestamps/version.

4. Retrieve a Single Leaderboard

GET /v1/leaderboards/{leaderboard_id}?tenant_id=${tenant_id}

This returns the full record (same shape as creation response). Use it to confirm deployed configs or to seed your admin UI.

5. Update Metadata or Status

PUT /v1/leaderboards/{leaderboard_id}?tenant_id=${tenant_id}
Content-Type: application/json

Body supports:

{
  "name": "Updated Display Name",
  "description": "New marketing copy",
  "status": "inactive"
}

• status accepts active, inactive, or archived.
• Phoenix automatically increments the version and updated_at fields.
• Config changes (scope/timeframe/scoring/ranking) require a new leaderboard today; we recommend cloning the existing config, editing, and recreating if you need structural changes. (Config mutability is on the roadmap; contact support for guidance.)

6. Delete a Leaderboard

DELETE /v1/leaderboards/{leaderboard_id}?tenant_id=${tenant_id}

Deletes the configuration and returns the removed record. Existing historical data remains accessible via Query Gateway snapshots.

Use deletion sparingly; inactive/archived statuses are usually sufficient to hide leaderboards from players while preserving admin history.

7. Error Reference

Responses follow the standard error envelope:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "leaderboard_id can only contain alphanumeric characters, hyphens, and underscores",
    "status": 400
  }
}

8. Tips Before Going Live

• Keep leaderboard_id slugs stable; they are referenced by ingestion and query clients.
• Store configs in source control so you can track changes outside Phoenix.
• Exercise new configs in a staging tenant (short timeframes) before promoting to production.
• Coordinate status changes (active ↔ inactive) with your live ops calendar so players know what to expect.

Next up: Realtime Updates, which covers WebSocket subscriptions, pagination, and filter strategies for displaying live leaderboards to players.