OpenAPI Specification
openapi: 3.1.0
info:
title: Itch.io Auth Builds 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: Builds
description: Operations related to wharf builds
paths:
/uploads/{uploadId}/builds:
get:
operationId: listUploadBuilds
summary: List upload builds
description: Lists recent builds for a given upload.
tags:
- Builds
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'
/builds/{buildId}:
get:
operationId: getBuild
summary: Get build
description: Retrieves info about a single build by ID (consumer-side endpoint).
tags:
- Builds
parameters:
- name: buildId
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/GetBuildResponse'
'404':
$ref: '#/components/responses/NotFound'
/builds/{buildId}/upgrade-paths/{targetBuildId}:
get:
operationId: getBuildUpgradePath
summary: Get build upgrade path
description: Returns the complete list of builds to go through to upgrade from one version to another.
tags:
- Builds
parameters:
- name: buildId
in: path
description: Current build ID
required: true
schema:
type: integer
format: int64
- name: targetBuildId
in: path
description: Target build ID
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/GetBuildUpgradePathResponse'
'404':
$ref: '#/components/responses/NotFound'
/builds/{buildId}/scanned-archive:
get:
operationId: getBuildScannedArchive
summary: Get build scanned archive
description: Retrieves scanned archive metadata for a build.
tags:
- Builds
parameters:
- name: buildId
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'
GetBuildUpgradePathResponse:
type: object
properties:
upgradePath:
$ref: '#/components/schemas/UpgradePath'
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
UpgradePath:
type: object
description: A series of builds for which sequential patches exist
properties:
builds:
type: array
items:
$ref: '#/components/schemas/Build'
GetBuildResponse:
type: object
properties:
build:
$ref: '#/components/schemas/Build'
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:
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