Organising assets

Use folders to organise content and scope access, metadata to attach structured information, and external IDs to connect assets to your own records.

External IDs

An externalId links an asset to the record it belongs to in your application, such as post-42 or comment-981. Use a stable ID that won't change.

WhereHow it's used
UploadingSet externalId on the upload, or in an upload token for browser uploads. Update it later on the asset.
Events and webhooksEvery asset event carries it as asset.externalId, so your receiver can update the record without a lookup.
CDN URLsUse it in place of the asset ID, as in /assets/{projectId}/post-42/rendered, so you can build URLs from your own records.
SearchSearching assets matches any part of it, and ranks exact and prefix matches first.

It's unique within a project: a second asset with the same ID returns 409 asset/duplicate-external-id, which also stops a retried upload creating a duplicate. Give each version its own ID when the same record is checked again, such as an edited comment. API requests address assets by their asset ID, so save that too if you'll fetch, update or delete them. Folders and moves change neither ID nor the CDN URLs.

Asset metadata

Attach custom metadata as an array of { id, value } items. To use a value for portal filtering or grouping, first define a field with the same ID in Portal › Metadata fields. The field title and type control how the item appears in the portal; uploaded values remain JSON values and are not checked against the field type.

import { readFile } from "node:fs/promises";

const asset = await client.assets.create({
  name: "campaign-image.jpg",
  content: { buffer: await readFile("./campaign-image.jpg"), type: "image/jpeg" },
  metadata: [{ id: "campaign.id", value: "launch-2026" }],
});

For POST /projects/:projectId/assets, include the same metadata array in the JSON body. For the direct binary and streamed multipart endpoints, pass the JSON array as the URL-encoded metadata query parameter; the SDKs handle this encoding.

File metadata

CalmLens reads the descriptive metadata embedded in each uploaded image (EXIF, XMP and IPTC) before storing it, and returns it as content.metadata. It's read-only, separate from the asset's own metadata, and shown on the asset's page in the portal. JPEG, PNG, APNG, WebP, HEIC, AVIF, TIFF, JPEG XL, JPEG 2000 and Photoshop images are read, as is the XMP of GIF images; other asset types, and images that declare none of these fields, have null.

FieldValue
capturedAtWhen the picture was taken, as an ISO 8601 date and time. It includes a UTC offset only when the file records one; otherwise it's the camera's local time.
cameraMake, cameraModel, lensModelThe camera, phone and lens.
softwareThe software that created or last edited the file.
copyrightThe copyright notice the file declares.
digitalSourceTypeThe IPTC digital source type the file declares, such as digitalCapture or trainedAlgorithmicMedia.
containsLocationWhether the uploaded file embedded GPS coordinates.
creatorThe creator the file names. Sensitive.
locationWhere the picture was taken, as latitude and longitude in decimal degrees. Sensitive.

Anyone can edit a file's metadata, so treat these values as what the file claims, not proof of when or how it was made. They are removed with the asset's content and hidden while the asset is held.

Sensitive metadata

Embedded metadata can carry a photo's GPS location, the serial numbers of the camera and lens, and the names of the people who took or own it. By default, CalmLens removes the EXIF, XMP and IPTC metadata from JPEG, PNG, APNG, WebP, GIF, HEIC, AVIF, TIFF, JPEG XL, JPEG 2000 and Photoshop (PSD and PSB) images before storing them, along with GIF and JPEG 2000 comments, keeping only their orientation, colour profile and animation looping, and content.metadata leaves out creator and location. Photoshop documents also lose each layer's metadata, their annotations and the files placed in them as smart objects; their layers and merged image stay. SVG images lose their metadata elements, comments and the file names and paths that editors record, and the photos they embed lose their metadata too. The stored file is the one the CDN serves as original, and content.sizeInBytes and content.checksums describe it, not the file as uploaded.

