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