Folders

Organizing content with folders

Folders group VOD in the dashboard and via the API. This guide covers create, list, lookup, rename/move, add a VOD to a folder, and delete.

📘

All examples use https://developer.dacast.com as the API host. Authenticate with X-Api-Key and send X-Format: default. JSON bodies must include Content-Type: application/json. Folder create, list, lookup, and update return 200. Delete returns 204.

Folder endpoints use /v2/folder (singular). Folder id values are numeric strings (for example "1259852"), not UUIDs.

Membership is on the VOD: send folder_ids on PUT /v2/vod/{id}. Confirm with the folders array on GET /v2/vod/{id} — folder_ids on the VOD response is often null even when the asset is in a folder.

1. Create a folder

Send full_path as an absolute path starting with /. Nested folders use multiple segments.

curl -X POST "https://developer.dacast.com/v2/folder" \
  -H "X-Api-Key: insertYourApiKeyHere" \
  -H "X-Format: default" \
  -H "Content-Type: application/json" \
  -d "{\"full_path\":\"/Conference sessions\"}"

fetch('https://developer.dacast.com/v2/folder', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'insertYourApiKeyHere',
    'X-Format': 'default',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ full_path: '/Conference sessions' })
})
  .then((response) => response.json())
  .then((folder) => {
    // store folder.id
  });

A successful create returns 200. The body includes id, path (the full path you created), created_at, and user_id. It does not include name — that appears on lookup.

{
  "created_at": "1787244076",
  "id": "1259852",
  "path": "/Conference sessions",
  "user_id": "bf30116f-5b67-2982-3796-230598aaa41c"
}

Nested example: "/Conference sessions/Day 1".

See Create Folder. After create, list/search by title can lag — poll list or lookup by id.

2. List folders

curl "https://developer.dacast.com/v2/folder?page=1&per_page=25&title=Conference" \
  -H "X-Api-Key: insertYourApiKeyHere" \
  -H "X-Format: default"

The response has data, lowercase paging (first / last / next / previous as URL path strings), and total_count (a string). Query size accepts per_page or perpage; paging links use perpage.

See List Folders.

3. Look up a folder

curl "https://developer.dacast.com/v2/folder/{folderId}" \
  -H "X-Api-Key: insertYourApiKeyHere" \
  -H "X-Format: default"

For a root folder, name is the title and path is /. For a nested folder, name is the leaf segment and path is the parent path (often with a trailing /).

{
  "created_at": "1787244076",
  "id": "1259852",
  "name": "Conference sessions",
  "path": "/",
  "user_id": "bf30116f-5b67-2982-3796-230598aaa41c"
}

See Lookup Folder.

4. Rename or move a folder

Use PATCH (not PUT) with the fields you want to change:

curl -X PATCH "https://developer.dacast.com/v2/folder/{folderId}" \
  -H "X-Api-Key: insertYourApiKeyHere" \
  -H "X-Format: default" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"Highlighted sessions\"}"

After 200, confirm with lookup — the PATCH body can briefly show the previous name or path.

See Update Folder.

5. Add a VOD to a folder

There is no separate “folder content” endpoint. Update the VOD with Update Video:

1. GET /v2/vod/{vodId} and read current membership from folders (array of { id, name, path }, or empty/null).
2. Build folder_ids as the existing folder ids plus the new folder id.
3. PUT /v2/vod/{vodId} with that folder_ids array.
4. Poll GET /v2/vod/{vodId} until folders includes the new id.

curl -X PUT "https://developer.dacast.com/v2/vod/{vodId}" \
  -H "X-Api-Key: insertYourApiKeyHere" \
  -H "X-Format: default" \
  -H "Content-Type: application/json" \
  -d "{\"folder_ids\":[\"1259852\"]}"

const folderIds = ['1259852']; // merge with ids from vod.folders

fetch('https://developer.dacast.com/v2/vod/' + vodId, {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'insertYourApiKeyHere',
    'X-Format': 'default',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ folder_ids: folderIds })
});

Always merge with existing folder ids so you do not drop other folders the asset already belongs to when you intend to add one.

🚧

Yes, we know: the API will happily put a VOD into a folder and then pretend not to hear you when you ask to take it back out. Empty folder_ids, omitting an id, null — all of that is a polite no-op. We will fix this. Someday.

Until then, the only API move that clears membership is deleting the folder (step 6). The media itself is kept.

6. Delete a folder

curl -X DELETE "https://developer.dacast.com/v2/folder/{folderId}" \
  -H "X-Api-Key: insertYourApiKeyHere" \
  -H "X-Format: default"

Expect 204 with an empty body. Media in the folder is not deleted. Nested child folders under the deleted folder are also removed. After 204, lookup can briefly still return the folder before it disappears.

See Delete Folder.

Reference

• Create Folder
• List Folders
• Lookup Folder
• Update Folder
• Delete Folder
• Update Video — folder_ids