Collections

Collections are folders in a tree. Use the Client API to list them and walk your library from code.

List Collections

GET /collections

Returns child collections under a given path.

Authentication

All Client API requests require a Bearer token:

Authorization: Bearer YOUR_API_KEY

Generate API keys in Settings > General. Keys are shown once at creation.

Parameters

Example request

curl "https://your-domain.com/api/client/v1/collections?path=root/marketing" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "name": "Campaigns",
      "path": "root/marketing/campaigns"
    },
    {
      "name": "Tutorials",
      "path": "root/marketing/tutorials"
    }
  ]
}

An empty data array means the path exists but has no child folders.

Errors

Path format

• root: Top-level collection
• root/folder: Sub-folder
• root/folder/subfolder: Nested path

Collection names are case-sensitive and must match exactly as created in the admin panel.

Path rules

Paths always start with root (not bare marketing), use / between segments, no trailing slash, and spaces are fine if you created the folder that way in the UI (root/My Folder).

Navigating the tree

List the root first, then drill into children:

# Root folders
curl "https://your-domain.com/api/client/v1/collections?path=root" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Children of marketing
curl "https://your-domain.com/api/client/v1/collections?path=root/marketing" \
  -H "Authorization: Bearer YOUR_API_KEY"

Combine with Videos API to list videos in a collection:

curl "https://your-domain.com/api/client/v1/videos?path=root/marketing" \
  -H "Authorization: Bearer YOUR_API_KEY"

Uploading to a collection

When uploading via API, pass the full collection path as folder:

curl -X POST "https://your-domain.com/api/client/v1/uploads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "folder=root/marketing/campaigns"

The target collection must exist. Create folders in the admin panel before API upload.

Collection metadata

Collections can have custom metadata fields in Settings > Metadata. The collections list endpoint doesn't return metadata. Fetch video or collection details from the admin API, or filter the video list.

Security profiles

Collections can inherit security profiles (domain restrictions, geo rules, encryption). Shared collection links respect the assigned profile. See Security.

Rate limits

The Client API has no hard rate limits by default, but polling too aggressively will load the server. Poll upload status every 5 to 10 seconds, not sub-second.

Example: sync folder structure

#!/bin/bash
API_KEY="your_key"
BASE="https://your-domain.com/api/client/v1"

function list_children() {
  local path="$1"
  curl -s "${BASE}/collections?path=${path}" \
    -H "Authorization: Bearer ${API_KEY}" | jq '.data[]'
}

list_children "root"
list_children "root/marketing"

List videos in a folder: Videos API. Upload into one: Uploads API. Panel workflow: VOD Uploads.