matrix-spec/api/client-server/banning.yaml

swagger: '2.0'
info:
  title: "Matrix Client-Server Room Banning API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  accessToken:
    type: apiKey
    description: The user_id or application service access_token
    name: access_token
    in: query
paths:
  "/rooms/{roomId}/ban":
    post:
      summary: Ban a user in the room.
      description: |-
        Ban a user in the room. If the user is currently in the room, also kick them.

        When a user is banned from a room, they may not join it until they are unbanned.

        The caller must have the required power level in order to perform this operation.
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: roomId
          description: The room identifier (not alias) from which the user should be banned.
          required: true
          x-example: "!e42d8c:matrix.org"
        - in: body
          name: body
          required: true
          schema:
            type: object
            example: |-
              {
                "reason": "Telling unfunny jokes",
                "user_id": "@cheeky_monkey:matrix.org"
              }
            properties:
              user_id:
                type: string
                description: The fully qualified user ID of the user being banned.
              reason:
                type: string
                description: The reason the user has been banned.
            required: ["user_id"]
      responses:
        200:
          description: The user has been kicked and banned from the room.
          examples:
            application/json: |-
              {}
          schema:
            type: object
        403:
          description: |-
            You do not have permission to ban the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:

            - The banner is not currently in the room.
            - The banner's power level is insufficient to ban users from the room.
          examples:
            application/json: |-
              {
                "errcode": "M_FORBIDDEN",
                "error": "You do not have a high enough power level to ban from this room."
              }