Creating Leaderboards

It assumes you already understand the configuration model from Leaderboards Overview.

1. Authentication Recap

Admin endpoints require API Key authentication (HMAC is supported for tenant-scoped operations but API keys are recommended). Include either of the following headers:

X-API-Key: <ADMIN_API_KEY>

or

Authorization: Bearer <ADMIN_API_KEY>

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

2. List Existing Leaderboards

Endpoint

GET /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 /tenants/{tenant_id}/leaderboards to filter by tenant when using API keys scoped to a specific partner.

3. Create a Leaderboard

Endpoint

POST /tenants/{tenant_id}/leaderboards

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.md. Errors return 400 with descriptive messages (e.g., “reset_day is required when type is 'weekly'”).

cURL example

curl -X POST \
  "$ADMIN_BASE_URL/tenants/$TENANT_ID/leaderboards" \
  -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 /tenants/{tenant_id}/leaderboards/{leaderboard_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

PATCH /tenants/{tenant_id}/leaderboards/{leaderboard_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 /tenants/{tenant_id}/leaderboards/{leaderboard_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: Real-time Updates, which covers WebSocket subscriptions, pagination, and filter strategies for displaying live leaderboards to players.