Asset management
List, fetch, and soft-delete media assets and their metadata.
These endpoints manage the asset records themselves. All require
authentication and can return 400 / 401 / 403 / 404 / 500.
User callers only see and act on their own assets; service callers scope by owner_user_id.
List assets
GET /api/v1/media → 200 OK
What it is — Lists a user's assets, newest first, with offset pagination.
When to use it — Building an owner's media library or a management screen — e.g. every image and video a user uploaded across their places and posts.
How to use it — GET with optional status, limit, and offset. Omitting status returns
everything except soft-deleted; pass status=deleted to see deleted assets. Page with
offset += limit.
Scope — A user token lists its own assets; a service key lists the given
owner_user_id.
Query parameters
| Param | Type | Notes |
|---|---|---|
owner_user_id | string (1–255) | Required for service-key callers; ignored for JWT. |
status | "pending" | "uploaded" | "deleted" | Filter by upload status. |
limit | integer (1–100) | Defaults to 20. |
offset | integer (≥0) | Defaults to 0. |
curl "https://media.example.com/api/v1/media?status=uploaded&limit=20&offset=0" \
-H "Authorization: Bearer $ACCESS_TOKEN"Pagination is offset-based. Request the next page with offset = offset + limit. Each items
entry is a full MediaAsset (trimmed here).
Get an asset
GET /api/v1/media/{id} → 200 OK
What it is — Fetches a single asset's stored metadata (status, kind, provider, timestamps).
When to use it — Reading an asset's current state — e.g. polling status / stream_status
after an upload, or resolving your external_ref context — without re-signing provider playback.
How to use it — GET by id. Returns the stored row as-is; the embedded playback may be stale,
so call /playback to refresh it before playing. 404 if it
doesn't exist (or is deleted); 403 if a user caller doesn't own it.
Scope — Token owner or service key.
curl https://media.example.com/api/v1/media/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer $ACCESS_TOKEN"Delete an asset
DELETE /api/v1/media/{id} → 200 OK
What it is — Soft-deletes the asset and removes the underlying object — from R2 for file / on-prem-source assets, or from the streaming provider for Bunny/Cloudflare videos.
When to use it — The user removes media: deleting a place image, a note attachment, or a video.
How to use it — DELETE by id. The record is kept as status: "deleted" for auditability, but
the stored object is gone so existing presigned/playback URLs stop working. Idempotent — a second
delete returns 404.
Scope — Token owner or service key.
curl -X DELETE https://media.example.com/api/v1/media/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer $ACCESS_TOKEN"Deletion removes the stored object immediately, so existing presigned/playback URLs stop working.
The database record is retained with status: "deleted" for auditability.