ROMs API: Browse, Search, and Manage Games

The ROMs API is the core of RomM’s programmatic interface, providing full CRUD access to your game library. Endpoints cover everything from browsing and filtering to metadata editing, file downloads, patch application, and bulk deletion.

GET /api/roms

Retrieve a paginated, filtered, and sorted list of ROMs. This is the primary browse endpoint and powers the web UI’s game library view. Required scope: roms.read

Pagination

limit

integer

default:"50"

Number of ROMs per page (1–10 000).

offset

integer

default:"0"

Zero-based page offset.

Filters

platform_ids

integer[]

Filter by one or more platform IDs. Repeat the parameter for multiple values.

search_term

string

Full-text search across ROM names.

collection_id

integer

Filter to ROMs in a specific collection.

virtual_collection_id

string

Filter to ROMs in a virtual collection.

smart_collection_id

integer

Filter to ROMs in a smart collection.

matched

boolean

true returns only ROMs matched to at least one metadata source; false returns unmatched ROMs only.

favorite

boolean

Filter by the current user’s favourite flag.

duplicate

boolean

Filter ROMs flagged as duplicates.

last_played

boolean

true returns ROMs the current user has played before.

playable

boolean

Filter to ROMs that can be launched in the browser emulator.

missing

boolean

Filter ROMs that are absent from the filesystem.

has_ra

boolean

Filter ROMs with RetroAchievements data.

has_saves

boolean

Filter ROMs the current user has saves for.

has_states

boolean

Filter ROMs the current user has save states for.

verified

boolean

Filter ROMs verified by Hasheous.

genres

string[]

Filter by genre tags (repeat for multiple). Logic controlled by genres_logic.

franchises

string[]

Filter by franchise. Logic controlled by franchises_logic.

collections

string[]

Filter by collection name. Logic controlled by collections_logic.

companies

string[]

Filter by associated company. Logic controlled by companies_logic.

age_ratings

string[]

Filter by age rating. Logic controlled by age_ratings_logic.

regions

string[]

Filter by region tag (e.g. USA, EUR). Logic controlled by regions_logic.

languages

string[]

Filter by language tag. Logic controlled by languages_logic.

Logic Operators

Each multi-value filter has a corresponding _logic parameter that accepts any (OR), all (AND), or none (NOT). For example: genres_logic=all returns only ROMs that match every listed genre.

Sorting

order_by

string

default:""

Field to sort by (e.g. name, updated_at). Leave empty to sort by search relevance when a search_term is given (MySQL/MariaDB only; other databases fall back to name).

order_dir

string

default:"asc"

Sort direction: asc or desc.

Incremental Sync

updated_after

string

ISO 8601 datetime. Returns only ROMs updated after this timestamp.

Other Options

group_by_meta_id

boolean

default:"false"

Group sibling ROMs (same game, multiple files) by their shared metadata ID.

with_files

boolean

default:"false"

Include each ROM’s file entries in the response.

with_char_index

boolean

default:"true"

Include a character index mapping for the AlphaStrip UI component.

with_filter_values

boolean

default:"true"

Include the set of available filter values (genres, regions, etc.) for the filter sidebar.

curl "http://localhost:8080/api/roms?platform_ids=3&limit=25&order_by=name" \
  -H "Authorization: Bearer <token>"

Response envelope:

{
  "items": [...],
  "total": 512,
  "limit": 25,
  "offset": 0,
  "char_index": {"A": 0, "B": 14, ...},
  "rom_id_index": [101, 102, ...],
  "filter_values": {
    "genres": ["Action", "RPG"],
    "regions": ["USA", "EUR"],
    ...
  }
}

GET /api/roms/identifiers

Retrieve only the IDs of all ROMs visible to the current user. Lightweight alternative to the full list. Required scope: roms.read

curl http://localhost:8080/api/roms/identifiers \
  -H "Authorization: Bearer <token>"

Response: [101, 102, 103, ...]

