# 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. swagger: '2.0' info: title: "Matrix Federation Join Room API" version: "1.0.0" host: localhost:8448 schemes: - https basePath: /_matrix/federation/v1 consumes: - application/json produces: - application/json securityDefinitions: $ref: definitions/security.yaml paths: "/make_join/{roomId}/{userId}": get: summary: Get information required to make a join event for a room description: |- Asks the receiving server to return information that the sending server will need to prepare a join event to get into the room. operationId: makeJoin security: - signedRequest: [] parameters: - in: path name: roomId type: string description: The room ID that is about to be joined. required: true x-example: "!abc123:matrix.org" - in: path name: userId type: string description: The user ID the join event will be for. required: true x-example: "@someone:example.org" - in: query type: array items: type: string name: ver description: |- The room versions the sending server has support for. Defaults to ``[1]``. x-example: ["1", "2"] responses: 200: description: |- A template to be used for the rest of the `Joining Rooms`_ handshake. Note that events have a different format depending on the room version - check the `room version specification`_ 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.** schema: type: object properties: room_version: type: string description: |- The version of the room where the server is trying to join. 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`_ for precise event formats. type: object title: Event Template properties: sender: type: string description: The user ID of the joining 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 joining member. example: "@someone:example.org" content: type: object title: Membership Event Content description: The content of the event. example: {"membership": "join"} properties: membership: type: string description: The value ``join``. example: "join" required: ['membership'] required: - state_key - origin - origin_server_ts - type - content - sender examples: application/json: { "room_version": "2", "event": { "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@someone:example.org", "origin": "example.org", "origin_server_ts": 1549041175876, "sender": "@someone:example.org", "content": { "membership": "join" } } } 400: description: |- The request is invalid or the room the server is attempting to join has a version that is not listed in the ``ver`` parameters. The error should be passed through to clients so that they may give better feedback to users. schema: allOf: - $ref: "../client-server/definitions/errors/error.yaml" - type: object properties: room_version: type: string description: |- The version of the room. Required if the ``errcode`` is ``M_INCOMPATIBLE_ROOM_VERSION``. examples: application/json: { "errcode": "M_INCOMPATIBLE_ROOM_VERSION", "error": "Your homeserver does not support the features required to join this room", "room_version": "3" } "/send_join/{roomId}/{eventId}": put: summary: Submit a signed join event to a resident server description: |- .. Note:: Servers should instead prefer to use the v2 ``/send_join`` endpoint. Submits a signed join 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`_ 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: sendJoinV1 security: - signedRequest: [] parameters: - in: path name: roomId type: string description: The room ID that is about to be joined. required: true x-example: "!abc123:matrix.org" - in: path name: eventId type: string description: The event ID for the join event. required: true x-example: "$abc123:example.org" - in: body name: body type: object required: true schema: type: object properties: sender: type: string description: The user ID of the joining member. example: "@someone:example.org" origin: type: string description: The name of the joining homeserver. example: "matrix.org" origin_server_ts: type: integer format: int64 description: A timestamp added by the joining 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 joining member. example: "@someone:example.org" content: type: object title: Membership Event Content description: The content of the event. example: {"membership": "join"} properties: membership: type: string description: The value ``join``. example: "join" required: ['membership'] required: - state_key - sender - origin - origin_server_ts - type - content example: { "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@someone:example.org", "origin": "example.org", "origin_server_ts": 1549041175876, "sender": "@someone:example.org", "content": { "membership": "join" } } responses: 200: description: |- The full state for the room, having accepted the join event. schema: type: array minItems: 2 maxItems: 2 items: - type: integer description: The value ``200``. example: 200 - type: object title: Room State description: The state for the room. properties: origin: type: string description: The resident server's DNS name. auth_chain: type: array description: |- The auth chain. Note that events have a different format depending on the room version - check the `room version specification`_ for precise event formats. items: type: object title: PDU description: |- The `PDUs <#pdus>`_ that make up the auth chain. The event format varies depending on the room version - check the `room version specification`_ for precise event formats. schema: type: object properties: [] example: $ref: "examples/minimal_pdu.json" state: type: array description: |- The room state. The event format varies depending on the room version - check the `room version specification`_ for precise event formats. items: type: object title: PDU description: |- The `PDUs <#pdus>`_ for the fully resolved state of the room. The event format varies depending on the room version - check the `room version specification`_ for precise event formats. schema: type: object properties: [] example: $ref: "examples/minimal_pdu.json" required: ["auth_chain", "state", "origin"] examples: application/json: [ 200, { "origin": "matrix.org", "auth_chain": [{"$ref": "examples/minimal_pdu.json"}], "state": [{"$ref": "examples/minimal_pdu.json"}] } ]