async-matrix 0.1.3 → 1.0.0

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

@@ -0,0 +1,993 @@
+# Copyright 2019-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 Client-Server Key Backup API
+  version: 1.0.0
+paths:
+  /room_keys/version:
+    post:
+      x-addedInMatrixVersion: "1.1"
+      summary: Create a new backup.
+      description: Creates a new backup.
+      operationId: postRoomKeysVersion
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                algorithm:
+                  description: The algorithm used for storing backups.
+                  type: string
+                  enum:
+                    - m.megolm_backup.v1.curve25519-aes-sha2
+                  example: m.megolm_backup.v1.curve25519-aes-sha2
+                auth_data:
+                  description: |-
+                    Algorithm-dependent data. See the documentation for the backup
+                    algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
+                    expected format of the data.
+                  type: object
+                  example:
+                    public_key: abcdefg
+                    signatures:
+                      "@alice:example.org":
+                        ed25519:deviceid: signature
+              required:
+                - algorithm
+                - auth_data
+        description: The backup configuration.
+        required: true
+      responses:
+        "200":
+          description: The version id of the new backup.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  version:
+                    type: string
+                    description: The backup version. This is an opaque string.
+                    example: "1"
+                required:
+                  - version
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - End-to-end encryption
+    get:
+      x-addedInMatrixVersion: "1.1"
+      summary: Get information about the latest backup version.
+      description: Get information about the latest backup version.
+      operationId: getRoomKeysVersionCurrent
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      responses:
+        "200":
+          description: The information about the backup.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  algorithm:
+                    type: string
+                    description: The algorithm used for storing backups.
+                    enum:
+                      - m.megolm_backup.v1.curve25519-aes-sha2
+                    example: m.megolm_backup.v1.curve25519-aes-sha2
+                  auth_data:
+                    description: |-
+                      Algorithm-dependent data. See the documentation for the backup
+                      algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
+                      expected format of the data.
+                    type: object
+                    example:
+                      public_key: abcdefg
+                      signatures:
+                        "@alice:example.org":
+                          ed25519:deviceid: signature
+                  count:
+                    description: The number of keys stored in the backup.
+                    type: integer
+                    example: 42
+                  etag:
+                    description: |-
+                      An opaque string representing stored keys in the backup.
+                      Clients can compare it with the `etag` value they received
+                      in the request of their last key storage request.  If not
+                      equal, another client has modified the backup.
+                    type: string
+                    example: anopaquestring
+                  version:
+                    type: string
+                    description: The backup version.
+                    example: "1"
+                required:
+                  - algorithm
+                  - auth_data
+                  - count
+                  - etag
+                  - version
+        "404":
+          description: No backup exists.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "No current backup version"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - End-to-end encryption
+  "/room_keys/version/{version}":
+    get:
+      x-addedInMatrixVersion: "1.1"
+      summary: Get information about an existing backup.
+      description: Get information about an existing backup.
+      operationId: getRoomKeysVersion
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: version
+          description: |-
+            The backup version to get, as returned in the `version` parameter
+            of the response in
+            [`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion)
+            or this endpoint.
+          required: true
+          example: "1"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The information about the requested backup.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  algorithm:
+                    type: string
+                    description: The algorithm used for storing backups.
+                    enum:
+                      - m.megolm_backup.v1.curve25519-aes-sha2
+                    example: m.megolm_backup.v1.curve25519-aes-sha2
+                  auth_data:
+                    description: |-
+                      Algorithm-dependent data. See the documentation for the backup
+                      algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
+                      expected format of the data.
+                    type: object
+                    example:
+                      public_key: abcdefg
+                      signatures:
+                        "@alice:example.org":
+                          ed25519:deviceid: signature
+                  count:
+                    description: The number of keys stored in the backup.
+                    type: integer
+                    example: 42
+                  etag:
+                    description: |-
+                      An opaque string representing stored keys in the backup.
+                      Clients can compare it with the `etag` value they received
+                      in the request of their last key storage request.  If not
+                      equal, another client has modified the backup.
+                    type: string
+                    example: anopaquestring
+                  version:
+                    type: string
+                    description: The backup version.
+                    example: "1"
+                required:
+                  - algorithm
+                  - auth_data
+                  - count
+                  - etag
+                  - version
+        "404":
+          description: The backup specified does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Unknown backup version"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - End-to-end encryption
+    put:
+      x-addedInMatrixVersion: "1.1"
+      summary: Update information about an existing backup.
+      description: Update information about an existing backup.  Only `auth_data` can
+        be modified.
+      operationId: putRoomKeysVersion
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: version
+          description: |-
+            The backup version to update, as returned in the `version`
+            parameter in the response of
+            [`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion)
+            or [`GET /_matrix/client/v3/room_keys/version/{version}`](/client-server-api/#get_matrixclientv3room_keysversionversion).
+          required: true
+          example: "1"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                algorithm:
+                  description: |-
+                    The algorithm used for storing backups.  Must be the same as
+                    the algorithm currently used by the backup.
+                  type: string
+                  enum:
+                    - m.megolm_backup.v1.curve25519-aes-sha2
+                  example: m.megolm_backup.v1.curve25519-aes-sha2
+                auth_data:
+                  description: |-
+                    Algorithm-dependent data. See the documentation for the backup
+                    algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
+                    expected format of the data.
+                  type: object
+                  example:
+                    public_key: abcdefg
+                    signatures:
+                      "@alice:example.org":
+                        ed25519:deviceid: signature
+                version:
+                  description: |-
+                    The backup version.  If present, must be the same as the
+                    version in the path parameter.
+                  type: string
+                  example: "1"
+              required:
+                - algorithm
+                - auth_data
+        description: The backup configuration
+        required: true
+      responses:
+        "200":
+          description: The update succeeded.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "400":
+          description: |-
+            A parameter was incorrect.  For example, the `algorithm` does not
+            match the current backup algorithm, or the `version` in the body
+            does not match the `version` in the path.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Algorithm does not match"
+                  }
+        "404":
+          description: The backup specified does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Unknown backup version"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - End-to-end encryption
+    delete:
+      x-addedInMatrixVersion: "1.1"
+      summary: Delete an existing key backup.
+      description: |-
+        Delete an existing key backup. Both the information about the backup,
+        as well as all key data related to the backup will be deleted.
+      operationId: deleteRoomKeysVersion
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: version
+          description: |-
+            The backup version to delete, as returned in the `version`
+            parameter in the response of
+            [`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion)
+            or [`GET /_matrix/client/v3/room_keys/version/{version}`](/client-server-api/#get_matrixclientv3room_keysversionversion).
+          required: true
+          example: "1"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: |-
+            The delete succeeded, or the specified backup was previously
+            deleted.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties: {}
+        "404":
+          description: |-
+            The backup specified does not exist. If the backup was previously
+            deleted, the call should succeed rather than returning an error.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Unknown backup version"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - End-to-end encryption
+  "/room_keys/keys/{roomId}/{sessionId}":
+    put:
+      x-addedInMatrixVersion: "1.1"
+      summary: Store a key in the backup.
+      description: Store a key in the backup.
+      operationId: putRoomKeyBySessionId
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: version
+          description: The backup in which to store the key. Must be the current backup.
+          required: true
+          example: "1"
+          schema:
+            type: string
+        - in: path
+          name: roomId
+          description: The ID of the room that the key is for.
+          required: true
+          example: "!roomid:example.org"
+          schema:
+            type: string
+        - in: path
+          name: sessionId
+          description: The ID of the megolm session that the key is for.
+          required: true
+          example: sessionid
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: definitions/key_backup_data.yaml
+        description: The key data.
+        required: true
+      responses:
+        "200":
+          description: The update succeeded.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
+        "403":
+          description: |-
+            The version specified does not match the current backup version.
+            The current version will be included in the `current_version`
+            field.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_WRONG_ROOM_KEYS_VERSION",
+                    "error": "Wrong backup version.",
+                    "current_version": "42"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - End-to-end encryption
+    get:
+      x-addedInMatrixVersion: "1.1"
+      summary: Retrieve a key from the backup.
+      description: Retrieve a key from the backup.
+      operationId: getRoomKeyBySessionId
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: version
+          description: The backup from which to retrieve the key.
+          required: true
+          example: "1"
+          schema:
+            type: string
+        - in: path
+          name: roomId
+          description: The ID of the room that the requested key is for.
+          required: true
+          example: "!roomid:example.org"
+          schema:
+            type: string
+        - in: path
+          name: sessionId
+          description: The ID of the megolm session whose key is requested.
+          required: true
+          example: sessionid
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The key data
+          content:
+            application/json:
+              schema:
+                $ref: definitions/key_backup_data.yaml
+        "404":
+          description: The key or backup was not found.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Key not found."
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - End-to-end encryption
+    delete:
+      x-addedInMatrixVersion: "1.1"
+      summary: Delete a key from the backup.
+      description: Delete a key from the backup.
+      operationId: deleteRoomKeyBySessionId
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: version
+          description: The backup from which to delete the key
+          required: true
+          example: "1"
+          schema:
+            type: string
+        - in: path
+          name: roomId
+          description: The ID of the room that the specified key is for.
+          required: true
+          example: "!roomid:example.org"
+          schema:
+            type: string
+        - in: path
+          name: sessionId
+          description: The ID of the megolm session whose key is to be deleted.
+          required: true
+          example: sessionid
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The update succeeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
+        "404":
+          description: The backup was not found.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Unknown backup version"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - End-to-end encryption
+  "/room_keys/keys/{roomId}":
+    put:
+      x-addedInMatrixVersion: "1.1"
+      summary: Store several keys in the backup for a given room.
+      description: Store several keys in the backup for a given room.
+      operationId: putRoomKeysByRoomId
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: version
+          description: The backup in which to store the keys. Must be the current backup.
+          required: true
+          example: "1"
+          schema:
+            type: string
+        - in: path
+          name: roomId
+          description: The ID of the room that the keys are for.
+          required: true
+          example: "!roomid:example.org"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: definitions/room_key_backup.yaml
+        description: The backup data
+        required: true
+      responses:
+        "200":
+          description: The update succeeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
+        "403":
+          description: |-
+            The version specified does not match the current backup version.
+            The current version will be included in the `current_version`
+            field.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_WRONG_ROOM_KEYS_VERSION",
+                    "error": "Wrong backup version.",
+                    "current_version": "42"
+                  }
+        "404":
+          description: The backup was not found.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Unknown backup version"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - End-to-end encryption
+    get:
+      x-addedInMatrixVersion: "1.1"
+      summary: Retrieve the keys from the backup for a given room.
+      description: Retrieve the keys from the backup for a given room.
+      operationId: getRoomKeysByRoomId
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: version
+          description: The backup from which to retrieve the key.
+          required: true
+          example: "1"
+          schema:
+            type: string
+        - in: path
+          name: roomId
+          description: The ID of the room that the requested key is for.
+          required: true
+          example: "!roomid:example.org"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: |-
+            The key data.  If no keys are found, then an object with an empty
+            `sessions` property will be returned (`{"sessions": {}}`).
+          content:
+            application/json:
+              schema:
+                type: object
+                $ref: definitions/room_key_backup.yaml
+        "404":
+          description: The backup was not found.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Unknown backup version"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - End-to-end encryption
+    delete:
+      x-addedInMatrixVersion: "1.1"
+      summary: Delete the keys from the backup for a given room.
+      description: Delete the keys from the backup for a given room.
+      operationId: deleteRoomKeysByRoomId
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: version
+          description: The backup from which to delete the key.
+          required: true
+          example: "1"
+          schema:
+            type: string
+        - in: path
+          name: roomId
+          description: The ID of the room that the specified key is for.
+          required: true
+          example: "!roomid:example.org"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The update succeeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
+        "404":
+          description: The backup was not found.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Unknown backup version"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - End-to-end encryption
+  /room_keys/keys:
+    put:
+      x-addedInMatrixVersion: "1.1"
+      summary: Store several keys in the backup.
+      description: Store several keys in the backup.
+      operationId: putRoomKeys
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: version
+          description: The backup in which to store the keys. Must be the current backup.
+          required: true
+          example: "1"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                rooms:
+                  type: object
+                  description: A map of room IDs to room key backup data.
+                  patternProperties:
+                    "^!":
+                      x-pattern-format: mx-room-id
+                      allOf:
+                        - $ref: definitions/room_key_backup.yaml
+                  example:
+                    "!room:example.org":
+                      sessions:
+                        sessionid1:
+                          first_message_index: 1
+                          forwarded_count: 0
+                          is_verified: true
+                          session_data:
+                            ephemeral: base64+ephemeral+key
+                            ciphertext: base64+ciphertext+of+JSON+data
+                            mac: base64+mac+of+ciphertext
+              required:
+                - rooms
+        description: The backup data.
+        required: true
+      responses:
+        "200":
+          description: The update succeeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
+        "403":
+          description: |-
+            The version specified does not match the current backup version.
+            The current version will be included in the `current_version`
+            field.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_WRONG_ROOM_KEYS_VERSION",
+                    "error": "Wrong backup version.",
+                    "current_version": "42"
+                  }
+        "404":
+          description: The backup was not found.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Unknown backup version"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - End-to-end encryption
+    get:
+      x-addedInMatrixVersion: "1.1"
+      summary: Retrieve the keys from the backup.
+      description: Retrieve the keys from the backup.
+      operationId: getRoomKeys
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: version
+          description: The backup from which to retrieve the keys.
+          required: true
+          example: "1"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: |-
+            The key data.  If no keys are found, then an object with an empty
+            `rooms` property will be returned (`{"rooms": {}}`).
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  rooms:
+                    type: object
+                    description: A map of room IDs to room key backup data.
+                    patternProperties:
+                      "^!":
+                        x-pattern-format: mx-room-id
+                        allOf:
+                          - $ref: definitions/room_key_backup.yaml
+                    example:
+                      "!room:example.org":
+                        sessions:
+                          sessionid1:
+                            first_message_index: 1
+                            forwarded_count: 0
+                            is_verified: true
+                            session_data:
+                              ephemeral: base64+ephemeral+key
+                              ciphertext: base64+ciphertext+of+JSON+data
+                              mac: base64+mac+of+ciphertext
+                required:
+                  - rooms
+        "404":
+          description: The backup was not found.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Unknown backup version."
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - End-to-end encryption
+    delete:
+      x-addedInMatrixVersion: "1.1"
+      summary: Delete the keys from the backup.
+      description: Delete the keys from the backup.
+      operationId: deleteRoomKeys
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: version
+          description: The backup from which to delete the key
+          required: true
+          example: "1"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The update succeeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
+        "404":
+          description: The backup was not found.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Unknown backup version"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - End-to-end encryption
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  schemas:
+    RoomKeysUpdateResponse:
+      type: object
+      title: RoomKeysUpdateResponse
+      properties:
+        etag:
+          description: |-
+            The new etag value representing stored keys in the backup.
+            
+            See [`GET /room_keys/version/{version}`](client-server-api/#get_matrixclientv3room_keysversionversion)
+            for more details.
+          type: string
+          example: abcdefg
+        count:
+          description: The number of keys stored in the backup
+          type: integer
+          example: 10
+      required:
+        - etag
+        - count
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer