The itch.io server-side API lets you query information about your games and account by making HTTP requests to the API hosted at api.itch.io.

Looking for the older itch.io/api/1/KEY/... endpoints? See the legacy serverside API reference.

Authentication

All API endpoints require authentication. Credentials are passed in the HTTP Authorization header as a bearer token:

GET https://api.itch.io/profile
Authorization: Bearer YOUR_API_KEY

There are two types of credentials you can use:

• API keys are long-lasting credentials that can be revoked by users
• JWT tokens are short-lived, expiring credentials

Both are passed using the same Authorization: Bearer header — the API distinguishes between them automatically.

API keys

You can generate API keys for your own account from the API keys page. (You'll need an itch.io account if you don’t already have one.)

If you want to make requests on behalf of other itch.io users, you can register an OAuth application and have them grant permissions to your app.

GET https://api.itch.io/profile
Authorization: Bearer YOUR_API_KEY

JWT tokens

JWT tokens can be passed to a game when it specifies a list of requested API scopes. Read the app manifest documentation for more information.

GET https://api.itch.io/profile
Authorization: Bearer YOUR_JWT_TOKEN

Scopes

Credentials (whether they're API keys or JWT tokens) usually have a limited scope, which means they'll give access to some endpoints but not others.

In the API reference below, endpoints are listed with: HTTP method (in blue), scope (in green), and template URL.

Having access to a scope gives access to all its subscopes. For example, profile gives access to profile:me, but game:view:purchases does not give access to game:view.

API keys that you generate from your user settings are unscoped — they have access to all endpoints.

Passing parameters

GET requests that take parameters should insert them in the query string.

POST requests can either take parameters as a form-encoded body, or in the query string.

Response format

API responses are JSON-encoded, and use snake_case.

Errors are signaled by the presence of an errors field (an array of strings) in the response body.

Dates are returned in RFC 3339 format (UTC), for example: 2017-10-19T13:35:06Z

Reference

Credentials

https://api.itch.io/credentials/info

Returns information on the set of credentials used to make this API request. The response includes the credential type ("key" for API keys, "jwt" for JWT tokens), the list of scopes the credentials give access to, and (for JWT tokens) the expiration date.

Takes no parameters.

Sample response for JWT token:

{
  "type": "jwt",
  "scopes": [ "profile:me" ],
  "expires_at": "2017-10-19T13:35:06Z"
}

Sample response for API key:

{
  "type": "key",
  "scopes": [ "profile:me", "profile:games" ]
}

Profile

Endpoints about the user the credentials belong to.

profile:me https://api.itch.io/profile

Fetches public profile data for the user to which the API key belongs.

Takes no parameters.

Sample response:

{
  "user": {
    "username": "fasterthanlime",
    "gamer": true,
    "display_name": "Amos",
    "cover_url": "https://img.itch.zone/aW1hZ2UyL3VzZXIvMjk3ODkvNjkwOTAxLnBuZw==/100x100%23/JkrN%2Bv.png",
    "url": "https://fasterthanlime.itch.io",
    "press_user": true,
    "developer": true,
    "id": 29789
  }
}

profile:games https://api.itch.io/profile/games

Fetches data about all the games you've uploaded or have edit access to.

Takes no additional parameters.

Sample response:

{
   "games":[
      {
         "cover_url":"http:\/\/img.itch.io\/aW1hZ2UvMy8xODM3LnBuZw==\/315x250%23\/y2uYQI.png",
         "created_at":"2013-03-03T23:02:14Z",
         "downloads_count":109,
         "id":3,
         "min_price":0,
         "traits":["p_windows","p_linux","p_osx"],
         "classification":"game",
         "published":true,
         "published_at":"2013-03-03T23:02:14Z",
         "purchases_count":4,
         "short_text":"Humans have been colonizing planets. It's time to stop them!",
         "title":"X-Moon",
         "type":"default",
         "url":"http:\/\/leafo.itch.io\/x-moon",
         "views_count":2682,
         "earnings":[
            {
               "currency":"USD",
               "amount_formatted":"$50.47",
               "amount":5047
            }
         ]
      }
   ]
}

Games

Endpoints for games you develop or have edit access to.

game:view:purchases https://api.itch.io/games/GAME_ID/download_keys

Checks if a download key exists for game and returns it.

GAME_ID can be retrieved from the /profile/games API call above.

Requires either of the following parameters:

• download_key: The download key to look up,
• or user_id: The user identifier to look up download keys for.
• or email: The e-mail to look up download keys for.

You can use this API call to verify that someone has a valid download key to download the game.

The download key can be extracted from a buyer’s download URL. For example:

http://leafo.itch.io/x-moon/download/YWKse5jeAeuZ8w3a5qO2b2PId1sChw2B9b637w6z

The download key would be YWKse5jeAeuZ8w3a5qO2b2PId1sChw2B9b637w6z.

Passing user_id instead is useful in scenarios where you have authenticated a user via an app manifest. That makes it impossible for users to spoof their user_id.

When passing email, you are responsible for verifying the user’s email address first, otherwise they could attempt to guess an email they don’t own in order to fake ownership.

Sample output:

{
  "download_key": {
    "id":124,
    "created_at":"2014-02-28T00:25:09Z",
    "downloads":74,
    "key":"YWKse5jeAeuZ8w3a5qO2b2PId1sChw2B9b637w6z",
    "game_id":3,
    "owner":{
      "display_name": "Amos",
      "gamer": true,
      "username": "fasterthanlime",
      "id": 1994,
      "url": "https://fasterthanlime.itch.io",
      "press_user": true,
      "developer": true,
      "cover_url":
      "https://img.itch.io/aW1hZ2UyL3VzZXIvMjk3ODkvMTk4MjkwLnBuZw==/100x100%23/qg3l0J.png"
    },
  }
}

If download_key is invalid, revoked, or for another game, returns:

{
  "errors": ["invalid download key"]
}

If email or user_id hasn’t purchased or claimed the game, returns:

{
  "errors": ["no download key found"]
}

game:view:purchases https://api.itch.io/games/GAME_ID/purchases

Returns the purchases an email address has created for a given game. Only successfully completed purchases are shown.

GAME_ID can be retrieved from the /profile/games API call above.

Requires either of the following parameters:

• email: The email address to look up purchases for,
• or user_id: The user identifier to look up purchases for.

The call is aware of verified email addresses associated with the one you provide. Meaning if someone has the email person@example.com and has linked person2@example.com. You can request with either email address to get their purchase regardless of which email address it originated from.

You can use this API call to verify that someone has bought your game on itch.io on your own server. You are responsible for verifying their email address first, otherwise they could attempt to guess an email they don’t own in order to fake ownership.

Claimed keys do not have purchases associated with them, and so this endpoint will return an empty purchases object. To look up both claimed keys and purchased keys, use the /download_keys endpoint.

Sample output:

{
   "purchases":[
      {
         "donation":false,
         "id":11561,
         "email":"leaf@example.com",
         "created_at":"2014-02-28T00:25:09Z",
         "source":"amazon",
         "currency":"USD",
         "price":"$1.00",
         "sale_rate":0,
         "quantity":1,
         "status":"complete",
         "purchase_type":"game",
         "game_id":3
      }
   ]
}

The donation field is true for any purchase that doesn’t have a download key associated with it, currently this only applies to web games.

purchase_type is one of game, bundle, or sub_product. When the purchase is for a bundle that includes the game being queried, game_id is returned as an array of all game IDs included in that bundle.

Collections

Reading a collection needs collection:view, listing your own needs profile:collections, and every POST endpoint below needs collection:edit. Collection admins can do everything the owner can.

profile:collections https://api.itch.io/profile/collections

Lists the collections the current user owns or is an admin of.

Parameters:

• game_id (optional): when given, every collection includes a has_game field saying whether that game is in it.

Sample response:

{
  "collections": [
    {
      "id": 1234,
      "title": "Couch coop games",
      "url": "https:\/\/itch.io\/c\/1234\/couch-coop-games",
      "user_id": 29789,
      "games_count": 12,
      "private": false,
      "description": "<p>Games to play with friends</p>",
      "layout": "grid",
      "has_game": true,
      "created_at": "2024-02-10T18:22:01Z",
      "updated_at": "2024-06-01T09:15:44Z"
    }
  ]
}

https://api.itch.io/collections/COLLECTION_ID

Fetches a single collection. Private collections are only returned to users who can edit them.

Returns {"collection": {...}} using the same collection format as above, without has_game.

collection:view https://api.itch.io/collections/COLLECTION_ID/collection-games

Lists the games in a collection, in display order.

Parameters:

• page (optional): page number, starting at 1
• per_page (optional): items per page, default 100, max 500

Sample response:

{
  "page": 1,
  "per_page": 100,
  "collection_games": [
    {
      "collection_id": 1234,
      "game_id": 3,
      "position": 2,
      "blurb": "<p>Great with four players</p>",
      "user_id": 29789,
      "created_at": "2024-02-10T18:25:12Z",
      "game": {
        "id": 3,
        "title": "X-Moon",
        "url": "http:\/\/leafo.itch.io\/x-moon",
        "...": "..."
      }
    }
  ]
}

collection:edit https://api.itch.io/collections

Creates a collection owned by the current user.

Parameters:

• title (optional): up to 60 characters. Defaults to “USERNAME’s Collection”.
• private (optional): true or false, default false
• description (optional): HTML
• layout (optional): grid or list. Defaults to list when a blurb is given, otherwise grid.
• game_id (optional): a game to add right away
• blurb (optional): HTML note for that game, only used with game_id

Returns {"collection": {...}}.

collection:edit https://api.itch.io/collections/COLLECTION_ID

Updates a collection. Only the parameters you send are changed.

Parameters:

• title: up to 60 characters
• description: HTML, send an empty string to clear
• private: true or false
• layout: grid or list
• on_profile: true or false, whether the collection shows on the current user’s profile

Returns {"collection": {...}} with the updated collection.

collection:edit https://api.itch.io/collections/COLLECTION_ID/delete

Deletes a collection and everything in it.

Returns {"success": true}.

collection:edit https://api.itch.io/collections/COLLECTION_ID/add-game

Adds a game to the end of a collection. Adding a game that is already in the collection returns the existing entry.

Parameters:

• game_id: the game to add
• blurb (optional): HTML note for the game

Returns {"collection_game": {...}}.

collection:edit https://api.itch.io/collections/COLLECTION_ID/remove-game

Removes a game from a collection.

Parameters:

• game_id: the game to remove

Returns {"success": true, "removed": false} when the game was not in the collection.

collection:edit https://api.itch.io/collections/COLLECTION_ID/collection-games/GAME_ID

Updates a game’s entry in a collection.

Parameters:

• blurb: HTML note for the game, send an empty string to clear

Returns {"collection_game": {...}}.

collection:edit https://api.itch.io/collections/COLLECTION_ID/order

Sets the order of games in a collection, and optionally removes games at the same time. Each list holds up to 500 ids.

Parameters:

• game_ids: JSON array of game ids in the desired order, first is shown first. Games left out keep their relative positions.
• remove_game_ids (optional): JSON array of game ids to remove before ordering

Returns {"success": true}.

Wharf

https://api.itch.io/wharf/latest

Returns the latest user-version for a given channel. Useful for notifying players from within a game when a new version of a build is available, without having to bundle the itch app.

This endpoint does not require authentication.

Requires the following parameter:

• channel_name: the name of the channel to query (for example win32-beta, osx-final)

Plus either of:

• game_id: numeric identifier of the game (found on the Edit game page),
• or target: user/game slug, just like the butler push command.

Sample response:

{
  "latest": "1.2.3"
}

If the latest build does not have a user-version (i.e. the developer didn’t pass --userversion or --userversion-file when pushing), the latest field will be omitted from the response.

Example requests:

GET https://api.itch.io/wharf/latest?target=user/game&channel_name=win32-beta

GET https://api.itch.io/wharf/latest?game_id=123&channel_name=osx-final

If the game’s visibility level is set to Private, this endpoint returns the error invalid game, to avoid potentially leaking information about unreleased games.