> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uplift.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Game

> Creates a game: the two teams, date, competition, pitch size and, optionally, the roster. Upload video to it with Create Clip.

> [!WARNING]
>
> The Game Data API is in preview. Endpoints, fields and limits may change before release, and it is not yet available to call.


## OpenAPI

````yaml api-reference/game-data/openapi.json POST /games
openapi: 3.0.0
info:
  title: Uplift Game Data API (Preview)
  version: v1
  description: >-
    Events, phases, possessions, physical summaries and tracking from match
    video. In preview: not yet available.
servers:
  - url: https://api.uplift.ai/v1
security: []
paths:
  /games:
    post:
      tags:
        - Games
      summary: Create Game
      description: >-
        Creates a game: the two teams, date, competition, pitch size and,
        optionally, the roster. Upload video to it with Create Clip.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - date
                - home_team
                - away_team
              properties:
                date:
                  type: string
                  format: date
                competition:
                  type: string
                home_team:
                  type: object
                  required:
                    - name
                  properties:
                    name:
                      type: string
                away_team:
                  type: object
                  required:
                    - name
                  properties:
                    name:
                      type: string
                pitch:
                  type: object
                  properties:
                    length_m:
                      type: number
                      default: 105
                    width_m:
                      type: number
                      default: 68
                roster:
                  type: array
                  items:
                    type: object
                    properties:
                      team_side:
                        type: string
                        enum:
                          - home
                          - away
                      shirt_number:
                        type: integer
                      name:
                        type: string
                      position:
                        type: string
                      athlete_id:
                        type: string
                        format: uuid
                  description: >-
                    Optional. Providing the lineup improves player
                    identification.
      responses:
        '200':
          description: Game created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  game:
                    $ref: '#/components/schemas/Game'
              example:
                game:
                  game_id: 6b1e0c2a-7d8f-4a51-9b0e-2f3c1d4e5a6b
                  status: awaiting_upload
                  run_id: null
                  date: '2026-10-18'
                  competition: Example League
                  home_team:
                    team_id: t-0451
                    team_side: home
                    name: Home FC
                  away_team:
                    team_id: t-0388
                    team_side: away
                    name: Away United
                  pitch:
                    length_m: 105
                    width_m: 68
                  periods:
                    - period: 1
                      duration_s: 2843
                      home_attacking_direction: left_to_right
                    - period: 2
                      duration_s: 2911
                      home_attacking_direction: right_to_left
                  roster:
                    - player_id: p07
                      team_id: t-0451
                      shirt_number: 7
                      name: Player Seven
                      position: midfielder
                      athlete_id: 3c9e1f2a-8b7d-4c6e-9a5f-1d2e3b4c5a6f
                  data_available: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - bearerAuth: []
components:
  schemas:
    Game:
      type: object
      properties:
        game_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - awaiting_upload
            - processing
            - completed
            - error
          description: Processing status of the game's latest run.
        run_id:
          type: string
          format: uuid
          nullable: true
          description: Processing run the game's data currently comes from.
        date:
          type: string
          format: date
        competition:
          type: string
          nullable: true
        home_team:
          $ref: '#/components/schemas/Team'
        away_team:
          $ref: '#/components/schemas/Team'
        fps:
          type: number
          nullable: true
          description: Frame rate of the game's data.
        pitch:
          type: object
          properties:
            length_m:
              type: number
            width_m:
              type: number
        periods:
          type: array
          items:
            type: object
            properties:
              period:
                type: integer
              duration_s:
                type: number
              home_attacking_direction:
                type: string
                enum:
                  - left_to_right
                  - right_to_left
        roster:
          type: array
          items:
            $ref: '#/components/schemas/RosterPlayer'
        data_available:
          type: array
          items:
            type: string
            enum:
              - events
              - segments
              - physical
              - tracking
    Team:
      type: object
      properties:
        team_id:
          type: string
          description: Stable team identifier.
        team_side:
          type: string
          enum:
            - home
            - away
        name:
          type: string
    RosterPlayer:
      type: object
      properties:
        player_id:
          type: string
          description: Roster entry for this game.
        team_id:
          type: string
          description: Stable team identifier. See `home_team` and `away_team` on the game.
        team_side:
          type: string
          enum:
            - home
            - away
        shirt_number:
          type: integer
          nullable: true
        name:
          type: string
          nullable: true
        position:
          type: string
          nullable: true
          description: '`goalkeeper`, `defender`, `midfielder` or `forward`.'
        class:
          type: string
          enum:
            - player
            - goalkeeper
            - referee
          description: Kind of person tracked. Officials are included as `referee`.
        athlete_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            Linked Uplift athlete, when known. Joins game data with capture
            data.
    Error:
      type: object
      properties:
        error:
          type: string
          description: A short error code representing the type of error.
        message:
          type: string
          description: A detailed message explaining the error.
  responses:
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: BadRequest
            message: >-
              The request parameters are invalid. Please review the request and
              try again.
    Unauthorized:
      description: Unauthorized. Bearer token is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
            message: Bearer token is missing or invalid.
    Forbidden:
      description: Forbidden. You do not have permission to access this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Forbidden
            message: You do not have permission to access this resource.
    TooManyRequests:
      description: Too Many Requests. The rate limit has been exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: TooManyRequests
            message: The rate limit has been exceeded. Please wait and try again later.
    InternalServerError:
      description: Internal Server Error. Something went wrong on the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: InternalServerError
            message: >-
              An unexpected error occurred on the server. Please try again
              later.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.