matrix-spec/data/api/client-server/joining.yaml

# 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.
openapi: 3.1.0
info:
  title: Matrix Client-Server Room Inviting API
  version: 1.0.0
paths:
  "/rooms/{roomId}/join":
    post:
      summary: Start the requesting user participating in a particular room.
      description: |-
        *Note that this API requires a room ID, not alias.*
        `/join/{roomIdOrAlias}` *exists if you have a room alias.*

        This API starts a user participating in a particular room, if that user
        is allowed to participate in that room. After this call, the client is
        allowed to see all current state events in the room, and all subsequent
        events associated with the room until the user leaves the room.

        After a user has joined a room, the room will appear as an entry in the
        response of the [`/initialSync`](/client-server-api/#get_matrixclientv3initialsync)
        and [`/sync`](/client-server-api/#get_matrixclientv3sync) APIs.
      operationId: joinRoomById
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: path
          name: roomId
          description: The room identifier (not alias) to join.
          required: true
          example: "!d41d8cd:matrix.org"
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                third_party_signed:
                  allOf:
                    - $ref: definitions/third_party_signed.yaml
                  description: |-
                    If supplied, the homeserver must verify that it matches a pending
                    `m.room.third_party_invite` event in the room, and perform
                    key validity checking if required by the event.
                reason:
                  x-addedInMatrixVersion: "1.1"
                  type: string
                  description: |-
                    Optional reason to be included as the `reason` on the subsequent
                    membership event.
                  example: Looking for support
        required: true
      responses:
        "200":
          description: |-
            The room has been joined.

            The joined room ID must be returned in the `room_id` field.
          content:
            application/json:
              schema:
                type: object
                properties:
                  room_id:
                    type: string
                    description: The joined room ID.
                required:
                  - room_id
              examples:
                response:
                  value: {
                    "room_id": "!d41d8cd:matrix.org"
                  }
        "403":
          description: |-
            You do not have permission to join the room. A meaningful `errcode`
            and description error text will be returned. Example reasons for rejection are:

            - The room is invite-only and the user was not invited.
            - The user has been banned from the room.
            - The room is restricted and the user failed to satisfy any of the conditions.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_FORBIDDEN",
                    "error": "You are not invited to this room."
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - Room membership
  "/join/{roomIdOrAlias}":
    post:
      summary: Start the requesting user participating in a particular room.
      description: |-
        *Note that this API takes either a room ID or alias, unlike* `/rooms/{roomId}/join`.

        This API starts a user participating in a particular room, if that user
        is allowed to participate in that room. After this call, the client is
        allowed to see all current state events in the room, and all subsequent
        events associated with the room until the user leaves the room.

        After a user has joined a room, the room will appear as an entry in the
        response of the [`/initialSync`](/client-server-api/#get_matrixclientv3initialsync)
        and [`/sync`](/client-server-api/#get_matrixclientv3sync) APIs.
      operationId: joinRoom
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: path
          name: roomIdOrAlias
          description: The room identifier or alias to join.
          required: true
          example: "#monkeys:matrix.org"
          schema:
            type: string
        - in: query
          name: server_name
          description: |-
            The servers to attempt to join the room through. One of the servers
            must be participating in the room.
          example:
            - matrix.org
            - elsewhere.ca
          schema:
            type: array
            items:
              type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                third_party_signed:
                  allOf:
                    - $ref: definitions/third_party_signed.yaml
                  description: |-
                    If a `third_party_signed` was supplied, the homeserver must verify
                    that it matches a pending `m.room.third_party_invite` event in the
                    room, and perform key validity checking if required by the event.
                reason:
                  x-addedInMatrixVersion: "1.1"
                  type: string
                  description: |-
                    Optional reason to be included as the `reason` on the subsequent
                    membership event.
                  example: Looking for support
        required: true
      responses:
        "200":
          description: |-
            The room has been joined.

            The joined room ID must be returned in the `room_id` field.
          content:
            application/json:
              schema:
                type: object
                properties:
                  room_id:
                    type: string
                    description: The joined room ID.
                required:
                  - room_id
              examples:
                response:
                  value: {
                    "room_id": "!d41d8cd:matrix.org"
                  }
        "403":
          description: |-
            You do not have permission to join the room. A meaningful `errcode`
            and description error text will be returned. Example reasons for rejection are:

            - The room is invite-only and the user was not invited.
            - The user has been banned from the room.
            - The room is restricted and the user failed to satisfy any of the conditions.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_FORBIDDEN",
                    "error": "You are not invited to this room."
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - Room membership
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8008
      basePath:
        default: /_matrix/client/v3
components:
  securitySchemes:
    accessTokenQuery:
      $ref: definitions/security.yaml#/accessTokenQuery
    accessTokenBearer:
      $ref: definitions/security.yaml#/accessTokenBearer