Folders
List folders
GET /api/v1/folders
Returns a paginated list of folders.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
parentId | string | — | Filter to a specific parent folder (omit for all folders) |
limit | integer | 50 | Results per page (max 200) |
offset | integer | 0 | Pagination offset |
Create a folder
POST /api/v1/folders
Requires write permission.
Body
{
"name": "Product shots",
"parentId": null,
"description": "Q2 campaign assets"
}
Folder names must be unique within the same parent. Returns 409 DUPLICATE_FOLDER on collision.
Get a folder
GET /api/v1/folders/:id
Returns the folder with its fileCount, childCount, and immediate children array.
Update a folder
PATCH /api/v1/folders/:id
Requires write permission. Update the name, description, or parent folder.
Body
{ "name": "Campaign assets", "parentId": "clx2xyz789" }
Moving a folder into itself or one of its own subfolders returns 400 CIRCULAR_REFERENCE.
Delete a folder
DELETE /api/v1/folders/:id
Requires delete permission. Returns 400 FOLDER_NOT_EMPTY if the folder has contents unless you append ?deleteContents=true.
Example
curl -X DELETE "https://medianest.app/api/v1/folders/clx1abc123?deleteContents=true" \
-H "X-API-Key: mn_your_key"