Files

List files

GET /api/v1/files

Returns a paginated list of your files.

Query parameters

Parameter	Type	Default	Description
`limit`	integer	`20`	Results per page (max 100)
`offset`	integer	`0`	Pagination offset
`folderId`	string	—	Filter by folder
`type`	string	—	Filter by file type: `IMAGE`, `VIDEO`, `AUDIO`, `DOCUMENT`
`search`	string	—	Search by filename or tag

Example

curl "https://medianest.app/api/v1/files?type=IMAGE&limit=10" \
  -H "X-API-Key: mn_your_key"

Get a file

GET /api/v1/files/:id

Returns a single file by ID.

Example

curl https://medianest.app/api/v1/files/clx1abc123 \
  -H "X-API-Key: mn_your_key"

Update file metadata

PATCH /api/v1/files

Requires write permission. Updates tags, description, visibility, or folder assignment.

Body

{
  "id": "clx1abc123",
  "tags": ["hero", "landing"],
  "description": "Homepage hero image",
  "isPublic": true
}

Delete a file

DELETE /api/v1/files/:id

Requires delete permission. Deletion is permanent: the file is removed from storage, then its record. If storage is briefly unavailable the file is hidden right away, purged is false, and its bytes count toward your quota until the removal is confirmed.

To delete up to 100 files at once, POST /api/v1/files/bulk-delete with { "ids": ["..."] }. The response lists deleted, pending and notFound IDs.

Example

curl -X DELETE https://medianest.app/api/v1/files/clx1abc123 \
  -H "X-API-Key: mn_your_key"

Response

{ "success": true, "data": { "deleted": true, "id": "clx1abc123", "purged": true } }