Folders

Folders are virtual containers stored as type=folder entries in the media table. They use the PostgreSQL ltree extension for hierarchical paths (e.g., collectionId.parentFolderId.childFolderId).

Create a Folder

POST /api/folder

Request Body

Field	Type	Required	Description
`datasetId`	string	Yes	The collection ID (UUID, hyphens are allowed)
`name`	string	Yes	Display name for the folder
`path`	string	No	ltree path of the parent folder. Defaults to the collection root
`reuse`	boolean	No	If `true`, returns an existing folder with the same name at the same parent instead of creating a duplicate

Example Requests

# Create a root-level folder
curl -X POST https://lab.coreviz.io/api/folder \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datasetId": "COLLECTION_ID",
    "name": "Spring 2026"
  }'

# Create a nested subfolder
curl -X POST https://lab.coreviz.io/api/folder \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datasetId": "COLLECTION_ID",
    "name": "Week 1",
    "path": "collectionId.parentFolderId"
  }'

Response

Status Code: 200 OK

{
  "folder": {
    "id": "newFolderId123",
    "name": "Spring 2026",
    "type": "folder",
    "blob": "folder",
    "path": "collectionId.newFolderId123",
    "datasetId": "COLLECTION_ID",
    "status": "active",
    "createdAt": "2026-03-23T10:00:00.000Z",
    "createdById": "userId456"
  }
}

Folder IDs in paths

The id in the response is a UUID without hyphens. Use it to build nested paths: parentPath.{folder.id}.

Error Responses

Status	Description
`400`	Missing `datasetId`
`401`	Missing or invalid authentication
`403`	No organization access or insufficient role (requires `admin` or `owner`)
`404`	Collection not found

Listing Folders

Folders appear in GET /api/dataset/{collectionId}/media results as items with type: "folder". They include:

folderItemCount — total images/videos inside
folderPreviews — up to 3 preview URLs from the folder's contents

curl -H "x-api-key: YOUR_API_KEY" \
  "https://lab.coreviz.io/api/dataset/COLLECTION_ID/media?type=folder"

Renaming & Moving Folders

Use the same endpoints as for media items:

Rename: PATCH /api/media/{folderId} with { "name": "New Name" }
Move: PATCH /api/media/{folderId}/move with { "destinationPath": "..." }

When moving a folder, all descendants are moved atomically.

JavaScript Example

// Create folder
const { folder } = await fetch('https://lab.coreviz.io/api/folder', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    datasetId: 'COLLECTION_ID',
    name: 'Spring 2026',
  }),
}).then(r => r.json());

console.log(folder.id);   // Use this in path for nested folders
console.log(folder.path); // e.g. "collectionId.newFolderId123"

Folders

On this page