Synapse media management and quarantine

Why Synapse media management matters once users can upload files

The media admin API in Synapse can quarantine, delete and purge media, and these are the controls an administrator uses to contain abuse and keep storage under control on a self-hosted homeserver. Quarantining makes a file inaccessible to users, with downloads returning 404, without removing the file from the server. Deleting removes local media by identifier, date or size. Purging targets remote media that your server cached from other servers. Together these give you a way to respond after something has already reached your server. Teams usually need this workflow in three situations. The first is abusive uploads, such as illegal imagery, malware or harassment content posted by a local user. The second is storage pressure, where media grows faster than the disk or object store you planned for. The third is a takedown request that requires a specific file to stop being served. Federation makes the second and third cases more likely, because a federated Synapse caches media from rooms that include users on other servers, and those caches grow without any local user uploading anything. This is an administrator workflow, not a client feature. Users in Element or another Matrix client do not see quarantine or purge controls, and they cannot trigger them. The actions require an admin account and an authenticated call to the admin endpoints, so the people who can run them should be named in your operations plan. Decide who can quarantine, who can delete, and who approves a purge of remote media before an incident happens. Write down the request path for takedowns that come from outside your organization.

Before you rely on these calls, confirm the exact endpoint paths, parameters and behavior for your Synapse release in the media admin API documentation, because the admin API changes between versions. Check how your deployment stores media, whether on local disk or in a configured media store, since that determines where a deleted file is physically removed and how you verify it. Also confirm that your backup policy covers media as well as the database, so that a quarantined item can be restored if a review finds it was a false positive. Quarantine is the step to plan first. It stops users from downloading a file immediately and is reversible in practice, which gives reviewers time to decide. Hash-based quarantine is worth understanding separately, because it also blocks matching media uploaded in the future. That protects you from re-upload of known bad content, but it also means a mistaken hash can affect legitimate users, so the process for adding and removing hashes should be documented and reviewed.

Synapse media management options and when each fits

This table compares the three Synapse media admin actions for local and remote files, plus the separate purge remote media API. Read each row for what the action touches, whether the file stays on disk, and whether matching future uploads are blocked. The main takeaway is that quarantine is the reversible choice for abusive content, while deletion and purging are for storage control.

Action	What it affects	File stays on disk	Blocks future matching uploads	Typical trigger
Quarantine local media	One uploaded file on this server	Yes, the file is kept but users get a 404 on download	Only when quarantined by hash	Reported or confirmed abusive upload that needs review
Quarantine remote media	One cached file from another server	Yes, the cached copy is kept but hidden from local users	Only when quarantined by hash	Abusive remote file already cached on this server
Delete a specific local media item	One local upload identified by server name and media ID	No, the file is removed	No, the admin call does not block re-uploads	Removing one known file without a broader sweep
Delete local media by date or size	Local uploads older than a timestamp, selected through the delete endpoint	No, matching files are removed	No, the action does not block re-uploads	Freeing storage on a schedule or after growth
Purge remote media API	Cached copies of files from other servers	No, cached copies are removed	No, the cache is cleared but nothing is blocked	Keeping cached federation media within storage limits
Quarantine by hash	Every matching file, including future uploads with the same hash	Yes, existing copies are kept but hidden	Yes, matching media uploaded later is also blocked	Known abusive content that keeps reappearing

How quarantine differs from deletion in Synapse

Quarantine and deletion answer different questions, so decide which outcome you need before you call either API. Quarantine makes a media item inaccessible to users: downloads return 404, but the file stays in the media store. Deletion removes the file from storage and cannot be reversed. The Synapse media admin API supports both, which lets your team hold abusive or disputed content while a review is open. Quarantine preserves the evidence needed for an appeal, an internal investigation or a report to an authority, and it lets the team reverse the decision if the content is found to be acceptable. Deletion is usually the end state after the review closes and your retention period has passed. Confirm your retention and legal hold obligations with counsel before you set the workflow.

Quarantine by media ID applies to one item on your homeserver. Quarantine by hash goes further, because it also blocks matching media that users upload in the future. A known abusive file can then not be re-shared under a new media ID. Use hash quarantine only when you are confident the bytes match the content you want blocked, and record the hash, the reason and the reviewer in your moderation log. Before you rely on it, test the behavior on a non-production homeserver: upload a file, quarantine it, confirm that a download returns 404, then upload the same bytes again and confirm the result. Confirm the exact hash-based request format in the media admin API documentation for your Synapse version.

