# Copyright 2016 OpenMarket Ltd # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. swagger: '2.0' info: title: "Matrix Client-Server Room Kicking API" version: "1.0.0" host: localhost:8008 schemes: - https - http basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: - application/json securityDefinitions: $ref: definitions/security.yaml paths: "/rooms/{roomId}/kick": post: summary: Kick a user from the room. description: |- Kick a user from the room. The caller must have the required power level in order to perform this operation. Kicking a user adjusts the target member's membership state to be ``leave`` with an optional ``reason``. Like with other membership changes, a user can directly adjust the target member's state by making a request to ``/rooms//state/m.room.member/``. operationId: kick security: - accessToken: [] parameters: - in: path type: string name: roomId description: The room identifier (not alias) from which the user should be kicked. 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 kicked. reason: type: string description: |- The reason the user has been kicked. This will be supplied as the ``reason`` on the target's updated `m.room.member`_ event. required: ["user_id"] responses: 200: description: The user has been kicked from the room. examples: application/json: { } schema: type: object 403: description: |- You do not have permission to kick the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are: - The kicker is not currently in the room. - The kickee is not currently in the room. - The kicker's power level is insufficient to kick users from the room. examples: application/json: { "errcode": "M_FORBIDDEN", "error": "You do not have a high enough power level to kick from this room." } schema: "$ref": "definitions/errors/error.yaml" tags: - Room membership