add links to endpoints and add delete endpoint

api/client-server/key_backup.yaml

@@ -230,6 +230,43 @@ paths:
             "$ref": "definitions/errors/error.yaml"
       tags:
         - End-to-end encryption
+    delete:
+      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:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: version
+          description: |-
+            The backup version to delete, as returned in the ``version``
+            parameter in the response of `POST
+            /_matrix/client/r0/room_keys/version`_ or `GET
+            /_matrix/client/r0/room_keys/version/{version}`_. Unlike with the
+            ``GET`` version of this endpoint, this may not be empty.
+          required: true
+          x-example: "1"
+      responses:
+        200:
+          description: The delete succeeded.
+          schema:
+            type: object
+            properties: {}
+        404:
+          description: The backup specified does not exist.
+          examples:
+            application/json: {
+                "errcode": "M_NOT_FOUND",
+                "error": "Unknown backup version"
+              }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+      tags:
+        - End-to-end encryption
   "/room_keys/keys/{roomId}/{sessionId}":
     put:
       summary: Store a key in the backup.

specification/modules/end_to_end_encryption.rst

@@ -780,15 +780,18 @@ device to be online from which to request keys. However, as the session keys are
 stored on the server encrypted, it requires users to enter a decryption key to
 decrypt the session keys.
 
-To create a backup, a client will call ``POST /room_keys/version`` and define
+To create a backup, a client will call `POST
-how the keys are to be encrypted through the backup's ``auth_data``; other
+/_matrix/client/r0/room_keys/version`_ and define how the keys are to be
-clients can discover the backup by calling ``GET /room_keys/version``.  Keys
+encrypted through the backup's ``auth_data``; other clients can discover the
-are encrypted according to the backups ``auth_data`` and added to the backup by
+backup by calling `GET /_matrix/client/r0/room_keys/version/{version}`_,
-calling ``PUT /room_keys/keys?version=$v`` or one of its variants, and can be
+setting ``{version}`` to the empty string.  Keys are encrypted according to the
-retrieved by calling ``GET /room_keys/keys?version=$v`` or one of its variants.
+backups ``auth_data`` and added to the backup by calling `PUT
-Keys can only be written to the most recently created version of the backup.
+/_matrix/client/r0/room_keys/keys`_ or one of its variants, and can be
-Backups can also be deleted using ``DELETE /room_keys/version``, or individual
+retrieved by calling `GET /_matrix/client/r0/room_keys/keys`_ or one of its
-keys can be deleted using ``DELETE /room_key/keys?version=$v`` or one of its
+variants.  Keys can only be written to the most recently created version of the
+backup.  Backups can also be deleted using `DELETE
+/_matrix/client/r0/room_keys/version/{version}`_, or individual keys can be
+deleted using `DELETE /_matrix/client/r0/room_keys/keys`_ or one of its
 variants.
 
 Clients must only store keys in backups after they have ensured that the