Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/S4nti4goCoder/cloudsyncpro/llms.txt

Use this file to discover all available pages before exploring further.

The purge-files Edge Function permanently removes files from both Cloudflare R2 object storage and the files Postgres table. It handles three distinct scenarios through a single mode field: deleting specific file IDs chosen by a user, emptying all trash in a workspace, and the daily scheduled job that auto-purges trash older than 30 days. Only files already in status = 'deleted' (i.e. in the trash) are eligible for purging.
This operation is irreversible. Files deleted by this function cannot be recovered from any trash or archive. Ensure the caller has confirmed the action before invoking.

​
Endpoint

POST /functions/v1/purge-files

​
Authentication

The function supports two authentication modes depending on the mode value: User-initiated modes (user_ids, user_workspace_trash): include a Bearer token and apikey header. The function validates the JWT, resolves the caller’s identity, and checks has_workspace_edit_permission before deleting anything. Cron mode (auto_purge): include the X-Cron-Secret header containing the value of the CRON_SECRET environment variable. No user JWT is required. This header is sent by the Supabase pg_cron job that runs daily at 03:15 UTC.
HeaderRequired for
Authorization: Bearer <access_token>user_ids, user_workspace_trash
apikey: <anon_key>user_ids, user_workspace_trash
x-cron-secret: <cron_secret>auto_purge

​
Request body

​
mode
string
required
Controls which files are purged and how the caller is authenticated. One of "user_ids", "user_workspace_trash", or "auto_purge".
​
ids
string[]
Required when mode is "user_ids". An array of file UUIDs to purge. Only files visible to the caller via RLS and with status = 'deleted' are deleted. Files that fail the RLS check are silently skipped.
​
workspaceId
string
Required when mode is "user_workspace_trash". UUID of the workspace whose entire trash should be emptied.

​
Mode reference

ModeTriggered byDeletesAuth
user_idsUser selects specific filesSpecific file IDs (must be in trash)Bearer token
user_workspace_trashUser clicks “Empty trash”All trashed files in one workspaceBearer token
auto_purgepg_cron daily jobAll trashed files older than 30 daysX-Cron-Secret

​
Response

​
purged
number
Number of file rows deleted from Postgres.
​
blobs_deleted
number
Number of R2 objects successfully deleted. May be less than purged if some R2 deletions failed; the database rows are still removed in that case to avoid ghost entries in the UI.

​
Error responses

StatusError messageCause
400Missing "mode" fieldThe request body did not include a mode
400Missing idsmode is "user_ids" but ids is absent or empty
400Missing workspaceIdmode is "user_workspace_trash" but workspaceId is absent
400Invalid modemode is not one of the three recognised values
401Missing AuthorizationUser-initiated request sent without an Authorization header
401UnauthorizedBearer token is invalid or expired
403ForbiddenCaller lacks edit permission in one of the affected workspaces
403auto_purge requires valid cron secretX-Cron-Secret header is missing or does not match CRON_SECRET
500(error message)Postgres query or R2 batch deletion failed

​
Examples

curl -X POST https://<project>.supabase.co/functions/v1/purge-files \
  -H "Authorization: Bearer <access_token>" \
  -H "apikey: <anon_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "user_ids",
    "ids": [
      "11111111-1111-1111-1111-111111111111",
      "22222222-2222-2222-2222-222222222222"
    ]
  }'
Both successful runs return the same shape: 
{ "purged": 4, "blobs_deleted": 4 }
When there is nothing to delete, the function returns 200 immediately: 
{ "purged": 0, "blobs_deleted": 0 }

Build docs developers (and LLMs) love

Get started for freeTalk to us