Add flag to control whether remote spaces are processed

1 files changed, 27 insertions, 16 deletions

diff --git a/docs/usage/administration/admin_api/spaces.md b/docs/usage/administration/admin_api/spaces.md

index ac91749407..98fa576543 100644
--- a/docs/usage/administration/admin_api/spaces.md
+++ b/docs/usage/administration/admin_api/spaces.md
@@ -16,31 +16,42 @@ The API is:
 DELETE /_synapse/admin/v1/rooms/<room_id>/hierarchy/members/<user_id>
 ```
 
+with an optional body of:
+
+```json
+{
+  "include_remote_spaces": true,
+}
+```
+
+`include_remote_spaces` controls whether to process subspaces that the
+local homeserver is not participating in. The listings of such subspaces
+have to be retrieved over federation and their accuracy cannot be
+guaranteed.
+
 Returning:
 
 ```json
 {
-    "left": ["!room1:example.net", "!room2:example.net", ...],
-    "failed": {
-        "!room3:example.net": [
-            "Could not explore space or room fully."
-        ],
-        "!room4:example.net": [
-            "Failed to leave room."
-        ],
+    "left_rooms": ["!room1:example.net", "!room2:example.net", ...],
+    "inaccessible_rooms": ["!subspace1:example.net", ...],
+    "failed_rooms": {
+        "!room4:example.net": "Failed to leave room.",
         ...
     }
 }
 ```
 
-`left`: A list of rooms that the user has been made to leave.
+`left_rooms`: A list of rooms that the user has been made to leave.
 
-`failed`: A dictionary with entries for rooms that could not be fully
-processed. The values of the dictionary are lists of failure reasons.
-Rooms may appear here if:
-  * The user failed to leave them for any reason.
-  * The room is a space that the local homeserver is not in, and so
-    its full list of child rooms could not be determined.
+`inaccessible_rooms`: A list of rooms and spaces that the local
+homeserver is not in, and may have not been fully processed. Rooms may
+appear here if:
+  * The room is a space that the local homeserver is not in, and so its
+    full list of child rooms could not be determined.
   * The room is inaccessible to the local homeserver, and it is not
     known whether the room is a subspace containing further rooms.
-  * Some combination of the above.
+
+`failed_rooms`: A dictionary of errors encountered when leaving rooms.
+The keys of the dictionary are room IDs and the values of the dictionary
+are error messages.