forked-synapse/docs/admin_api/media_admin_api.md

List all media in a room

This API gets a list of known media in a room.

The API is:

GET /_synapse/admin/v1/room/<room_id>/media

To use it, you will need to authenticate by providing an access_token for a server admin: see README.rst.

The API returns a JSON body like the following:

{
    "local": [
        "mxc://localhost/xwvutsrqponmlkjihgfedcba",
        "mxc://localhost/abcdefghijklmnopqrstuvwx"
    ],
    "remote": [
        "mxc://matrix.org/xwvutsrqponmlkjihgfedcba",
        "mxc://matrix.org/abcdefghijklmnopqrstuvwx"
    ]
}

Quarantine media

Quarantining media means that it is marked as inaccessible by users. It applies to any local media, and any locally-cached copies of remote media.

The media file itself (and any thumbnails) is not deleted from the server.

Quarantining media by ID

This API quarantines a single piece of local or remote media.

Request:

POST /_synapse/admin/v1/media/quarantine/<server_name>/<media_id>

{}

Where server_name is in the form of example.org, and media_id is in the form of abcdefg12345....

Response:

{}

Quarantining media in a room

This API quarantines all local and remote media in a room.

Request:

POST /_synapse/admin/v1/room/<room_id>/media/quarantine

{}

Where room_id is in the form of !roomid12345:example.org.

Response:

{
  "num_quarantined": 10  # The number of media items successfully quarantined
}

Note that there is a legacy endpoint, POST /_synapse/admin/v1/quarantine_media/<room_id >, that operates the same. However, it is deprecated and may be removed in a future release.

Quarantining all media of a user

This API quarantines all local media that a local user has uploaded. That is to say, if you would like to quarantine media uploaded by a user on a remote homeserver, you should instead use one of the other APIs.

Request:

POST /_synapse/admin/v1/user/<user_id>/media/quarantine

{}

Where user_id is in the form of @bob:example.org.

Response:

{
  "num_quarantined": 10  # The number of media items successfully quarantined
}

Delete local media

This API deletes the local media from the disk of your own server. This includes any local thumbnails and copies of media downloaded from remote homeservers. This API will not affect media that has been uploaded to external media repositories (e.g https://github.com/turt2live/matrix-media-repo/). See also purge_remote_media.rst.

Delete a specific local media

Delete a specific media_id.

Request:

DELETE /_synapse/admin/v1/media/<server_name>/<media_id>

{}

URL Parameters

• server_name: string - The name of your local server (e.g matrix.org)
• media_id: string - The ID of the media (e.g abcdefghijklmnopqrstuvwx)

Response:

    {
       "deleted_media": [
          "abcdefghijklmnopqrstuvwx"
       ],
       "total": 1
    }

The following fields are returned in the JSON response body:

• deleted_media: an array of strings - List of deleted media_id
• total: integer - Total number of deleted media_id

Delete local media by date or size

Request:

POST /_synapse/admin/v1/media/<server_name>/delete?before_ts=<before_ts>

{}

URL Parameters

• server_name: string - The name of your local server (e.g matrix.org).
• before_ts: string representing a positive integer - Unix timestamp in ms. Files that were last used before this timestamp will be deleted. It is the timestamp of last access and not the timestamp creation.
• size_gt: Optional - string representing a positive integer - Size of the media in bytes. Files that are larger will be deleted. Defaults to 0.
• keep_profiles: Optional - string representing a boolean - Switch to also delete files that are still used in image data (e.g user profile, room avatar). If false these files will be deleted. Defaults to true.

Response:

    {
       "deleted_media": [
          "abcdefghijklmnopqrstuvwx",
          "abcdefghijklmnopqrstuvwz"
       ],
       "total": 2
    }

The following fields are returned in the JSON response body:

• deleted_media: an array of strings - List of deleted media_id
• total: integer - Total number of deleted media_id