purge_history_api.rst 1.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263
  1. Purge History API
  2. =================
  3. The purge history API allows server admins to purge historic events from their
  4. database, reclaiming disk space.
  5. Depending on the amount of history being purged a call to the API may take
  6. several minutes or longer. During this period users will not be able to
  7. paginate further back in the room from the point being purged from.
  8. The API is:
  9. ``POST /_matrix/client/r0/admin/purge_history/<room_id>[/<event_id>]``
  10. including an ``access_token`` of a server admin.
  11. By default, events sent by local users are not deleted, as they may represent
  12. the only copies of this content in existence. (Events sent by remote users are
  13. deleted.)
  14. Room state data (such as joins, leaves, topic) is always preserved.
  15. To delete local message events as well, set ``delete_local_events`` in the body:
  16. .. code:: json
  17. {
  18. "delete_local_events": true
  19. }
  20. The caller must specify the point in the room to purge up to. This can be
  21. specified by including an event_id in the URI, or by setting a
  22. ``purge_up_to_event_id`` or ``purge_up_to_ts`` in the request body. If an event
  23. id is given, that event (and others at the same graph depth) will be retained.
  24. If ``purge_up_to_ts`` is given, it should be a timestamp since the unix epoch,
  25. in milliseconds.
  26. The API starts the purge running, and returns immediately with a JSON body with
  27. a purge id:
  28. .. code:: json
  29. {
  30. "purge_id": "<opaque id>"
  31. }
  32. Purge status query
  33. ------------------
  34. It is possible to poll for updates on recent purges with a second API;
  35. ``GET /_matrix/client/r0/admin/purge_history_status/<purge_id>``
  36. (again, with a suitable ``access_token``). This API returns a JSON body like
  37. the following:
  38. .. code:: json
  39. {
  40. "status": "active"
  41. }
  42. The status will be one of ``active``, ``complete``, or ``failed``.