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 uses a Redis-backed RQ (Redis Queue) task queue to run background operations without blocking the API. The Tasks API lets you list available tasks, trigger them on demand, and inspect the status of running or completed jobs.
All Tasks API endpoints require the tasks.run scope, which is only available to admin users by default.

​
GET /api/tasks

List all available tasks grouped by type (scheduled, manual, and watcher). Returns task metadata — name, title, description, enabled status, and cron schedule — but not execution history. Required scope: tasks.run 
curl http://localhost:8080/api/tasks \
  -H "Authorization: Bearer <token>"
Response: 
{
  "scheduled": [
    {
      "name": "scan_library",
      "type": "scan",
      "title": "Scan Library",
      "description": "...",
      "enabled": true,
      "manual_run": true,
      "cron_string": "0 3 * * *"
    },
    ...
  ],
  "manual": [
    {
      "name": "cleanup_orphaned_resources",
      "type": "cleanup",
      ...
    },
    ...
  ],
  "watcher": [
    {
      "name": "filesystem_watcher",
      "type": "watcher",
      "title": "Rescan on filesystem change",
      "enabled": false,
      "manual_run": false,
      "cron_string": ""
    }
  ]
}
​
name
string
Machine-readable task identifier used when triggering via POST /api/tasks/run/{task_name}.
​
type
string
Task category: scan, update, cleanup, conversion, sync, watcher, or generic.
​
title
string
Human-readable display name.
​
description
string
What the task does.
​
enabled
boolean
Whether the task is active. Disabled tasks cannot be triggered.
​
manual_run
boolean
Whether the task can be triggered via the API. Watcher tasks cannot be triggered manually.
​
cron_string
string
Cron expression for scheduled tasks, or an empty string for manual-only tasks.

​
Available Tasks

​
Scheduled Tasks

These run automatically on their cron schedule and can also be triggered manually:
NameTypeDescription
scan_libraryscanScans the library filesystem and updates ROM metadata
update_launchbox_metadataupdateDownloads the latest LaunchBox metadata database
update_switch_titledbupdateDownloads the latest Nintendo Switch TitleDB
convert_images_to_webpconversionConverts stored cover images to WebP format

​
Manual Tasks

These must be triggered explicitly and do not run on a schedule:
NameTypeDescription
cleanup_orphaned_resourcescleanupRemoves cover images and resources for ROMs/platforms no longer in the database
cleanup_missing_romscleanupRemoves database entries for ROM files missing from the filesystem
sync_folder_scansyncSynchronises the folder structure with the database
recompute_save_content_hashescleanupRecomputes content hashes for all save files

​
Watcher Task

NameTypeDescription
filesystem_watcherwatcherAutomatically triggers a scan when a change is detected in the library path (enable with ENABLE_RESCAN_ON_FILESYSTEM_CHANGE=true, delay set by RESCAN_ON_FILESYSTEM_CHANGE_DELAY)

​
GET /api/tasks/status

Get all active, queued, completed, and failed task jobs from all three priority queues. Required scope: tasks.run 
curl http://localhost:8080/api/tasks/status \
  -H "Authorization: Bearer <token>"
Response: Array of TaskStatusResponse objects, sorted by start time descending.
​
task_name
string
Human-readable task name (from the job metadata or function name).
​
task_id
string
Unique RQ job ID. Use this to query a specific job via GET /api/tasks/{task_id}.
​
task_type
string
Task type: scan, update, cleanup, conversion, sync, watcher, or generic.
​
status
string
RQ job status: queued, started, finished, failed, stopped, or canceled.
​
meta
object
Type-specific metadata. Shape depends on task_type:
  • scan → { "scan_stats": {...} }
  • update → { "update_stats": {...} }
  • cleanup → { "cleanup_stats": {...} }
  • conversion → { "conversion_stats": {...} }
  • All others → {}
​
created_at
string | null
ISO 8601 job creation time.
​
enqueued_at
string | null
ISO 8601 time the job entered the queue.
​
started_at
string | null
ISO 8601 time the job started executing.
​
ended_at
string | null
ISO 8601 time the job finished (success or failure).

​
GET /api/tasks/

Retrieve the status of a specific task by its RQ job ID. Required scope: tasks.run
​
task_id
string
required
The RQ job ID returned when the task was enqueued (from POST /api/tasks/run/{task_name}).
curl http://localhost:8080/api/tasks/abc123-def456 \
  -H "Authorization: Bearer <token>"
Response: A single TaskStatusResponse object. Returns 404 if the job ID is not found.
Completed job results are retained in Redis for a duration controlled by the TASK_RESULT_TTL environment variable (default: 300 seconds). After this TTL, the job record is removed and this endpoint will return 404.

​
POST /api/tasks/run/

Enqueue a task for immediate execution. Only tasks with enabled: true and manual_run: true can be triggered. Required scope: tasks.run
​
task_name
string
required
The machine-readable task name (e.g. scan_library, cleanup_orphaned_resources). See the task table above for all valid names.
​
task_kwargs
object
Optional keyword arguments forwarded to the task’s run() method. Shape varies by task.
# Trigger a library scan
curl -X POST http://localhost:8080/api/tasks/run/scan_library \
  -H "Authorization: Bearer <token>"

# Trigger a scan with optional kwargs
curl -X POST http://localhost:8080/api/tasks/run/scan_library \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"platforms": ["gba", "n64"]}'
Response: 
{
  "task_name": "Scan Library",
  "task_id": "abc123-def456-...",
  "status": "queued",
  "created_at": "2024-01-15T10:00:00Z",
  "enqueued_at": "2024-01-15T10:00:00Z"
}
Use the returned task_id to poll GET /api/tasks/{task_id} for progress, or stream real-time progress via the /ws WebSocket endpoint.
Tasks run in the background worker process. If no worker is running, jobs will remain queued indefinitely. Ensure the RomM worker container is up when triggering tasks.

Build docs developers (and LLMs) love

Get started for freeTalk to us