Creates a folder owned by the caller. If parent_id is provided, the folder is nested under that parent and inherits a depth of parent.depth + 1. The DB enforces sibling-name uniqueness — duplicates return HTTP 409.

Lists folders owned by the caller. Default scope is the current parent's children (or roots when parent_id is omitted). Set recursive=true to flatten the entire subtree.

Renames a folder. The DB trigger trg_update_folder_path rewrites every descendant's path inside the same transaction. Root folders cannot be renamed.

Returns the immediate children: subfolders and media files in a single paginated response. Useful for a Drive-style file browser UI.

Deletes the folder. The non-force path requires the folder to be empty (no media, no subfolders) and returns HTTP 412 if it is not. With force=true the entire subtree is purged: for every media in the subtree, all derived variant blobs (medium /high/low) are removed first, then the original blob, then the media row; finally the folder rows cascade. Variant cleanup failures are logged but never abort the purge — same reasoning as the single-media delete endpoint.

Returns a JSON payload indicating the service process is up. Does not check downstream dependencies (DB, storage).

model_3d_enabled advertises whether the 3D model pipeline is operational — i.e. whether Blender (the primary converter) is configured and runnable on this host. Probed once at first call (blender --background --version) and cached. The frontend reads this to disable the "3D model" upload action up-front when the administrator hasn't installed/configured Blender, rather than letting a user upload and hit a 503 MODEL_3D_UNAVAILABLE.

Paginated listing. Supports filtering by folder, visibility, file type, and a search term applied to original_name. The search input is parameterised at the SQL layer. Default sort is newest-first (created_at desc).

Each item carries model_3d (boolean): true when the file was uploaded via ?as=3d-model and has a renderable glTF. The UI uses it to offer the 3D viewer even when the stored MIME is ambiguous (e.g. a .zip bundle reported as application/zip).

Streams the media bytes back with the original Content-Type and Content-Disposition. Visibility rules apply: public is unauthenticated, organization requires same-org JWT, private requires the owner's JWT.

Variant selection (?variant=) — the service stores the original plus optional re-encoded variants. The variant tier is the same query string for every supported MIME class; what the server produces depends on the source type:

original (default) — uncompressed bytes, format as uploaded. SHA-256 matches the upload-time checksum. high (q=90) — light recompression, near-original quality. medium (q=75, max 1280 px) — balanced; suitable for previews. low (q=50, max 320 px) — aggressive; suitable for thumbnails.

Per-MIME thumbnail behaviour for ?variant=low (and the smaller-cap ?variant=medium):

image/* → resized + re-encoded in the original format (JPEG/PNG/WebP/GIF). Aspect ratio preserved. video/* → JPEG poster frame extracted via ffmpeg at the 1-second mark, scaled to fit the cap. application/pdf → JPEG of the first page rendered via pdftoppm at the cap resolution. audio/* → transparent PNG waveform (16:9), decoded with symphonia (ffmpeg fallback for containers symphonia can't read, e.g. Opus-in-WebM voice notes). 3D models (uploaded ?as=3d-model) → 320×320 transparent PNG rendered by f3d. Generated eagerly at upload. MIMEs without an adapter → HTTP 404 (no thumbnail). UI is expected to fall back to a generic icon.

3D model viewer tiers — for media uploaded with ?as=3d-model, the glTF binary is served at three level-of-detail tiers so the viewer can stream a light model on mobile and the full one on desktop (the 3D analogue of image tiers). All three are meshopt-compressed glTF binary (model/gltf-binary):

web — full geometry + full-resolution texture. web-medium — ~50% triangles, texture capped at 2048 px. * web-low — ~20% triangles, texture capped at 1024 px (the mobile default the viewer requests first).

Texture downscaling happens in Blender (gltfpack only resizes textures alongside KTX2, which we avoid to keep the viewer decoder-free); gltfpack does the geometry decimation. These tiers are produced by the asynchronous post-upload pipeline (see ?as=3d-model under Upload), never lazily on demand.

Three response states for a glb tier: 200 — variant ready, body is the glb bytes. 202 Accepted — model is still converting (metadata.model_3d_status = "processing"). Body is a JSON status {"error":"MODEL_3D_PROCESSING", "message":…}, NOT media bytes. Clients should back off + refresh, not pass the body to a model viewer. * 404 Not Found — no such 3D asset (legacy upload that predates LODs, conversion failed, or the source was never uploaded as 3D). Frontend falls back to web or shows a "no preview" state.

All thumbnail responses ship Content-Type: image/jpeg or image/png regardless of the source MIME — a single <img> element renders every case.

Aliases also accepted: orig / raw for original, hi for high, med for medium, lo for low. Invalid values return HTTP 400 with the allowed list.

The medium and low variants for images are generated eagerly on upload (when IMAGE_EAGER_MEDIUM=true); video / PDF / audio thumbnails plus all other levels are generated lazily on first request and cached for subsequent ones. Generation is best-effort — adapters that can't decode the source surface 404, not 500.

The Content-Disposition filename is always the upload's display name regardless of variant — the tier is invisible to the user-facing UI.

Range / streaming (video only) — when the underlying MIME is video/*, the response includes Accept-Ranges: bytes and the endpoint honours Range: request headers. This lets the browser's HTML5 <video> element scrub mid-file without downloading from byte 0. Supported forms:

Range: bytes=N-M → 206 Partial Content Range: bytes=N- → 206 from N to EOF Range: bytes=-M → 206 last M bytes Multi-range / unparseable → ignored, full 200 returned * Out-of-bounds → 416 with Content-Range: bytes */<total>

