Administrative REST API for managing the Synapse homeserver. Provides server administrators with endpoints for user management, room administration, media management, federation control, registration tokens, background updates, event reports, and server statistics.
openapi: 3.0.3
info:
title: Synapse Admin API
description: >-
Administrative REST API for the Synapse Matrix homeserver. Provides server
administrators with endpoints to manage users, rooms, media, federation,
registration tokens, background updates, event reports, and server statistics.
Authentication requires an access token belonging to a server admin account,
passed as a Bearer token. Admin API endpoints should be protected behind a
reverse proxy.
version: '1.0'
contact:
name: Element (Synapse maintainers)
url: https://github.com/element-hq/synapse
license:
name: AGPL-3.0
url: https://github.com/element-hq/synapse/blob/develop/LICENSE
servers:
- url: https://matrix.example.com/_synapse/admin
description: Synapse Admin API base URL
security:
- BearerAuth: []
tags:
- name: Users
description: User account management
- name: Rooms
description: Room administration and membership
- name: Media
description: Media file administration
- name: Registration
description: User registration and tokens
- name: Federation
description: Federation management
- name: Statistics
description: Server usage statistics
- name: Reports
description: Event and user reports
- name: Server
description: Server information and background updates
paths:
/v2/users:
get:
summary: List All Users
description: List all local users on the homeserver with optional filtering
operationId: listUsers
tags:
- Users
parameters:
- name: user_id
in: query
schema:
type: string
description: Filter by user ID (prefix match)
- name: name
in: query
schema:
type: string
description: Filter by display name or user ID
- name: guests
in: query
schema:
type: boolean
description: Include guest accounts
- name: deactivated
in: query
schema:
type: boolean
description: Include deactivated accounts
- name: limit
in: query
schema:
type: integer
default: 100
description: Maximum number of results to return
- name: from
in: query
schema:
type: integer
default: 0
description: Offset for pagination
responses:
'200':
description: List of users
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/v2/users/{userId}:
get:
summary: Get User Details
description: Get detailed information about a specific user
operationId: getUser
tags:
- Users
parameters:
- name: userId
in: path
required: true
schema:
type: string
description: The fully qualified Matrix user ID (e.g. @user:example.com)
responses:
'200':
description: User details
content:
application/json:
schema:
$ref: '#/components/schemas/UserDetail'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
put:
summary: Create or Modify User
description: Create a new user account or modify an existing user
operationId: upsertUser
tags:
- Users
parameters:
- name: userId
in: path
required: true
schema:
type: string
description: The fully qualified Matrix user ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserUpsert'
responses:
'200':
description: User updated
content:
application/json:
schema:
$ref: '#/components/schemas/UserDetail'
'201':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/UserDetail'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/v1/deactivate/{userId}:
post:
summary: Deactivate User Account
description: Deactivate a user account, optionally erasing their data
operationId: deactivateUser
tags:
- Users
parameters:
- name: userId
in: path
required: true
schema:
type: string
description: The fully qualified Matrix user ID
requestBody:
content:
application/json:
schema:
type: object
properties:
erase:
type: boolean
description: Whether to erase all user data
responses:
'200':
description: User deactivated
content:
application/json:
schema:
type: object
properties:
id_server_unbind_result:
type: string
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/v1/reset_password/{userId}:
post:
summary: Reset User Password
description: Reset the password for a local user
operationId: resetUserPassword
tags:
- Users
parameters:
- name: userId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- new_password
properties:
new_password:
type: string
description: New password for the user
logout_devices:
type: boolean
description: Whether to log out all devices
responses:
'200':
description: Password reset successfully
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/v1/users/{userId}/rooms:
get:
summary: List User Rooms
description: List all rooms that a user is a member of
operationId: listUserRooms
tags:
- Users
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: List of rooms the user is in
content:
application/json:
schema:
$ref: '#/components/schemas/RoomMembershipList'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/v1/rooms:
get:
summary: List All Rooms
description: List all rooms on the homeserver with optional filtering and sorting
operationId: listRooms
tags:
- Rooms
parameters:
- name: search_term
in: query
schema:
type: string
description: Filter rooms by room ID, name, or canonical alias
- name: order_by
in: query
schema:
type: string
enum: [alphabetical, size, joined_members, joined_local_members, version, creator, encryption, federatable, public, join_rules, guest_access, history_visibility, state_events]
description: Sort order for results
- name: dir
in: query
schema:
type: string
enum: [f, b]
description: Sort direction (forward/backward)
- name: limit
in: query
schema:
type: integer
default: 100
- name: from
in: query
schema:
type: integer
default: 0
responses:
'200':
description: List of rooms
content:
application/json:
schema:
$ref: '#/components/schemas/RoomList'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/v1/rooms/{roomId}:
get:
summary: Get Room Details
description: Get details about a specific room
operationId: getRoom
tags:
- Rooms
parameters:
- name: roomId
in: path
required: true
schema:
type: string
description: The room ID (e.g. !abc123:example.com)
responses:
'200':
description: Room details
content:
application/json:
schema:
$ref: '#/components/schemas/RoomDetail'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
delete:
summary: Delete Room
description: Delete a room and all its messages from the homeserver
operationId: deleteRoom
tags:
- Rooms
parameters:
- name: roomId
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
new_room_user_id:
type: string
description: User to create a shadow room for displaced members
room_name:
type: string
description: Name for the replacement room
message:
type: string
description: Message sent to users before deletion
block:
type: boolean
description: Block the room from being recreated
purge:
type: boolean
description: Purge all messages from the database
responses:
'200':
description: Room deletion initiated
content:
application/json:
schema:
type: object
properties:
delete_id:
type: string
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/v1/rooms/{roomId}/members:
get:
summary: Get Room Members
description: List all members of a room
operationId: getRoomMembers
tags:
- Rooms
parameters:
- name: roomId
in: path
required: true
schema:
type: string
responses:
'200':
description: Room member list
content:
application/json:
schema:
$ref: '#/components/schemas/RoomMemberList'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/v1/join/{roomIdOrAlias}:
post:
summary: Join User to Room
description: Force a local user to join a room
operationId: joinUserToRoom
tags:
- Rooms
parameters:
- name: roomIdOrAlias
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- user_id
properties:
user_id:
type: string
description: The Matrix user ID to join
responses:
'200':
description: User joined room
content:
application/json:
schema:
type: object
properties:
room_id:
type: string
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/v1/statistics/users/media:
get:
summary: Get User Media Statistics
description: Get statistics on media usage by users
operationId: getUserMediaStatistics
tags:
- Statistics
- Media
parameters:
- name: limit
in: query
schema:
type: integer
- name: from
in: query
schema:
type: integer
- name: order_by
in: query
schema:
type: string
responses:
'200':
description: Media statistics
content:
application/json:
schema:
type: object
properties:
users:
type: array
items:
type: object
next_token:
type: integer
total:
type: integer
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/v1/server_version:
get:
summary: Get Server Version
description: Get the current Synapse server version
operationId: getServerVersion
tags:
- Server
responses:
'200':
description: Server version information
content:
application/json:
schema:
type: object
properties:
server_version:
type: string
description: Synapse version string
python_version:
type: string
description: Python version in use
/v1/registration_tokens:
get:
summary: List Registration Tokens
description: List all registration tokens for controlled user registration
operationId: listRegistrationTokens
tags:
- Registration
parameters:
- name: valid
in: query
schema:
type: boolean
description: Filter by validity
responses:
'200':
description: List of registration tokens
content:
application/json:
schema:
type: object
properties:
registration_tokens:
type: array
items:
$ref: '#/components/schemas/RegistrationToken'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
post:
summary: Create Registration Token
description: Create a new registration token
operationId: createRegistrationToken
tags:
- Registration
requestBody:
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: Custom token string (auto-generated if omitted)
uses_allowed:
type: integer
description: Maximum number of uses (unlimited if null)
expiry_time:
type: integer
description: Token expiry time in milliseconds since epoch
responses:
'200':
description: Registration token created
content:
application/json:
schema:
$ref: '#/components/schemas/RegistrationToken'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/v1/event_reports:
get:
summary: List Event Reports
description: List events that users have reported
operationId: listEventReports
tags:
- Reports
parameters:
- name: limit
in: query
schema:
type: integer
- name: from
in: query
schema:
type: integer
- name: dir
in: query
schema:
type: string
enum: [f, b]
- name: room_id
in: query
schema:
type: string
- name: user_id
in: query
schema:
type: string
responses:
'200':
description: List of event reports
content:
application/json:
schema:
type: object
properties:
event_reports:
type: array
items:
type: object
next_token:
type: integer
total:
type: integer
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/v1/federation/destinations:
get:
summary: List Federation Destinations
description: List all remote homeservers that this server has federated with
operationId: listFederationDestinations
tags:
- Federation
parameters:
- name: limit
in: query
schema:
type: integer
- name: from
in: query
schema:
type: integer
- name: destination
in: query
schema:
type: string
responses:
'200':
description: List of federation destinations
content:
application/json:
schema:
type: object
properties:
destinations:
type: array
items:
type: object
next_token:
type: string
total:
type: integer
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/v1/background_updates/enabled:
get:
summary: Get Background Updates Status
description: Check whether background database updates are enabled
operationId: getBackgroundUpdatesEnabled
tags:
- Server
responses:
'200':
description: Background updates status
content:
application/json:
schema:
type: object
properties:
enabled:
type: boolean
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Admin access token obtained from the Synapse homeserver
responses:
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized - missing or invalid access token
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Forbidden - requires server admin access
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
properties:
errcode:
type: string
description: Matrix error code (e.g. M_FORBIDDEN, M_NOT_FOUND)
error:
type: string
description: Human-readable error description
UserList:
type: object
properties:
users:
type: array
items:
$ref: '#/components/schemas/UserSummary'
next_token:
type: integer
total:
type: integer
UserSummary:
type: object
properties:
name:
type: string
description: Matrix user ID
displayname:
type: string
avatar_url:
type: string
is_guest:
type: boolean
deactivated:
type: boolean
erased:
type: boolean
shadow_banned:
type: boolean
admin:
type: boolean
creation_ts:
type: integer
format: int64
UserDetail:
allOf:
- $ref: '#/components/schemas/UserSummary'
- type: object
properties:
threepids:
type: array
items:
type: object
properties:
medium:
type: string
address:
type: string
external_ids:
type: array
items:
type: object
user_type:
type: string
UserUpsert:
type: object
properties:
password:
type: string
displayname:
type: string
avatar_url:
type: string
admin:
type: boolean
deactivated:
type: boolean
user_type:
type: string
RoomMembershipList:
type: object
properties:
joined_rooms:
type: array
items:
type: string
total:
type: integer
RoomList:
type: object
properties:
rooms:
type: array
items:
$ref: '#/components/schemas/RoomSummary'
offset:
type: integer
next_batch:
type: integer
prev_batch:
type: integer
total_rooms:
type: integer
RoomSummary:
type: object
properties:
room_id:
type: string
name:
type: string
canonical_alias:
type: string
joined_members:
type: integer
joined_local_members:
type: integer
version:
type: string
creator:
type: string
encryption:
type: string
nullable: true
federatable:
type: boolean
public:
type: boolean
join_rules:
type: string
guest_access:
type: string
nullable: true
history_visibility:
type: string
state_events:
type: integer
RoomDetail:
allOf:
- $ref: '#/components/schemas/RoomSummary'
- type: object
properties:
room_type:
type: string
nullable: true
forgotten:
type: boolean
RoomMemberList:
type: object
properties:
members:
type: array
items:
type: string
total:
type: integer
RegistrationToken:
type: object
properties:
token:
type: string
uses_allowed:
type: integer
nullable: true
pending:
type: integer
completed:
type: integer
expiry_time:
type: integer
nullable: true