Media and files API

8 endpoints (6 media + 2 room-files).

Media#

Method	Path	Purpose
`POST`	`/v1/media/upload`	Upload a file. Multipart.
`GET`	`/v1/media/{media_id}/info`	Metadata (sha256, size, mime, dimensions).
`GET`	`/v1/media/download/{media_id}`	Download bytes.
`GET`	`/v1/media/download/{media_id}/thumbnail`	Pre-generated thumbnail (images/videos).
`GET`	`/v1/media/signed/{media_id}`	Get a short-lived signed URL (no auth header needed).
`POST`	`/v1/transcribe`	Submit an audio file for transcription.

POST /v1/media/upload#

bash
curl -X POST "$BASE/v1/media/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@./photo.jpg" \
  -F "tenant_scope=true"

Returns:

json
{
  "data": {
    "media_id": "med-…",
    "sha256": "abc123…",
    "size": 184234,
    "mime_type": "image/jpeg",
    "thumbnail_id": "med-thumb-…",
    "width": 1920,
    "height": 1080,
    "scan_status": "clean"
  }
}

scan_status is pending immediately, becomes clean or infected once ClamAV has scanned. Infected files are auto-deleted; references to them 404.

POST /v1/transcribe#

bash
curl -X POST "$BASE/v1/transcribe" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@./meeting.m4a" \
  -F "language=en"

Async — returns immediately with a job_id:

json
{ "data": { "job_id": "job-…", "status": "queued" } }

Poll GET /v1/jobs/{job_id} (under Queue and scheduled tasks) for completion. The result includes:

json
{
  "data": {
    "transcript": "Full text…",
    "segments": [{ "start": 0, "end": 3.2, "text": "Hello" }, …],
    "language": "en",
    "duration": 312.4
  }
}

Room file index#

Files uploaded into a room are tracked in a per-room index so the client can show a "Files" tab.

Method	Path	Purpose
`GET`	`/v1/rooms/{room_id}/files`	List media attached in this room.
`DELETE`	`/v1/rooms/{room_id}/files/{media_id}`	Remove from the index (doesn't delete the media).

Storage#

All media goes to MinIO/S3 via the path tenant/{tenant_id}/{sha256}. Content-addressable: uploading the same file twice (same sha256) dedupes server-side.

Quotas#

Per-tenant max_storage_mb. Hit returns 413.

Signed URLs#

For clients that can't include auth headers (image tags, embedded players), use /v1/media/signed/{media_id} to get a URL valid for the next 5 minutes:

jsonc

{
  "data": {
    "url": "https://...minio.../tenant/.../sha256?X-Amz-...",
    "expires_at": "2026-05-17T14:05:00Z"
  }
}