Turn on Store sensitive metadata to store images exactly as uploaded and record their creator and location. Set processingOptions.storeSensitiveMetadata to choose for a single upload or an upload preset; it overrides the project setting either way.

Tags

Tags are short labels in an asset's tags array, such as ["catalogue", "backpacks"]. Set them when uploading with the tags option: in the JSON body of POST /projects/:projectId/assets, or as a URL-encoded JSON array in the tags query parameter of the direct binary and streamed multipart endpoints, like metadata. Set or replace them later with PATCH /assets/:assetId, the SDKs' asset update method. Filter by tag with tags=in=(catalogue) (see Asset filters), and pass the matching asset IDs to POST /projects/:projectId/assets/batch to delete them or remove their content.

Folders

Folders organize assets hierarchically within a project without changing asset IDs or CDN URLs. Like files in a filesystem, folders can contain assets and nested subfolders. Pass a folderId when you upload to put the new asset straight into a folder. See the Folders API reference for complete folder endpoint references and schemas.

  • Stable IDs: Folders and assets are identified by immutable IDs, such as fldr_7Nc4Wq2Lm8Xt5Rk9Bv3P for a folder. Folder names and paths are display values and cannot be used as resource identifiers in API calls.
  • Nesting: Create folders with POST /projects/:projectId/folders at the project root (parentId: null or omitted) or nested under an existing folder by passing its parentId.
  • Renaming: Rename a folder with PATCH /folders/:folderId.
  • Moving: Move a folder with POST /folders/:folderId/move and { "parentId": string | null }, and an asset with POST /assets/:assetId/move and { "folderId": string | null }. Pass null to move a folder or asset to the project root. Moving a folder changes the access of everything inside it, so it needs Manage project (project:manage), held by administrators.
  • Name uniqueness: Folder names must be unique among siblings sharing the same parent folder (or at the root). The same folder name can be used in different branches of the folder tree.
  • Hierarchy cycles: Moving a folder into itself or one of its descendants is rejected with 409 folder/parent-cycle.
  • Safe deletion: Only empty folders can be deleted. Attempting to delete a folder that still contains assets or child folders is rejected with 409 folder/not-empty.
const parent = await client.folders.create({ name: "Campaigns" });
const child = await client.folders.create({ name: "Launch", parentId: parent.id });

await client.assets.move({ assetId: asset.id, folderId: child.id });
await client.folders.move({ folderId: child.id, parentId: null });

To manage the folder tree itself:

// 1. Create a root folder
const marketing = await client.folders.create({
  name: "Marketing",
});

// 2. Create a nested child folder
const campaigns = await client.folders.create({
  name: "Campaigns",
  parentId: marketing.id,
});

// 3. List all folders in the project
const folders = await client.folders.list();

// 4. Retrieve a folder by ID
const folder = await client.folders.retrieve({
  folderId: campaigns.id,
});

// 5. Rename a folder
const updated = await client.folders.update({
  folderId: campaigns.id,
  name: "Summer Campaigns",
});

// 6. Move an asset into a folder
await client.assets.move({
  assetId: "asset_5Gm2Rk8XqT3wLp9VbN4c",
  folderId: campaigns.id,
});

// 7. Move an asset back to the project root
await client.assets.move({
  assetId: "asset_5Gm2Rk8XqT3wLp9VbN4c",
  folderId: null,
});

// 8. Move a folder under another parent or to root
await client.folders.move({
  folderId: campaigns.id,
  parentId: null, // Move to root
});

// 9. Delete an empty folder
await client.folders.delete({
  folderId: campaigns.id,
});

Find assets

See Pagination and filtering to query assets and Members and permissions to restrict access by folder.

Last updated

Signing in

Signing out

Cookies on CalmLens

We use essential cookies for sign-in and security. With your permission, functional cookies remember your preferences and Google Analytics measures website use and signups. Optional ad measurement cookies link Google ad clicks to signups. Personalised advertising stays off. Manage cookies