Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


This repository provides the source code of the new HHub API, which powers Homebrew Hub, the largest digital collection of Game Boy and Game Boy Color homebrews, playable natively in your browser.

Table of contents:

API Documentation

The API is exposed at

Here's a quick overview of the available endpoints:

GET /entry/<entry-slug>.json

Get the game manifest for the game with the given slug identifier, providing every information available in the database about the entry. Here's a quick overview on how it's built:

  • title - Full name of the game
  • slug - A unique string identifier for a game
  • typetag - Type of the software (can be "game", "homebrew", "demo", "hackrom" or "music")
  • developer - Name of the author(s)
  • files - Attached ROM files
  • license - License under which the software is released
  • platform - Target console (can be "GB", "GBC" or "GBA")
  • screenshots - A list of filenames of screenshots
  • tags - A list of the categories representing the entry

To learn more about formal definitions of each of these properties, check the specification JSON Schema, against which every manifest is validated.



will return:

  "developer": "Sanqui",
  "files": [
      "default": true,
      "filename": "",
      "playable": true
  "license": "Zlib",
  "platform": "GB",
  "repository": "",
  "screenshots": ["1.png", "2.png"],
  "slug": "2048gb",
  "tags": ["Open Source", "Puzzle"],
  "title": "2048gb",
  "typetag": "game"

Some of these fields can be queried through the /search route.

GET /entry/<entry-slug>/<filename>

Gives access to the files related to an entry (e.g. the ROMs, screenshots,..).

File names are found in the game manifest, accessed with the previous route.


# Get the game manifest for the game with the slug "2048gb"
# In the response JSON, a file name "" is found in the "files" array, as a playable ROM
#  Let's get it:

GET /all

Returns every entry in the database. Every entry is represented by its game manifest.

GET /search

Return every entry in the database matching the given conditions. Every entry is represented by its game manifest.

The following query parameters can be used:

  • type (exact matching)
  • developer (exact matching)
  • platform (exact matching)
  • tags (exact matching, comma-separated array e.g. /search?tags=Open Source,RPG)
  • title ("contains" matching, e.g. /search?title=brick will return "Brickster" and "BrickBreaker")

More than one query parameter can be specified. They will be concatenated in "AND" statements, i.e. /search?type=homebrew&platform=GBC will return every Homebrew developed with GBC features.

Every matching is case-insensitive.


# Get every RPG released as Open Source with Game Boy Color features:
curl Source,RPG&platform=GBC


Every result is paginated. These additional query params can be used in any of the previous routes:

  • page - Selects the current page
  • page_elements - Selects how many elements per-page

The following values are always present in responses, related to the given query:

  • results - Total number of results
  • page_total - Total pages
  • page_current - Current page. This can be different from the requested page (using the page query param) when the number is invalid or out of the range
  • page_elements - Elements per page. This can be customised (in the allowed range 1..10) by passing the page_elements query param.

Sort and order by

This API supports sort and order operations, you just need to specify these query params while doing requests (respectively sort and order_by).

order_by could assume these values:

  • slug
  • title

sort is intended to be used with order_by and could assume the following values:

  • asc: enabled by default, ascending order
  • desc: descending order


# Get every game in the homebrewhub ordered by title in a descending order:



You need Python 3 and a couple of packages to build psycopg2:

apt install python3 libpq-dev python3-dev python3-venv

Run server

Here's how to quickly get started:

# Set up a virtual env
python3 -m venv env
# Activate it
source env/bin/activate
# Install Python dependencies
pip install -r requirements.txt

# Prepare migrations for our Entry model
python3 makemigrations hhub
# Sync the database for the first time
python3 migrate

# Clone the database repositories
git clone
git clone database-gba

# Populate with the entries from the database repository

# Start the Django app
python3 runserver

# Query the /all route to see if everything's there
curl https://localhost:8000/all

Synchronising the database

The Homebrew Hub "source" database is simply a collection of folders, hosted as a git repository, each one containing an homebrew entry (ROM, screenshots, ..) and a "game.json" manifest file providing more details and metadata in a consisting way (see the game.json JSON schema).

For more information check the "database" repository documentation.

This enables the database to be "community-maintained", allowing everyone to add new entries (manually or by writing scrapers) or improve existing ones simply by opening Pull Requests.

The "real" database needs to be built (and updated when a commit gets pushed) from this collection of folders. This job is done by the script.

Keep in mind that the two are not equivalent, as the Django database will keep additional values about each entry (e.g. simple analytics).

python runscript sync-db


If you were looking for old version written in Node/Express, check homebrewhub-legacy.


A showcase/archive of homebrews, patches, hackroms for old consoles. Provides community submission, tagging and rating features.







Sponsor this project