Media

The media endpoints handle generic file attachments — images, documents, or other assets that can be attached to scene blocks.

Endpoints overview

Method	Endpoint	Permission	Description
GET	/api/media/file/*	—	Download media file (public)
POST	/api/media/upload	scene:block:media:attach	Upload a media file
DELETE	/api/media/file/*	scene:block:media:delete	Delete a media file

Endpoints

Download media file

GET /api/media/file/*

Public — no authentication required. The wildcard supports arbitrarily nested paths.

Example: GET /api/media/file/proj-uuid/ep-uuid/scene-uuid/media/image.png

---

Upload media file

POST /api/media/upload — Auth required, multipart/form-data, Permission: scene:block:media:attach

Form fields:

Field	Type	Required
file	any file	yes
projectId	string (UUID)	no — used to build storage path
episodeId	string (UUID)	no — used to build storage path
sceneId	string (UUID)	no — used to build storage path

When projectId, episodeId, and sceneId are all provided, the file is stored at {projectId}/{episodeId}/{sceneId}/media/{filename}. Otherwise a flat path is used.

Response — 201

{
  "data": {
    "url": "/api/media/file/proj-uuid/ep-uuid/scene-uuid/media/image.png",
    "filename": "image.png"
  }
}

---

Delete media file

DELETE /api/media/file/* — Auth required, Permission: scene:block:media:delete

Deletes the file at the specified path.

Example: DELETE /api/media/file/proj-uuid/ep-uuid/scene-uuid/media/image.png

Response — 204