# Copyright 2018 New Vector Ltd # Copyright 2020 The Matrix.org Foundation C.I.C. # # 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. openapi: 3.1.0 info: title: Matrix Federation Leave Room API version: 1.0.0 paths: "/make_leave/{roomId}/{userId}": get: summary: Get information required to make a leave event for a room description: |- Asks the receiving server to return information that the sending server will need to prepare a leave event to get out of the room. operationId: makeLeave security: - signedRequest: [] parameters: - in: path name: roomId description: The room ID that is about to be left. required: true example: "!abc123:matrix.org" schema: type: string - in: path name: userId description: The user ID the leave event will be for. required: true example: "@someone:example.org" schema: type: string responses: "200": description: |- A template to be used to call `/send_leave`. Note that events have a different format depending on the room version - check the [room version specification](/rooms) for precise event formats. **The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.** content: application/json: schema: type: object properties: room_version: type: string description: |- The version of the room where the server is trying to leave. If not provided, the room version is assumed to be either "1" or "2". example: "2" event: description: |- An unsigned template event. Note that events have a different format depending on the room version - check the [room version specification](/rooms) for precise event formats. type: object title: Event Template properties: sender: type: string description: The user ID of the leaving member. example: "@someone:example.org" origin: type: string description: The name of the resident homeserver. example: matrix.org origin_server_ts: type: integer format: int64 description: A timestamp added by the resident homeserver. example: 1234567890 type: type: string description: The value `m.room.member`. example: m.room.member state_key: type: string description: The user ID of the leaving member. example: "@someone:example.org" content: type: object title: Membership Event Content description: The content of the event. example: membership: leave properties: membership: type: string description: The value `leave`. example: leave required: - membership required: - state_key - sender - origin - origin_server_ts - type - content examples: response: value: { "room_version": "2", "event": { "room_id": "!somewhere:example.org", "type": "m.room.member", "state_key": "@someone:example.org", "origin": "example.org", "origin_server_ts": 1549041175876, "sender": "@someone:example.org", "content": { "membership": "leave" } } } "403": description: The request is not authorized. This could mean that the user is not in the room. content: application/json: schema: $ref: ../client-server/definitions/errors/error.yaml examples: response: value: { "errcode": "M_FORBIDDEN", "error": "User is not in the room." } "/send_leave/{roomId}/{eventId}": put: deprecated: true summary: Submit a signed leave event to a resident server description: |- **Note:** Servers should instead prefer to use the v2 `/send_leave` endpoint. Submits a signed leave event to the resident server for it to accept it into the room's graph. Note that events have a different format depending on the room version - check the [room version specification](/rooms) for precise event formats. **The request and response body here describe the common event fields in more detail and may be missing other required fields for a PDU.** operationId: sendLeaveV1 security: - signedRequest: [] parameters: - in: path name: roomId description: The room ID that is about to be left. required: true example: "!abc123:matrix.org" schema: type: string - in: path name: eventId description: The event ID for the leave event. required: true example: $abc123:example.org schema: type: string requestBody: content: application/json: schema: type: object properties: sender: type: string description: The user ID of the leaving member. example: "@someone:example.org" origin: type: string description: The name of the leaving homeserver. example: matrix.org origin_server_ts: type: integer format: int64 description: A timestamp added by the leaving homeserver. example: 1234567890 type: type: string description: The value `m.room.member`. example: m.room.member state_key: type: string description: The user ID of the leaving member. example: "@someone:example.org" content: type: object title: Membership Event Content description: The content of the event. example: membership: leave properties: membership: type: string description: The value `leave`. example: leave required: - membership depth: type: integer description: This field must be present but is ignored; it may be 0. example: 12 required: - state_key - sender - origin - origin_server_ts - type - depth - content required: true responses: "200": description: |- An empty response to indicate the event was accepted into the graph by the receiving homeserver. content: application/json: schema: type: array minItems: 2 maxItems: 2 items: anyOf: - type: integer description: The value `200`. example: 200 - type: object title: Empty Object description: An empty object. examples: response: value: [ 200, {} ] servers: - url: "{protocol}://{hostname}{basePath}" variables: protocol: enum: - http - https default: https hostname: default: localhost:8448 basePath: default: /_matrix/federation/v1 components: securitySchemes: $ref: definitions/security.yaml