openapi: 3.1.0
info:
  title: Itch.io Auth Wharf 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: Wharf
  description: Wharf build infrastructure operations (butler/CI integration)
paths:
  /wharf/status:
    get:
      operationId: wharfStatus
      summary: Wharf status
      description: Requests the status of the wharf build infrastructure.
      tags:
      - Wharf
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WharfStatusResponse'
  /wharf/channels:
    get:
      operationId: listChannels
      summary: List wharf channels
      description: Returns a list of channels for a game.
      tags:
      - Wharf
      parameters:
      - name: target
        in: query
        required: true
        description: Target in the format user/game
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListChannelsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /wharf/channels/{channelName}:
    get:
      operationId: getChannel
      summary: Get wharf channel
      description: Returns information about a given channel for a given game.
      tags:
      - Wharf
      parameters:
      - name: channelName
        in: path
        required: true
        schema:
          type: string
      - name: target
        in: query
        required: true
        description: Target in the format user/game
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetChannelResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /wharf/builds:
    post:
      operationId: createBuild
      summary: Create wharf build
      description: Creates a new build for a given user/game:channel, with an optional user version.
      tags:
      - Wharf
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - target
              - channel
              properties:
                target:
                  type: string
                  description: Target in the format user/game
                channel:
                  type: string
                  description: Channel name (e.g. windows-64)
                user_version:
                  type: string
                  description: Optional developer-specified version string
                hidden:
                  type: boolean
                  description: If true, the build is hidden
                source:
                  type: string
                  description: Source that initiated the push (e.g. cli, butlerd, app)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateBuildResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /wharf/builds/{buildId}:
    get:
      operationId: getWharfBuild
      summary: Get wharf build
      description: Retrieves info about a single build by ID via the owner-side wharf endpoint.
      tags:
      - Wharf
      parameters:
      - name: buildId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWharfBuildResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /wharf/builds/{buildId}/files:
    get:
      operationId: listBuildFiles
      summary: List build files
      description: Returns a list of files associated to a build.
      tags:
      - Wharf
      parameters:
      - name: buildId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBuildFilesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createBuildFile
      summary: Create build file
      description: Creates a new build file entry for a build.
      tags:
      - Wharf
      parameters:
      - name: buildId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - type
              properties:
                type:
                  type: string
                  enum:
                  - patch
                  - archive
                  - signature
                  - manifest
                  - unpacked
                sub_type:
                  type: string
                  enum:
                  - default
                  - gzip
                  - optimized
                upload_type:
                  type: string
                  enum:
                  - multipart
                  - resumable
                  - deferred_resumable
                filename:
                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateBuildFileResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /wharf/builds/{buildId}/files/{fileId}:
    post:
      operationId: finalizeBuildFile
      summary: Finalize build file
      description: Marks the end of the upload for a build file. Validates that the file size in storage matches the provided size.
      tags:
      - Wharf
      parameters:
      - name: buildId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: fileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - size
              properties:
                size:
                  type: integer
                  format: int64
                  description: Expected file size in bytes
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /wharf/builds/{buildId}/events:
    get:
      operationId: listBuildEvents
      summary: List build events
      description: Returns a series of events associated with a given build.
      tags:
      - Wharf
      parameters:
      - name: buildId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBuildEventsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createBuildEvent
      summary: Create build event
      description: Associates a new build event (e.g. log message) to a build.
      tags:
      - Wharf
      parameters:
      - name: buildId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - type
              - message
              properties:
                type:
                  type: string
                  enum:
                  - log
                message:
                  type: string
                data:
                  type: string
                  description: JSON-encoded additional event data
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /wharf/builds/{buildId}/failures:
    post:
      operationId: createBuildFailure
      summary: Mark build as failed
      description: Marks a given build as failed with an error message.
      tags:
      - Wharf
      parameters:
      - name: buildId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - message
              properties:
                message:
                  type: string
                fatal:
                  type: boolean
                  description: If true, the build cannot be retried
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /wharf/builds/{buildId}/failures/rediff:
    post:
      operationId: createRediffBuildFailure
      summary: Mark build rediff as failed
      description: Marks a given build as having failed to rediff (optimize).
      tags:
      - Wharf
      parameters:
      - name: buildId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - message
              properties:
                message:
                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
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
    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
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
    CreateBuildFileResponse:
      type: object
      properties:
        file:
          $ref: '#/components/schemas/FileUploadSpec'
    FileUploadSpec:
      type: object
      description: Contains the info needed to upload one specific build file
      properties:
        id:
          type: integer
          format: int64
        uploadUrl:
          type: string
          format: uri
        uploadParams:
          type: object
          additionalProperties:
            type: string
        uploadHeaders:
          type: object
          additionalProperties:
            type: string
    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
    ListBuildEventsResponse:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/BuildEvent'
    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
    ListChannelsResponse:
      type: object
      properties:
        channels:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Channel'
    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
    GetWharfBuildResponse:
      type: object
      properties:
        build:
          $ref: '#/components/schemas/Build'
    Channel:
      type: object
      description: Contains information about a channel and its current status
      properties:
        name:
          type: string
          description: Name of the channel (e.g. windows-64-beta, osx-universal)
        tags:
          type: string
        upload:
          $ref: '#/components/schemas/Upload'
        head:
          $ref: '#/components/schemas/Build'
        pending:
          $ref: '#/components/schemas/Build'
    GetChannelResponse:
      type: object
      properties:
        channel:
          $ref: '#/components/schemas/Channel'
    ListBuildFilesResponse:
      type: object
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/BuildFile'
    BuildEvent:
      type: object
      description: Describes something that happened while processing a build
      properties:
        type:
          type: string
          enum:
          - log
        message:
          type: string
        data:
          type: object
          additionalProperties: true
    CreateBuildResponse:
      type: object
      properties:
        build:
          type: object
          properties:
            id:
              type: integer
              format: int64
            uploadId:
              type: integer
              format: int64
            parentBuild:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
    WharfStatusResponse:
      type: object
      properties:
        success:
          type: boolean
  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