RomM Users API
The users API from RomM — 8 operation(s) for users.
The users API from RomM — 8 operation(s) for users.
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-users-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 Users API
version: 5.4.0
tags:
- name: Users
paths:
/api/users:
get:
tags:
- Users
summary: Get Users
description: 'Get all users endpoint
Args:
request (Request): Fastapi Request object
Returns:
list[UserSchema]: All users stored in the RomM''s database'
operationId: get_users_api_users_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
items:
$ref: '#/components/schemas/UserSchema'
type: array
title: Response Get Users Api Users Get
security:
- OAuth2PasswordBearer:
- users.read
- HTTPBasic: []
post:
tags:
- Users
summary: Add User
description: 'Create user endpoint
Args:
request (Request): Fastapi Requests object
username (str): User username
password (str): User password
email (str): User email
role (str): RomM Role object represented as string
Returns:
UserSchema: Newly created user'
operationId: add_user_api_users_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_add_user_api_users_post'
required: true
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UserSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- OAuth2PasswordBearer: []
- HTTPBasic: []
/api/users/invite-link:
post:
tags:
- Users
summary: Create Invite Link
description: 'Create an invite link for a user.
Args:
request (Request): FastAPI Request object
role (str): The role of the user
expiration (int | None): Token expiration in seconds. Defaults to
the INVITE_TOKEN_EXPIRY_SECONDS environment variable.
Returns:
InviteLinkSchema: Invite link'
operationId: create_invite_link_api_users_invite_link_post
security:
- OAuth2PasswordBearer: []
- HTTPBasic: []
parameters:
- name: role
in: query
required: true
schema:
type: string
title: Role
- name: expiration
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
title: Expiration
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/InviteLinkSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/users/register:
post:
tags:
- Users
summary: Create User From Invite
description: 'Create user endpoint with invite link
Args:
username (str): User username
email (str): User email
password (str): User password
token (str): Invite link token
Returns:
UserSchema: Newly created user'
operationId: create_user_from_invite_api_users_register_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_create_user_from_invite_api_users_register_post'
required: true
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UserSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/users/identifiers:
get:
tags:
- Users
summary: Get User Identifiers
description: 'Get all user identifiers endpoint
Args:
request (Request): Fastapi Request object
Returns:
list[int]: All user ids stored in the RomM''s database'
operationId: get_user_identifiers_api_users_identifiers_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
items:
type: integer
type: array
title: Response Get User Identifiers Api Users Identifiers Get
security:
- OAuth2PasswordBearer:
- users.read
- HTTPBasic: []
/api/users/me:
get:
tags:
- Users
summary: Get Current User
description: 'Get current user endpoint
Args:
request (Request): Fastapi Request object
Returns:
UserSchema | None: Current user'
operationId: get_current_user_api_users_me_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/UserSchema'
- type: 'null'
title: Response Get Current User Api Users Me Get
security:
- OAuth2PasswordBearer:
- me.read
- HTTPBasic: []
/api/users/{id}:
get:
tags:
- Users
summary: Get User
description: 'Get user endpoint
Args:
request (Request): Fastapi Request object
Returns:
UserSchem: User stored in the RomM''s database'
operationId: get_user_api_users__id__get
security:
- OAuth2PasswordBearer:
- users.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/UserSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- Users
summary: Update User
description: 'Update user endpoint
Args:
request (Request): Fastapi Requests object
user_id (int): User internal id
form_data (Annotated[UserUpdateForm, Depends): Form Data with user updated info
Raises:
HTTPException: User is not found in database
HTTPException: Username already in use by another user
Returns:
UserSchema: Updated user info'
operationId: update_user_api_users__id__put
security:
- OAuth2PasswordBearer:
- me.write
- HTTPBasic: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
title: Id
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/UserForm'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UserSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Users
summary: Delete User
description: 'Delete a user by ID.
Raises:
HTTPException: User is not found in database
HTTPException: User deleting itself
HTTPException: User is the last admin user'
operationId: delete_user_api_users__id__delete
security:
- OAuth2PasswordBearer:
- users.write
- HTTPBasic: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
minimum: 1
description: User internal id.
title: Id
description: User internal id.
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'400':
description: Bad Request
'404':
description: Not Found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/users/{id}/avatar:
get:
tags:
- Users
summary: Get User Avatar
description: 'Serve a user''s avatar image. Avatars are public to any authenticated
user (rendered next to community content, activity, and user lists).'
operationId: get_user_avatar_api_users__id__avatar_get
security:
- OAuth2PasswordBearer:
- assets.read
- HTTPBasic: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
minimum: 1
description: User internal id.
title: Id
description: User internal id.
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'404':
description: Not Found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/users/{id}/ra/refresh:
post:
tags:
- Users
summary: Refresh RetroAchievements
description: Refresh RetroAchievements progression data for a user.
operationId: refresh_retro_achievements_api_users__id__ra_refresh_post
security:
- OAuth2PasswordBearer:
- me.write
- HTTPBasic: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
minimum: 1
description: User internal id.
title: Id
description: User internal id.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Body_refresh_retro_achievements_api_users__id__ra_refresh_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'404':
description: Not Found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
Body_create_user_from_invite_api_users_register_post:
properties:
username:
type: string
title: Username
email:
type: string
title: Email
password:
type: string
title: Password
token:
type: string
title: Token
type: object
required:
- username
- email
- password
- token
title: Body_create_user_from_invite_api_users_register_post
RAUserGameProgression:
properties:
rom_ra_id:
anyOf:
- type: integer
- type: 'null'
title: Rom Ra Id
max_possible:
anyOf:
- type: integer
- type: 'null'
title: Max Possible
num_awarded:
anyOf:
- type: integer
- type: 'null'
title: Num Awarded
num_awarded_hardcore:
anyOf:
- type: integer
- type: 'null'
title: Num Awarded Hardcore
most_recent_awarded_date:
anyOf:
- type: string
- type: 'null'
title: Most Recent Awarded Date
highest_award_kind:
anyOf:
- type: string
- type: 'null'
title: Highest Award Kind
earned_achievements:
items:
$ref: '#/components/schemas/EarnedAchievement'
type: array
title: Earned Achievements
type: object
required:
- rom_ra_id
- max_possible
- num_awarded
- num_awarded_hardcore
- earned_achievements
title: RAUserGameProgression
Role:
type: string
enum:
- user
- admin
title: Role
UserForm:
properties:
username:
anyOf:
- type: string
- type: 'null'
title: Username
password:
anyOf:
- type: string
- type: 'null'
title: Password
email:
anyOf:
- type: string
- type: 'null'
title: Email
role:
anyOf:
- type: string
- type: 'null'
title: Role
enabled:
anyOf:
- type: boolean
- type: 'null'
title: Enabled
ra_username:
anyOf:
- type: string
maxLength: 255
- type: 'null'
title: Ra Username
avatar:
anyOf:
- type: string
contentMediaType: application/octet-stream
- type: 'null'
title: Avatar
ui_settings:
anyOf:
- type: string
- type: 'null'
title: Ui Settings
type: object
title: UserForm
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
EarnedAchievement:
properties:
id:
type: string
title: Id
date:
type: string
title: Date
date_hardcore:
type: string
title: Date Hardcore
type: object
required:
- id
- date
title: EarnedAchievement
InviteLinkSchema:
properties:
token:
type: string
title: Token
url:
anyOf:
- type: string
- type: 'null'
title: Url
type: object
required:
- token
title: InviteLinkSchema
UserSchema:
properties:
id:
type: integer
title: Id
username:
type: string
title: Username
email:
anyOf:
- type: string
- type: 'null'
title: Email
enabled:
type: boolean
title: Enabled
role:
$ref: '#/components/schemas/Role'
permission_group_id:
anyOf:
- type: integer
- type: 'null'
title: Permission Group Id
oauth_scopes:
items:
type: string
type: array
title: Oauth Scopes
avatar_path:
type: string
title: Avatar Path
last_login:
anyOf:
- type: string
- type: 'null'
title: Last Login
last_active:
anyOf:
- type: string
- type: 'null'
title: Last Active
ra_username:
anyOf:
- type: string
- type: 'null'
title: Ra Username
ra_progression:
anyOf:
- $ref: '#/components/schemas/RAProgression'
- type: 'null'
ui_settings:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Ui Settings
current_device_id:
anyOf:
- type: string
- type: 'null'
title: Current Device Id
created_at:
type: string
title: Created At
updated_at:
type: string
title: Updated At
type: object
required:
- id
- username
- email
- enabled
- role
- oauth_scopes
- avatar_path
- last_login
- last_active
- created_at
- updated_at
title: UserSchema
RAProgression:
properties:
total:
type: integer
title: Total
results:
items:
$ref: '#/components/schemas/RAUserGameProgression'
type: array
title: Results
type: object
title: RAProgression
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_user_api_users_post:
properties:
username:
type: string
title: Username
email:
type: string
title: Email
password:
type: string
title: Password
role:
type: string
title: Role
type: object
required:
- username
- email
- password
- role
title: Body_add_user_api_users_post
Body_refresh_retro_achievements_api_users__id__ra_refresh_post:
properties:
incremental:
type: boolean
title: Incremental
description: Whether to only retrieve RetroAchievements progression incrementally.
default: false
type: object
title: Body_refresh_retro_achievements_api_users__id__ra_refresh_post
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