Deletion has two forms in the supplied API. DELETE /_synapse/admin/v1/media/<server_name>/<media_id> removes one local media item. POST /_synapse/admin/v1/media/delete?before_ts=<before_ts> removes local media older than a timestamp. Both remove files from storage, so run them only after an item has been quarantined, reviewed and cleared for removal, or after your retention period ends. Keep a record of each media ID and the timestamp you used, because the removal is permanent and your audit trail depends on it. The outline also names size-based bulk deletion. Confirm which size parameters your Synapse version accepts in the media admin API documentation before you script any size-based cleanup.

Cached media from other servers follows a different path. When local users view remote content, Synapse keeps copies on your storage, and the local deletion calls above are scoped to local media. The media admin documentation points to a separate purge remote media API for these cached files. Plan a recurring purge to control storage growth, and agree the age threshold with the team that owns storage capacity. Confirm the endpoint, its parameters and its effect on quarantined remote items in the documentation for your version, and run the purge in a test environment first so you know what it removes.

Setting up media management through the Synapse admin API

This sequence takes a Synapse operator from a verified admin token to bulk quarantine and deletion runs that are tested, logged and repeatable. Each step closes with a check, so a failed test stops the work before it reaches production media.

Confirm an admin token with the right permissions
A server administrator confirms that the account calling the media admin API is a Synapse server admin and that the access token was issued to that account. Store the token in your secrets manager and keep it out of shell history and shared scripts. Then send one read-only admin request chosen from the Synapse media admin API docs for your version. Done when the request returns data and not an authorization error, and the token owner and expiry are recorded in your access register.
Identify the media to act on
Collect the inputs each action needs: the server_name for local media, the media IDs of the files under review, and a date cutoff for any bulk work. Use the reports your moderation team already holds to find the IDs. Write the cutoff in the timestamp format the endpoint expects, and confirm that format in the Synapse media admin API docs for your version before you use it. Done when the ID list and cutoff are attached to the ticket and a second reviewer has checked both.
Test quarantine and deletion on a copy
Build a non-production Synapse from a copy of the media store and database, then run one quarantine and one deletion against a known test file. Confirm the exact quarantine request path, method and parameters in the Synapse media admin API docs for your version, since these details can change between releases. Done when the test file is the only item affected on the copy and the staging server behaves as the docs describe.
Confirm quarantined media returns 404
Sign in to the copy with a test account and request the download URL for the quarantined file. A 404 response confirms that users can no longer reach the file, although the file itself still exists on disk until you delete it. If you use hash-based quarantine, also upload a file with the same content and confirm that the upload is blocked. Done when both results match what the docs describe and you have saved the responses as evidence.
Confirm storage use changes after deletion
Measure media storage on the copy before the test deletion, using file system or object storage metrics, and record the figure. Run the deletion, then measure again. Storage use should fall by roughly the size of the deleted files, and the media rows should no longer appear in the database. Quarantine alone does not free space, so confirm that the deletion step, not the quarantine step, produced the change. Done when the before and after figures are recorded and the difference matches the test file.
Record each action in the moderation log
Before any production call, write one log entry for each planned action. Include the approver, the server_name, the media IDs or cutoff, the endpoint and Synapse version, the staging results from the previous steps, and the planned run time. Keep the log in the same system your trust and safety or compliance team reviews. Done when every planned action has an entry that links to the staging evidence and the approval is recorded before the production call is made.
Run bulk operations with a documented cutoff
Run production quarantines first, then bulk deletion by date or size, using the cutoff recorded in the log. Start with a narrow scope, such as one server_name or a small ID list, and compare the response with the expected count before widening the scope. Repeat the 404 and storage checks on a sample of the affected media. Done when the log records the final counts, the storage change matches the expected figure, and any mismatch has been investigated.
Plan purges of cached remote media
Media cached from other servers is handled through the separate purge remote media API that the Synapse media admin docs describe. Confirm its path, parameters and cutoff format for your version, then test it on the copy using the same checks as the local steps. Document which operator owns remote purges and how often they run under your policy. Done when you have a tested runbook entry for remote purges that operations staff can repeat without guessing at the request format.

