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.

RomM’s backend is a FastAPI application that exposes a full REST API for programmatic access to your game library. Every operation available in the web UI — scanning platforms, managing ROMs, uploading saves, running background tasks — is accessible through these endpoints, making RomM scriptable and integrable with external tools.

​
Base URL

The default base URL depends on how you mapped ports in your docker-compose.yml: 
http://<your-romm-host>:8080
If you mapped port 80 in your Compose file the base URL becomes http://<your-romm-host>. All API endpoints are prefixed with /api. For example, the platforms list endpoint is /api/platforms.

​
Interactive API Docs

FastAPI auto-generates two documentation UIs from the OpenAPI schema:
UIURLDescription
Swagger UI/docsTry endpoints directly from the browser
ReDoc/redocClean, read-only reference layout
Both are always enabled and require no additional configuration.

​
Authentication

The RomM API supports four authentication methods. OAuth2 bearer tokens are recommended for programmatic access and integrations, while session cookies power the web UI. See the Authentication guide for full details including token scopes, client token creation, and the OAuth2 password flow.

​
Pagination

Most list endpoints (GET /api/roms, GET /api/platforms, etc.) use limit/offset pagination with the following query parameters:
​
limit
integer
default:"50"
Maximum number of items to return per page. Maximum is 10 000 for ROMs.
​
offset
integer
default:"0"
Zero-based offset into the result set.
Paginated responses return an envelope with the following shape: 
{
  "items": [...],
  "total": 1024,
  "limit": 50,
  "offset": 0
}
The ROMs endpoint extends this envelope with char_index, rom_id_index, and filter_values fields used by the web UI’s virtual scroll and filter sidebar.

​
Error Format

FastAPI returns errors as JSON objects with a detail key: 
{ "detail": "ROM with ID 99 not found" }
Validation errors from Pydantic return HTTP 422 Unprocessable Entity with an array of error objects: 
{
  "detail": [
    {
      "loc": ["body", "fs_slug"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​
Rate Limiting

RomM has no built-in rate limiting. If you need rate limiting, configure it at the reverse proxy level (nginx, Traefik, Caddy, etc.).

​
Content Types

Use caseContent-Type
Most requests and responsesapplication/json
File uploads (saves, states, artwork, ROMs)multipart/form-data
Feed endpoints (PKGi, PKGj, Kekatsu)text/plain

​
WebSocket Endpoints

Two WebSocket endpoints are available for real-time communication:
EndpointPurpose
/wsScan progress updates and server log streaming
/netplayNetplay room coordination between browser clients

​
Endpoint Reference

Authentication

OAuth2 password flow, token refresh, client tokens, and HTTP Basic auth

Platforms

List, create, update, and delete gaming platforms

ROMs

Browse, search, update metadata, upload, and download ROMs

Collections

Create and manage curated and smart ROM collections

Users

Manage user accounts, roles, and invite links

Saves & States

Upload, download, and manage save files and save states

Tasks

Trigger library scans, metadata updates, and cleanup jobs

Feeds

Tinfoil, WebRcade, PKGi, and other frontend client feeds

Build docs developers (and LLMs) love

Get started for freeTalk to us