Playlists API

Group videos and live streams into ordered, named collections you can render as carousels, grids, or paginated channels on your storefront. Playlists are creator-scoped — each pk_* key only sees and mutates its own account's playlists. Items can be either a videoId or a streamId.

Endpoints

List my playlists

curl -s -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
  "https://api.dcast.pro/api/v1/me/playlists?page=1&limit=20"

# Response
{
  "success": true,
  "data": {
    "playlists": [
      {
        "id": "cmpl…",
        "title": "Yoga essentials",
        "description": "Morning + evening flows",
        "isPublic": true,
        "itemCount": 12,
        "createdAt": "2026-05-25T10:00:00.000Z",
        "updatedAt": "2026-05-27T18:42:11.000Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 7, "pages": 1 }
  }
}

page 1-indexed, limit clamped to 1–100 (default 20). Sorted newest-first by updatedAt.

Create a playlist

curl -s -X POST https://api.dcast.pro/api/v1/playlists \
  -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Yoga essentials",
    "description": "Morning + evening flows",
    "isPublic": true
  }'

Required: title (1–200 chars). Optional: description (0–4000 chars, sanitized), isPublic (default true). 201 on create.

Read a playlist (public)

curl -s https://api.dcast.pro/api/v1/playlists/{playlistId}

# Response
{
  "success": true,
  "data": {
    "id": "cmpl…",
    "title": "Yoga essentials",
    "description": "Morning + evening flows",
    "isPublic": true,
    "userId": "…",
    "createdAt": "2026-05-25T10:00:00.000Z",
    "updatedAt": "2026-05-27T18:42:11.000Z",
    "items": [
      {
        "id": "cmpli…",
        "position": 0,
        "videoId": "…",
        "streamId": null,
        "video": { "id": "…", "title": "…", "thumbnailUrl": "…", "duration": 509 }
      },
      {
        "id": "cmpli…",
        "position": 1,
        "videoId": null,
        "streamId": "9c283f07…"
      }
    ],
    "itemCount": 2,
    "owner": { "username": "pamela", "displayName": "Pamela Reif" }
  }
}

No auth required for isPublic=true playlists. Private playlists return 404 NOT_FOUND to non-owners. Items are returned in their stored order.

Update

curl -s -X PATCH https://api.dcast.pro/api/v1/playlists/{playlistId} \
  -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "title": "New title", "isPublic": false }'

Whitelisted writable: title, description, isPublic. Out-of-whitelist fields are silently dropped. Empty body returns current playlist unchanged.

Add a video or stream

# Append a video
curl -s -X POST https://api.dcast.pro/api/v1/playlists/{playlistId}/videos \
  -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "videoId": "cmpm76klv…" }'

# Append a live stream
curl -s -X POST https://api.dcast.pro/api/v1/playlists/{playlistId}/videos \
  -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "streamId": "9c283f07…" }'

Body must contain exactly one of videoId or streamId. The referenced asset must belong to the API key owner; foreign ids return 404 NOT_FOUND. Duplicates are not checked: adding the same asset again appends a second item.

Remove an item

# Remove by videoId
curl -s -X DELETE https://api.dcast.pro/api/v1/playlists/{playlistId}/videos/{videoId} \
  -H "Authorization: Bearer pk_YOUR_KEY_HERE"

# Remove by streamId (same path; backend matches both columns)
curl -s -X DELETE https://api.dcast.pro/api/v1/playlists/{playlistId}/videos/{streamId} \
  -H "Authorization: Bearer pk_YOUR_KEY_HERE"

# Remove by playlistItem.id (when you have the item-level id rather than asset id)
curl -s -X DELETE https://api.dcast.pro/api/v1/playlists/{playlistId}/videos/{playlistItemId} \
  -H "Authorization: Bearer pk_YOUR_KEY_HERE"

404 if the playlist or item is not on this account. The path segment after /videos/ is the asset id (videoId or streamId) or the playlist-item row id — the server matches all three columns.

Channel discovery — public playlists

GET /channel/:username/playlists lists a creator's public playlists for embed-page rendering. No pk_* key required. See Channels API for the full discovery surface.

curl -s "https://api.dcast.pro/api/v1/channel/{username}/playlists?page=1&limit=20"

Security & scope

Playlist endpoints are creator-scoped. POST, PATCH, DELETE on a playlist or its items require the API key to own the playlist; foreign ids return 404 NOT_FOUND. GET /playlists/:id is the only public-read surface and respects the isPublic flag — private playlists 404 for non-owners. READ_ONLY keys may only call GET endpoints.