Folders
Folders organize assets hierarchically within a project without changing asset IDs or CDN URLs. Folders and assets are always addressed by ID; names are display values, unique among siblings.
Guide: Organising assets.
Endpoints
| Endpoint | Description |
|---|---|
GET / | List all asset folders in a project |
POST / | Create an asset folder with an optional parent folder ID |
GET / | Get an asset folder by ID |
PATCH / | Rename an asset folder |
DELETE / | Delete an empty asset folder by ID |
POST / | Move a folder under another folder, or to the project root |
POST / | Move an asset into a folder, or to the project root |
The folder object
| Field | Type | Presence | Description |
|---|---|---|---|
id | string | Required | Unique folder ID |
projectId | string | Required | ID of the project that owns the folder |
parentId | string | Optional, nullable | ID of the parent folder; null for folders at the project root |
name | string | Required | Display name, unique among folders with the same parent. 1 to 100 characters, without slashes. |
createdAt | integer | Required | When the folder was created, in milliseconds since the Unix epoch |
updatedAt | integer | Optional | When the folder was last updated, in milliseconds since the Unix epoch |
Endpoint details
import { CalmLensClient } from "@calmlens/sdk";
const client = new CalmLensClient({
apiKey: "your-api-key",
projectId: "your-project-id"
});
const response = await client.folders.list();
Response
folders[]Folder[]Required
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
404
project/not-foundProject not found
import { CalmLensClient } from "@calmlens/sdk";
const client = new CalmLensClient({
apiKey: "your-api-key",
projectId: "your-project-id"
});
const response = await client.folders.create({});
Response
Folder
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
404
project/not-foundProject not found
404
folder/not-foundFolder not found
409
folder/duplicate-nameA folder with this name already exists in this location.
import { CalmLensClient } from "@calmlens/sdk";
const client = new CalmLensClient({
apiKey: "your-api-key",
projectId: "your-project-id"
});
const response = await client.folders.retrieve({});
Response
Folder
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
404
project/not-foundProject not found
404
folder/not-foundFolder not found
import { CalmLensClient } from "@calmlens/sdk";
const client = new CalmLensClient({
apiKey: "your-api-key",
projectId: "your-project-id"
});
const response = await client.folders.update({});
Response
Folder
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
404
project/not-foundProject not found
404
folder/not-foundFolder not found
409
folder/duplicate-nameA folder with this name already exists in this location.
import { CalmLensClient } from "@calmlens/sdk";
const client = new CalmLensClient({
apiKey: "your-api-key",
projectId: "your-project-id"
});
const response = await client.folders.delete({});
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
404
project/not-foundProject not found
404
folder/not-foundFolder not found
409
folder/not-emptyFolder must be empty before it can be deleted.
import { CalmLensClient } from "@calmlens/sdk";
const client = new CalmLensClient({
apiKey: "your-api-key",
projectId: "your-project-id"
});
const response = await client.folders.move({});
Response
Folder
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
404
folder/not-foundFolder not found
409
folder/duplicate-nameA folder with this name already exists in this location.
409
folder/parent-cycleA folder cannot be moved inside itself or one of its descendants.
import { CalmLensClient } from "@calmlens/sdk";
const client = new CalmLensClient({
apiKey: "your-api-key",
projectId: "your-project-id"
});
const response = await client.assets.move({});
Response
Asset
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
404
asset/not-foundAsset not found
500
asset/update-failedFailed to update asset
423
asset/safety-heldAsset access is restricted by a safety hold.
404
folder/not-foundFolder not found