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

Endpoint	Method	Scope	Notes
/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.

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 playlist order

Note: On the list endpoint (GET /api/v1/playlists), video_ids contains 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 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).

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

Name	Description	Required
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.

Parameter	Type	Required	Description
channel_id	string	✅	Firework encoded channel ID
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)

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_id and before_id params are still accepted as aliases for after and before respectively, but only during the paging deprecation window — they retire together with the legacy paging response object. New integrations should use the opaque after/before cursors above and ignore since_id/before_id.

5.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"]
    }
  ],
  "links": {
    "next": "/api/v1/playlists?channel_id=7RXwK8k&page_size=10&before=Q3Vyc29yOjEyMzQ1"
  },
  "pagination": {
    "cursor": "Q3Vyc29yOjEyMzQ1",
    "has_more": true
  },
  "paging": {
    "next": "/api/v1/playlists?channel_id=7RXwK8k&page_size=10&before_id=Dal1amypVY7"
  }
}

Response Envelope

Field	Type	Nullable	Description
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

Field	Type	Description
next	string / null	Path to the next page (opaque). null when there is no next page.

pagination object

Field	Type	Description
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.next verbatim. The paging object is deprecated and will be removed in a future release; new integrations should not depend on it.

5.4. List Channel Playlists Error Responses

Status Code	Description
400 Bad Request	Missing channel_id, 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:

{
  "error": "Error Message"
}

5.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 (next page)

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

---

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

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅
Content-Type	application/json	✅

6.2. Request Body

Field	Type	Required	Description
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).

{
  "id": "5mpaqv",
  "name": "My Playlist",
  "description": "Summer campaign videos",
  "updated_at": "2026-07-02T01:22:39.431667Z",
  "video_ids": ["o9lYEq", "o8V2Rb"]
}

6.4. Create Playlist Error Responses

Status Code	Description
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

curl -X POST "https://api.firework.com/api/v1/playlists" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "7RXwK8k",
    "name": "My Playlist",
    "description": "Summer campaign videos",
    "video_ids": ["o9lYEq", "o8V2Rb"]
  }'

---

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

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅
Content-Type	application/json	✅

7.2. Path Parameters

Parameter	Type	Required	Description
id	string	✅	Encoded playlist ID

7.3. Request Body

Only the provided fields are updated.

Field	Type	Required	Description
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).

{
  "id": "5mpaqv",
  "name": "Renamed Playlist",
  "description": "Updated description",
  "updated_at": "2026-07-02T02:10:11.000000Z",
  "video_ids": ["o8V2Rb", "o9lYEq"]
}

7.5. Update Playlist Error Responses

Status Code	Description
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

curl -X PATCH "https://api.firework.com/api/v1/playlists/5mpaqv" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Renamed Playlist",
    "video_ids": ["o8V2Rb", "o9lYEq"]
  }'

---

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

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

8.2. Path Parameters

Parameter	Type	Required	Description
id	string	✅	Encoded playlist ID

8.3. Delete Playlist Response

Success Response: 204 No Content (empty body)

8.4. Delete Playlist Error Responses

Status Code	Description
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

curl -X DELETE "https://api.firework.com/api/v1/playlists/5mpaqv" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

---

9. List Playlist Videos

Retrieve the full video objects for a playlist, in playlist order. Only approved, non-archived videos are returned.

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

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

9.2. Path Parameters

Parameter	Type	Required	Description
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).

Parameter	Type	Required	Description
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. See the Video API for the full video object field reference; the object below is abbreviated.

{
  "videos": [
    {
      "id": "o9lYEq",
      "caption": "Summer Lookbook",
      "description": null,
      "access": "public",
      "hashtags": ["summer", "lookbook"],
      "product_ids": ["p8Vq2R"],
      "thumbnail_url": "https://cdn.firework.com/medias/2026/07/01/abc/thumbnail.jpg",
      "video_posters": []
    }
  ],
  "links": {
    "next": "/api/v1/playlists/5mpaqv/videos?page=2&page_size=10",
    "prev": null
  },
  "pagination": {
    "page": 1,
    "page_size": 10,
    "total_pages": 3,
    "total_entries": 24,
    "has_more": true
  },
  "paging": {
    "next": "/api/v1/playlists/5mpaqv/videos?page=2&page_size=10"
  }
}

Response Envelope

Field	Type	Nullable	Description
videos	object[]	❌	Array of video objects (see the Video API)
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

Field	Type	Description
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

Field	Type	Description
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

Status Code	Description
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

curl -X GET "https://api.firework.com/api/v1/playlists/5mpaqv/videos?page=1&page_size=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

---

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

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅
Content-Type	application/json	✅

10.2. Path Parameters

Parameter	Type	Required	Description
id	string	✅	Encoded playlist ID

10.3. Request Body

Field	Type	Required	Description
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).

{
  "id": "5mpaqv",
  "name": "My Playlist",
  "description": null,
  "updated_at": "2026-07-02T03:00:00.000000Z",
  "video_ids": ["oNewVid", "o9lYEq", "o8V2Rb"]
}

10.5. Add Video Error Responses

Status Code	Description
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

curl -X POST "https://api.firework.com/api/v1/playlists/5mpaqv/videos" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "video_id": "oNewVid",
    "position": 0
  }'

---

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

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅
Content-Type	application/json	✅

11.2. Path Parameters

Parameter	Type	Required	Description
id	string	✅	Encoded playlist ID

11.3. Request Body

Field	Type	Required	Description
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).

{
  "id": "5mpaqv",
  "name": "My Playlist",
  "description": null,
  "updated_at": "2026-07-02T03:15:00.000000Z",
  "video_ids": ["o8V2Rb", "o9lYEq"]
}

11.5. Reorder Error Responses

Status Code	Description
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

curl -X PUT "https://api.firework.com/api/v1/playlists/5mpaqv/videos" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "video_ids": ["o8V2Rb", "o9lYEq"]
  }'

---

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

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

12.2. Path Parameters

Parameter	Type	Required	Description
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

Status Code	Description
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

curl -X DELETE "https://api.firework.com/api/v1/playlists/5mpaqv/videos/o9lYEq" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

---

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 video

• DELETE /api/v1/playlists/{id}/videos/{video_id}/pin — unpin the video

Authentication: Bearer token required Required Scope: playlists:write

13.1. Request Headers

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

13.2. Path Parameters

Parameter	Type	Required	Description
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

Status Code	Description
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

curl -X POST "https://api.firework.com/api/v1/playlists/5mpaqv/videos/o9lYEq/pin" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Unpin a Video

curl -X DELETE "https://api.firework.com/api/v1/playlists/5mpaqv/videos/o9lYEq/pin" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"