OpenAPI Specification
openapi: 3.1.0
info:
title: Itch.io Auth Bundles 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: Bundles
description: Operations related to game bundles
paths:
/bundles/{bundleId}/bundle-games:
get:
operationId: getBundleGames
summary: Get bundle games
description: Retrieves a page of a bundle's games. The current user must own the bundle.
tags:
- Bundles
parameters:
- name: bundleId
in: path
required: true
schema:
type: integer
format: int64
- name: page
in: query
schema:
type: integer
format: int64
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetBundleGamesResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/bundles/{bundleId}/claim-game:
post:
operationId: claimBundleGame
summary: Claim bundle game
description: Returns a DownloadKey for a game owned via a bundle purchase, materializing one if the bundle defers download key creation. Atomic and idempotent.
tags:
- Bundles
parameters:
- name: bundleId
in: path
required: true
schema:
type: integer
format: int64
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- game_id
properties:
game_id:
type: integer
format: int64
description: ID of the game to claim from the bundle
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ClaimBundleGameResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
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
BundleGame:
type: object
description: Represents a game's membership in a bundle
properties:
bundleId:
type: integer
format: int64
bundle:
$ref: '#/components/schemas/Bundle'
gameId:
type: integer
format: int64
game:
$ref: '#/components/schemas/Game'
position:
type: integer
format: int64
minPrice:
type: integer
format: int64
description: Minimum price for this game inside the bundle in cents of a dollar
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
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
Bundle:
type: object
description: A collection of games sold together as a single purchase
properties:
id:
type: integer
format: int64
title:
type: string
url:
type: string
format: uri
coverUrl:
type: string
format: uri
gamesCount:
type: integer
format: int64
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
bundleGames:
type: array
items:
$ref: '#/components/schemas/BundleGame'
DownloadKey:
type: object
description: Allows downloading uploads for a game; typically generated at purchase time
properties:
id:
type: integer
format: int64
gameId:
type: integer
format: int64
game:
$ref: '#/components/schemas/Game'
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
ownerId:
type: integer
format: int64
ErrorResponse:
type: object
properties:
errors:
type: array
items:
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
ClaimBundleGameResponse:
type: object
properties:
downloadKey:
$ref: '#/components/schemas/DownloadKey'
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
GetBundleGamesResponse:
type: object
properties:
page:
type: integer
format: int64
perPage:
type: integer
format: int64
bundleGames:
type: array
items:
$ref: '#/components/schemas/BundleGame'
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
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