RomM States API
The states API from RomM — 9 operation(s) for states.
The states API from RomM — 9 operation(s) for states.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/romm:romm-states-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a 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.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: RomM States API
version: 5.4.0
tags:
- name: States
paths:
/api/states:
post:
tags:
- States
summary: Add State
operationId: add_state_api_states_post
security:
- OAuth2PasswordBearer:
- assets.write
- HTTPBasic: []
parameters:
- name: rom_id
in: query
required: true
schema:
type: integer
title: Rom Id
- name: emulator
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 50
- type: 'null'
title: Emulator
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Body_add_state_api_states_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StateSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- States
summary: Get States
description: Retrieve states for the current user.
operationId: get_states_api_states_get
security:
- OAuth2PasswordBearer:
- assets.read
- HTTPBasic: []
parameters:
- name: rom_id
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
title: Rom Id
- name: rom_ids
in: query
required: false
schema:
anyOf:
- type: array
items:
type: integer
exclusiveMinimum: 0
maxItems: 500
- type: 'null'
description: ROM IDs to scope the results to, for clients syncing a known set of ROMs. Multiple values are allowed by repeating the parameter. Combined with `rom_id` when both are given.
title: Rom Ids
description: ROM IDs to scope the results to, for clients syncing a known set of ROMs. Multiple values are allowed by repeating the parameter. Combined with `rom_id` when both are given.
- name: platform_id
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
title: Platform Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/StateSchema'
title: Response Get States Api States Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/states/identifiers:
get:
tags:
- States
summary: Get State Identifiers
description: 'Get state identifiers endpoint
Args:
request (Request): Fastapi Request object
Returns:
list[int]: List of state IDs'
operationId: get_state_identifiers_api_states_identifiers_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
items:
type: integer
type: array
title: Response Get State Identifiers Api States Identifiers Get
security:
- OAuth2PasswordBearer:
- assets.read
- HTTPBasic: []
/api/states/{id}:
get:
tags:
- States
summary: Get State
operationId: get_state_api_states__id__get
security:
- OAuth2PasswordBearer:
- assets.read
- HTTPBasic: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
title: Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StateSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- States
summary: Update State
operationId: update_state_api_states__id__put
security:
- OAuth2PasswordBearer:
- assets.write
- HTTPBasic: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
title: Id
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Body_update_state_api_states__id__put'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StateSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/states/{id}/content:
get:
tags:
- States
summary: Download State
description: 'Download a state file. Owner can download any of their states; everyone
else only public ones.'
operationId: download_state_api_states__id__content_get
security:
- OAuth2PasswordBearer:
- assets.read
- HTTPBasic: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
title: Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/states/{id}/visibility:
put:
tags:
- States
summary: Update State Visibility
description: Toggle a state's public/private visibility (owner only).
operationId: update_state_visibility_api_states__id__visibility_put
security:
- OAuth2PasswordBearer:
- assets.write
- HTTPBasic: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
title: Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Body_update_state_visibility_api_states__id__visibility_put'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StateSchema'
'404':
description: Not Found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/states/{id}/favorite:
put:
tags:
- States
summary: Update State Favorite
description: Favorite a state, sorting it ahead of the rest (owner only).
operationId: update_state_favorite_api_states__id__favorite_put
security:
- OAuth2PasswordBearer:
- assets.write
- HTTPBasic: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
title: Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Body_update_state_favorite_api_states__id__favorite_put'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StateSchema'
'404':
description: Not Found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/states/{id}/labels:
put:
tags:
- States
summary: Update State Labels
description: Replace a state's free-text labels (owner only).
operationId: update_state_labels_api_states__id__labels_put
security:
- OAuth2PasswordBearer:
- assets.write
- HTTPBasic: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
title: Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Body_update_state_labels_api_states__id__labels_put'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StateSchema'
'404':
description: Not Found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/states/{id}/file-name:
put:
tags:
- States
summary: Rename State
description: Rename a state's file, its screenshot following along (owner only).
operationId: rename_state_api_states__id__file_name_put
security:
- OAuth2PasswordBearer:
- assets.write
- HTTPBasic: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
title: Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Body_rename_state_api_states__id__file_name_put'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StateSchema'
'400':
description: Bad Request
'404':
description: Not Found
'409':
description: Conflict
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/states/delete:
post:
tags:
- States
summary: Delete States
description: Delete states.
operationId: delete_states_api_states_delete_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_delete_states_api_states_delete_post'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
items:
type: integer
type: array
title: Response Delete States Api States Delete Post
'400':
description: Bad Request
'404':
description: Not Found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- OAuth2PasswordBearer:
- assets.write
- HTTPBasic: []
components:
schemas:
Body_update_state_visibility_api_states__id__visibility_put:
properties:
is_public:
type: boolean
title: Is Public
type: object
required:
- is_public
title: Body_update_state_visibility_api_states__id__visibility_put
Body_rename_state_api_states__id__file_name_put:
properties:
file_name:
type: string
maxLength: 450
title: File Name
type: object
required:
- file_name
title: Body_rename_state_api_states__id__file_name_put
Body_update_state_api_states__id__put:
properties:
stateFile:
anyOf:
- type: string
contentMediaType: application/octet-stream
- type: 'null'
title: Statefile
description: Updated state file content.
screenshotFile:
anyOf:
- type: string
contentMediaType: application/octet-stream
- type: 'null'
title: Screenshotfile
description: Updated screenshot file.
type: object
title: Body_update_state_api_states__id__put
StateSchema:
properties:
is_favorite:
type: boolean
title: Is Favorite
default: false
labels:
items:
type: string
type: array
title: Labels
default: []
id:
type: integer
title: Id
rom_id:
type: integer
title: Rom Id
user_id:
type: integer
title: User Id
file_name:
type: string
title: File Name
file_name_no_tags:
type: string
title: File Name No Tags
file_name_no_ext:
type: string
title: File Name No Ext
file_extension:
type: string
title: File Extension
file_path:
type: string
title: File Path
file_size_bytes:
type: integer
title: File Size Bytes
full_path:
type: string
title: Full Path
download_path:
type: string
title: Download Path
missing_from_fs:
type: boolean
title: Missing From Fs
created_at:
type: string
title: Created At
updated_at:
type: string
title: Updated At
emulator:
anyOf:
- type: string
- type: 'null'
title: Emulator
core:
anyOf:
- type: string
- type: 'null'
title: Core
is_public:
type: boolean
title: Is Public
default: false
screenshot:
anyOf:
- $ref: '#/components/schemas/ScreenshotSchema'
- type: 'null'
type: object
required:
- id
- rom_id
- user_id
- file_name
- file_name_no_tags
- file_name_no_ext
- file_extension
- file_path
- file_size_bytes
- full_path
- download_path
- missing_from_fs
- created_at
- updated_at
- emulator
- screenshot
title: StateSchema
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
Body_update_state_favorite_api_states__id__favorite_put:
properties:
is_favorite:
type: boolean
title: Is Favorite
type: object
required:
- is_favorite
title: Body_update_state_favorite_api_states__id__favorite_put
Body_delete_states_api_states_delete_post:
properties:
states:
items:
type: integer
type: array
title: States
description: List of states ids to delete from database.
type: object
required:
- states
title: Body_delete_states_api_states_delete_post
Body_update_state_labels_api_states__id__labels_put:
properties:
labels:
items:
type: string
type: array
title: Labels
type: object
required:
- labels
title: Body_update_state_labels_api_states__id__labels_put
ScreenshotSchema:
properties:
id:
type: integer
title: Id
rom_id:
type: integer
title: Rom Id
user_id:
type: integer
title: User Id
file_name:
type: string
title: File Name
file_name_no_tags:
type: string
title: File Name No Tags
file_name_no_ext:
type: string
title: File Name No Ext
file_extension:
type: string
title: File Extension
file_path:
type: string
title: File Path
file_size_bytes:
type: integer
title: File Size Bytes
full_path:
type: string
title: Full Path
download_path:
type: string
title: Download Path
missing_from_fs:
type: boolean
title: Missing From Fs
created_at:
type: string
title: Created At
updated_at:
type: string
title: Updated At
is_gallery:
type: boolean
title: Is Gallery
default: false
is_public:
type: boolean
title: Is Public
default: false
type: object
required:
- id
- rom_id
- user_id
- file_name
- file_name_no_tags
- file_name_no_ext
- file_extension
- file_path
- file_size_bytes
- full_path
- download_path
- missing_from_fs
- created_at
- updated_at
title: ScreenshotSchema
Body_add_state_api_states_post:
properties:
stateFile:
type: string
contentMediaType: application/octet-stream
title: Statefile
description: State file to upload.
screenshotFile:
anyOf:
- type: string
contentMediaType: application/octet-stream
- type: 'null'
title: Screenshotfile
description: Screenshot file associated with this state.
type: object
required:
- stateFile
title: Body_add_state_api_states_post
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
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