> ## Documentation Index > Fetch the complete documentation index at: https://docs.trophy.so/llms.txt > Use this file to discover all available pages before exploring further. # Create leaderboards > Create leaderboards. Maximum 100 leaderboards per request. ## OpenAPI ````yaml https://admin.trophy.so/v1/openapi post /leaderboards openapi: 3.1.0 info: title: Trophy version: 1.19.0 servers: - x-fern-server-name: Admin API url: https://admin.trophy.so/v1 description: Admin API security: [] paths: /leaderboards: servers: - url: https://admin.trophy.so/v1 description: Admin API parameters: - $ref: '#/components/parameters/TenantId' post: tags: - Admin summary: Create leaderboards description: Create leaderboards. Maximum 100 leaderboards per request. operationId: admin_leaderboards_create requestBody: description: Array of leaderboards to create. required: true content: application/json: schema: $ref: '#/components/schemas/CreateLeaderboardsRequest' examples: Create leaderboards: value: - name: Revenue Champions key: revenue-champions status: inactive rankBy: metric metricId: 550e8400-e29b-41d4-a716-446655440000 maxParticipants: 100 start: '2026-04-20' breakdownAttributes: - 550e8400-e29b-41d4-a716-446655440010 runUnit: month runInterval: 1 - name: Streak Legends key: streak-legends status: scheduled rankBy: streak start: '2026-04-27' responses: '200': description: Successful operation (no leaderboards created) content: application/json: schema: $ref: '#/components/schemas/CreateLeaderboardsResponse' '201': description: Created (at least one leaderboard created) content: application/json: schema: $ref: '#/components/schemas/CreateLeaderboardsResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/AdminErrorBody' '422': description: Unprocessible Entity content: application/json: schema: $ref: '#/components/schemas/AdminErrorBody' security: - ApiKeyAuth: [] servers: - url: https://admin.trophy.so/v1 description: Admin API x-codeSamples: - lang: javascript source: | import { TrophyApiClient } from '@trophyso/node'; const trophy = new TrophyApiClient({ apiKey: 'YOUR_API_KEY' }); const response = await trophy.admin.leaderboards.create([ { name: 'Revenue Champions', key: 'revenue-champions', status: 'inactive', rankBy: 'metric', metricId: '550e8400-e29b-41d4-a716-446655440000', maxParticipants: 100, start: '2026-04-20' }, { name: 'Streak Legends', key: 'streak-legends', status: 'scheduled', rankBy: 'streak', start: '2026-04-27' } ]); - lang: python source: | from trophy import TrophyApi client = TrophyApi(api_key='YOUR_API_KEY') response = client.admin.leaderboards.create([ { "name": "Revenue Champions", "key": "revenue-champions", "status": "inactive", "rankBy": "metric", "metricId": "550e8400-e29b-41d4-a716-446655440000", "maxParticipants": 100, "start": "2026-04-20" }, { "name": "Streak Legends", "key": "streak-legends", "status": "scheduled", "rankBy": "streak", "start": "2026-04-27" } ]) - lang: go source: > import ( "context" api "github.com/trophyso/trophy-go" trophyclient "github.com/trophyso/trophy-go/client" "github.com/trophyso/trophy-go/option" ) client := trophyclient.NewClient( option.WithApiKey("YOUR_API_KEY"), ) response, err := client.Admin.Leaderboards.Create(context.TODO(), api.CreateLeaderboardsRequest{}) components: parameters: TenantId: name: Tenant-ID in: header description: >- The tenant identifier for multi-tenant organisations. Required when the organisation has multi-tenancy enabled. Pass your own internal customer ID for the tenant. Ignored for single-tenant organisations. required: false schema: type: string example: customer_12345 schemas: CreateLeaderboardsRequest: title: CreateLeaderboardsRequest type: array description: Request body for creating leaderboards. items: $ref: '#/components/schemas/CreateLeaderboardRequestItem' minItems: 1 maxItems: 100 CreateLeaderboardsResponse: title: CreateLeaderboardsResponse type: object description: Response containing created leaderboards and any per-item issues. properties: created: type: array items: $ref: '#/components/schemas/AdminLeaderboard' description: Array of successfully created leaderboards. issues: type: array items: $ref: '#/components/schemas/AdminIssue' description: Array of issues encountered during leaderboard creation. required: - created - issues AdminErrorBody: title: AdminErrorBody type: object properties: error: type: string required: - error CreateLeaderboardRequestItem: title: CreateLeaderboardRequestItem type: object description: A leaderboard to create. properties: name: type: string description: The leaderboard name. example: Revenue Champions key: type: string pattern: ^[a-zA-Z\d-_]+$ description: >- The leaderboard key. Only alphanumeric characters, hyphens, and underscores are permitted. example: revenue-champions description: type: string description: The leaderboard description. example: Ranked by monthly revenue status: type: string enum: - inactive - active - scheduled - finished default: inactive description: >- The initial user-facing status. Defaults to `inactive`. Use `scheduled` for leaderboards that should be active in the future and `finished` only when creating a leaderboard with an end date in the past. example: inactive rankBy: type: string enum: - metric - streak - points description: What the leaderboard ranks by. example: metric metricId: type: string format: uuid description: The metric ID to rank by when `rankBy` is `metric`. pointsSystemId: type: string format: uuid description: The points system ID to rank by when `rankBy` is `points`. maxParticipants: type: - integer - 'null' minimum: 1 maximum: 1000 default: 1000 description: The maximum number of participants. Defaults to `1000`. example: 100 start: type: string format: date description: >- The leaderboard start date in YYYY-MM-DD format. Defaults to today when omitted. example: '2026-04-20' end: type: string format: date description: The optional leaderboard end date in YYYY-MM-DD format. example: '2026-05-20' startTime: type: string pattern: ^([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: >- When set, ranking only counts activity at or after this time of day in the user's timezone (HH:mm format). example: '09:00' endTime: type: string pattern: ^([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: >- When set, ranking only counts activity before this time of day in the user's timezone (HH:mm format). example: '17:00' breakdownAttributes: type: array description: The UUIDs of the active user attributes to break rankings down by. items: type: string format: uuid runUnit: type: string enum: - day - month - year description: >- How often the leaderboard repeats. Omit for a non-recurring leaderboard. Streak leaderboards cannot repeat. example: month runInterval: type: integer minimum: 1 description: >- The number of `runUnit`s between repeats. Required when `runUnit` is set. example: 1 required: - name - key - rankBy AdminLeaderboard: title: AdminLeaderboard type: object description: A leaderboard returned from the admin leaderboards endpoints. properties: id: type: string format: uuid description: The UUID of the leaderboard. name: type: string description: The leaderboard name. key: type: string description: The leaderboard key. description: type: string description: The leaderboard description. status: type: string enum: - inactive - active - scheduled - finished description: The current user-facing status of the leaderboard. rankBy: type: string enum: - metric - streak - points description: What the leaderboard ranks by. metricId: type: string format: uuid description: The metric ID used when `rankBy` is `metric`. pointsSystemId: type: string format: uuid description: The points system ID used when `rankBy` is `points`. maxParticipants: type: - integer - 'null' description: The maximum number of participants. start: type: string format: date description: The leaderboard start date in YYYY-MM-DD format. end: type: string format: date description: The optional leaderboard end date in YYYY-MM-DD format. startTime: type: string pattern: ^([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: >- When set, ranking only counts activity at or after this time of day in the user's timezone (HH:mm format). example: '09:00' endTime: type: string pattern: ^([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: >- When set, ranking only counts activity before this time of day in the user's timezone (HH:mm format). example: '17:00' breakdownAttributes: type: array description: The UUIDs of the user attributes used for ranking breakdowns. items: type: string format: uuid runUnit: type: string enum: - day - month - year description: The recurrence unit when the leaderboard repeats. runInterval: type: integer description: The number of recurrence units between leaderboard runs. required: - id - name - key - status - rankBy - maxParticipants - start - breakdownAttributes AdminIssue: title: AdminIssue type: object description: An issue encountered while processing an item in an admin API request. properties: id: type: string description: The ID of the resource the issue relates to, when applicable. example: 550e8400-e29b-41d4-a716-446655440000 userId: type: string description: The ID of the user the issue relates to, when applicable. example: user-123 boostId: type: string description: The ID of the points boost the issue relates to, when applicable. example: 550e8400-e29b-41d4-a716-446655440000 index: type: integer description: >- The zero-based index of the item the issue relates to, when no resource ID exists yet. example: 0 severity: type: string enum: - error - warning description: The severity level of the issue. example: warning message: type: string description: A human-readable description of the issue. example: Would exceed maximum freeze limit required: - severity - message securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY ````