RomM Saves API
The saves API from RomM — 13 operation(s) for saves.
The saves API from RomM — 13 operation(s) for saves.
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-saves-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 Saves API
version: 5.4.0
tags:
- name: saves
paths:
/api/saves:
post:
tags:
- saves
summary: Add Save
description: Upload a save file for a ROM.
operationId: add_save_api_saves_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
- name: slot
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 255
- type: 'null'
title: Slot
- name: device_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Device Id
- name: content_hash
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Content Hash
- name: session_id
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
title: Session Id
- name: overwrite
in: query
required: false
schema:
type: boolean
default: false
title: Overwrite
- name: autocleanup
in: query
required: false
schema:
type: boolean
default: false
title: Autocleanup
- name: autocleanup_limit
in: query
required: false
schema:
type: integer
default: 10
title: Autocleanup Limit
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Body_add_save_api_saves_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SaveSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- saves
summary: Get Saves
description: Retrieve saves for the current user.
operationId: get_saves_api_saves_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
- name: device_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Device Id
- name: slot
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Slot
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SaveSchema'
title: Response Get Saves Api Saves Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/saves/identifiers:
get:
tags:
- saves
summary: Get Save Identifiers
description: Retrieve save identifiers.
operationId: get_save_identifiers_api_saves_identifiers_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
items:
type: integer
type: array
title: Response Get Save Identifiers Api Saves Identifiers Get
security:
- OAuth2PasswordBearer:
- assets.read
- HTTPBasic: []
/api/saves/summary:
get:
tags:
- saves
summary: Get Saves Summary
description: Retrieve saves summary grouped by slot.
operationId: get_saves_summary_api_saves_summary_get
security:
- OAuth2PasswordBearer:
- assets.read
- HTTPBasic: []
parameters:
- name: rom_id
in: query
required: true
schema:
type: integer
title: Rom Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SaveSummarySchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/saves/{id}:
get:
tags:
- saves
summary: Get Save
description: Retrieve a save by ID.
operationId: get_save_api_saves__id__get
security:
- OAuth2PasswordBearer:
- assets.read
- HTTPBasic: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
title: Id
- name: device_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Device Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SaveSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- saves
summary: Update Save
description: Update a save file.
operationId: update_save_api_saves__id__put
security:
- OAuth2PasswordBearer:
- assets.write
- HTTPBasic: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
title: Id
- name: device_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Device Id
- name: content_hash
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Content Hash
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Body_update_save_api_saves__id__put'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SaveSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/saves/{id}/content:
get:
tags:
- saves
summary: Download Save
description: Download a save file.
operationId: download_save_api_saves__id__content_get
security:
- OAuth2PasswordBearer:
- assets.read
- HTTPBasic: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
title: Id
- name: device_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Device Id
- name: session_id
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
title: Session Id
- name: optimistic
in: query
required: false
schema:
type: boolean
default: true
title: Optimistic
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/saves/{id}/downloaded:
post:
tags:
- saves
summary: Confirm Download
description: Confirm a save was downloaded successfully.
operationId: confirm_download_api_saves__id__downloaded_post
security:
- OAuth2PasswordBearer:
- devices.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_confirm_download_api_saves__id__downloaded_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SaveSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/saves/{id}/visibility:
put:
tags:
- saves
summary: Update Save Visibility
description: Toggle a save's public/private visibility (owner only).
operationId: update_save_visibility_api_saves__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_save_visibility_api_saves__id__visibility_put'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SaveSchema'
'404':
description: Not Found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/saves/{id}/favorite:
put:
tags:
- saves
summary: Update Save Favorite
description: Favorite a save, sorting it ahead of the rest (owner only).
operationId: update_save_favorite_api_saves__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_save_favorite_api_saves__id__favorite_put'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SaveSchema'
'404':
description: Not Found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/saves/{id}/labels:
put:
tags:
- saves
summary: Update Save Labels
description: Replace a save's free-text labels (owner only).
operationId: update_save_labels_api_saves__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_save_labels_api_saves__id__labels_put'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SaveSchema'
'404':
description: Not Found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/saves/{id}/file-name:
put:
tags:
- saves
summary: Rename Save
description: Rename a save's file, its screenshot following along (owner only).
operationId: rename_save_api_saves__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_save_api_saves__id__file_name_put'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SaveSchema'
'400':
description: Bad Request
'404':
description: Not Found
'409':
description: Conflict
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/saves/delete:
post:
tags:
- saves
summary: Delete Saves
description: Delete saves.
operationId: delete_saves_api_saves_delete_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_delete_saves_api_saves_delete_post'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
items:
type: integer
type: array
title: Response Delete Saves Api Saves 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: []
/api/saves/{id}/track:
post:
tags:
- saves
summary: Track Save
description: Re-enable sync tracking for a save on a device.
operationId: track_save_api_saves__id__track_post
security:
- OAuth2PasswordBearer:
- devices.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_track_save_api_saves__id__track_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SaveSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/saves/{id}/untrack:
post:
tags:
- saves
summary: Untrack Save
description: Disable sync tracking for a save on a device.
operationId: untrack_save_api_saves__id__untrack_post
security:
- OAuth2PasswordBearer:
- devices.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_untrack_save_api_saves__id__untrack_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SaveSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
Body_delete_saves_api_saves_delete_post:
properties:
saves:
items:
type: integer
type: array
title: Saves
description: List of save ids to delete from database.
type: object
required:
- saves
title: Body_delete_saves_api_saves_delete_post
Body_untrack_save_api_saves__id__untrack_post:
properties:
device_id:
type: string
title: Device Id
type: object
required:
- device_id
title: Body_untrack_save_api_saves__id__untrack_post
SaveSchema:
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
slot:
anyOf:
- type: string
- type: 'null'
title: Slot
content_hash:
anyOf:
- type: string
- type: 'null'
title: Content Hash
is_public:
type: boolean
title: Is Public
default: false
screenshot:
anyOf:
- $ref: '#/components/schemas/ScreenshotSchema'
- type: 'null'
origin_device_id:
anyOf:
- type: string
- type: 'null'
title: Origin Device Id
device_syncs:
items:
$ref: '#/components/schemas/DeviceSyncSchema'
type: array
title: Device Syncs
default: []
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: SaveSchema
Body_update_save_api_saves__id__put:
properties:
saveFile:
anyOf:
- type: string
contentMediaType: application/octet-stream
- type: 'null'
title: Savefile
description: Updated save file content.
screenshotFile:
anyOf:
- type: string
contentMediaType: application/octet-stream
- type: 'null'
title: Screenshotfile
description: Updated screenshot file.
type: object
title: Body_update_save_api_saves__id__put
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
Body_confirm_download_api_saves__id__downloaded_post:
properties:
device_id:
type: string
title: Device Id
content_hash:
anyOf:
- type: string
- type: 'null'
title: Content Hash
type: object
required:
- device_id
title: Body_confirm_download_api_saves__id__downloaded_post
Body_update_save_favorite_api_saves__id__favorite_put:
properties:
is_favorite:
type: boolean
title: Is Favorite
type: object
required:
- is_favorite
title: Body_update_save_favorite_api_saves__id__favorite_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_track_save_api_saves__id__track_post:
properties:
device_id:
type: string
title: Device Id
type: object
required:
- device_id
title: Body_track_save_api_saves__id__track_post
Body_update_save_labels_api_saves__id__labels_put:
properties:
labels:
items:
type: string
type: array
title: Labels
type: object
required:
- labels
title: Body_update_save_labels_api_saves__id__labels_put
Body_update_save_visibility_api_saves__id__visibility_put:
properties:
is_public:
type: boolean
title: Is Public
type: object
required:
- is_public
title: Body_update_save_visibility_api_saves__id__visibility_put
DeviceSyncSchema:
properties:
device_id:
type: string
title: Device Id
device_name:
anyOf:
- type: string
- type: 'null'
title: Device Name
last_synced_at:
type: string
title: Last Synced At
is_untracked:
type: boolean
title: Is Untracked
is_current:
type: boolean
title: Is Current
type: object
required:
- device_id
- device_name
- last_synced_at
- is_untracked
- is_current
title: DeviceSyncSchema
Body_rename_save_api_saves__id__file_name_put:
properties:
file_name:
type: string
maxLength: 450
title: File Name
type: object
required:
- file_name
title: Body_rename_save_api_saves__id__file_name_put
SaveSummarySchema:
properties:
total_count:
type: integer
title: Total Count
slots:
items:
$ref: '#/components/schemas/SlotSummarySchema'
type: array
title: Slots
type: object
required:
- total_count
- slots
title: SaveSummarySchema
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
Body_add_save_api_saves_post:
properties:
saveFile:
type: string
contentMediaType: application/octet-stream
title: Savefile
description: Save file to upload.
screenshotFile:
anyOf:
- type: string
contentMediaType: application/octet-stream
- type: 'null'
title: Screenshotfile
description: Screenshot file associated with this save.
type: object
required:
- saveFile
title: Body_add_save_api_saves_post
SlotSummarySchema:
properties:
slot:
anyOf:
- type: string
- type: 'null'
title: Slot
count:
type: integer
title: Count
latest:
$ref: '#/components/schemas/SaveSchema'
type: object
required:
- slot
- count
- latest
title: SlotSummarySchema
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