Non-video MIMEs do NOT advertise Accept-Ranges and ignore any Range: header — they always stream the full body.

Returns the metadata only (no bytes). Useful for clients that want size/MIME/checksum without paying for the download.

Updates the user-facing original_name. The on-disk filename is unchanged; only the display name is rewritten.

Switches the media row's visibility level. Does not propagate to shared links; existing tokens keep working until they expire or are deleted.

Re-runs the 3D conversion pipeline (Blender → gltfpack → f3d) for a media that was uploaded with ?as=3d-model. Use when metadata.model_3d_status is "failed" (transient binary failure, a corrupt input, etc.) or stuck "processing" after a service restart had killed the prior detached task.

Owner-only. Flips the row's status back to "processing" and spawns the pipeline asynchronously — the response is 202 Accepted as soon as the task is queued. The pipeline updates the status to "ready" (variants on disk) or "failed" (+ a short model_3d_error) when it finishes.

Idempotent under concurrent calls: if the row is already "processing", the second call is a no-op (returns 202 without spawning another task). Conversion is deterministic so even a racing double-spawn would converge to the same outcome.

Reject conditions: 404 NOT_FOUND — media does not exist 403 FORBIDDEN — caller is not the owner 422 MODEL_3D_VALIDATION — media was not uploaded as a 3D model (no metadata.model_3d flag), so there is nothing to re-convert. Re-upload via POST /upload?as=3d-model. 503 MODEL_3D_UNAVAILABLE — Blender is not configured on this host (see model_3d_enabled on /health).

Removes every blob (original + each derived variant) from storage, then deletes the media row. The matching media_variants rows go away via FK cascade. A StorageError::NotFound is tolerated per file so retries on a partially-failed delete are idempotent.

A failure cleaning a single variant blob is logged but does not abort the delete — the user's media still goes away; worst case is one orphan blob on disk. Operators can sweep orphans by walking the storage directory and reconciling against media_variants.storage_path.

Deletion code guard (optional, per row). If the file was uploaded with X-Deletion-Code: <secret>, the row is "guarded" — every delete must echo the same plaintext via the same header. Distinct 403 body codes signal which failure mode so UIs can prompt vs re-prompt:

DELETION_CODE_REQUIRED — guarded row, no header sent. INVALID_DELETION_CODE — guarded row, header sent but the hash didn't verify. Re-prompt the user. * FORBIDDEN — role check failed (not owner, not org-admin). A code can't fix this.

Rows uploaded without the header (or before this feature was released) ignore the header on delete — behaviour is unchanged.

