openapi: 3.1.0
info:
  title: Amazon DeepRacer Cars Leaderboards API
  description: The Amazon DeepRacer API provides programmatic access to manage DeepRacer vehicles, reinforcement learning models, leaderboards, and training tracks for autonomous racing experiences on AWS. Resources are versioned under /20201101/.
  version: 2020-11-01
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/deepracer/
  termsOfService: https://aws.amazon.com/service-terms/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://deepracer.amazonaws.com
  description: Amazon DeepRacer API
security:
- awsSignatureV4: []
tags:
- name: Leaderboards
  description: Manage racing leaderboards and submissions
paths:
  /20201101/leaderboards:
    get:
      operationId: listLeaderboards
      summary: List Leaderboards
      description: List all active and past DeepRacer racing leaderboards.
      tags:
      - Leaderboards
      parameters:
      - name: nextToken
        in: query
        description: Pagination token from a previous list response.
        required: false
        schema:
          type: string
      - name: maxResults
        in: query
        description: Maximum number of leaderboards to return.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: status
        in: query
        description: Filter leaderboards by status (ACTIVE, EXPIRED).
        required: false
        schema:
          type: string
          enum:
          - ACTIVE
          - EXPIRED
      responses:
        '200':
          description: List of leaderboards retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListLeaderboardsResponse'
              example:
                leaderboards:
                - arn: arn:aws:deepracer:us-east-1:123456789012:leaderboard/deepracer-league-2024
                  name: DeepRacer League 2024
                  status: ACTIVE
                  submissionClosureTime: '2024-12-31T23:59:59Z'
                  isQualifier: true
                nextToken: null
                x-microcks-default: true
        '400':
          description: Bad request — invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /20201101/leaderboards/{arn}:
    get:
      operationId: getLeaderboard
      summary: Get Leaderboard
      description: Retrieve the details and current rankings for a specific leaderboard.
      tags:
      - Leaderboards
      parameters:
      - name: arn
        in: path
        description: The ARN of the leaderboard.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Leaderboard details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Leaderboard'
              example:
                arn: arn:aws:deepracer:us-east-1:123456789012:leaderboard/deepracer-league-2024
                name: DeepRacer League 2024
                status: ACTIVE
                submissionClosureTime: '2024-12-31T23:59:59Z'
                isQualifier: true
                trackType: REINVENT_2018
                minimumCountOfLaps: 1
                x-microcks-default: true
        '404':
          description: Leaderboard not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /20201101/leaderboards/{arn}/rankings:
    get:
      operationId: listLeaderboardSubmissions
      summary: List Leaderboard Submissions
      description: List submissions and rankings for a specific leaderboard.
      tags:
      - Leaderboards
      parameters:
      - name: arn
        in: path
        description: The ARN of the leaderboard.
        required: true
        schema:
          type: string
      - name: nextToken
        in: query
        description: Pagination token from a previous list response.
        required: false
        schema:
          type: string
      - name: maxResults
        in: query
        description: Maximum number of submissions to return.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Leaderboard submissions and rankings retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListLeaderboardSubmissionsResponse'
              example:
                leaderboardSubmissions:
                - leaderboardSubmissionId: submission-abc123
                  participantName: racer-001
                  modelArn: arn:aws:deepracer:us-east-1:123456789012:model/reinforcement_learning/SpeedModel
                  rank: 1
                  lapTime: 8.543
                  avgLapTime: 8.721
                nextToken: null
                x-microcks-default: true
        '404':
          description: Leaderboard not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ListLeaderboardsResponse:
      type: object
      description: Response containing a list of DeepRacer leaderboards.
      properties:
        leaderboards:
          type: array
          description: List of leaderboards.
          items:
            $ref: '#/components/schemas/Leaderboard'
        nextToken:
          type: string
          description: Token for retrieving the next page of results.
    LeaderboardSubmission:
      type: object
      description: A participant's submission to a DeepRacer leaderboard including their race performance.
      properties:
        leaderboardSubmissionId:
          type: string
          description: Unique identifier for this leaderboard submission.
        participantName:
          type: string
          description: The participant's alias or username.
        modelArn:
          type: string
          description: The ARN of the model submitted for evaluation.
        rank:
          type: integer
          description: The participant's current rank on the leaderboard.
        lapTime:
          type: number
          format: double
          description: The participant's best single lap time in seconds.
        avgLapTime:
          type: number
          format: double
          description: The participant's average lap time across all evaluated laps.
    Leaderboard:
      type: object
      description: A DeepRacer racing leaderboard where participants submit model performances.
      properties:
        arn:
          type: string
          description: The ARN uniquely identifying the leaderboard.
        name:
          type: string
          description: The display name of the leaderboard.
        status:
          type: string
          description: Current status of the leaderboard (ACTIVE or EXPIRED).
          enum:
          - ACTIVE
          - EXPIRED
        submissionClosureTime:
          type: string
          format: date-time
          description: Timestamp when the leaderboard stops accepting new submissions.
        isQualifier:
          type: boolean
          description: Whether this leaderboard qualifies participants for championship events.
        trackType:
          type: string
          description: The type of track used for this leaderboard.
        minimumCountOfLaps:
          type: integer
          description: Minimum number of consecutive laps required for a valid submission.
    Error:
      type: object
      description: Error response returned when an API request fails.
      properties:
        message:
          type: string
          description: A human-readable description of the error.
        code:
          type: string
          description: An error code identifying the type of failure.
    ListLeaderboardSubmissionsResponse:
      type: object
      description: Response containing leaderboard rankings and submissions.
      properties:
        leaderboardSubmissions:
          type: array
          description: List of participant submissions and rankings.
          items:
            $ref: '#/components/schemas/LeaderboardSubmission'
        nextToken:
          type: string
          description: Token for retrieving the next page of results.
  securitySchemes:
    awsSignatureV4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4 authentication. Sign requests using your AWS access key, secret key, and session token.