RomM

RomM Tasks API

The tasks API from RomM — 5 operation(s) for tasks.

GitHub OpenAPI

Operations 5

GET /api/tasks List Tasks #
GET /api/tasks/status Get Tasks Status #
GET /api/tasks/{task_id} Get Task By Id #
POST /api/tasks/run/{task_name} Run Single Task #
POST /api/tasks/scan Start Scan #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/romm/openapi/romm-tasks-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/romm/json-schema/romm-detailed-rom-schema-schema.json
📊
JSONSchema
https://artifacts.apis.io/romm/json-schema/romm-simple-rom-schema-schema.json
📊
JSONSchema
https://artifacts.apis.io/romm/json-schema/romm-config-response-schema.json
📊
JSONSchema
https://artifacts.apis.io/romm/json-schema/romm-body-update-rom-api-roms-id-put-schema.json
📊
JSONSchema
https://artifacts.apis.io/romm/json-schema/romm-platform-schema-schema.json
📊
JSONSchema
https://artifacts.apis.io/romm/json-schema/romm-search-rom-schema-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/romm:romm-tasks-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API 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.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

romm-tasks-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: RomM Tasks API
  version: 5.4.0
tags:
- name: Tasks
paths:
  /api/tasks:
    get:
      tags:
      - Tasks
      summary: List Tasks
      description: 'List all available tasks grouped by task type.


        Args:

        request (Request): FastAPI Request object

        Returns:

        GroupedTasksDict: Dictionary with tasks grouped by their type (scheduled, manual, watcher)'
      operationId: list_tasks_api_tasks_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupedTasksDict'
      security:
      - OAuth2PasswordBearer:
        - tasks.run
      - HTTPBasic: []
  /api/tasks/status:
    get:
      tags:
      - Tasks
      summary: Get Tasks Status
      description: 'Get all active, queued, completed, and failed tasks.


        Args:

        request (Request): FastAPI Request object

        Returns:

        list[TaskStatusResponse]: List of all tasks with their current status'
      operationId: get_tasks_status_api_tasks_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  anyOf:
                  - $ref: '#/components/schemas/ScanTaskStatusResponse'
                  - $ref: '#/components/schemas/ConversionTaskStatusResponse'
                  - $ref: '#/components/schemas/UpdateTaskStatusResponse'
                  - $ref: '#/components/schemas/CleanupTaskStatusResponse'
                  - $ref: '#/components/schemas/SyncTaskStatusResponse'
                  - $ref: '#/components/schemas/WatcherTaskStatusResponse'
                  - $ref: '#/components/schemas/GenericTaskStatusResponse'
                type: array
                title: Response Get Tasks Status Api Tasks Status Get
      security:
      - OAuth2PasswordBearer:
        - tasks.run
      - HTTPBasic: []
  /api/tasks/{task_id}:
    get:
      tags:
      - Tasks
      summary: Get Task By Id
      description: 'Get the status of a task by its job ID.


        Args:

        request (Request): FastAPI Request object

        task_id (str): Job ID of the task to retrieve status for

        Returns:

        TaskStatusResponse: Task status information'
      operationId: get_task_by_id_api_tasks__task_id__get
      security:
      - OAuth2PasswordBearer:
        - tasks.run
      - HTTPBasic: []
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ScanTaskStatusResponse'
                - $ref: '#/components/schemas/ConversionTaskStatusResponse'
                - $ref: '#/components/schemas/UpdateTaskStatusResponse'
                - $ref: '#/components/schemas/CleanupTaskStatusResponse'
                - $ref: '#/components/schemas/SyncTaskStatusResponse'
                - $ref: '#/components/schemas/WatcherTaskStatusResponse'
                - $ref: '#/components/schemas/GenericTaskStatusResponse'
                title: Response Get Task By Id Api Tasks  Task Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/tasks/run/{task_name}:
    post:
      tags:
      - Tasks
      summary: Run Single Task
      description: 'Run a single task endpoint.


        Args:

        request (Request): FastAPI Request object

        task_name (str): Name of the task to run

        task_kwargs (dict | None): Optional keyword arguments forwarded to the task''s run() method

        Returns:

        TaskExecutionResponse: Task execution response with details'
      operationId: run_single_task_api_tasks_run__task_name__post
      security:
      - OAuth2PasswordBearer:
        - tasks.run
      - HTTPBasic: []
      parameters:
      - name: task_name
        in: path
        required: true
        schema:
          type: string
          title: Task Name
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - type: object
                additionalProperties: true
              - type: 'null'
              title: Task Kwargs
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskExecutionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/tasks/scan:
    post:
      tags:
      - Tasks
      summary: Start Scan
      description: 'Queue a scan, for clients that authenticate without a session cookie.


        Args:

        request (Request): FastAPI Request object

        payload (ScanPayload): What to scan and which metadata sources to use,

        a quick scan of the whole library when the body is left out

        Returns:

        TaskExecutionResponse: The queued scan, to follow on `GET /api/tasks/{task_id}`'
      operationId: start_scan_api_tasks_scan_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanPayload'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskExecutionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer:
        - tasks.run
      - HTTPBasic: []
