Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rommapp/romm/llms.txt

Use this file to discover all available pages before exploring further.

The Platforms API lets you query and manage the gaming platforms in your RomM library. Platforms map directly to filesystem slugs under your library base path — each platform folder you create becomes a platform record when scanned.

​
GET /api/platforms

Retrieve all platforms visible to the authenticated user. Required scope: platforms.read
​
updated_after
string
ISO 8601 datetime with timezone (e.g. 2024-01-01T00:00:00Z). Returns only platforms updated after this timestamp. Useful for incremental sync.
curl http://localhost:8080/api/platforms \
  -H "Authorization: Bearer <token>"
Response: Array of platform objects.
​
id
integer
Internal platform ID.
​
slug
string
Canonical slug used by metadata providers (e.g. nintendo-64).
​
fs_slug
string
Filesystem folder name under the library base path (e.g. n64).
​
name
string
Official platform name (e.g. Nintendo 64).
​
display_name
string
Computed field: returns custom_name if set, otherwise name.
​
custom_name
string | null
User-set override for the display name.
​
rom_count
integer
Number of ROMs associated with this platform.
​
fs_size_bytes
integer
Total size of all ROM files on disk for this platform.
​
igdb_id
integer | null
IGDB platform ID.
​
igdb_slug
string | null
IGDB platform slug.
​
sgdb_id
integer | null
SteamGridDB platform ID.
​
moby_id
integer | null
MobyGames platform ID.
​
moby_slug
string | null
MobyGames platform slug.
​
ss_id
integer | null
ScreenScraper platform ID.
​
ra_id
integer | null
RetroAchievements platform ID.
​
launchbox_id
integer | null
LaunchBox platform ID.
​
hasheous_id
integer | null
Hasheous platform ID.
​
tgdb_id
integer | null
TheGamesDB platform ID.
​
flashpoint_id
integer | null
Flashpoint platform ID.
​
hltb_slug
string | null
HowLongToBeat platform slug.
​
libretro_slug
string | null
Libretro platform slug.
​
category
string | null
Platform category (e.g. console, portable, computer).
​
generation
integer | null
Console generation number.
​
family_name
string | null
Platform family name (e.g. Nintendo).
​
family_slug
string | null
Platform family slug.
​
url
string | null
URL to the platform’s official page.
URL to the platform logo image.
​
firmware
array
List of firmware files associated with this platform.
​
firmware_count
integer
Number of firmware files associated with this platform.
​
is_unidentified
boolean
True if the platform could not be matched to any metadata source.
​
is_identified
boolean
True if the platform was matched to at least one metadata source.
​
missing_from_fs
boolean
True if the platform folder no longer exists on disk.
​
created_at
string
ISO 8601 creation timestamp (UTC).
​
updated_at
string
ISO 8601 last-updated timestamp (UTC).

​
GET /api/platforms/identifiers

Retrieve just the IDs of all visible platforms. Useful for sync clients that want a lightweight list to diff against. Required scope: platforms.read 
curl http://localhost:8080/api/platforms/identifiers \
  -H "Authorization: Bearer <token>"
Response: [1, 2, 3, ...]

​
GET /api/platforms/supported

Retrieve the full list of platforms that RomM supports (slug → name mapping). This list is static and does not reflect what is in your library. Required scope: platforms.read 
curl http://localhost:8080/api/platforms/supported \
  -H "Authorization: Bearer <token>"

​
POST /api/platforms

Add a new platform to the library. RomM creates the platform folder on disk (if it doesn’t already exist) and immediately scans it. Required scope: platforms.write
​
fs_slug
string
required
Filesystem slug for the new platform. Must match an entry in the supported platforms list (e.g. n64, gba, psx).
curl -X POST http://localhost:8080/api/platforms \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"fs_slug": "gba"}'
Response: 201 Created — the newly created PlatformSchema object.

​
GET /api/platforms/

Retrieve a single platform by its internal ID. Required scope: platforms.read
​
id
integer
required
Platform internal ID (must be ≥ 1).
curl http://localhost:8080/api/platforms/3 \
  -H "Authorization: Bearer <token>"
Response: A single PlatformSchema object, or 404 if not found.

​
PUT /api/platforms/

Update a platform’s custom display name. Required scope: platforms.write
​
id
integer
required
Platform internal ID.
​
custom_name
string | null
Custom display name to override the default platform name. Pass null to clear the override and revert to the canonical name.
curl -X PUT http://localhost:8080/api/platforms/3 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"custom_name": "Game Boy Advance (My Library)"}'
Response: Updated PlatformSchema object.

​
DELETE /api/platforms/

Delete a platform and all of its associated ROM records from the database. This does not delete files from disk. Required scope: platforms.write
​
id
integer
required
Platform internal ID.
curl -X DELETE http://localhost:8080/api/platforms/3 \
  -H "Authorization: Bearer <token>"
Response: 204 No Content on success, 404 if the platform was not found.
Deleting a platform removes all ROM metadata records associated with it from the database. The actual ROM files on disk are not affected. Re-scanning the library will re-import them.

Build docs developers (and LLMs) love

Get started for freeTalk to us