Playlist

1. Overview

The Firework Playlist API allows you to retrieve playlists for a specific channel on the Firework platform.

Use the playlist video_ids to cross-reference with the Video API (GET /api/v1/videos/{id}).

This API provides read-only access. Playlists are created through the Firework dashboard or Business API.

Base URL: <https://api.firework.com>

2. Authentication

The Firework Playlist API uses OAuth 2.0 for authentication. Before using this API, you must obtain an access token.

Authentication Methods Supported:

• Client Credentials: OAuth 2.0 Client Credentials flow for server-to-server authentication (machine-to-machine)

• User Authentication: Standard OAuth 2.0 user authorization flow

📖 Documentation:

• Client Credentials OAuth - Server-to-server authentication for OAuth apps

---

3. Endpoint Summary

Endpoint	Scope	Notes
GET /api/v1/playlists	playlists:read	List playlists for a channel

---

4. List Channel Playlists

Retrieve a paginated list of playlists for a specific channel. The authenticated user or OAuth app must have access to the channel's business. Only enabled, non-archived playlists are returned. Results are ordered by sort position descending (newest first). The video_ids field contains only currently available videos (deleted or unapproved videos are filtered out).

Endpoint: GET /api/v1/playlists Authentication: Bearer token required Required Scope: playlists:read (for OAuth apps; playlists:write also satisfies this)

4.1. Request Headers

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅

4.2. Query Parameters

Parameter	Type	Required	Description
channel_id	string	✅	Firework encoded channel ID
page_size	integer	❌	Number of playlists per page (default: 10, max: 100)
before_id	string	❌	Cursor for pagination: return entries before this encoded ID (descending)
since_id	string	❌	Cursor for pagination: return entries after this encoded ID (ascending)

4.3. List Channel Playlists Response

Success Response: 200 OK

{
    "playlists": [
    {
        "id": "5mpaqv",
        "name": "My Playlist",
        "description": null,
        "updated_at": "2022-04-27T01:22:39.431667Z",
        "video_ids": ["o9lYEq", "o8V2Rb"]
    }],
    "paging":
    {
        "next": "/api/v1/playlists?channel_id=7RXwK8k&page_size=10&before_id=Dal1amypVY7"
    }
}

When no more results exist, paging will be an empty object: {}.

Note: Use before_id to page through older entries (descending order). Use since_id to get newer entries (ascending order). Only one of before_id or since_id may be used per request.

Playlist Fields

Field	Type	Nullable	Description
id	string	❌	Encoded playlist ID
name	string	❌	Name of the playlist
description	string	✅	Description of the playlist
updated_at	string	❌	ISO 8601 timestamp of last update
video_ids	string[]	❌	Array of encoded video IDs in the playlist

4.4. List Channel Playlists Error Responses

Status Code	Description
400 Bad Request	Missing channel_id or invalid parameters
401 Unauthorized	Missing or invalid authentication token
403 Forbidden	Missing playlists:read scope or channel belongs to other business
404 Not Found	Channel not found

Error Response Format:

{ "error": "Error Message" }

4.5. Examples

CURL Request

curl -X GET "<https://api.firework.com/api/v1/playlists?channel_id=7RXwK8k&page_size=10>" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Paginated Request (older entries)

curl -X GET "<https://api.firework.com/api/v1/playlists?channel_id=7RXwK8k&page_size=10&before_id=Dal1amypVY7>" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Paginated Request (newer entries)

curl -X GET "<https://api.firework.com/api/v1/playlists?channel_id=7RXwK8k&page_size=10&since_id=Dal1amypVY7>" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"