Skip to content
Snippets Groups Projects
Select Git revision
  • tedomum default
  • v1.3.7+tedomum.1
  • v1.3.4+tedomum.1
  • v1.3.3+tedomum.1
  • v1.3.2+tedomum.1
  • v1.3.1+tedomum.1
  • v1.3.0+tedomum.1
  • v1.2.13+tedomum.1
8 results
Blame Permalink
admin.md 16.69 KiB

Media repository administration

All the API calls here require your user ID to be listed in the configuration as an administrator. After that, your access token for your homeserver will grant you access to these APIs. The URLs should be hit against a configured homeserver. For example, if you have t2bot.io configured as a homeserver, then the admin API can be used at https://t2bot.io/_matrix/media/unstable/admin/....

Media purge

Sometimes you just want your disk space back - purging media is the best way to do that. Be careful about what you're purging. The media repo will happily purge a local media object, making it highly unlikely to ever exist in Matrix again. When the media repo deletes remote media, it is only deleting its copy of it - it cannot delete media on the remote server itself. Thumbnails will also be deleted for the media.

If the file is duplicated over many media records, it will not be physically deleted (however the media record that was purged will be counted as deleted). The exception to this is quarantined media: when the record being purged is also quarantined, the media is deleted from the datastore even if it is duplicated in multiple records.

Purge remote media

URL: POST /_matrix/media/unstable/admin/purge/remote?before_ts=1234567890&access_token=your_access_token (before_ts is in milliseconds)

This will delete remote media from the file store that was downloaded before the timestamp specified. If the file is referenced by newer remote media or local files to any of the configured homeservers, it will not be deleted. Be aware that removing a homeserver from the config will cause it to be considered a remote server, and therefore the media may be deleted.

Any remote media that is deleted and requested by a user will be downloaded again.

This endpoint is only available to repository administrators.

Purge quarantined media

URL: POST /_matrix/media/unstable/admin/purge/quarantined?access_token=your_access_token

This will delete all media that has previously been quarantined, local or remote. If called by a homeserver administrator (who is not a repository administrator), only content quarantined for their domain will be purged.

Purge individual record

URL: POST /_matrix/media/unstable/admin/purge/<server>/<media id>?access_token=your_access_token

This will delete the media record, regardless of it being local or remote. Can be called by homeserver administrators and the uploader to delete it.

Purge media uploaded by user

URL: POST /_matrix/media/unstable/admin/purge/user/<user id>?before_ts=1234567890&access_token=your_access_token (before_ts is in milliseconds)

This will delete all media uploaded by that user before the timestamp specified. Can be called by homeserver administrators, if they own the user ID being purged.

Purge media uploaded in a room

URL: POST /_matrix/media/unstable/admin/purge/room/<room id>?before_ts=1234567890&access_token=your_access_token (before_ts is in milliseconds)

This will delete all media known to that room, regardless of it being local or remote, before the timestamp specified. If called by a homeserver administrator, only media uploaded to their domain will be deleted.

Purge media uploaded by a server

URL: POST /_matrix/media/unstable/admin/purge/server/<server name>?before_ts=1234567890&access_token=your_access_token (before_ts is in milliseconds)

This will delete all media known to be uploaded by that server, regardless of it being local or remote, before the timestamp specified. If called by a homeserver administrator, only media uploaded to their domain will be deleted.

Purge media that hasn't been accessed in a while

URL: POST /_matrix/media/unstable/admin/purge/old?before_ts=1234567890&include_local=false&access_token=your_access_token (before_ts is in milliseconds)

This will delete all media that hasn't been accessed since before_ts (defaults to 'now'). If include_local is false (the default), only remote media will be deleted.

This endpoint is only available to repository administrators.

Quarantine media

The quarantine media API allows administrators to quarantine media that may not be appropriate for their server. Using this API will prevent the media from being downloaded any further. It will not delete the file from your storage though: that is a task left for the administrator.

Remote media that has been quarantined will not be purged either. This is so that the media remains flagged as quarantined. It is safe to delete the file on your disk, but not delete the media from the database.

Quarantining media will also quarantine any media with the same file hash.

This API is unique in that it can allow administrators of configured homeservers to quarantine media on their homeserver only. This will not allow local administrators to quarantine remote media or media on other homeservers though, just on theirs.

Quarantine a specific record

URL: POST /_matrix/media/unstable/admin/quarantine/<server>/<media id>?access_token=your_access_token

The <server> and <media id> can be retrieved from an MXC URI (mxc://<server>/<media id>).

Quarantine a whole room's worth of media

URL: POST /_matrix/media/unstable/admin/quarantine/room/<room id>?access_token=your_access_token

Quarantine a whole user's worth of media