Security and operational risks in media moderation

Media moderation on Synapse changes what users can see and what storage holds, and some of those changes cannot be undone. The cards below cover the risks an admin team should control before running any quarantine, deletion or purge, from scoping errors and lost evidence to access control and copies that outlive local action.

Bulk deletion from a wrong cutoff

The bulk delete call removes local media selected by a before_ts timestamp or a size criterion, so a mistyped timestamp, a wrong unit or a misread size threshold can remove far more than intended. Before running it, dry-run the selection where your tooling allows, list the candidate media IDs, confirm the timestamp unit with your own test data, and record the exact request in your change log. Treat the first run as the only chance to catch an error.

Loss of evidence on deletion

Deleting a file removes the bytes that an investigation, a user appeal or a legal hold may need, and the database record alone does not reproduce the content. Quarantining instead keeps the file in place while making it unavailable to users, since downloads return 404. Decide the default action for each abuse category in advance, and reserve permanent deletion for media your policy has already cleared for removal.

Admin token exposure

Every media admin call runs under an admin access token, and anyone who holds that token can quarantine, delete or purge media on the server. Keep tokens out of shell history, scripts committed to source control and shared chat channels, and rotate them when staff change roles. Use a dedicated admin account for moderation tasks so its activity is distinguishable from routine administration.

Incomplete audit trails

Moderation decisions need a record of who acted, on which media, under what policy and at what time, and the Synapse API responses alone may not capture the reasoning. Log every quarantine, deletion and purge request in a system the moderation team cannot silently edit, and tie each entry to a ticket or report. Confirm with your log pipeline that admin requests on the media endpoints are captured and retained for the period your policy requires.

Copies left on other servers

Local action on your homeserver does not reach copies of a file that users on other federated servers have already fetched and cached. Quarantining or purging media locally stops your server from serving it, but other servers may keep their own copies under their own policies. Identify which remote media your server cached, use the purge remote media API for your cached copies, and contact the operators of other servers when content must be removed from their storage.

Backups before destructive actions

Deletion and purge calls cannot be reversed by Synapse, so the only recovery path for an accidental removal is a backup taken before the action. Back up the media store and the database together so file references and stored records stay consistent, and test that a restore returns the expected media. Schedule the backup as a required step in the moderation runbook, and confirm the restore procedure with your storage team before the first production run.

Who holds media admin access

Media admin endpoints can change what every user on the server sees, so the set of accounts with admin rights should be small, named and reviewed on a fixed schedule. Separate the people who review reports from the people who run destructive calls, and require a second approver for bulk deletion. Confirm how your identity provider maps administrative roles to Synapse admin status before you grant access.

Controlling storage growth from cached remote media

Storage growth from remote media on a federated Synapse usually comes from traffic you do not control directly. When a user in a room hosted on another server opens an image, file or video, your homeserver fetches a copy and keeps it locally so later requests can be served quickly. The more rooms your users join across other servers, the more this cache grows, even if nobody on your server uploads anything. Local uploads and cached remote media are stored and counted separately, so the first step is to measure both before you set any policy. Record the size of the media store, split by origin, over a representative period, and confirm with your Synapse version how the media repository reports that split on your own deployment.

Purging cached remote media saves disk space, but it moves the cost somewhere else. If a user later opens a purged item, Synapse must fetch it again from the originating server, which adds latency for that user, uses bandwidth on both sides and places load on the remote server. If the origin has deleted the file, goes offline or is restricted by its own policy, the media may no longer be retrievable at all. Rooms that are rarely opened are good candidates for aggressive purging, while busy rooms with large shared files may justify keeping their cache. Decide this trade-off with your users and your federation partners in mind, and document the retention rule you choose so support staff can explain missing media when it happens.

The Synapse media admin documentation refers to a separate purge remote media API for cached media from other servers. It is distinct from the endpoints used to delete local media by date or size, so do not assume that a local cleanup job also clears the remote cache. Before you schedule anything, confirm the endpoint, its parameters and its behavior in the Synapse version you run, because admin API details can change between releases. Read the upgrade notes for every release between your current version and your target. Then run the call against a test environment or a copy of your media store, check what was removed, and only then add it to a scheduled job with clear logging.

