Folders & Tags

Folders

Folders are virtual containers within a collection that help you organize media items. They use an ltree path structure (e.g., collectionId.folder1.subfolder).

`sdk.folders.create(collectionId, name, path?)`

Create a new folder inside a collection.

Parameters:

Parameter	Type	Required	Description
`collectionId`	string	Yes	The parent collection
`name`	string	Yes	Display name for the folder
`path`	string	No	ltree path of the parent folder. Defaults to collection root

Returns: Promise<Folder>

// Create a folder at the collection root
const folder = await sdk.folders.create('collectionId', 'Spring 2026');
console.log(folder.id); // Use this ID in paths: 'collectionId.{folder.id}'

// Create a nested subfolder
const subfolder = await sdk.folders.create(
  'collectionId',
  'Week 1',
  'collectionId.parentFolderId'
);

Folder Object

Field	Type	Description
`id`	string	Unique folder ID
`name`	string	Display name
`path`	string	Full ltree path
`datasetId`	string	Parent collection ID

Folders in the media table

Folders are stored as type: "folder" entries in the media table. You'll see them when you call sdk.media.browse() — they have a type of "folder" and a blob of "folder".

Tags

Tags are key-value metadata attached to media items. They're organized as label (group) → value[] pairs.

Examples:

{ label: "color", value: "red" }
{ label: "category", value: "product" }
{ label: "season", value: "spring" }

`sdk.tags.list(collectionId)`

Aggregate all tag groups and their distinct values across an entire collection.

Parameters:

Parameter	Type	Required	Description
`collectionId`	string	Yes	The collection to aggregate tags from

Returns: Promise<Record<string, string[]>>

const tags = await sdk.tags.list('collectionId');
// {
//   color: ['red', 'blue', 'green'],
//   category: ['product', 'lifestyle', 'editorial'],
//   season: ['spring', 'summer']
// }

Use this to build filter UIs or understand how your collection is categorized.

Adding & Removing Tags

Tags are managed per-item via sdk.media.addTag() and sdk.media.removeTag(). See the Media reference for full details.

// Add tags to a media item
await sdk.media.addTag('mediaId', 'color', 'red');
await sdk.media.addTag('mediaId', 'category', 'product');

// Remove a tag
await sdk.media.removeTag('mediaId', 'color', 'red');

Browsing by Tag Filter

You can filter media by tags when browsing a collection:

const { media } = await sdk.media.browse('collectionId', {
  tagFilters: {
    category: ['product'],      // OR within a group
    season: ['spring', 'fall'], // AND between groups
  },
});

REST API Equivalents

SDK Method	HTTP	Endpoint
`folders.create()`	`POST`	`/api/folder`
`tags.list()`	`GET`	`/api/dataset/{collectionId}/tags`

Create Folder (curl)

curl -X POST https://lab.coreviz.io/api/folder \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "datasetId": "collectionId",
    "name": "Spring 2026",
    "path": "collectionId.parentFolderId"
  }'

curl https://lab.coreviz.io/api/dataset/COLLECTION_ID/tags \
  -H "Authorization: Bearer YOUR_TOKEN"

Next Steps

Media: Browse, search, and manage media items
Collections: List and create collections
MCP Server: Use folders and tags from Claude Code

Folders & Tags

On this page