Organizing Your ROM Library with Collections in RomM

Collections let you group ROMs from any platform into curated lists, making it easy to build cross-platform compilations like “Saturday morning classics”, “games to finish this weekend”, or “favourites from childhood”. RomM supports three distinct collection types — regular user-curated collections, smart collections that are automatically filtered, and virtual collections that are auto-generated by the system — each with different management flows and visibility rules.

All collection types are per-user: each user sees and manages their own collections independently. Administrators can view and modify every collection in the system regardless of who created it.

Types of Collections

Regular Collections

Manually curated lists where you choose exactly which ROMs to include. You have full control over the name, description, cover art, and membership.

Smart Collections

Rule-based collections defined by a JSON filter criteria object. RomM re-evaluates the filter whenever the underlying ROM data changes and updates membership automatically.

Virtual Collections

Read-only, system-generated collections derived from metadata attributes such as genre, franchise, or company. They are rebuilt automatically during and after scans.

Regular Collections

Creating a collection

From the UI: Click the Collections section in the sidebar, then New Collection. Give it a name, an optional description, and optional cover art. Toggle Public to make it visible to all other users. Via the API:

POST /api/collections
Content-Type: multipart/form-data

name=My Collection
description=A handpicked list of platformers
is_public=false

A successful response returns a CollectionSchema object containing the new collection’s id, name, description, is_public, rom_ids, and cover art paths.

Retrieving collections

GET /api/collections

Returns all collections that belong to the authenticated user, plus any collections marked as is_public=true that belong to other users. Use the updated_after query parameter to fetch only collections modified since a given ISO 8601 timestamp.

GET /api/collections?updated_after=2024-01-01T00%3A00%3A00Z

Updating a collection

PUT /api/collections/{id}
Content-Type: multipart/form-data

name=Updated Name
rom_ids=[1, 2, 3, 42]
is_public=true

The rom_ids field must be a JSON-encoded array of ROM IDs. The full list of IDs you supply replaces the current membership — it is not an additive operation.

Adding or removing individual ROMs

To atomically add ROMs without replacing the entire membership list:

POST /api/collections/{id}/roms
Content-Type: application/json

{
  "rom_ids": [101, 202]
}

To atomically remove specific ROMs:

DELETE /api/collections/{id}/roms
Content-Type: application/json

{
  "rom_ids": [101]
}

Both endpoints return the updated CollectionSchema.

Deleting a collection

DELETE /api/collections/{id}

This removes the collection record and its associated cover art resources from disk. Only the collection owner can delete it.

Cover art

You can supply cover art in three ways:

Upload a file — include an artwork multipart file field in the create or update request.
Remote URL — pass a url_cover string; RomM fetches and caches the image locally.
No cover — RomM composites a mosaic from the covers of the first few member ROMs.

To remove a manually uploaded cover, pass remove_cover=true in the update request.

Smart Collections

Smart collections use a filter_criteria JSON object to define membership rules. RomM evaluates the criteria against all ROMs the current user can see and populates rom_ids automatically.

Creating a smart collection

POST /api/collections/smart
Content-Type: multipart/form-data

name=Top Rated RPGs
description=All RPGs matched against a metadata provider
is_public=false
filter_criteria={"genres": ["Role-playing (RPG)"], "matched": true}

The filter_criteria field is a JSON object. Supported keys include:

Key	Type	Description
`genres`	`string[]`	Match ROMs whose metadata includes any of these genres
`franchises`	`string[]`	Match ROMs belonging to any of these franchises
`companies`	`string[]`	Match ROMs published or developed by these companies
`regions`	`string[]`	Match ROMs with any of these region tags
`languages`	`string[]`	Match ROMs supporting any of these languages
`tags`	`string[]`	Match ROMs carrying any of these extra tags
`platform_ids`	`int[]`	Restrict matches to specific platform IDs
`search_term`	`string`	Filter by ROM name substring
`matched`	`bool`	`true` = identified by a metadata provider; `false` = unidentified
`favorite`	`bool`	Filter by user favourite status
`playable`	`bool`	Filter to ROMs with a playable emulator core
`has_ra`	`bool`	Filter to ROMs with RetroAchievements support
`missing`	`bool`	Filter to ROMs flagged as missing from the filesystem
`order_by`	`string`	Sort field (default `"name"`)
`order_dir`	`string`	Sort direction: `"asc"` or `"desc"`

For multi-value filters (genres, franchises, etc.) you can control match logic with a companion _logic key, e.g. "genres_logic": "all" (default "any").

Updating a smart collection

PUT /api/collections/smart/{id}
Content-Type: multipart/form-data

name=Top Rated RPGs (updated)
filter_criteria={"genres": ["Role-playing (RPG)"], "matched": true, "regions": ["USA"]}

Retrieving smart collections

GET /api/collections/smart

As with regular collections, pass updated_after to limit results to recently changed entries.

Virtual Collections

Virtual collections are generated automatically from ROM metadata (for example, one collection per genre or franchise discovered during scanning). They are read-only: you cannot add or remove ROMs manually.

Retrieving virtual collections

GET /api/collections/virtual?type=genre

The type parameter filters by the virtual collection category. Pass type=all to retrieve every virtual collection regardless of type.

GET /api/collections/virtual/{id}

A virtual collection’s id is a URL-safe Base64 encoding of its name and type, making it stable and reversible.

Setting	Behaviour
`is_public=false` (default)	Only the owner and admins can view the collection
`is_public=true`	Any authenticated user can view the collection and its ROM list

Even when a collection is public, ROMs that are hidden from a given user (via platform or ROM-level visibility settings) are filtered out of the rom_ids list and the rom_count before the collection is returned to that user. A public collection never leaks the existence of hidden content.

Ownership cannot be transferred — collections are permanently associated with the user who created them. Admins can manage all collections through the same API endpoints without any additional permission flags.

Library Management

Playing Games

Integrations

Operations

Organizing Your ROM Library with Collections in RomM

Types of Collections

Regular Collections

Smart Collections

Virtual Collections

Regular Collections

Creating a collection

Retrieving collections

Updating a collection

Adding or removing individual ROMs

Deleting a collection

Cover art

Smart Collections

Creating a smart collection

Updating a smart collection

Retrieving smart collections

Virtual Collections

Retrieving virtual collections

Build docs developers (and LLMs) love

Library Management

Playing Games

Integrations

Operations

Documentation Index

​Types of Collections

Regular Collections

Smart Collections

Virtual Collections

​Regular Collections

​Creating a collection

​Retrieving collections

​Updating a collection

​Adding or removing individual ROMs

​Deleting a collection

​Cover art

​Smart Collections

​Creating a smart collection

​Updating a smart collection

​Retrieving smart collections

​Virtual Collections

​Retrieving virtual collections

​Visibility and Sharing

Build docs developers (and LLMs) love

Types of Collections

Regular Collections

Creating a collection

Retrieving collections

Updating a collection

Adding or removing individual ROMs

Deleting a collection

Cover art

Smart Collections

Creating a smart collection

Updating a smart collection

Retrieving smart collections

Virtual Collections

Retrieving virtual collections

Visibility and Sharing