# Copyright 2021 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 Knock Room API version: 1.0.0 paths: "/make_knock/{roomId}/{userId}": get: x-addedInMatrixVersion: "1.1" summary: Get information required to make a knock event for a room. description: |- Asks the receiving server to return information that the sending server will need to prepare a knock event for the room. operationId: makeKnock security: - signedRequest: [] parameters: - in: path name: roomId description: The room ID that is about to be knocked. required: true example: "!abc123:example.org" schema: type: string - in: path name: userId description: The user ID the knock event will be for. required: true example: "@someone:example.org" schema: type: string - in: query name: ver description: The room versions the sending server has support for. required: true # knocking was supported in v7 example: - "1" - "7" schema: type: array items: type: string responses: "200": description: |- A template to be used for the rest of the [Knocking Rooms](/server-server-api/#knocking-rooms) handshake. Note that events have a different format depending on 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 knock. example: "7" 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 knocking 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 knocking member. example: "@someone:example.org" content: type: object title: Membership Event Content description: The content of the event. example: membership: knock properties: membership: type: string description: The value `knock`. example: knock required: - membership required: - state_key - origin - origin_server_ts - type - content - sender required: - room_version # knocking was added in v7 - event examples: response: value: { "room_version": "7", "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": "knock" } } } "400": description: |- The request is invalid or the room the server is attempting to knock upon 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. content: application/json: 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: response: value: { "errcode": "M_INCOMPATIBLE_ROOM_VERSION", "error": "Your homeserver does not support the features required to knock on this room", "room_version": "7" } "403": description: |- The knocking server or user is not permitted to knock on the room, such as when the server/user is banned or the room is not set up for receiving knocks. content: application/json: schema: $ref: ../client-server/definitions/errors/error.yaml examples: response: value: { "errcode": "M_FORBIDDEN", "error": "You are not permitted to knock on this room" } "404": description: |- The room that the knocking server is attempting to knock upon is unknown to the receiving server. content: application/json: schema: $ref: ../client-server/definitions/errors/error.yaml examples: response: value: { "errcode": "M_NOT_FOUND", "error": "Unknown room" } "/send_knock/{roomId}/{eventId}": put: x-addedInMatrixVersion: "1.1" summary: Submit a signed knock event to a resident server. description: |- Submits a signed knock event to the resident server for it to accept 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: sendKnock security: - signedRequest: [] parameters: - in: path name: roomId description: The room ID that is about to be knocked upon. required: true example: "!abc123:example.org" schema: type: string - in: path name: eventId description: The event ID for the knock 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 knocking member. example: "@someone:example.org" origin: type: string description: The name of the knocking homeserver. example: matrix.org origin_server_ts: type: integer format: int64 description: A timestamp added by the knocking 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 knocking member. example: "@someone:example.org" content: type: object title: Membership Event Content description: The content of the event. example: membership: knock properties: membership: type: string description: The value `knock`. example: knock required: - membership required: - state_key - sender - origin - origin_server_ts - type - content example: { "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": "knock" } } required: true responses: "200": description: |- Information about the room to pass along to clients regarding the knock. content: application/json: schema: type: object properties: knock_room_state: type: array items: $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml description: |- A list of [stripped state events](/client-server-api/#stripped-state) to help the initiator of the knock identify the room. example: $ref: ../../event-schemas/examples/knock_room_state.json required: - knock_room_state examples: response: value: { "knock_room_state": { "$ref": "../../event-schemas/examples/knock_room_state.json" } } "403": description: |- The knocking server or user is not permitted to knock on the room, such as when the server/user is banned or the room is not set up for receiving knocks. content: application/json: schema: $ref: ../client-server/definitions/errors/error.yaml examples: response: value: { "errcode": "M_FORBIDDEN", "error": "You are not permitted to knock on this room" } "404": description: |- The room that the knocking server is attempting to knock upon is unknown to the receiving server. content: application/json: schema: $ref: ../client-server/definitions/errors/error.yaml examples: response: value: { "errcode": "M_NOT_FOUND", "error": "Unknown room" } servers: - url: "{protocol}://{hostname}{basePath}" variables: protocol: enum: - http - https default: https hostname: default: localhost:8448 basePath: default: /_matrix/federation/v1 components: securitySchemes: signedRequest: $ref: definitions/security.yaml#/signedRequest