Folders API
Create, manage, and organize assets into folders.
Folders are an organizational tool for grouping related assets. They do not affect widgets — widgets reference assets directly. All endpoints require JWT authentication.
Create folder
POST
/api/projects/{projectId}/foldersJWTRequest body
| Name | Type | Default | Description |
|---|---|---|---|
name* | string | — | Folder display name |
slug* | string | — | URL-friendly identifier, unique within the project |
description | string | — | Optional description |
Request
{
"name": "Hero Banners",
"slug": "hero-banners",
"description": "Homepage hero images"
}Response 201
Response
{
"id": "990e8400-e29b-41d4-a716-446655440000",
"projectId": "770e8400-e29b-41d4-a716-446655440000",
"name": "Hero Banners",
"slug": "hero-banners",
"description": "Homepage hero images",
"createdAt": "2026-01-15T10:30:00",
"updatedAt": "2026-01-15T10:30:00"
}List folders
GET
/api/projects/{projectId}/foldersJWTResponse 200
Returns an array of folder objects.
Get folder
GET
/api/projects/{projectId}/folders/{folderId}JWTResponse 200
Returns the folder object.
Update folder
PUT
/api/projects/{projectId}/folders/{folderId}JWTRequest body
| Name | Type | Default | Description |
|---|---|---|---|
name* | string | — | Updated folder name |
description | string | — | Updated description |
Response 200
Returns the updated folder object.
Delete folder
DELETE
/api/projects/{projectId}/folders/{folderId}JWTResponse 204
No content.
Deleting a folder does not delete the assets in it — they become unfiled. Widgets that reference those assets are not affected.
List folder assets
GET
/api/projects/{projectId}/folders/{folderId}/assetsJWTResponse 200
Returns an array of asset objects in the folder.
Move assets to folder
POST
/api/projects/{projectId}/folders/{folderId}/assetsJWTRequest body
| Name | Type | Default | Description |
|---|---|---|---|
assetIds* | UUID[] | — | Array of asset IDs to move into this folder |
Request
{
"assetIds": [
"880e8400-e29b-41d4-a716-446655440000",
"880e8400-e29b-41d4-a716-446655440001"
]
}Remove asset from folder
DELETE
/api/projects/{projectId}/folders/{folderId}/assets/{assetId}JWTResponse 204
No content. The asset becomes unfiled but is not deleted.