openapi: 3.1.0
info:
  title: Itch.io Auth Uploads API
  description: The itch.io server-side API provides authenticated access to user profiles, uploaded games, download key validation, purchase lookup, and build version retrieval. Authentication is via API key or short-lived JWT tokens using the Authorization Bearer header. Responses are JSON with snake_case naming and RFC 3339 dates.
  version: 1.0.0
  contact:
    name: Itch.io Support
    url: https://itch.io/support
  license:
    name: Proprietary
    url: https://itch.io/docs/legal/terms
servers:
- url: https://api.itch.io
  description: Itch.io API Server
security:
- bearerAuth: []
tags:
- name: Uploads
  description: Operations related to game uploads and downloads
paths:
  /games/{gameId}/uploads:
    get:
      operationId: listGameUploads
      summary: List game uploads
      description: Lists the uploads for a game that are accessible with the current API key and game credentials.
      tags:
      - Uploads
      parameters:
      - name: gameId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/downloadKeyId'
      - $ref: '#/components/parameters/password'
      - $ref: '#/components/parameters/secret'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGameUploadsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /uploads/{uploadId}:
    get:
      operationId: getUpload
      summary: Get upload
      description: Retrieves information about a single upload by ID.
      tags:
      - Uploads
      parameters:
      - name: uploadId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/downloadKeyId'
      - $ref: '#/components/parameters/password'
      - $ref: '#/components/parameters/secret'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUploadResponse'
        '404':
          $ref: '#/components/responses/NotFound'
  /uploads/{uploadId}/builds:
    get:
      operationId: listUploadBuilds
      summary: List upload builds
      description: Lists recent builds for a given upload.
      tags:
      - Uploads
      parameters:
      - name: uploadId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/downloadKeyId'
      - $ref: '#/components/parameters/password'
      - $ref: '#/components/parameters/secret'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUploadBuildsResponse'
        '404':
          $ref: '#/components/responses/NotFound'
  /uploads/{uploadId}/scanned-archive:
    get:
      operationId: getUploadScannedArchive
      summary: Get upload scanned archive
      description: Retrieves scanned archive metadata for an upload.
      tags:
      - Uploads
      parameters:
      - name: uploadId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/downloadKeyId'
      - $ref: '#/components/parameters/password'
      - $ref: '#/components/parameters/secret'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetScannedArchiveResponse'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    BuildFile:
      type: object
      description: Contains information about a build file (archive, signature, patch, etc.)
      properties:
        id:
          type: integer
          format: int64
        size:
          type: integer
          format: int64
        state:
          type: string
          enum:
          - created
          - uploading
          - uploaded
          - failed
        type:
          type: string
          enum:
          - patch
          - archive
          - signature
          - manifest
          - unpacked
        subType:
          type: string
          enum:
          - default
          - gzip
          - optimized
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    GetScannedArchiveResponse:
      type: object
      properties:
        scannedArchive:
          $ref: '#/components/schemas/ScannedArchive'
    Build:
      type: object
      description: Contains information about a specific build
      properties:
        id:
          type: integer
          format: int64
        parentBuildId:
          type: integer
          format: int64
          description: Identifier of the build before this one on the same channel, or -1 if initial
        state:
          type: string
          enum:
          - started
          - queued
          - processing
          - completed
          - failed
        uploadId:
          type: integer
          format: int64
        gameId:
          type: integer
          format: int64
        userId:
          type: integer
          format: int64
        version:
          type: integer
          format: int64
          description: Automatically-incremented version number, starting with 1
        userVersion:
          type: string
          description: Developer-specified version string from --userversion
        files:
          type: array
          items:
            $ref: '#/components/schemas/BuildFile'
        user:
          $ref: '#/components/schemas/User'
        upload:
          $ref: '#/components/schemas/Upload'
        game:
          $ref: '#/components/schemas/Game'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ScannedArchive:
      type: object
      properties:
        objectId:
          type: integer
          format: int64
        objectType:
          type: string
          enum:
          - upload
          - build
        extractedSize:
          type: integer
          format: int64
        launchTargets:
          type: object
          description: JSON metadata about launch targets
        manifest:
          type: object
          description: JSON manifest data
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
    ListUploadBuildsResponse:
      type: object
      properties:
        builds:
          type: array
          items:
            $ref: '#/components/schemas/Build'
    ListGameUploadsResponse:
      type: object
      properties:
        uploads:
          type: array
          items:
            $ref: '#/components/schemas/Upload'
    GetUploadResponse:
      type: object
      properties:
        upload:
          $ref: '#/components/schemas/Upload'
    Sale:
      type: object
      description: Describes a discount for a game
      properties:
        id:
          type: integer
          format: int64
        gameId:
          type: integer
          format: int64
        rate:
          type: number
          description: Discount rate in percent; can be negative (reverse sales)
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
    Upload:
      type: object
      description: A downloadable file; may be wharf-enabled for versioned channel-based distribution
      properties:
        id:
          type: integer
          format: int64
        storage:
          type: string
          enum:
          - hosted
          - build
          - external
        host:
          type: string
          description: Host if external storage
        filename:
          type: string
          description: Original file name (e.g. Overland_x64.zip)
        displayName:
          type: string
          description: Human-friendly name set by developer
        size:
          type: integer
          format: int64
          description: Size of upload in bytes
        channelName:
          type: string
          description: Name of the wharf channel for this upload, if wharf-enabled
        build:
          $ref: '#/components/schemas/Build'
        buildId:
          type: integer
          format: int64
        type:
          type: string
          enum:
          - default
          - flash
          - unity
          - java
          - html
          - soundtrack
          - book
          - video
          - documentation
          - mod
          - audio_assets
          - graphical_assets
          - sourcecode
          - other
        preorder:
          type: boolean
          description: Is this upload a pre-order placeholder?
        demo:
          type: boolean
          description: Is this upload a free demo?
        platforms:
          $ref: '#/components/schemas/Platforms'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    GameEmbedData:
      type: object
      description: Presentation information for embed games
      properties:
        gameId:
          type: integer
          format: int64
        width:
          type: integer
          format: int64
          description: Width of the initial viewport in pixels
        height:
          type: integer
          format: int64
          description: Height of the initial viewport in pixels
        fullscreen:
          type: boolean
          description: Whether a fullscreen button should be shown
    Game:
      type: object
      description: Represents a page on itch.io; could be a game, tool, comic, etc.
      properties:
        id:
          type: integer
          format: int64
          description: Site-wide unique identifier
        url:
          type: string
          format: uri
          description: Canonical address of the game's page on itch.io
        title:
          type: string
          description: Human-friendly title (may contain any character)
        shortText:
          type: string
          description: Human-friendly short description
        type:
          type: string
          enum:
          - default
          - flash
          - unity
          - java
          - html
          description: Type of the game page
        classification:
          type: string
          enum:
          - game
          - tool
          - assets
          - game_mod
          - physical_game
          - soundtrack
          - other
          - comic
          - book
          description: Creator-picked classification
        embed:
          $ref: '#/components/schemas/GameEmbedData'
        coverUrl:
          type: string
          format: uri
          description: Cover URL (might be a GIF)
        stillCoverUrl:
          type: string
          format: uri
          description: Non-gif cover URL; only set if the main cover is a GIF
        createdAt:
          type: string
          format: date-time
          description: Date the game was created
        publishedAt:
          type: string
          format: date-time
          description: Date the game was published; empty if not currently published
        minPrice:
          type: integer
          format: int64
          description: Price in cents of a dollar
        canBeBought:
          type: boolean
          description: Are payments accepted?
        hasDemo:
          type: boolean
          description: Does this game have a demo available?
        inPressSystem:
          type: boolean
          description: Is this game part of the itch.io press system?
        platforms:
          $ref: '#/components/schemas/Platforms'
        user:
          $ref: '#/components/schemas/User'
        userId:
          type: integer
          format: int64
        sale:
          $ref: '#/components/schemas/Sale'
        viewsCount:
          type: integer
          format: int64
          description: Owner-only field
        downloadsCount:
          type: integer
          format: int64
          description: Owner-only field
        purchasesCount:
          type: integer
          format: int64
          description: Owner-only field
        published:
          type: boolean
          description: Owner-only field
    Platforms:
      type: object
      description: Describes which OS/architectures a game or upload is compatible with
      properties:
        windows:
          type: string
          enum:
          - all
          - '386'
          - amd64
        linux:
          type: string
          enum:
          - all
          - '386'
          - amd64
        osx:
          type: string
          enum:
          - all
          - '386'
          - amd64
    User:
      type: object
      description: Represents an itch.io account with basic profile info
      properties:
        id:
          type: integer
          format: int64
          description: Site-wide unique identifier generated by itch.io
        username:
          type: string
          description: The user's username (used for login)
        displayName:
          type: string
          description: The user's display name; may contain spaces and unicode characters
        developer:
          type: boolean
          description: Has the user opted into creating games?
        pressUser:
          type: boolean
          description: Is the user part of itch.io's press program?
        url:
          type: string
          format: uri
          description: The address of the user's page on itch.io
        coverUrl:
          type: string
          format: uri
          description: User's avatar URL; may be a GIF
        stillCoverUrl:
          type: string
          format: uri
          description: Static version of user's avatar; only set if the main cover URL is a GIF
  parameters:
    password:
      name: password
      in: query
      description: Password for restricted pages
      schema:
        type: string
    secret:
      name: secret
      in: query
      description: Secret for private pages
      schema:
        type: string
    downloadKeyId:
      name: download_key_id
      in: query
      description: Download key ID for accessing paid content
      schema:
        type: integer
        format: int64
  responses:
    Unauthorized:
      description: Authentication is required or credentials are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or JWT token issued by itch.io