RomM System API
The system API from RomM — 4 operation(s) for system.
The system API from RomM — 4 operation(s) for system.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/romm:romm-system-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: RomM System API
version: 5.4.0
tags:
- name: System
paths:
/api/heartbeat:
get:
tags:
- System
summary: Heartbeat
description: 'Endpoint to set the CSRF token in cache and return all the basic RomM config
Returns:
HeartbeatReturn: TypedDict structure with all the defined values in the HeartbeatReturn class.'
operationId: heartbeat_api_heartbeat_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/HeartbeatResponse'
/api/heartbeat/metadata/{source}:
get:
tags:
- System
summary: Metadata Heartbeat
description: Endpoint to return the heartbeat of the metadata sources
operationId: metadata_heartbeat_api_heartbeat_metadata__source__get
parameters:
- name: source
in: path
required: true
schema:
type: string
title: Source
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: boolean
title: Response Metadata Heartbeat Api Heartbeat Metadata Source Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/setup/library:
get:
tags:
- System
summary: Get Setup Library Info
description: 'Get library structure information for setup wizard.
Only accessible during initial setup (no admin users) or with authentication.
Returns:
SetupLibraryResponse: The library folder state and the platforms to offer.'
operationId: get_setup_library_info_api_setup_library_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SetupLibraryResponse'
security:
- OAuth2PasswordBearer: []
- HTTPBasic: []
/api/setup/platforms:
post:
tags:
- System
summary: Create Setup Platforms
description: 'Create platform folders during setup wizard.
Only accessible during initial setup (no admin users) or with authentication.
Args:
platform_slugs: List of platform fs_slugs to create
Returns:
SetupPlatformsResponse: How many platform folders were created.'
operationId: create_setup_platforms_api_setup_platforms_post
requestBody:
content:
application/json:
schema:
items:
type: string
type: array
title: Platform Slugs
required: true
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SetupPlatformsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- OAuth2PasswordBearer: []
- HTTPBasic: []
components:
schemas:
EmulationDict:
properties:
DISABLE_EMULATOR_JS:
type: boolean
title: Disable Emulator Js
DISABLE_RUFFLE_RS:
type: boolean
title: Disable Ruffle Rs
DISABLE_JSDOS:
type: boolean
title: Disable Jsdos
DISABLE_PICO8:
type: boolean
title: Disable Pico8
DISABLE_EASYRPG:
type: boolean
title: Disable Easyrpg
type: object
required:
- DISABLE_EMULATOR_JS
- DISABLE_RUFFLE_RS
- DISABLE_JSDOS
- DISABLE_PICO8
- DISABLE_EASYRPG
title: EmulationDict
SetupLibraryResponse:
properties:
library_ready:
type: boolean
title: Library Ready
library_structure:
type: string
title: Library Structure
existing_platforms:
items:
$ref: '#/components/schemas/SetupExistingPlatform'
type: array
title: Existing Platforms
supported_platforms:
items:
$ref: '#/components/schemas/PlatformSchema'
type: array
title: Supported Platforms
type: object
required:
- library_ready
- library_structure
- existing_platforms
- supported_platforms
title: SetupLibraryResponse
PlatformSchema:
properties:
id:
type: integer
title: Id
slug:
type: string
title: Slug
fs_slug:
type: string
title: Fs Slug
rom_count:
type: integer
title: Rom Count
name:
type: string
title: Name
igdb_slug:
anyOf:
- type: string
- type: 'null'
title: Igdb Slug
moby_slug:
anyOf:
- type: string
- type: 'null'
title: Moby Slug
hltb_slug:
anyOf:
- type: string
- type: 'null'
title: Hltb Slug
libretro_slug:
anyOf:
- type: string
- type: 'null'
title: Libretro Slug
custom_name:
anyOf:
- type: string
- type: 'null'
title: Custom Name
description:
anyOf:
- type: string
- type: 'null'
title: Description
igdb_id:
anyOf:
- type: integer
- type: 'null'
title: Igdb Id
sgdb_id:
anyOf:
- type: integer
- type: 'null'
title: Sgdb Id
moby_id:
anyOf:
- type: integer
- type: 'null'
title: Moby Id
launchbox_id:
anyOf:
- type: integer
- type: 'null'
title: Launchbox Id
ss_id:
anyOf:
- type: integer
- type: 'null'
title: Ss Id
ra_id:
anyOf:
- type: integer
- type: 'null'
title: Ra Id
hasheous_id:
anyOf:
- type: integer
- type: 'null'
title: Hasheous Id
tgdb_id:
anyOf:
- type: integer
- type: 'null'
title: Tgdb Id
flashpoint_id:
anyOf:
- type: integer
- type: 'null'
title: Flashpoint Id
category:
anyOf:
- type: string
- type: 'null'
title: Category
generation:
anyOf:
- type: integer
- type: 'null'
title: Generation
family_name:
anyOf:
- type: string
- type: 'null'
title: Family Name
family_slug:
anyOf:
- type: string
- type: 'null'
title: Family Slug
url:
anyOf:
- type: string
- type: 'null'
title: Url
url_logo:
anyOf:
- type: string
- type: 'null'
title: Url Logo
firmware:
items:
$ref: '#/components/schemas/FirmwareSchema'
type: array
title: Firmware
created_at:
type: string
title: Created At
updated_at:
type: string
title: Updated At
fs_size_bytes:
type: integer
title: Fs Size Bytes
is_unidentified:
type: boolean
title: Is Unidentified
is_identified:
type: boolean
title: Is Identified
missing_from_fs:
type: boolean
title: Missing From Fs
display_name:
type: string
title: Display Name
readOnly: true
abbreviation:
type: string
title: Abbreviation
readOnly: true
alternative_names:
items:
type: string
type: array
title: Alternative Names
readOnly: true
firmware_count:
type: integer
title: Firmware Count
readOnly: true
type: object
required:
- id
- slug
- fs_slug
- rom_count
- name
- igdb_slug
- moby_slug
- hltb_slug
- libretro_slug
- created_at
- updated_at
- fs_size_bytes
- is_unidentified
- is_identified
- missing_from_fs
- display_name
- abbreviation
- alternative_names
- firmware_count
title: PlatformSchema
MetadataSourcesDict:
properties:
ANY_SOURCE_ENABLED:
type: boolean
title: Any Source Enabled
IGDB_API_ENABLED:
type: boolean
title: Igdb Api Enabled
SS_API_ENABLED:
type: boolean
title: Ss Api Enabled
SS_DEV_CREDENTIALS_SET:
type: boolean
title: Ss Dev Credentials Set
MOBY_API_ENABLED:
type: boolean
title: Moby Api Enabled
STEAMGRIDDB_API_ENABLED:
type: boolean
title: Steamgriddb Api Enabled
RA_API_ENABLED:
type: boolean
title: Ra Api Enabled
LAUNCHBOX_API_ENABLED:
type: boolean
title: Launchbox Api Enabled
HASHEOUS_API_ENABLED:
type: boolean
title: Hasheous Api Enabled
PLAYMATCH_API_ENABLED:
type: boolean
title: Playmatch Api Enabled
TGDB_API_ENABLED:
type: boolean
title: Tgdb Api Enabled
FLASHPOINT_API_ENABLED:
type: boolean
title: Flashpoint Api Enabled
HLTB_API_ENABLED:
type: boolean
title: Hltb Api Enabled
DEMOZOO_API_ENABLED:
type: boolean
title: Demozoo Api Enabled
POUET_API_ENABLED:
type: boolean
title: Pouet Api Enabled
CSDB_API_ENABLED:
type: boolean
title: Csdb Api Enabled
STEAM_API_ENABLED:
type: boolean
title: Steam Api Enabled
LIBRETRO_API_ENABLED:
type: boolean
title: Libretro Api Enabled
type: object
required:
- ANY_SOURCE_ENABLED
- IGDB_API_ENABLED
- SS_API_ENABLED
- SS_DEV_CREDENTIALS_SET
- MOBY_API_ENABLED
- STEAMGRIDDB_API_ENABLED
- RA_API_ENABLED
- LAUNCHBOX_API_ENABLED
- HASHEOUS_API_ENABLED
- PLAYMATCH_API_ENABLED
- TGDB_API_ENABLED
- FLASHPOINT_API_ENABLED
- HLTB_API_ENABLED
- DEMOZOO_API_ENABLED
- POUET_API_ENABLED
- CSDB_API_ENABLED
- STEAM_API_ENABLED
- LIBRETRO_API_ENABLED
title: MetadataSourcesDict
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ConvertoDict:
properties:
ENABLED:
type: boolean
title: Enabled
type: object
required:
- ENABLED
title: ConvertoDict
SetupPlatformsResponse:
properties:
success:
type: boolean
title: Success
created_count:
type: integer
title: Created Count
message:
type: string
title: Message
type: object
required:
- success
- created_count
- message
title: SetupPlatformsResponse
FrontendDict:
properties:
DISABLE_USERPASS_LOGIN:
type: boolean
title: Disable Userpass Login
DISABLE_LOGS_VIEWER:
type: boolean
title: Disable Logs Viewer
YOUTUBE_BASE_URL:
type: string
title: Youtube Base Url
type: object
required:
- DISABLE_USERPASS_LOGIN
- DISABLE_LOGS_VIEWER
- YOUTUBE_BASE_URL
title: FrontendDict
FirmwareSchema:
properties:
id:
type: integer
title: Id
platform_id:
type: integer
title: Platform Id
file_name:
type: string
title: File Name
file_name_no_tags:
type: string
title: File Name No Tags
file_name_no_ext:
type: string
title: File Name No Ext
file_extension:
type: string
title: File Extension
file_path:
type: string
title: File Path
file_size_bytes:
type: integer
title: File Size Bytes
full_path:
type: string
title: Full Path
is_verified:
type: boolean
title: Is Verified
crc_hash:
type: string
title: Crc Hash
md5_hash:
type: string
title: Md5 Hash
sha1_hash:
type: string
title: Sha1 Hash
missing_from_fs:
type: boolean
title: Missing From Fs
created_at:
type: string
title: Created At
updated_at:
type: string
title: Updated At
type: object
required:
- id
- platform_id
- file_name
- file_name_no_tags
- file_name_no_ext
- file_extension
- file_path
- file_size_bytes
- full_path
- is_verified
- crc_hash
- md5_hash
- sha1_hash
- missing_from_fs
- created_at
- updated_at
title: FirmwareSchema
HeartbeatResponse:
properties:
SYSTEM:
$ref: '#/components/schemas/SystemDict'
METADATA_SOURCES:
$ref: '#/components/schemas/MetadataSourcesDict'
FILESYSTEM:
$ref: '#/components/schemas/FilesystemDict'
EMULATION:
$ref: '#/components/schemas/EmulationDict'
FRONTEND:
$ref: '#/components/schemas/FrontendDict'
OIDC:
$ref: '#/components/schemas/OIDCDict'
NOTIFICATIONS:
$ref: '#/components/schemas/NotificationsDict'
DEVICE_INSTALL:
$ref: '#/components/schemas/DeviceInstallDict'
CONVERTO:
$ref: '#/components/schemas/ConvertoDict'
TASKS:
$ref: '#/components/schemas/TasksDict'
type: object
required:
- SYSTEM
- METADATA_SOURCES
- FILESYSTEM
- EMULATION
- FRONTEND
- OIDC
- NOTIFICATIONS
- DEVICE_INSTALL
- CONVERTO
- TASKS
title: HeartbeatResponse
TasksDict:
properties:
ENABLE_SCHEDULED_RESCAN:
type: boolean
title: Enable Scheduled Rescan
SCHEDULED_RESCAN_CRON:
type: string
title: Scheduled Rescan Cron
ENABLE_SCHEDULED_UPDATE_SWITCH_TITLEDB:
type: boolean
title: Enable Scheduled Update Switch Titledb
SCHEDULED_UPDATE_SWITCH_TITLEDB_CRON:
type: string
title: Scheduled Update Switch Titledb Cron
ENABLE_SCHEDULED_UPDATE_LAUNCHBOX_METADATA:
type: boolean
title: Enable Scheduled Update Launchbox Metadata
SCHEDULED_UPDATE_LAUNCHBOX_METADATA_CRON:
type: string
title: Scheduled Update Launchbox Metadata Cron
ENABLE_SCHEDULED_CONVERT_IMAGES_TO_WEBP:
type: boolean
title: Enable Scheduled Convert Images To Webp
SCHEDULED_CONVERT_IMAGES_TO_WEBP_CRON:
type: string
title: Scheduled Convert Images To Webp Cron
type: object
required:
- ENABLE_SCHEDULED_RESCAN
- SCHEDULED_RESCAN_CRON
- ENABLE_SCHEDULED_UPDATE_SWITCH_TITLEDB
- SCHEDULED_UPDATE_SWITCH_TITLEDB_CRON
- ENABLE_SCHEDULED_UPDATE_LAUNCHBOX_METADATA
- SCHEDULED_UPDATE_LAUNCHBOX_METADATA_CRON
- ENABLE_SCHEDULED_CONVERT_IMAGES_TO_WEBP
- SCHEDULED_CONVERT_IMAGES_TO_WEBP_CRON
title: TasksDict
FilesystemDict:
properties:
FS_PLATFORMS:
items:
type: string
type: array
title: Fs Platforms
TITLE_ID_EXTRACTION_ENABLED:
type: boolean
title: Title Id Extraction Enabled
type: object
required:
- FS_PLATFORMS
- TITLE_ID_EXTRACTION_ENABLED
title: FilesystemDict
DeviceInstallDict:
properties:
ENABLED:
type: boolean
title: Enabled
EXCLUDED_PLATFORM_SLUGS:
items:
type: string
type: array
title: Excluded Platform Slugs
type: object
required:
- ENABLED
- EXCLUDED_PLATFORM_SLUGS
title: DeviceInstallDict
OIDCDict:
properties:
ENABLED:
type: boolean
title: Enabled
AUTOLOGIN:
type: boolean
title: Autologin
PROVIDER:
type: string
title: Provider
RP_INITIATED_LOGOUT:
type: boolean
title: Rp Initiated Logout
type: object
required:
- ENABLED
- AUTOLOGIN
- PROVIDER
- RP_INITIATED_LOGOUT
title: OIDCDict
SystemDict:
properties:
VERSION:
type: string
title: Version
GIT_BRANCH:
anyOf:
- type: string
- type: 'null'
title: Git Branch
SHOW_SETUP_WIZARD:
type: boolean
title: Show Setup Wizard
type: object
required:
- VERSION
- GIT_BRANCH
- SHOW_SETUP_WIZARD
title: SystemDict
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
NotificationsDict:
properties:
EMAIL_ENABLED:
type: boolean
title: Email Enabled
EMAILS_RESET_LINKS:
type: boolean
title: Emails Reset Links
type: object
required:
- EMAIL_ENABLED
- EMAILS_RESET_LINKS
title: NotificationsDict
SetupExistingPlatform:
properties:
fs_slug:
type: string
title: Fs Slug
rom_count:
type: integer
title: Rom Count
type: object
required:
- fs_slug
- rom_count
title: SetupExistingPlatform
securitySchemes:
OAuth2PasswordBearer:
type: oauth2
flows:
password:
scopes:
me.read: View your profile
roms.read: View ROMs
platforms.read: View platforms
assets.read: View assets
devices.read: View devices
firmware.read: View firmware
roms.user.read: View user-rom properties
collections.read: View collections
playlists.read: View music playlists
me.write: Modify your profile
assets.write: Modify assets
devices.write: Modify devices
roms.user.write: Modify user-rom properties
collections.write: Modify collections
playlists.write: Modify music playlists
roms.write: Modify ROMs
platforms.write: Modify platforms
firmware.write: Modify firmware
users.read: View users
users.write: Modify users
tasks.run: Run tasks
logs.read: View backend logs
tokenUrl: /token
HTTPBasic:
type: http
scheme: basic