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