GET /api/roms/download

Download multiple ROMs as a single zip file. Required scope: roms.read

rom_ids

string

required

Comma-separated list of ROM IDs (e.g. 1,2,3).

filename

string

Custom name for the output zip file (optional).

curl "http://localhost:8080/api/roms/download?rom_ids=1,2,3" \
  -H "Authorization: Bearer <token>" \
  -o roms.zip

GET /api/roms/by-metadata-provider

Look up a single ROM by its external metadata ID. At least one ID parameter must be provided. Required scope: roms.read (unless DISABLE_DOWNLOAD_ENDPOINT_AUTH=true)

igdb_id

integer

IGDB game ID.

moby_id

integer

MobyGames game ID.

ss_id

integer

ScreenScraper game ID.

ra_id

integer

RetroAchievements game ID.

launchbox_id

integer

LaunchBox game ID.

hasheous_id

integer

Hasheous game ID.

tgdb_id

integer

TheGamesDB game ID.

flashpoint_id

string

Flashpoint game ID.

hltb_id

integer

HowLongToBeat game ID.

curl "http://localhost:8080/api/roms/by-metadata-provider?igdb_id=2113" \
  -H "Authorization: Bearer <token>"

GET /api/roms/by-hash

Look up a single ROM by its file hash. At least one hash parameter must be provided. Required scope: roms.read (unless DISABLE_DOWNLOAD_ENDPOINT_AUTH=true)

crc_hash

string

CRC32 hash value.

md5_hash

string

MD5 hash value.

sha1_hash

string

SHA1 hash value.

ra_hash

string

RetroAchievements hash value.

curl "http://localhost:8080/api/roms/by-hash?crc_hash=a1b2c3d4" \
  -H "Authorization: Bearer <token>"

GET /api/roms/

Retrieve full details for a single ROM, including metadata, file list, platform info, and user-specific data. Required scope: roms.read (unless DISABLE_DOWNLOAD_ENDPOINT_AUTH=true)

integer

required

ROM internal ID.

curl http://localhost:8080/api/roms/42 \
  -H "Authorization: Bearer <token>"

GET /api/roms//content/

Download a ROM file. For single-file ROMs the file is served directly; for multi-file ROMs a zip archive is returned. Required scope: roms.read (unless DISABLE_DOWNLOAD_ENDPOINT_AUTH=true)

integer

required

ROM internal ID.

file_name

string

required

Used as the output filename (or zip filename). The actual file(s) served are determined by the database record.

file_ids

string

Comma-separated list of file IDs to include for multi-part ROMs. If omitted, all files are included.

curl "http://localhost:8080/api/roms/15/content/SuperMario64.z64" \
  -H "Authorization: Bearer <token>" \
  -o SuperMario64.z64

PUT /api/roms/

Update a ROM’s metadata. Accepts multipart/form-data so that cover artwork can be uploaded in the same request. Required scope: roms.write

integer

required

ROM internal ID.

Show Form fields

name

string

Display name override.

summary

string

Game summary / description.

fs_name

string

Filesystem filename. Changing this renames the file on disk.

igdb_id

string

IGDB game ID. Providing a new ID fetches fresh IGDB metadata.

sgdb_id

string

SteamGridDB game ID.

moby_id

string

MobyGames game ID.

ss_id

string

ScreenScraper game ID.

ra_id

string

RetroAchievements game ID.

launchbox_id

string

LaunchBox game ID.

hasheous_id

string

Hasheous game ID.

tgdb_id

string

TheGamesDB game ID.

flashpoint_id

string

Flashpoint game ID.

hltb_id

string

HowLongToBeat game ID.

libretro_id

string

Libretro thumbnail ID.

url_cover

string

Remote URL to fetch and store as cover art.

artwork

file

Cover image file to upload directly (JPEG/PNG/WebP).

remove_cover

boolean

Set to true to remove the existing cover image.

unmatch_metadata

boolean

