openapi: 3.0.1
info:
  title: Unity Analytics Allocations Leaderboards API
  description: The Unity Analytics REST API provides endpoints for ingesting custom analytics events from game clients and servers. Events are used to track player behavior, game performance, and feature adoption. The API supports batched event ingestion with automatic retry and buffering for high-volume game telemetry.
  version: v1.0.0
  termsOfService: https://unity.com/legal/terms-of-service
  contact:
    name: Unity Support
    url: https://support.unity.com
  license:
    name: Unity Terms of Service
    url: https://unity.com/legal/terms-of-service
servers:
- url: https://analytics.services.api.unity.com
  description: Unity Analytics Production Server
security:
- apiKeyAuth: []
tags:
- name: Leaderboards
  description: Manage leaderboard definitions and configuration
paths:
  /v1/projects/{projectId}/environments/{environmentId}/leaderboards:
    get:
      operationId: listLeaderboards
      summary: List Leaderboards
      description: Returns a list of all leaderboard definitions for the specified project and environment.
      tags:
      - Leaderboards
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
        description: The Unity project identifier
      - name: environmentId
        in: path
        required: true
        schema:
          type: string
        description: The environment identifier
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
        description: Maximum number of leaderboards to return
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Cursor for pagination
      responses:
        '200':
          description: List of leaderboards
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardList'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    post:
      operationId: createLeaderboard
      summary: Create Leaderboard
      description: Creates a new leaderboard definition for the specified project and environment.
      tags:
      - Leaderboards
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: environmentId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeaderboardCreate'
      responses:
        '200':
          description: Leaderboard created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Leaderboard'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
  /v1/projects/{projectId}/environments/{environmentId}/leaderboards/{leaderboardId}:
    get:
      operationId: getLeaderboard
      summary: Get Leaderboard
      description: Returns configuration details for a specific leaderboard.
      tags:
      - Leaderboards
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: environmentId
        in: path
        required: true
        schema:
          type: string
      - name: leaderboardId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Leaderboard details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Leaderboard'
        '404':
          description: Not Found
    put:
      operationId: updateLeaderboard
      summary: Update Leaderboard
      description: Updates the configuration of an existing leaderboard.
      tags:
      - Leaderboards
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: environmentId
        in: path
        required: true
        schema:
          type: string
      - name: leaderboardId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeaderboardUpdate'
      responses:
        '200':
          description: Leaderboard updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Leaderboard'
    delete:
      operationId: deleteLeaderboard
      summary: Delete Leaderboard
      description: Deletes a leaderboard and all associated scores.
      tags:
      - Leaderboards
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: environmentId
        in: path
        required: true
        schema:
          type: string
      - name: leaderboardId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Leaderboard deleted
        '404':
          description: Not Found
components:
  schemas:
    LeaderboardList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Leaderboard'
        next:
          type: string
          description: Cursor for next page
    ResetConfig:
      type: object
      properties:
        start:
          type: string
          format: date-time
        schedule:
          type: string
          description: Cron expression for reset schedule
        archive:
          type: boolean
    Leaderboard:
      type: object
      properties:
        id:
          type: string
          description: Unique leaderboard identifier
        name:
          type: string
          description: Display name for the leaderboard
        sortOrder:
          type: string
          enum:
          - asc
          - desc
          description: Sort order for scores
        bucketSize:
          type: number
          description: Bucket size for bucket leaderboards
        resetConfig:
          $ref: '#/components/schemas/ResetConfig'
        tieringConfig:
          $ref: '#/components/schemas/TieringConfig'
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
    LeaderboardUpdate:
      type: object
      properties:
        name:
          type: string
        sortOrder:
          type: string
          enum:
          - asc
          - desc
        resetConfig:
          $ref: '#/components/schemas/ResetConfig'
    LeaderboardCreate:
      type: object
      required:
      - id
      - sortOrder
      properties:
        id:
          type: string
        name:
          type: string
        sortOrder:
          type: string
          enum:
          - asc
          - desc
        bucketSize:
          type: number
        resetConfig:
          $ref: '#/components/schemas/ResetConfig'
    TieringConfig:
      type: object
      properties:
        strategy:
          type: string
          enum:
          - score
          - percentile
        tiers:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              cutoff:
                type: number
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
externalDocs:
  description: Unity Analytics Documentation
  url: https://docs.unity.com/ugs/en-us/manual/analytics/manual/rest-api