From 795709e34490c595fcdbb098df8bd36468c234ce Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Thu, 18 Jun 2026 18:12:57 -0400 Subject: [PATCH] docs(frontend-guide): document event_file DELETE and hosted_file orphan_scan Co-Authored-By: Claude Sonnet 4.6 --- .../GUIDE__AE_API_V3_for_Frontend.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/documentation/GUIDE__AE_API_V3_for_Frontend.md b/documentation/GUIDE__AE_API_V3_for_Frontend.md index dbaa8fa..a78bc98 100644 --- a/documentation/GUIDE__AE_API_V3_for_Frontend.md +++ b/documentation/GUIDE__AE_API_V3_for_Frontend.md @@ -345,6 +345,25 @@ The endpoint supports byte-range requests (`Range` header), so it works correctl > [!NOTE] > The `?key=` bypass verifies only that the account ID exists — it does not confirm the file belongs to that account. It is appropriate for internal staff tools. For publicly distributed links, prefer `?site_key=` which ties access to a specific site's configured key. +### Delete Event File + +Atomic delete that cleans up an event_file and its linked hosted_file in a single call. Use this instead of a manual two-step sequence. + +- **Method:** `DELETE` +- **Path:** `/v3/action/event_file/{event_file_id}` +- **Auth:** standard V3 headers + +| Query param | Type | Default | Description | +|---|---|---|---| +| `rm_orphan` | bool | `true` | If `true` and no other links point to the hosted_file, also deletes the physical file and hosted_file DB record. Set `false` to only remove the event_file row and its link without touching the hosted_file. | + +**Response:** +```json +{ "event_file_deleted": true, "hosted_file_link_cleaned": true } +``` + +`hosted_file_link_cleaned: true` means the hosted_file_link was removed successfully (and orphan cleanup ran if `rm_orphan=true`). It does not distinguish between "file was deleted" and "file has other links" — both are successful outcomes. + --- ## 6. Hosted File Actions: Convert & Clip (Frontend Notes) @@ -384,6 +403,15 @@ These helper endpoints let the frontend request small server-side transformation - Behavior: removes the specified link record, then if `rm_orphan=true` and no links remain, applies `method` to the file. Use `method=delete` to hard-delete the physical file and DB record. Without `link_to_type`/`link_to_id`, no link is removed; `rm_orphan` only fires if the file already has zero links. - Use the `/links` endpoint first to get `link_to_id_random` — the delete endpoint resolves `link_to_id` as a random string, not an integer. +- **Orphan Scan** *(admin)* + - Method: `GET` + - Path: `/v3/action/hosted_file/orphan_scan` + - Auth: standard V3 headers + - Query params: `limit` (int, default 500, max 5000), `offset` (int, default 0), `include_disk_orphans` (bool, default `false`) + - Returns DB orphans (hosted_file rows with no hosted_file_link entries), paginated. Each entry includes `hosted_file_id`, `filename`, `hash_sha256`, `subdirectory_path`, `size`, `content_type`, `created_on`. + - Set `include_disk_orphans=true` to also scan the physical files directory for `.file` blobs with no corresponding DB record. + - Use this on the admin files page (`/core/files/`) to detect and clean up the backlog — call this once instead of N+1 per-file link checks. + Frontend guidance: - Call these routes with the same `link_to_type` / `link_to_id` you plan to associate the resulting hosted_file with — the server resolves random IDs for you.