components:
  schemas:
    UpdateTaskStatusResponse:
      properties:
        task_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Key
        task_name:
          type: string
          title: Task Name
        task_id:
          type: string
          title: Task Id
        status:
          $ref: '#/components/schemas/JobStatus'
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        enqueued_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Enqueued At
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
        ended_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Ended At
        task_type:
          type: string
          const: update
          title: Task Type
        meta:
          $ref: '#/components/schemas/UpdateTaskMeta'
      type: object
      required:
      - task_key
      - task_name
      - task_id
      - status
      - created_at
      - enqueued_at
      - started_at
      - ended_at
      - task_type
      - meta
      title: UpdateTaskStatusResponse
    TaskType:
      type: string
      enum:
      - scan
      - conversion
      - cleanup
      - update
      - sync
      - watcher
      - generic
      title: TaskType
      description: Enumeration of task types for categorization and UI display.
    ScanPayload:
      properties:
        type:
          $ref: '#/components/schemas/ScanType'
          default: quick
        platforms:
          items:
            type: integer
          type: array
          title: Platforms
          default: []
        platform_fs_slugs:
          items:
            type: string
          type: array
          title: Platform Fs Slugs
          default: []
        roms_ids:
          items:
            type: integer
          type: array
          title: Roms Ids
          default: []
        apis:
          anyOf:
          - items:
              $ref: '#/components/schemas/MetadataSource'
            type: array
          - type: 'null'
          title: Apis
        launchbox_remote_enabled:
          type: boolean
          title: Launchbox Remote Enabled
          default: true
      additionalProperties: false
      type: object
      title: ScanPayload
      description: What to scan, with the options the `scan` socket event takes.
    SyncTaskMeta:
      properties: {}
      type: object
      title: SyncTaskMeta
    MissingRomsCleanupStats:
      properties:
        platform_ids:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Platform Ids
        roms_found:
          type: integer
          title: Roms Found
        roms_deleted:
          type: integer
          title: Roms Deleted
        errors:
          type: integer
          title: Errors
      type: object
      required:
      - platform_ids
      - roms_found
      - roms_deleted
      - errors
      title: MissingRomsCleanupStats
    GenericTaskMeta:
      properties: {}
      type: object
      title: GenericTaskMeta
    JobStatus:
      type: string
      enum:
      - created
      - queued
      - finished
      - failed
      - started
      - deferred
      - scheduled
      - stopped
      - canceled
      title: JobStatus
      description: The Status of Job within its lifecycle at any given time.
    TaskInfo:
      properties:
        name:
          type: string
          title: Name
        type:
          $ref: '#/components/schemas/TaskType'
        manual_run:
          type: boolean
          title: Manual Run
        title:
          type: string
          title: Title
        description:
          type: string
          title: Description
        enabled:
          type: boolean
          title: Enabled
        destructive:
          type: boolean
          title: Destructive
        cron_string:
          type: string
          title: Cron String
      type: object
      required:
      - name
      - type
      - manual_run
      - title
      - description
      - enabled
      - destructive
      - cron_string
      title: TaskInfo
    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
    ScanTaskMeta:
      properties:
        scan_stats:
          anyOf:
          - $ref: '#/components/schemas/ScanStats'
          - type: 'null'
      type: object
      required:
      - scan_stats
      title: ScanTaskMeta
    ScanType:
      type: string
      enum:
      - new_platforms
      - quick
      - update
      - unmatched
      - complete
      - hashes
      title: ScanType
    SyncTaskStatusResponse:
      properties:
        task_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Key
        task_name:
          type: string
          title: Task Name
        task_id:
          type: string
          title: Task Id
        status:
          $ref: '#/components/schemas/JobStatus'
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        enqueued_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Enqueued At
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
        ended_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Ended At
        task_type:
          type: string
          const: sync
          title: Task Type
        meta:
          $ref: '#/components/schemas/SyncTaskMeta'
      type: object
      required:
      - task_key
      - task_name
      - task_id
      - status
      - created_at
      - enqueued_at
      - started_at
      - ended_at
      - task_type
      - meta
      title: SyncTaskStatusResponse
    TaskExecutionResponse:
      properties:
        task_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Key
        task_name:
          type: string
          title: Task Name
        task_id:
          type: string
          title: Task Id
        status:
          $ref: '#/components/schemas/JobStatus'
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        enqueued_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Enqueued At
      type: object
      required:
      - task_key
      - task_name
      - task_id
      - status
      - created_at
      - enqueued_at
      title: TaskExecutionResponse
    CleanupTaskStatusResponse:
      properties:
        task_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Key
        task_name:
          type: string
          title: Task Name
        task_id:
          type: string
          title: Task Id
        status:
          $ref: '#/components/schemas/JobStatus'
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        enqueued_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Enqueued At
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
        ended_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Ended At
        task_type:
          type: string
          const: cleanup
          title: Task Type
        meta:
          $ref: '#/components/schemas/CleanupTaskMeta'
      type: object
      required:
      - task_key
      - task_name
      - task_id
      - status
      - created_at
      - enqueued_at
      - started_at
      - ended_at
      - task_type
      - meta
      title: CleanupTaskStatusResponse
    MissingFirmwareCleanupStats:
      properties:
        platform_ids:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Platform Ids
        firmware_found:
          type: integer
          title: Firmware Found
        firmware_deleted:
          type: integer
          title: Firmware Deleted
        errors:
          type: integer
          title: Errors
      type: object
      required:
      - platform_ids
      - firmware_found
      - firmware_deleted
      - errors
      title: MissingFirmwareCleanupStats
    WatcherTaskStatusResponse:
      properties:
        task_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Key
        task_name:
          type: string
          title: Task Name
        task_id:
          type: string
          title: Task Id
        status:
          $ref: '#/components/schemas/JobStatus'
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        enqueued_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Enqueued At
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
        ended_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Ended At
        task_type:
          type: string
          const: watcher
          title: Task Type
        meta:
          $ref: '#/components/schemas/WatcherTaskMeta'
      type: object
      required:
      - task_key
      - task_name
      - task_id
      - status
      - created_at
      - enqueued_at
      - started_at
      - ended_at
      - task_type
      - meta
      title: WatcherTaskStatusResponse
    ScanTaskStatusResponse:
      properties:
        task_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Key
        task_name:
          type: string
          title: Task Name
        task_id:
          type: string
          title: Task Id
        status:
          $ref: '#/components/schemas/JobStatus'
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        enqueued_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Enqueued At
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
        ended_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Ended At
        task_type:
          type: string
          const: scan
          title: Task Type
        meta:
          $ref: '#/components/schemas/ScanTaskMeta'
      type: object
      required:
      - task_key
      - task_name
      - task_id
      - status
      - created_at
      - enqueued_at
      - started_at
      - ended_at
      - task_type
      - meta
      title: ScanTaskStatusResponse
    GroupedTasksDict:
      properties:
        scheduled:
          items:
            $ref: '#/components/schemas/TaskInfo'
          type: array
          title: Scheduled
        manual:
          items:
            $ref: '#/components/schemas/TaskInfo'
          type: array
          title: Manual
        watcher:
          items:
            $ref: '#/components/schemas/TaskInfo'
          type: array
          title: Watcher
      type: object
      required:
      - scheduled
      - manual
      - watcher
      title: GroupedTasksDict
    OrphanedResourcesCleanupStats:
      properties:
        platforms_in_db:
          type: integer
          title: Platforms In Db
        roms_in_db:
          type: integer
          title: Roms In Db
        platforms_in_fs:
          type: integer
          title: Platforms In Fs
        roms_in_fs:
          type: integer
          title: Roms In Fs
        removed_fs_platforms:
          type: integer
          title: Removed Fs Platforms
        removed_fs_roms:
          type: integer
          title: Removed Fs Roms
      type: object
      required:
      - platforms_in_db
      - roms_in_db
      - platforms_in_fs
      - roms_in_fs
      - removed_fs_platforms
      - removed_fs_roms
      title: OrphanedResourcesCleanupStats
    UpdateTaskMeta:
      properties:
        update_stats:
          anyOf:
          - $ref: '#/components/schemas/UpdateStats'
          - type: 'null'
      type: object
      required:
      - update_stats
      title: UpdateTaskMeta
    ScanStats:
      properties:
        total_platforms:
          type: integer
          title: Total Platforms
        total_roms:
          type: integer
          title: Total Roms
        scanned_platforms:
          type: integer
          title: Scanned Platforms
        new_platforms:
          type: integer
          title: New Platforms
        identified_platforms:
          type: integer
          title: Identified Platforms
        scanned_roms:
          type: integer
          title: Scanned Roms
        new_roms:
          type: integer
          title: New Roms
        identified_roms:
          type: integer
          title: Identified Roms
        scanned_firmware:
          type: integer
          title: Scanned Firmware
        new_firmware:
          type: integer
          title: New Firmware
        updated_roms:
          type: integer
          title: Updated Roms
        new_files:
          type: integer
          title: New Files
      type: object
      required:
      - total_platforms
      - total_roms
      - scanned_platforms
      - new_platforms
      - identified_platforms
      - scanned_roms
      - new_roms
      - identified_roms
      - scanned_firmware
      - new_firmware
      - updated_roms
      - new_files
      title: ScanStats
    ConversionTaskMeta:
      properties:
        conversion_stats:
          anyOf:
          - $ref: '#/components/schemas/ConversionStats'
          - type: 'null'
      type: object
      required:
      - conversion_stats
      title: ConversionTaskMeta
    CleanupTaskMeta:
      properties:
        cleanup_stats:
          anyOf:
          - $ref: '#/components/schemas/OrphanedResourcesCleanupStats'
          - $ref: '#/components/schemas/MissingRomsCleanupStats'
          - $ref: '#/components/schemas/MissingFirmwareCleanupStats'
          - type: 'null'
          title: Cleanup Stats
      type: object
      required:
      - cleanup_stats
      title: CleanupTaskMeta
    WatcherTaskMeta:
      properties: {}
      type: object
      title: WatcherTaskMeta
    UpdateStats:
      properties:
        processed:
          type: integer
          title: Processed
        total:
          type: integer
          title: Total
      type: object
      required:
      - processed
      - total
      title: UpdateStats
    GenericTaskStatusResponse:
      properties:
        task_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Key
        task_name:
          type: string
          title: Task Name
        task_id:
          type: string
          title: Task Id
        status:
          $ref: '#/components/schemas/JobStatus'
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        enqueued_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Enqueued At
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
        ended_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Ended At
        task_type:
          type: string
          const: generic
          title: Task Type
        meta:
          $ref: '#/components/schemas/GenericTaskMeta'
      type: object
      required:
      - task_key
      - task_name
      - task_id
      - status
      - created_at
      - enqueued_at
      - started_at
      - ended_at
      - task_type
      - meta
      title: GenericTaskStatusResponse
    ConversionStats:
      properties:
        processed:
          type: integer
          title: Processed
        errors:
          type: integer
          title: Errors
        total:
          type: integer
          title: Total
      type: object
      required:
      - processed
      - errors
      - total
      title: ConversionStats
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ConversionTaskStatusResponse:
      properties:
        task_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Key
        task_name:
          type: string
          title: Task Name
        task_id:
          type: string
          title: Task Id
        status:
          $ref: '#/components/schemas/JobStatus'
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        enqueued_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Enqueued At
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
        ended_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Ended At
        task_type:
          type: string
          const: conversion
          title: Task Type
        meta:
          $ref: '#/components/schemas/ConversionTaskMeta'
      type: object
      required:
      - task_key
      - task_name
      - task_id
      - status
      - created_at
      - enqueued_at
      - started_at
      - ended_at
      - task_type
      - meta
      title: ConversionTaskStatusResponse
    MetadataSource:
      type: string
      enum:
      - igdb
      - moby
      - ss
      - ra
      - launchbox
      - hasheous
      - tgdb
      - sgdb
      - flashpoint
      - hltb
      - demozoo
      - pouet
      - csdb
      - steam
      - gamelist
      - libretro
      - playmatch
      title: MetadataSource
  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