# Playlist

### 1. Overview <a href="#id-1.-overview" id="id-1.-overview"></a>

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 <a href="#id-2.-authentication" id="id-2.-authentication"></a>

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)

> 📖 **Documentation:**
>
> * [Client Credentials OAuth](https://docs.firework.com/firework-for-developers/api/authentication) - Server-to-server authentication for OAuth apps

***

### 3. Endpoint Summary <a href="#id-3.-endpoint-summary" id="id-3.-endpoint-summary"></a>

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

***

### 4. List Channel Playlists <a href="#id-4.-list-channel-playlists" id="id-4.-list-channel-playlists"></a>

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 <a href="#id-4.1.-request-headers" id="id-4.1.-request-headers"></a>

| Name            | Description                           | Required |
| --------------- | ------------------------------------- | -------- |
| `Authorization` | Bearer token: `Bearer {ACCESS_TOKEN}` | ✅        |

#### 4.2. Query Parameters <a href="#id-4.2.-query-parameters" id="id-4.2.-query-parameters"></a>

| 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 <a href="#id-4.3.-list-channel-playlists-response" id="id-4.3.-list-channel-playlists-response"></a>

**Success Response**: `200 OK`

```json
{
    "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 <a href="#id-4.4.-list-channel-playlists-error-responses" id="id-4.4.-list-channel-playlists-error-responses"></a>

| 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 <a href="#id-4.5.-examples" id="id-4.5.-examples"></a>

**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"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.firework.com/firework-for-developers/api/playlist.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.