From 3371ec0b85089db7fe33af413d497fb2eb8ede2b Mon Sep 17 00:00:00 2001
From: Sean Quah <seanq@element.io>
Date: Fri, 12 Nov 2021 18:36:18 +0000
Subject: Add documentation for new admin API to remove a local user from a
 space

---
 docs/SUMMARY.md                               |  1 +
 docs/usage/administration/admin_api/spaces.md | 46 +++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 docs/usage/administration/admin_api/spaces.md

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index cdedf8bccc..e71df89797 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -60,6 +60,7 @@
       - [Registration Tokens](usage/administration/admin_api/registration_tokens.md)
       - [Manipulate Room Membership](admin_api/room_membership.md)
       - [Rooms](admin_api/rooms.md)
+      - [Spaces](usage/administration/admin_api/spaces.md)
       - [Server Notices](admin_api/server_notices.md)
       - [Statistics](admin_api/statistics.md)
       - [Users](admin_api/user_admin_api.md)
diff --git a/docs/usage/administration/admin_api/spaces.md b/docs/usage/administration/admin_api/spaces.md
new file mode 100644
index 0000000000..ac91749407
--- /dev/null
+++ b/docs/usage/administration/admin_api/spaces.md
@@ -0,0 +1,46 @@
+# Spaces API
+
+This API allows a server administrator to manage spaces.
+
+## Remove local user
+
+This API forces a local user to leave all non-public rooms in a space.
+
+The space itself is always left, regardless of whether it is public.
+
+May succeed partially if the user fails to leave some rooms.
+
+The API is:
+
+```
+DELETE /_synapse/admin/v1/rooms/<room_id>/hierarchy/members/<user_id>
+```
+
+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`: 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.
+  * 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.
-- 
cgit 1.5.1