diff --git a/docs/admin_api/purge_history_api.md b/docs/admin_api/purge_history_api.md
index bd29e29ab8..277e28d9cb 100644
--- a/docs/admin_api/purge_history_api.md
+++ b/docs/admin_api/purge_history_api.md
@@ -70,6 +70,8 @@ This API returns a JSON body like the following:
The status will be one of `active`, `complete`, or `failed`.
+If `status` is `failed` there will be a string `error` with the error message.
+
## Reclaim disk space (Postgres)
To reclaim the disk space and return it to the operating system, you need to run
diff --git a/docs/admin_api/rooms.md b/docs/admin_api/rooms.md
index 41a4961d00..6a6ae92d66 100644
--- a/docs/admin_api/rooms.md
+++ b/docs/admin_api/rooms.md
@@ -4,6 +4,9 @@
- [Room Members API](#room-members-api)
- [Room State API](#room-state-api)
- [Delete Room API](#delete-room-api)
+ * [Version 1 (old version)](#version-1-old-version)
+ * [Version 2 (new version)](#version-2-new-version)
+ * [Status of deleting rooms](#status-of-deleting-rooms)
* [Undoing room shutdowns](#undoing-room-shutdowns)
- [Make Room Admin API](#make-room-admin-api)
- [Forward Extremities Admin API](#forward-extremities-admin-api)
@@ -397,10 +400,10 @@ as room administrator and will contain a message explaining what happened. Users
to the new room will have power level `-10` by default, and thus be unable to speak.
If `block` is `true`, users will be prevented from joining the old room.
-This option can also be used to pre-emptively block a room, even if it's unknown
-to this homeserver. In this case, the room will be blocked, and no further action
-will be taken. If `block` is `false`, attempting to delete an unknown room is
-invalid and will be rejected as a bad request.
+This option can in [Version 1](#version-1-old-version) also be used to pre-emptively
+block a room, even if it's unknown to this homeserver. In this case, the room will be
+blocked, and no further action will be taken. If `block` is `false`, attempting to
+delete an unknown room is invalid and will be rejected as a bad request.
This API will remove all trace of the old room from your database after removing
all local users. If `purge` is `true` (the default), all traces of the old room will
@@ -412,6 +415,17 @@ several minutes or longer.
The local server will only have the power to move local user and room aliases to
the new room. Users on other servers will be unaffected.
+To use it, you will need to authenticate by providing an ``access_token`` for a
+server admin: see [Admin API](../usage/administration/admin_api).
+
+## Version 1 (old version)
+
+This version works synchronously. That means you only get the response once the server has
+finished the action, which may take a long time. If you request the same action
+a second time, and the server has not finished the first one, the second request will block.
+This is fixed in version 2 of this API. The parameters are the same in both APIs.
+This API will become deprecated in the future.
+
The API is:
```
@@ -430,9 +444,6 @@ with a body of:
}
```
-To use it, you will need to authenticate by providing an ``access_token`` for a
-server admin: see [Admin API](../usage/administration/admin_api).
-
A response body like the following is returned:
```json
@@ -449,6 +460,44 @@ A response body like the following is returned:
}
```
+The parameters and response values have the same format as
+[version 2](#version-2-new-version) of the API.
+
+## Version 2 (new version)
+
+**Note**: This API is new, experimental and "subject to change".
+
+This version works asynchronously, meaning you get the response from server immediately
+while the server works on that task in background. You can then request the status of the action
+to check if it has completed.
+
+The API is:
+
+```
+DELETE /_synapse/admin/v2/rooms/<room_id>
+```
+
+with a body of:
+
+```json
+{
+ "new_room_user_id": "@someuser:example.com",
+ "room_name": "Content Violation Notification",
+ "message": "Bad Room has been shutdown due to content violations on this server. Please review our Terms of Service.",
+ "block": true,
+ "purge": true
+}
+```
+
+The API starts the shut down and purge running, and returns immediately with a JSON body with
+a purge id:
+
+```json
+{
+ "delete_id": "<opaque id>"
+}
+```
+
**Parameters**
The following parameters should be set in the URL:
@@ -470,7 +519,8 @@ The following JSON body parameters are available:
is not permitted and rooms in violation will be blocked.`
* `block` - Optional. If set to `true`, this room will be added to a blocking list,
preventing future attempts to join the room. Rooms can be blocked
- even if they're not yet known to the homeserver. Defaults to `false`.
+ even if they're not yet known to the homeserver (only with
+ [Version 1](#version-1-old-version) of the API). Defaults to `false`.
* `purge` - Optional. If set to `true`, it will remove all traces of the room from your database.
Defaults to `true`.
* `force_purge` - Optional, and ignored unless `purge` is `true`. If set to `true`, it
@@ -480,17 +530,124 @@ The following JSON body parameters are available:
The JSON body must not be empty. The body must be at least `{}`.
-**Response**
+## Status of deleting rooms
-The following fields are returned in the JSON response body:
+**Note**: This API is new, experimental and "subject to change".
+
+It is possible to query the status of the background task for deleting rooms.
+The status can be queried up to 24 hours after completion of the task,
+or until Synapse is restarted (whichever happens first).
+
+### Query by `room_id`
-* `kicked_users` - An array of users (`user_id`) that were kicked.
-* `failed_to_kick_users` - An array of users (`user_id`) that that were not kicked.
-* `local_aliases` - An array of strings representing the local aliases that were migrated from
- the old room to the new.
-* `new_room_id` - A string representing the room ID of the new room, or `null` if
- no such room was created.
+With this API you can get the status of all active deletion tasks, and all those completed in the last 24h,
+for the given `room_id`.
+
+The API is:
+
+```
+GET /_synapse/admin/v2/rooms/<room_id>/delete_status
+```
+
+A response body like the following is returned:
+
+```json
+{
+ "results": [
+ {
+ "delete_id": "delete_id1",
+ "status": "failed",
+ "error": "error message",
+ "shutdown_room": {
+ "kicked_users": [],
+ "failed_to_kick_users": [],
+ "local_aliases": [],
+ "new_room_id": null
+ }
+ }, {
+ "delete_id": "delete_id2",
+ "status": "purging",
+ "shutdown_room": {
+ "kicked_users": [
+ "@foobar:example.com"
+ ],
+ "failed_to_kick_users": [],
+ "local_aliases": [
+ "#badroom:example.com",
+ "#evilsaloon:example.com"
+ ],
+ "new_room_id": "!newroomid:example.com"
+ }
+ }
+ ]
+}
+```
+
+**Parameters**
+
+The following parameters should be set in the URL:
+
+* `room_id` - The ID of the room.
+
+### Query by `delete_id`
+
+With this API you can get the status of one specific task by `delete_id`.
+
+The API is:
+
+```
+GET /_synapse/admin/v2/rooms/delete_status/<delete_id>
+```
+
+A response body like the following is returned:
+
+```json
+{
+ "status": "purging",
+ "shutdown_room": {
+ "kicked_users": [
+ "@foobar:example.com"
+ ],
+ "failed_to_kick_users": [],
+ "local_aliases": [
+ "#badroom:example.com",
+ "#evilsaloon:example.com"
+ ],
+ "new_room_id": "!newroomid:example.com"
+ }
+}
+```
+
+**Parameters**
+
+The following parameters should be set in the URL:
+
+* `delete_id` - The ID for this delete.
+
+### Response
+
+The following fields are returned in the JSON response body:
+- `results` - An array of objects, each containing information about one task.
+ This field is omitted from the result when you query by `delete_id`.
+ Task objects contain the following fields:
+ - `delete_id` - The ID for this purge if you query by `room_id`.
+ - `status` - The status will be one of:
+ - `shutting_down` - The process is removing users from the room.
+ - `purging` - The process is purging the room and event data from database.
+ - `complete` - The process has completed successfully.
+ - `failed` - The process is aborted, an error has occurred.
+ - `error` - A string that shows an error message if `status` is `failed`.
+ Otherwise this field is hidden.
+ - `shutdown_room` - An object containing information about the result of shutting down the room.
+ *Note:* The result is shown after removing the room members.
+ The delete process can still be running. Please pay attention to the `status`.
+ - `kicked_users` - An array of users (`user_id`) that were kicked.
+ - `failed_to_kick_users` - An array of users (`user_id`) that that were not kicked.
+ - `local_aliases` - An array of strings representing the local aliases that were
+ migrated from the old room to the new.
+ - `new_room_id` - A string representing the room ID of the new room, or `null` if
+ no such room was created.
## Undoing room deletions
|
