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.

Collections are user-curated groups of ROMs that span platform boundaries, letting you build playlists like “My Favorites”, “Holiday Games”, or “RPGs to Finish”. RomM also supports smart collections (filter-driven, auto-updating) and virtual collections (system-generated groupings like by genre or franchise).

​
Regular Collections

​
GET /api/collections

Retrieve all collections visible to the current user. Public collections from other users are included; private collections belonging to other users are excluded. Required scope: collections.read
​
updated_after
string
ISO 8601 datetime with timezone. Returns only collections updated after this timestamp.
curl http://localhost:8080/api/collections \
  -H "Authorization: Bearer <token>"
Response: Array of CollectionSchema objects.
​
id
integer
Internal collection ID.
​
name
string
Collection name.
​
description
string
Collection description.
​
is_public
boolean
Whether the collection is visible to other users.
​
is_favorite
boolean
Whether the collection is marked as a favourite.
​
user_id
integer
ID of the owning user.
​
rom_ids
integer[]
IDs of ROMs in this collection (hidden ROMs are excluded for the caller).
​
rom_count
integer
Number of visible ROMs in this collection.
​
path_cover_s
string | null
Path to the small cover image.
​
path_cover_l
string | null
Path to the large cover image.
​
created_at
string
ISO 8601 creation timestamp.
​
updated_at
string
ISO 8601 last-updated timestamp.

​
GET /api/collections/identifiers

Retrieve only the IDs of collections the current user owns or that are public. Required scope: collections.read 
curl http://localhost:8080/api/collections/identifiers \
  -H "Authorization: Bearer <token>"
Response: [1, 2, 5, ...]

​
POST /api/collections

Create a new collection. Accepts multipart/form-data to allow cover artwork upload in the same request. Required scope: collections.write
​
name
string
required
Collection name (must be unique for the current user).
​
description
string
Optional description text.
​
is_public
boolean
default:"false"
Whether the collection should be visible to other users.
​
is_favorite
boolean
default:"false"
Whether to mark this collection as a favourite.
​
url_cover
string
Remote URL to fetch and store as cover artwork.
​
artwork
file
Cover image file to upload (JPEG/PNG/WebP).
curl -X POST http://localhost:8080/api/collections \
  -H "Authorization: Bearer <token>" \
  -F "name=My RPG Backlog" \
  -F "description=All the RPGs I need to finish" \
  -F "is_public=false"
Response: 200 OK — the newly created CollectionSchema object.

​
GET /api/collections/

Retrieve a single collection by ID. Returns 403 if the collection is private and owned by another user. Required scope: collections.read
​
id
integer
required
Collection internal ID.
curl http://localhost:8080/api/collections/5 \
  -H "Authorization: Bearer <token>"

​
PUT /api/collections/

Replace a collection’s ROM list and update its metadata. The full rom_ids list is required and replaces the current list entirely. Required scope: collections.write Only the collection’s owner can update it.
​
id
integer
required
Collection internal ID.
​
rom_ids
string
required
JSON array string of ROM IDs that should be in the collection (e.g. "[1, 2, 3]").
​
name
string
Updated collection name.
​
description
string
Updated description.
​
is_public
boolean
Update visibility.
​
url_cover
string
Remote URL for a new cover image.
​
artwork
file
New cover image file.
​
remove_cover
boolean
Set to true to remove the existing cover.
curl -X PUT http://localhost:8080/api/collections/5 \
  -H "Authorization: Bearer <token>" \
  -F 'rom_ids=[1,2,3,42]' \
  -F "name=My RPG Backlog (Updated)"

​
POST /api/collections//roms

Atomically add ROMs to a collection without replacing the full list. Required scope: collections.write
​
id
integer
required
Collection internal ID.
​
rom_ids
integer[]
required
List of ROM IDs to add.
curl -X POST http://localhost:8080/api/collections/5/roms \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"rom_ids": [55, 56, 57]}'

​
DELETE /api/collections//roms

Atomically remove ROMs from a collection without replacing the full list. Required scope: collections.write
​
id
integer
required
Collection internal ID.
​
rom_ids
integer[]
required
List of ROM IDs to remove.
curl -X DELETE http://localhost:8080/api/collections/5/roms \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"rom_ids": [55]}'

​
DELETE /api/collections/

Delete a collection. Only the collection’s owner can delete it. Required scope: collections.write
​
id
integer
required
Collection internal ID.
curl -X DELETE http://localhost:8080/api/collections/5 \
  -H "Authorization: Bearer <token>"
Response: 204 No Content.

​
Smart Collections

Smart collections are filter-driven: RomM evaluates their filter_criteria against the library and keeps the ROM list up to date automatically.

​
POST /api/collections/smart

Create a new smart collection. Required scope: collections.write
​
name
string
required
Collection name (unique per user).
​
description
string
Optional description.
​
is_public
boolean
default:"false"
Whether the collection is visible to other users.
​
filter_criteria
string
required
JSON string of filter criteria (same filter keys as GET /api/roms). Example: '{"genres": ["RPG"], "genres_logic": "any"}'
curl -X POST http://localhost:8080/api/collections/smart \
  -H "Authorization: Bearer <token>" \
  -F "name=All RPGs" \
  -F 'filter_criteria={"genres":["RPG"]}'

​
GET /api/collections/smart

Retrieve all smart collections for the current user, plus public ones from other users. Required scope: collections.read
​
updated_after
string
ISO 8601 datetime filter.

​
GET /api/collections/smart/identifiers

Retrieve smart collection IDs. Required scope: collections.read

​
GET /api/collections/smart/

Retrieve a single smart collection by ID. Required scope: collections.read

​
PUT /api/collections/smart/

Update a smart collection’s name, description, visibility, or filter criteria. Required scope: collections.write

​
DELETE /api/collections/smart/

Delete a smart collection. Required scope: collections.write

​
Virtual Collections

Virtual collections are system-generated groupings (e.g. by genre, franchise, or company) and are read-only.

​
GET /api/collections/virtual

Required scope: collections.read
​
type
string
required
The virtual collection type to retrieve (e.g. genre, franchise, company).
​
limit
integer
Maximum number of virtual collections to return.

​
GET /api/collections/virtual/identifiers

Retrieve virtual collection IDs for a given type. Required scope: collections.read

​
GET /api/collections/virtual/

Retrieve a single virtual collection by its generated string ID. Required scope: collections.read

Build docs developers (and LLMs) love

Get started for freeTalk to us