Create a new leaderboard - Returning.AI-dev

Creates a leaderboard for the API-key's community and returns the created leaderboard document.

Use this when a partner integration needs to create a custom leaderboard that is immediately readable in the ReturningAI UI.

Authentication:

Bearer API key in Authorization header

Required permission: leaderboard

Community is resolved from the API key token; do not pass communityID

Returns 401 if missing, invalid, or insufficient

Side effects:

Creates a leaderboard in the resolved community

Publishes the create:leaderboard command through the partner publisher path

Gamification service processes the command and persists the leaderboard

New leaderboard appears in the custom leaderboard UI after persistence

Rate limits:

Standard API rate limits apply

Constraints:

name must be 1-100 characters

slug must be unique per community and match lowercase letters, numbers, and hyphens

New integrations should use rankingField, displayedColumns, startDate, endDate, hasNoEndDate, isEnabled, and isPreviewEnabled

Create requires rankingField or legacy rankBy

Create requires displayedColumns or both legacy displayedFields and displayFieldsOrder

Create requires startDate or legacy duration.start

Create requires isEnabled or legacy enabled

displayedColumns has max 50 items

allowedTimeFilters values are all-time, daily, weekly, monthly, or yearly

widget.whitelistedDomains has max 50 domains

Legacy aliases are accepted for backward compatibility, but flat fields win when both are present

Example — create:

{
  "name": "April Last Leaderboard",
  "slug": "april-last-leaderboard",
  "description": "Monthly leaderboard created through the partner API.",
  "image": "https://cdn.example.com/leaderboards/april.png",
  "rankingField": "currencies",
  "displayedColumns": [
    { "column": "user", "visible": true, "order": 0 },
    { "column": "currencies", "visible": true, "order": 1 }
  ],
  "topRankOnly": false,
  "topRankLimit": 10,
  "onlyPositiveRanks": false,
  "includeDummyUsers": false,
  "startDate": "2026-01-30T19:30:00.000Z",
  "endDate": "2026-12-31T23:59:59.999Z",
  "hasNoEndDate": true,
  "timeZone": 5.3,
  "startTime": { "hours": 5, "minutes": 0, "ampm": "AM" },
  "endTime": { "hours": 11, "minutes": 59, "ampm": "PM" },
  "allowedTimeFilters": ["all-time", "monthly", "weekly"],
  "allowedUsersToRank": [],
  "allowedRolesToRank": ["507f1f77bcf86cd799439014"],
  "allowedTagsToRank": [],
  "allowedUsersToView": [],
  "allowedRolesToView": ["507f1f77bcf86cd799439014"],
  "allowedTagsToView": [],
  "isEnabled": true,
  "isPreviewEnabled": false,
  "displayOrder": 3,
  "widget": {
    "enabled": false,
    "whitelistedDomains": ["example.com"],
    "size": { "type": "custom", "value": { "width": 420, "height": 640 } },
    "button": { "enabled": true, "text": "View leaderboard", "link": "https://example.com/leaderboard" }
  }
}

Related endpoints:

GET /leaderboards — list leaderboards

GET /leaderboards/{leaderboardID} — read a single leaderboard

PATCH /leaderboards/{leaderboardID} — update a leaderboard

DELETE /leaderboards/{leaderboardID} — delete a leaderboard

Responses

🟢201Created

application/json

Leaderboard created successfully. The response envelope is required; leaderboard data fields are documented but optional for compatibility with projected or legacy shapes.

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠409

🔴500Server Error

🔴502Bad Gateway

curl --location 'https://api.returning.ai/v1/leaderboards' \ --header 'Authorization: Bearer XXXXXX' \ --header 'Content-Type: application/json' \ --data '{ "name": "April Last Leaderboard", "slug": "april-last-leaderboard", "description": "Monthly leaderboard updated through the partner API.", "image": "https://cdn.example.com/leaderboards/april.png", "rankingField": "currencies", "displayedColumns": [ { "column": "user", "visible": true, "order": 0 }, { "column": "currencies", "visible": true, "order": 1 } ], "topRankOnly": false, "topRankLimit": 10, "onlyPositiveRanks": false, "includeDummyUsers": false, "startDate": "2026-01-30T19:30:00.000Z", "endDate": "2026-12-31T23:59:59.999Z", "hasNoEndDate": true, "timeZone": 5.3, "startTime": { "hours": 5, "minutes": 0, "ampm": "AM" }, "endTime": { "hours": 11, "minutes": 59, "ampm": "PM" }, "allowedTimeFilters": [ "all-time", "monthly", "weekly" ], "allowedUsersToRank": [], "allowedRolesToRank": [ "507f1f77bcf86cd799439014" ], "allowedTagsToRank": [], "allowedUsersToView": [], "allowedRolesToView": [ "507f1f77bcf86cd799439014" ], "allowedTagsToView": [], "isEnabled": true, "isPreviewEnabled": false, "displayOrder": 3, "widget": { "enabled": false, "whitelistedDomains": [ "example.com" ], "size": { "type": "custom", "value": { "width": 420, "height": 640 } }, "button": { "enabled": true, "text": "View leaderboard", "link": "https://example.com/leaderboard" } } }'

{ "meta": { "status": "success", "statusCode": 201 }, "message": "Create leaderboard success.", "data": { "_id": "507f1f77bcf86cd799439012", "communityID": "6502c97314a3e564c5bbfa84", "name": "April Last Leaderboard", "slug": "april-last-leaderboard", "description": "Monthly leaderboard updated through the partner API.", "image": "https://cdn.example.com/leaderboards/april.png", "rankBy": "currencies", "displayedFields": [ "user", "currencies" ], "displayFieldsOrder": [ "user", "currencies" ], "timeFilters": [ "all-time", "monthly", "weekly" ], "performanceDisplay": { "showTop": { "enabled": false, "value": 10 }, "showPositive": { "enabled": false }, "showDummy": { "enabled": false } }, "duration": { "start": "2026-01-30T19:30:00.000Z", "end": "2026-12-31T23:59:59.999Z", "noEndDate": true, "timeZone": 5.3, "startTime": { "hours": 5, "minutes": 0, "ampm": "AM" }, "endTime": { "hours": 11, "minutes": 59, "ampm": "PM" } }, "rankedUserRoles": { "users": [], "roles": [ "507f1f77bcf86cd799439014" ], "tags": [] }, "viewPermissionUserRoles": { "users": [], "roles": [ "507f1f77bcf86cd799439014" ], "tags": [] }, "widget": { "enabled": false, "whitelistedDomains": [ "example.com" ], "size": { "type": "custom", "value": { "width": 420, "height": 640 } }, "button": { "enabled": true, "text": "View leaderboard", "link": "https://example.com/leaderboard" } }, "enabled": true, "previewEnabled": false, "displayOrder": 3, "selected": false, "updatedAt": "2026-04-13T12:00:00.000Z", "createdAt": "2026-04-13T12:00:00.000Z" } }