Treat the purge as an operational change with an owner. Assign a named administrator to approve the retention rule, the schedule and any manual runs, and keep a record of when purges ran and what parameters were used. Schedule them outside peak hours and watch disk usage, request latency and error rates for a period afterward. Check how remote purges interact with media you have quarantined, so that a purge does not change the status of content your moderation team is still reviewing. Storage on infrastructure you control is paid for by your organization, so when you request a quote for media management, ask the implementation partner to state which monitoring, testing and runbook work is included.

Limits to confirm in your environment before you rely on this

These five checks cover where Synapse media management can fail without an obvious error: request syntax, federation reach, deletion and backups, upgrade drift, and file variants. Treat each one as a question to test in your own environment, then record the results in your runbook before you depend on quarantine or deletion for abuse response or storage limits.

Exact request formats for your version

The media admin API endpoints for quarantining, deleting and purging are documented per Synapse release, so the paths, methods, parameters and response bodies your scripts call must be confirmed for the exact version you run. Test each call on a staging homeserver with a known test file, and record the response for a successful call, a missing media ID and a call made without admin rights. Do not assume a path copied from an older guide still works after an upgrade.

Visibility to federated servers

Quarantine blocks downloads on your homeserver, but whether a quarantined file is also hidden from remote servers that cached it earlier, or from servers that request it later, depends on your federation settings and how your deployment serves media. Test this with a second homeserver you control, federated with yours, by quarantining a file and requesting it from that server. Confirm the result against your own configuration before you tell users that abusive content is contained.

Deletion, backups and retention

Deleting local media removes files from your media store, but copies held in database backups, object storage snapshots or archives may keep them for their own retention period. Ask which copies exist, who can restore them, how long each one is kept, and whether a restored backup brings deleted media back into service. Your retention policy and any legal hold obligations determine whether a deletion can happen on the date an admin requests it.

Admin API behavior after upgrades

Endpoints and their behavior can change between Synapse releases, so read the upgrade notes for every version between your current and target release, including the latest one. Repeat your scripted quarantine, delete and purge tests in staging after each upgrade and compare responses with your previous baseline. Plan for the possibility that rolling back is difficult because of database schema changes, and test the upgrade path before it reaches production.

Hash matching and re-encoded files

Quarantining by hash blocks matching uploads in future, but a re-encoded, resized, trimmed or metadata-stripped version of the same image or video produces a different hash and may pass the block. Test this with controlled variants of a known test file, including different encodings and containers, to see which ones the block catches. Decide whether hash blocking meets your abuse policy alone or whether you also need content review and user reporting workflows.

Questions teams ask about Synapse media management

What drives the cost of Synapse media management work?

Scope is the main driver, and the quote follows from the written scope. The cost components are:

Storage scope: how much local media exists, where it sits, and whether it lives on a local disk, shared storage or object storage.
Rooms and federation peers: the number of rooms and remote servers affects how much remote media the server caches and how many policies apply.
Moderation process: whether takedowns are handled by one admin or by a documented queue with review steps.
Testing and backups: a dry run in a test environment and a verified backup before any deletion job.

DeployOpen is paid for planning, configuring and scripting these controls, testing them, and documenting the runbook. Most of this work is one-time, while routine moderation and periodic cleanup recur. Ask the quote to separate one-time setup from ongoing operations.

How long does a scoped Synapse media setup take?

Duration depends on your environment, and no timeline is stated here. Work moves faster when your Synapse release, database, storage backend and monitoring are documented and reachable. It slows when access must go through change control, when media is spread across several systems, or when the moderation policy still needs approval. Confirm three things before you ask for an estimate: the Synapse release you run, whether the homeserver uses a single process or workers, and where media files are stored. The written quote should set out the phases, the dependencies on your change windows, and the points where your staff must act.

What does our team need to provide for media management work?

Plan to provide four things before work starts:

Admin access: an account with Synapse admin API permissions, plus access to the server host and reverse proxy logs.
Storage access: read and delete rights on the media store, whether that is a local directory or an object storage bucket, and read access to the database records that map files to media IDs.
A test environment: a copy of the homeserver with representative media so quarantine and deletion steps can be rehearsed.
A moderation policy: written criteria for quarantine, appeals, retention periods, and who may approve deletions.

