Playlist
1. Overview
The Firework Playlist API lets you manage playlists on a channel: list a channel's playlists, create new playlists, update them, delete them, and manage the videos they contain (list, add, reorder, remove, and pin/unpin).
A playlist belongs to a single channel (its creator) and holds an ordered list of video IDs. Use the playlist video_ids to cross-reference with the Video API (GET /api/v1/videos/{id}), or call GET /api/v1/playlists/{id}/videos to page through the full video objects directly.
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
Read operations require the playlists:read scope; write operations require playlists:write (which implicitly grants read access). The api:admin scope bypasses all scope checks.
📖 Documentation:
Client Credentials OAuth - Server-to-server authentication for OAuth apps
3. Endpoint Summary
/api/v1/playlists
GET
playlists:read
List a channel's playlists (cursor pagination)
/api/v1/playlists
POST
playlists:write
Create a playlist in a channel
/api/v1/playlists/{id}
PATCH
playlists:write
Update a playlist
/api/v1/playlists/{id}
DELETE
playlists:write
Delete a playlist
/api/v1/playlists/{id}/videos
GET
playlists:read
List a playlist's videos (page pagination)
/api/v1/playlists/{id}/videos
POST
playlists:write
Add a video to a playlist
/api/v1/playlists/{id}/videos
PUT
playlists:write
Reorder a playlist's videos
/api/v1/playlists/{id}/videos/{video_id}
DELETE
playlists:write
Remove a video from a playlist
/api/v1/playlists/{id}/videos/{video_id}/pin
POST
playlists:write
Pin a video to the top (AI-feed playlists only)
/api/v1/playlists/{id}/videos/{video_id}/pin
DELETE
playlists:write
Unpin a video (AI-feed playlists only)
All write scopes (playlists:write) implicitly satisfy the playlists:read requirement.
4. Playlist Object
The create, update, add-video, and reorder endpoints return a single playlist object as the top-level response body. The list endpoint returns an array of these objects under playlists.
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 playlist order
Note: On the list endpoint (
GET /api/v1/playlists),video_idscontains only currently available videos — deleted or unapproved videos are filtered out. The create/update/add/reorder responses echo the stored order without that filtering.
5. List Channel Playlists
Retrieve a paginated list of playlists for a channel. The authenticated user or OAuth app must have access to the channel's business. By default, archived playlists are excluded; set archived=true to return only archived playlists. Results are ordered by sort position descending (newest first).
Endpoint: GET /api/v1/playlists
Authentication: Bearer token required
Required Scope: playlists:read (for OAuth apps; playlists:write also satisfies this)
5.1. Request Headers
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
5.2. Query Parameters
This endpoint uses cursor pagination. Treat after/before values as opaque tokens issued by the server (via pagination.cursor or links.next) — do not construct them yourself.
channel_id
string
❌*
Firework encoded channel ID
archived
boolean
❌
Omitted or false returns only non-archived playlists; true returns only archived playlists
q
string
❌
Case-insensitive substring search on playlist name; % and _ are treated as literal characters
page_size
integer
❌
Number of playlists per page (default: 10, max: 100; values above the max are clamped)
after
string
❌
Opaque cursor: return the page after this cursor (ascending order)
before
string
❌
Opaque cursor: return the page before this cursor (descending order)
* Optional when the token resolves to a business with exactly one channel; that channel is used by default. Otherwise channel_id is required.
The q value is always interpreted as a name search, including when it contains only digits.
after and before are mutually exclusive — supplying both returns 400 Bad Request with {"error": "after and before are mutually exclusive"}.
Deprecated (legacy). The raw
since_idandbefore_idparams are still accepted as aliases forafterandbeforerespectively, but only during thepagingdeprecation window — they retire together with the legacypagingresponse object. New integrations should use the opaqueafter/beforecursors above and ignoresince_id/before_id.
5.3. List Channel Playlists Response
Success Response: 200 OK
Response Envelope
playlists
object[]
❌
Array of playlist objects (see the Playlist Object section above)
links
object
❌
Pagination links. Always present. Follow next verbatim; it is null on the last page. This is a forward-only feed, so prev is omitted.
pagination
object
❌
Pagination state. Always present.
paging
object
✅
Deprecated. Legacy pagination object retained during the migration window. Use links + pagination instead.
links object
next
string / null
Path to the next page (opaque). null when there is no next page.
pagination object
cursor
string / null
Opaque cursor for the next round; pass it back as after/before. null when exhausted.
has_more
boolean
true when another page is available.
Note: Clients should prefer following
links.nextverbatim. Thepagingobject is deprecated and will be removed in a future release; new integrations should not depend on it.
5.4. List Channel Playlists Error Responses
400 Bad Request
Missing channel_id when no sole channel can be resolved, conflicting cursors, or invalid parameters
401 Unauthorized
Missing, invalid, or expired authentication token
403 Forbidden
Missing playlists:read scope or channel belongs to other business
404 Not Found
Channel not found
Error Response Format:
5.5. Examples
CURL Request
Paginated Request (next page)
6. Create Playlist
Create a playlist in a channel. The authenticated user or OAuth app must have access to the channel's business. If video_ids is supplied, every video must belong to the same business as the channel, otherwise the request is rejected with 403 Forbidden.
Endpoint: POST /api/v1/playlists
Authentication: Bearer token required
Required Scope: playlists:write
6.1. Request Headers
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
Content-Type
application/json
✅
6.2. Request Body
channel_id
string
✅
Encoded channel ID the playlist belongs to
name
string
✅
Playlist name (max 100 characters)
description
string
❌
Playlist description (nullable)
video_ids
string[]
❌
Initial encoded video IDs, in order
6.3. Create Playlist Response
Success Response: 201 Created
Returns the created playlist object (see the Playlist Object section above).
6.4. Create Playlist Error Responses
400 Bad Request
Missing channel_id/name or malformed body
401 Unauthorized
Missing, invalid, or expired authentication token
403 Forbidden
Missing playlists:write scope, channel belongs to another business, or a video_id belongs to another business
404 Not Found
Channel not found
422 Unprocessable Entity
Validation failed (e.g. name longer than 100 characters)
6.5. Examples
CURL Request
7. Update Playlist
Update a playlist. Only the fields present in the request body are changed; omitted fields are left untouched. Supplying video_ids replaces the playlist's entire video list (and order). Every video in video_ids must belong to the playlist's business.
Endpoint: PATCH /api/v1/playlists/{id}
Authentication: Bearer token required
Required Scope: playlists:write
7.1. Request Headers
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
Content-Type
application/json
✅
7.2. Path Parameters
id
string
✅
Encoded playlist ID
7.3. Request Body
Only the provided fields are updated.
name
string
❌
Playlist name (max 100 characters)
description
string
❌
Playlist description (nullable)
video_ids
string[]
❌
Full ordered list of videos (replaces the existing order)
7.4. Update Playlist Response
Success Response: 200 OK
Returns the updated playlist object (see the Playlist Object section above).
7.5. Update Playlist Error Responses
400 Bad Request
Malformed body
401 Unauthorized
Missing, invalid, or expired authentication token
403 Forbidden
Missing playlists:write scope, playlist belongs to another business, or a video_id belongs to another business
404 Not Found
Playlist not found
422 Unprocessable Entity
Validation failed (e.g. name longer than 100 characters)
7.6. Examples
CURL Request
8. Delete Playlist
Delete a playlist. The authenticated user or OAuth app must have access to the playlist's business.
Endpoint: DELETE /api/v1/playlists/{id}
Authentication: Bearer token required
Required Scope: playlists:write
8.1. Request Headers
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
8.2. Path Parameters
id
string
✅
Encoded playlist ID
8.3. Delete Playlist Response
Success Response: 204 No Content (empty body)
8.4. Delete Playlist Error Responses
401 Unauthorized
Missing, invalid, or expired authentication token
403 Forbidden
Missing playlists:write scope or playlist belongs to another business
404 Not Found
Playlist not found
8.5. Examples
CURL Request
9. List Playlist Videos
Retrieve the full video objects for a playlist, in playlist order. Only approved videos are returned. By default, archived videos are excluded; set archived=true to return only archived videos.
Endpoint: GET /api/v1/playlists/{id}/videos
Authentication: Bearer token required
Required Scope: playlists:read (for OAuth apps; playlists:write also satisfies this)
9.1. Request Headers
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
9.2. Path Parameters
id
string
✅
Encoded playlist ID
9.3. Query Parameters
Unlike GET /api/v1/playlists, this endpoint uses page-number pagination (playlists have an arbitrary, non-monotonic order, so cursor pagination does not apply).
archived
boolean
❌
Omitted or false returns only non-archived videos; true returns only archived videos
fields
string
❌
Comma-separated top-level Video fields to return. id is always included. Omit or leave blank for full objects
page
integer
❌
1-based page number (default: 1)
page_size
integer
❌
Number of videos per page (default: 10, max: 100; values above the max are clamped)
9.4. List Playlist Videos Response
Success Response: 200 OK
Returns a paginated list of video objects. The fields parameter has the same valid names and behavior as the Video API's sparse field selection; whitespace and duplicate names are ignored, while unknown names return 400 Bad Request. See the Video API for the full video object field reference; the object below is abbreviated.
Response Envelope
links
object
❌
Pagination links. Always present.
pagination
object
❌
Pagination state. Always present.
paging
object
✅
Deprecated. Legacy pagination object retained during the migration window. Use links + pagination instead.
links object
next
string / null
Path to the next page. null when on the last page.
prev
string / null
Path to the previous page. null when on the first page.
pagination object
page
integer
1-based current page number.
page_size
integer
Items per page.
total_pages
integer
Total number of pages.
total_entries
integer
Total number of videos across all pages.
has_more
boolean
true when another page is available.
9.5. List Playlist Videos Error Responses
400 Bad Request
Invalid pagination parameter or unknown fields name
401 Unauthorized
Missing, invalid, or expired authentication token
403 Forbidden
Missing playlists:read scope or playlist belongs to another business
404 Not Found
Playlist not found
9.6. Examples
CURL Request
10. Add Video to Playlist
Add a single video to a playlist. The video must belong to the same business as the playlist. By default the video is appended to the end; pass position to insert it at a specific 0-based index.
Endpoint: POST /api/v1/playlists/{id}/videos
Authentication: Bearer token required
Required Scope: playlists:write
10.1. Request Headers
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
Content-Type
application/json
✅
10.2. Path Parameters
id
string
✅
Encoded playlist ID
10.3. Request Body
video_id
string
✅
Encoded video ID to add
position
integer
❌
0-based insert index; appends to the end when omitted
10.4. Add Video Response
Success Response: 200 OK
Returns the updated playlist object (see the Playlist Object section above).
10.5. Add Video Error Responses
400 Bad Request
Missing video_id or malformed body
401 Unauthorized
Missing, invalid, or expired authentication token
403 Forbidden
Missing playlists:write scope, playlist belongs to another business, or the video belongs to another business
404 Not Found
Playlist not found
10.6. Examples
CURL Request
11. Reorder Playlist Videos
Replace the playlist's video order with a full ordered list. Every video in video_ids must belong to the playlist's business.
Endpoint: PUT /api/v1/playlists/{id}/videos
Authentication: Bearer token required
Required Scope: playlists:write
11.1. Request Headers
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
Content-Type
application/json
✅
11.2. Path Parameters
id
string
✅
Encoded playlist ID
11.3. Request Body
video_ids
string[]
✅
Full ordered list of the playlist's video IDs
11.4. Reorder Response
Success Response: 200 OK
Returns the updated playlist object (see the Playlist Object section above).
11.5. Reorder Error Responses
400 Bad Request
Missing video_ids, wrong type, or malformed body
401 Unauthorized
Missing, invalid, or expired authentication token
403 Forbidden
Missing playlists:write scope, playlist belongs to another business, or a video belongs to another business
404 Not Found
Playlist not found
11.6. Examples
CURL Request
12. Remove Video from Playlist
Remove a single video from a playlist. Removing a video that is not in the playlist is a no-op and still returns 204.
Endpoint: DELETE /api/v1/playlists/{id}/videos/{video_id}
Authentication: Bearer token required
Required Scope: playlists:write
12.1. Request Headers
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
12.2. Path Parameters
id
string
✅
Encoded playlist ID
video_id
string
✅
Encoded video ID
12.3. Remove Video Response
Success Response: 204 No Content (empty body)
12.4. Remove Video Error Responses
401 Unauthorized
Missing, invalid, or expired authentication token
403 Forbidden
Missing playlists:write scope or playlist belongs to another business
404 Not Found
Playlist not found
12.5. Examples
CURL Request
13. Pin / Unpin a Video
Pin a video to the top of a playlist, or remove an existing pin. Pinning is only supported on playlists that have an AI feed enabled; calling these endpoints on a playlist without an AI feed returns 422 Unprocessable Entity. The video must already be in the playlist, otherwise 404 Not Found is returned.
Endpoints:
POST /api/v1/playlists/{id}/videos/{video_id}/pin— pin the videoDELETE /api/v1/playlists/{id}/videos/{video_id}/pin— unpin the video
Authentication: Bearer token required
Required Scope: playlists:write
13.1. Request Headers
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
13.2. Path Parameters
id
string
✅
Encoded playlist ID
video_id
string
✅
Encoded video ID
13.3. Pin / Unpin Response
Success Response: 204 No Content (empty body)
13.4. Pin / Unpin Error Responses
401 Unauthorized
Missing, invalid, or expired authentication token
403 Forbidden
Missing playlists:write scope or playlist belongs to another business
404 Not Found
Playlist not found, or the video is not in the playlist
422 Unprocessable Entity
The playlist does not have an AI feed enabled
13.5. Examples
Pin a Video
Unpin a Video
Last updated
Was this helpful?