GuidesAPI ReferenceChangelog
Guides
Start Free Trial

Playlists

Organizing VOD and livestreams into playlists

Playlists group VOD and live channels so viewers can watch a series in one player. This guide covers create, lookup, replace content, update metadata, 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. Create, lookup, and content update return 200. Delete returns 204.

The content endpoints are under /v2/playlists (plural).

Setting playlist items is a full replace, not a delta: every PUT ā€¦/content must send the complete list you want after the change. To add an item, include the existing items plus the new one. To remove an item, omit it. To reorder, send the same ids with new position values.

A VOD must be online before you can add it to a playlist. After PUT ā€¦/content, content.list on that response may still be null - confirm with GET /v2/playlists/{id} (indexing can lag).

1. Create a playlist

curl -X POST "https://developer.dacast.com/v2/playlists" \
  -H "X-Api-Key: insertYourApiKeyHere" \
  -H "X-Format: default" \
  -H "Content-Type: application/json" \
  -d "{\"title\":\"My Test Playlist\",\"description\":\"A first test playlist\"}"
const headers = new Headers();
headers.append('X-Api-Key', 'insertYourApiKeyHere');
headers.append('X-Format', 'default');
headers.append('Content-Type', 'application/json');

fetch('https://developer.dacast.com/v2/playlists', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    title: 'My Test Playlist',
    description: 'A first test playlist'
  })
})
  .then((response) => response.json())
  .then((playlist) => {
    // store playlist.id
  });

Store id from the 200 response. Optional create fields (see Create Playlist): online, password, google_analytics, theme_id, referers_id, countries_id.

A new playlist has an empty content list:

{
  "id": "a4c11578-d1e4-3e1e-4d0b-2f4635bec0c0",
  "title": "My Test Playlist",
  "description": "A first test playlist",
  "content": {
    "list": null,
    "start_time": "00:00:00"
  }
}

2. Look up the playlist

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

Use content.list as the current membership. Each item has id, type (vod or channel), position, and title. position may be a number or a string - treat it as a string when comparing.

After the playlist contains a VOD, lookup looks like:

{
  "ads": null,
  "asset_id": "8f2facdc-1a29-5903-bffb-8414b3ee5da5-playlist-efdf4706-988c-8c05-cdcb-04098b4a873d",
  "autoplay": false,
  "company_url": null,
  "content": {
    "list": [
      {
        "id": "dc090404-8554-45ed-aafc-944bad359597",
        "position": "1",
        "thumbnail_id": "1",
        "title": "sample_video2.MOV",
        "type": "vod"
      }
    ],
    "start_time": "00:00:00"
  },
  "countdown_date": "",
  "countdown_timezone": "",
  "counter_live_limit": -1,
  "countries_id": "",
  "creation_date": "2026-08-17T15:03:54Z",
  "custom_data": null,
  "description": "",
  "enable_payperview": false,
  "enable_subscription": false,
  "external_video_page": "http://",
  "google_analytics": "false",
  "id": "efdf4706-988c-8c05-cdcb-04098b4a873d",
  "logo_url": null,
  "noframe_security": 0,
  "online": true,
  "password": null,
  "pictures": {
    "splashscreen": null,
    "thumbnail": null
  },
  "player_height": 0,
  "player_size_id": 10,
  "player_width": 0,
  "publish_on_dacast": true,
  "save_date": "2026-08-17T15:03:54Z",
  "stream_category": 0,
  "theme_id": "8cd97b5d-a7f7-4c98-342b-d49b4625d398",
  "title": "My Test Playlist"
}
šŸš§

online means the playlist is enabled for playback, not that an item is currently playing.

To list playlists: GET /v2/playlists?page=1&per_page=15.

3. Set playlist content (replace)

Set Playlist Content: PUT /v2/playlists/{playlistId}/content.

Build the full list of objects { id, type, position }, then send it as a JSON string in the content field - not as a raw array:

{
  "content": "[{\"id\":\"dc090404-8554-45ed-aafc-944bad359597\",\"type\":\"vod\",\"position\":1}]"
}
curl -X PUT "https://developer.dacast.com/v2/playlists/{playlistId}/content" \
  -H "X-Api-Key: insertYourApiKeyHere" \
  -H "X-Format: default" \
  -H "Content-Type: application/json" \
  -d "{\"content\":\"[{\\\"id\\\":\\\"VOD_OR_CHANNEL_ID\\\",\\\"type\\\":\\\"vod\\\",\\\"position\\\":1}]\"}"
const items = [
  { id: 'VOD_OR_CHANNEL_ID', type: 'vod', position: 1 }
];

fetch('https://developer.dacast.com/v2/playlists/' + playlistId + '/content', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'insertYourApiKeyHere',
    'X-Format': 'default',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ content: JSON.stringify(items) })
});
ActionHow
AddGET current list, append { id, type, position }, PUT the whole list
RemoveGET current list, drop that object, PUT what remains (empty list = {"content":"[]"})
ReorderPUT the same ids with new position values, or send positions (an array of { id, position }, also as a JSON string). If both content and positions are set, content wins.

type must be vod or channel. Source ids from List videos and Lookup Stream / the channel list.

Then poll lookup until content.list contains the expected ids.

4. Update playlist metadata

Title and description are a separate call - not /content:

curl -X PUT "https://developer.dacast.com/v2/playlists/{playlistId}" \
  -H "X-Api-Key: insertYourApiKeyHere" \
  -H "X-Format: default" \
  -H "Content-Type: application/json" \
  -d "{\"title\":\"Updated playlist title\",\"description\":\"Updated description\"}"

5. Delete

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

Expect 204.

After the playlist exists

Updated about 16 hours ago