Set to true to clear all metadata matches for this ROM.

curl -X PUT http://localhost:8080/api/roms/42 \
  -H "Authorization: Bearer <token>" \
  -F "name=Super Mario 64 (USA)" \
  -F "igdb_id=2113"

Response: Full DetailedRomSchema with updated fields.

POST /api/roms//patch

Apply a ROM patch file server-side and download the patched output. Both the base ROM file and the patch file must already exist in your library. Required scope: roms.read

integer

required

ROM file ID of the base game file to patch.

patch_file_id

integer

required

ROM file ID of the patch file (.ips, .bps, .xdelta, etc.).

output_file_name

string

Custom name for the patched output file. If omitted, RomM derives one from the ROM and patch filenames.

curl -X POST http://localhost:8080/api/roms/15/patch \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"patch_file_id": 28}' \
  -o patched_rom.sfc

The response is the patched binary file (application/octet-stream). The X-Patch-Validated response header is true when the patch’s source checksum matched the base ROM, or false when it did not (the output may still be usable).

There is a maximum file size for patching controlled by ROM_PATCHER_MAX_FILE_SIZE_BYTES. Oversized files return 400 Bad Request.

PUT /api/roms//props

Update ROM properties specific to the current user — play status, ratings, backlog flag, hidden flag, etc. Required scope: roms.user.write

integer

required

ROM internal ID.

update_last_played

boolean

default:"false"

Set the last-played timestamp to now.

remove_last_played

boolean

default:"false"

Clear the last-played timestamp.

Show Request body fields

is_main_sibling

boolean

Mark as the primary file in a sibling group.

backlogged

boolean

Add/remove from the backlog.

now_playing

boolean

Mark as currently being played.

hidden

boolean

Hide/show this ROM for the current user.

rating

integer

User rating 0–10.

difficulty

integer

User difficulty rating 0–10.

completion

integer

User completion percentage 0–100.

status

string

User play status value (e.g. playing, completed, abandoned).

curl -X PUT http://localhost:8080/api/roms/42/props \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"rating": 9, "status": "completed"}'

POST /api/roms/delete

Delete one or more ROMs. Optionally also remove the files from disk. Required scope: roms.write

roms

integer[]

required

List of ROM IDs to delete from the database.

delete_from_fs

integer[]

Subset of roms IDs to also delete from the filesystem. Defaults to an empty list (database-only deletion).

curl -X POST http://localhost:8080/api/roms/delete \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"roms": [42, 43], "delete_from_fs": [42]}'

Response:

{
  "successful_items": 2,
  "failed_items": 0,
  "errors": []
}

Overview

Endpoints

ROMs API: Browse, Search, and Manage Games

GET /api/roms

Filters

Logic Operators

Sorting

Incremental Sync

Other Options

GET /api/roms/identifiers

GET /api/roms/download

GET /api/roms/by-metadata-provider

GET /api/roms/by-hash

GET /api/roms/

GET /api/roms//content/

PUT /api/roms/

POST /api/roms//patch

PUT /api/roms//props

POST /api/roms/delete

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/roms

​Pagination

​Filters

​Logic Operators

​Sorting

​Incremental Sync

​Other Options

​GET /api/roms/identifiers

​GET /api/roms/download

​GET /api/roms/by-metadata-provider

​GET /api/roms/by-hash

​GET /api/roms/

​GET /api/roms//content/

​PUT /api/roms/

​POST /api/roms//patch

​PUT /api/roms//props

​POST /api/roms/delete

Build docs developers (and LLMs) love

GET /api/roms

Pagination

Filters

Logic Operators

Sorting

Incremental Sync

Other Options

GET /api/roms/identifiers

GET /api/roms/download

GET /api/roms/by-metadata-provider

GET /api/roms/by-hash

GET /api/roms/

GET /api/roms//content/

PUT /api/roms/

POST /api/roms//patch

PUT /api/roms//props

POST /api/roms/delete