Head-of-file text preview for text-y MIMEs (text/*, application/json, application/xml, application/x-yaml, application/javascript, plus extension-based fallback for markdown / source code: .md, .mmd, .txt, .log, .csv, .tsv, .json, .yaml, .toml, .xml, .rs, .ts, .py, .go, .java, .sql, .sh, etc.).

Returns up to 8 KB (cap is hard). Non-text MIMEs → 415 with body UNSUPPORTED. UTF-8 boundary safe via lossy decode so a cut mid-codepoint yields U+FFFD instead of a 5xx.

Lists the entries inside a zip / tar / tar.gz without extracting any payload. Reads only the central-directory headers; bounded at 5 000 entries (zip-bomb cap) with a truncated flag past that.

Format is auto-detected from MIME, with a sensible extension fallback so application/octet-stream uploads ending in .zip / .tgz are still recognised. Non-archive MIMEs → 415.

Entry paths are sanitised: any .. segments and leading slashes are stripped before serialisation, so the UI can render name verbatim without re-validating.

Returns the caller's most recently accessed media, newest-first. Capped at the value the client requests (default applied server-side).

Records an access event for the given media. Idempotent at the row level — repeated tracks update the existing row's timestamp instead of inserting duplicates.

Wipes the caller's entire recent-files history. The underlying media files are untouched.

Lookup existence + ownership untuk satu media_id. Cocok untuk validasi single-field cover_outlet_media_id / attachment_id saat consumer menerima request dari owner.

Response shape:

exists selalu true di body 200 — kalau tidak ada, response-nya 404 dengan body error standar. visibility salah satu public / organization / private. Consumer enforce same-org rule sendiri. organization_id null ketika row orphan (tidak ada org-nya). Untuk media visibility=organization, consumer bisa cocokkan dengan org-nya sendiri. expired dihitung server-side dari expires_at vs NOW(). Tidak ada off-by-one antar service clock.

Lookup existence + ownership untuk banyak media_id dalam satu round-trip. Pakai ini saat consumer menyimpan record dengan beberapa media reference (mis. outlet dengan cover + photo, atau survey response dengan multiple attachment).

Partial result by contract. Response 200 berisi satu entry per id yang di-request — bahkan untuk id yang tidak ditemukan (entry-nya {id, exists: false}). Consumer bisa simpan yang valid + flag yang invalid dalam satu pass.

Order preserved. items[i].id == request.ids[i]. Kalau caller kirim duplicate id, response berisi duplikat juga.

Cap 100 ids. Body di luar cap → 400 VALIDATION_ERROR. Body kosong → 400 dengan pesan "ids must be a non-empty array".

Mints a shared-link token for the given media. The caller must own the media or have download access through it. Visibility defaults to restricted (creator-only) — set public for anonymous access or organization to gate by the caller's org.

Anonymous (or authenticated, for restricted/organization links) entry point. Streams the media bytes back. The download counter is incremented atomically.

Failure modes (401/403/404): link not found / revoked → 404 expired → 410 download cap reached → 429 password missing/wrong → 401 * caller not eligible for restricted / organization → 403

Lists shared links the caller created. Paginated.

Revokes a shared link. Subsequent GET /share/:token requests return 404. The underlying media file is unaffected.

Lists the caller's starred media in reverse-chronological order (most recently starred first). Each item includes the underlying media metadata plus starred_at and notes.

Stars (or re-stars) a media file. Optional notes are stored alongside the star. Calling this on an already-starred file is a no-error update.

Removes the star. Idempotent — unstarring an already-unstarred file returns success.

Convenience endpoint that flips the star state. Useful for UIs that bind a single button to "star/unstar" without tracking current state client-side.

Bulk lookup: given a list of media IDs, returns which ones the caller has starred. Lets a list view annotate every row in one round-trip.

Streams a single multipart file part (field name file) into storage. The response carries the canonical media metadata, including the SHA-256 checksum and the storage path of the original bytes.

Accepted credentials. Any RS256 JWT carrying media:upload is accepted — both ordinary user tokens and service-principal tokens (principal_type: service), including the short-lived token a headless backend obtains from the Account Service POST /auth/system-token flow. There is no anonymous path: a valid token is always required (missing/invalid → 401). Service-principal uploads are attributed to the token's sub as owner_id; set visibility=public if the resulting file must be readable without auth (e.g. an anonymous applicant's document fetched later via GET /media/{id}).

Storage quota by principal. Human uploads draw on the per-user bucket (MAX_STORAGE_PER_USER, default 1 GiB). Service-principal uploads — which funnel many end-users through a single owner id — draw on a separate, typically larger per-service bucket (MAX_STORAGE_PER_SERVICE, default 10 GiB). The limit is applied both as the fast-path pre-check and as the authoritative storage_quota.max_bytes for the service owner; over-quota uploads fail with 413 and the staged blob is removed.

Cross-organisation attribution (trusted backends). The X-Organization-Id header lets the caller pick which organisation the resulting media belongs to. For ordinary user tokens that org must be in the caller's own membership set — otherwise 403, no escalation. A headless backend that serves end-users across many orgs (e.g. a careers portal uploading documents on behalf of anonymous applicants) can bypass the membership gate when ALL three hold:

1. The token is principal_type: service (cryptographically pinned by account-service; cannot be forged by a user token). 2. The token carries the media:act_as_any_org permission. 3. X-Organization-Id: <target-org-uuid> is sent on the upload request.

The media's organization_id is then set to the supplied UUID; owner_id remains the service principal's sub. Without the header the existing fallback applies (the token's org_id claim, or NULL if absent). A user token granted media:act_as_any_org alone is NOT elevated — the principal-type factor is a deliberate defence-in-depth against accidental grant. The cross-org write is logged with the service principal's sub and target org for audit.

Validation order: filename → MIME allow/block → quota fast-path → stream to disk (max-size enforced authoritatively) → magic-byte sniff → rebuild against policy → metadata probe → DB row.

Original is never overwritten. For images, the upload pipeline additionally generates the low + medium variants (true thumbnails at 320 / 1280 px max) post-DB-save when IMAGE_EAGER_MEDIUM=true. Video / PDF / audio thumbnails are generated lazily on first GET /media/{id}?variant=low. Variant generation is best-effort — failure here logs a warning but the upload itself succeeds with the original committed.

Metadata probe runs at end of upload and writes type-specific facts to media.metadata: image/* → width, height (via the image crate) audio/* → duration_ms, bitrate_bps, sample_rate_hz, channels (via lofty) * video/* → duration_ms, width, height, bitrate_bps (via ffprobe)

Caller-supplied metadata (in the form body) wins per-key; the probe only fills keys the caller left empty.

Optional X-Deletion-Code header (per row). When present, server stores a sha256:<hex> hash of the supplied secret. Future deletes against this row must echo the same plaintext via the same header, or be refused with 403 DELETION_CODE_REQUIRED / INVALID_DELETION_CODE. Useful for service-to-service uploads where the panel web UI / other callers must not be able to delete files arbitrarily.

Caller is responsible for storing the plaintext code — server provides no recovery. Code must be 16-256 printable ASCII characters; out-of-range or non-printable input → 400.

Optional ?as=3d-model (per upload — ASYNCHRONOUS). Routes the upload through the 3D pipeline: Blender import/export → gltfpack compress → f3d render preview. Blender is the primary converter (accurate geometry + PBR materials + textures); assimp is a per-format fallback for inputs Blender can't read (e.g. .3ds) or transient Blender failures. Accepted inputs: .glb / .gltf (binary) — already self-contained .stl / .ply (ASCII or binary) — geometry-only .obj without mtllib declarations — bare geometry .zip / .tar.gz — must contain a recognisable entry (.obj+.mtl+textures, or .glb, .stl, etc.) * .fbx / .dae — Blender importers; .3ds via assimp fallback

Lifecycle. The endpoint returns 201 immediately once the original bytes are saved — it does NOT block on conversion. The response carries model_3d: true and model_3d_status: "processing". The pipeline runs detached (it survives client disconnect) and writes the final state to the same row:

model_3d_status: "ready" — variants web (full), web-medium, web-low (mobile default), and low (PNG thumbnail) are all on disk and listed. model_3d_status: "failed" — conversion errored; a short model_3d_error reason is recorded; the original file is kept (no rollback). Owner can re-trigger via POST /media/{id}/reprocess-3d.

Concurrency is capped by MEDIA_3D_MAX_CONCURRENCY (default 2); extra pipelines queue rather than thrash the host. On service restart, any row stuck in processing is swept to failed at startup so it's recoverable via reprocess.

Variant fetch while converting. GET /media/{id}?variant=web* for a model whose status is processing returns 202 Accepted with body {"error":"MODEL_3D_PROCESSING", ...} (distinct from 404 "no such 3D asset" and 200 ready). Clients should back off and retry after a refresh.

Reject conditions surfaced as model_3d_status: "failed" (the upload itself returns 201; the failure shows on the row): naked .obj with mtllib material.mtl — bundle it in a zip alongside the referenced material + textures archive with no recognisable 3D file inside archive past size caps (50 MB / file, 200 MB cumulative, 5 000 entries) — zip-bomb defence unsupported extension entirely

Disabled-feature (503 MODEL_3D_UNAVAILABLE returned synchronously on the upload itself): the host has no runnable Blender (MEDIA_BLENDER_BIN unset / not installed). The frontend reads model_3d_enabled from GET /health to warn before the user uploads.

When as is NOT set, even .glb / .stl uploads are stored as plain bytes — no 3D processing (no variants, no status field).

On any pre-conversion failure (auth, MIME, quota, body-parse) the staged blob is removed; the invariant "DB row ⇒ storage file exists" is preserved.