From 73636cab69c32746ef6b7708deeeb0c718b7b3b9 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
Date: Thu, 3 Jun 2021 14:06:03 +0100
Subject: Convert admin api docs to markdown (#10089)

So that they render nicely in mdbook (see #10086), and so that we no longer have a mix of structured text languages in our documentation (excluding files outside of `docs/`).
---
 docs/admin_api/purge_history_api.md | 78 +++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 docs/admin_api/purge_history_api.md

(limited to 'docs/admin_api/purge_history_api.md')

diff --git a/docs/admin_api/purge_history_api.md b/docs/admin_api/purge_history_api.md
new file mode 100644
index 0000000000..44971acd91
--- /dev/null
+++ b/docs/admin_api/purge_history_api.md
@@ -0,0 +1,78 @@
+# Purge History API
+
+The purge history API allows server admins to purge historic events from their
+database, reclaiming disk space.
+
+Depending on the amount of history being purged a call to the API may take
+several minutes or longer. During this period users will not be able to
+paginate further back in the room from the point being purged from.
+
+Note that Synapse requires at least one message in each room, so it will never
+delete the last message in a room.
+
+The API is:
+
+```
+POST /_synapse/admin/v1/purge_history/<room_id>[/<event_id>]
+```
+
+To use it, you will need to authenticate by providing an `access_token` for a
+server admin: [Admin API](README.rst)
+
+By default, events sent by local users are not deleted, as they may represent
+the only copies of this content in existence. (Events sent by remote users are
+deleted.)
+
+Room state data (such as joins, leaves, topic) is always preserved.
+
+To delete local message events as well, set `delete_local_events` in the body:
+
+```
+{
+   "delete_local_events": true
+}
+```
+
+The caller must specify the point in the room to purge up to. This can be
+specified by including an event_id in the URI, or by setting a
+`purge_up_to_event_id` or `purge_up_to_ts` in the request body. If an event
+id is given, that event (and others at the same graph depth) will be retained.
+If `purge_up_to_ts` is given, it should be a timestamp since the unix epoch,
+in milliseconds.
+
+The API starts the purge running, and returns immediately with a JSON body with
+a purge id:
+
+```json
+{
+    "purge_id": "<opaque id>"
+}
+```
+
+## Purge status query
+
+It is possible to poll for updates on recent purges with a second API;
+
+```
+GET /_synapse/admin/v1/purge_history_status/<purge_id>
+```
+
+Again, you will need to authenticate by providing an `access_token` for a
+server admin.
+
+This API returns a JSON body like the following:
+
+```json
+{
+    "status": "active"
+}
+```
+
+The status will be one of `active`, `complete`, or `failed`.
+
+## Reclaim disk space (Postgres)
+
+To reclaim the disk space and return it to the operating system, you need to run
+`VACUUM FULL;` on the database.
+
+<https://www.postgresql.org/docs/current/sql-vacuum.html>
-- 
cgit 1.4.1