The technical work cannot be finished properly without the policy, because the rules that decide what gets removed would still be undefined. Your legal or trust and safety contact should own that policy.

Can an internal team manage Synapse media without a partner?

Yes, a team with Synapse operations experience can do it alone. The media admin API is documented, and server admins can quarantine media, delete items by server name and media ID, and delete local media by date or size. The harder parts are rarely the API calls. They are writing the moderation policy, proving that a deletion job removes what it should and nothing else, keeping backups current, and running cleanup on a schedule without disrupting users. Decide based on who would own each step, how often moderation actions occur, and whether anyone can rehearse a purge safely. A scoped engagement can cover the parts your team lacks, such as the test plan or the runbook, while your staff keeps day-to-day control.

Does quarantining media delete the file from the server?

Quarantining does not delete the file. It makes the media item inaccessible to users, so downloads return a 404 response, while the file stays on the server. Admins can quarantine local or remote media. Quarantining by hash also blocks matching media uploaded in the future. Deletion is a separate action: admins can delete one local media item by server name and media ID, or delete local media by a timestamp cutoff through the delete endpoint. Use quarantine first when a decision is still pending, keeping the evidence available for review. Confirm with your moderation policy when a file should be removed permanently.

How do we control remote media cached from other servers?

Cached copies of remote media are handled through a separate purge remote media API, which the Synapse media admin documentation describes. The cache grows with the number of rooms and federation peers, so the storage trend depends on how actively your users join rooms on other servers. Before you purge, decide on the age or size threshold, and confirm that the cache can refill from the origin server when users need a file again. The federation_domain_whitelist setting can also limit which servers take part at all. Ask for a dry run on a copy of the store to measure the effect before the first production purge.

What should we test before running a media deletion job?

Test the job on a copy of production data before running it live. Confirm that a current backup exists and that a restore has been tried. Check the selection logic, so a timestamp or size filter matches only the items your policy names. Verify that quarantined items stay hidden and that clients show the expected error. Record the count and total size of the items the job will touch, then compare that with the result. Keep an approval step for deletions that cannot be reversed. Ask for the rollback limits to be documented as well, since database schema changes between Synapse releases can make rollback difficult.

What happens to media management after the first setup is complete?

Ongoing work continues. Your team reviews moderation reports, applies quarantine decisions, runs scheduled cleanup, and checks storage trends. Synapse upgrades also need a review of the release notes, because a change in database schema or a dropped Python or PostgreSQL version can affect the media jobs. Some organizations keep all of this in-house, while others add a retainer for upgrades, periodic testing and support when moderation volume rises. Ask the quote to show which tasks are included in the one-time setup and which would recur under a support agreement, so you can compare the ongoing cost with your internal staffing plan.

How DeployOpen scopes and supports Synapse media management

DeployOpen scopes media controls as part of your Synapse homeserver's retention and moderation policy, then implements them in infrastructure you control. Quarantine, local deletion and remote cache purging are configured against written rules for your users, your federation settings and your storage budget, then tested before handover.

How we scope

Written scope lists which admin API actions your moderators and operators will run, and who may run them.
Scope records your federation policy, because remote media quarantine and cache purging depend on which servers you federate with.
Retention targets for local media, by age and size, are agreed in writing before any deletion job is built.

How we build

Quarantine procedure built around the media admin API, so flagged files return 404 to users while staying stored.
Hash-based quarantine rules are tested so matching uploads from future users are blocked as intended.
Scheduled deletion of local media by date or size is reviewed, logged and preceded by a backup.

How we hand over

Runbooks cover each quarantine, delete and purge action, with the exact endpoints and the required admin access token.
Moderation roles, reviewers and escalation paths are documented so abuse reports reach the right person.
Handover includes a test record showing quarantined media returns 404 and deleted media cannot be retrieved.

How we support

Retainer options cover monitoring of storage growth, periodic purge runs and review of new admin API behavior.
Synapse upgrades are checked against media admin endpoints before the upgrade is applied in production.
Ask any quote to name the retention period, storage scope and which federated remote servers it covers.