> For the complete documentation index, see [llms.txt](https://docs.firework.com/firework-for-developers/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.firework.com/firework-for-developers/api/channel.md).

# Channel

### 1. Overview

The Firework Channel API allows you to retrieve and update channels associated with your business. Channels are the primary content containers in Firework, each with its own video library and branding.

Use the channel `id` returned by the list endpoint as the `channel_id` parameter when creating videos via `POST /api/v1/videos`.

> Channels are created through the Firework dashboard or Business API. This API lets you list them and update their metadata (name, bio, country, locale, avatar, and cover image).

**Base URL**: `https://api.firework.com`

### 2. Authentication

The Firework Channel 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](/firework-for-developers/api/authentication.md) - Server-to-server authentication for OAuth apps

***

### 3. Endpoint Summary

| Endpoint                      | Scope            | Notes                                        |
| ----------------------------- | ---------------- | -------------------------------------------- |
| `GET /api/v1/channels`        | `channels:read`  | List channels for the authenticated business |
| `PATCH /api/v1/channels/{id}` | `channels:write` | Update a channel's metadata                  |

***

### 4. List Channels

Retrieve all channels belonging to the specified business. The authenticated user or OAuth app must have access to the business. Results are ordered by channel ID descending (newest first).

**Endpoint**: `GET /api/v1/channels` **Authentication**: Bearer token required (OAuth 2.0 Client Credentials) **Required Scope**: `channels:read` (for OAuth apps)

#### 4.1. Request Headers

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

#### 4.2. Query Parameters

Results are returned in descending order by channel ID (newest first) unless an `after` cursor is supplied.

| Parameter     | Type    | Required | Description                                                                                                                                                                                             |
| ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `business_id` | string  | ❌        | Encoded business ID to list channels for. Optional: app tokens default to the token's business; user tokens default to the user's sole business (required when the user belongs to multiple businesses) |
| `page_size`   | integer | ❌        | Number of channels per page (default: 10, range: 1–100). Values above the max are clamped                                                                                                               |
| `after`       | string  | ❌        | Opaque pagination cursor. Returns the page **after** this cursor (newer entries, ascending)                                                                                                             |
| `before`      | string  | ❌        | Opaque pagination cursor. Returns the page **before** this cursor (older entries, descending)                                                                                                           |

> **Cursors are opaque.** Treat `after` / `before` values as opaque tokens — obtain them from `pagination.cursor` or by following `links.next`, and do not construct or parse them yourself. `after` and `before` are mutually exclusive; supplying both returns `400 Bad Request`.

> **Deprecated (legacy):** The `since_id` and `before_id` parameters are still accepted during the migration window but are deprecated. `after` supersedes `since_id` (newer, ascending) and `before` supersedes `before_id` (older, descending). New integrations should use `after` / `before`.

#### 4.3. List Channels Response

**Success Response**: `200 OK`

```json
{
  "channels": [
    {
      "id": "616dOp",
      "name": "My Channel",
      "username": "my_channel",
      "avatar_url": "https://asset.fireworktv.com/images/default_avatar.png",
      "bio": null,
      "business_id": "J1BA8n",
      "country": "US",
      "locale": "en"
    }
  ],
  "links": {
    "next": "/api/v1/channels?business_id=J1BA8n&page_size=10&before=eyJiZWZvcmVfaWQiOiI2MTZkT3AifQ"
  },
  "pagination": {
    "cursor": "eyJiZWZvcmVfaWQiOiI2MTZkT3AifQ",
    "has_more": true
  },
  "paging": {
    "next": "/api/v1/channels?business_id=J1BA8n&page_size=10&before_id=616dOp"
  }
}
```

To fetch the next page, follow `links.next` verbatim, or pass `pagination.cursor` as the `before` query parameter. When there are no more results, `links.next` and `pagination.cursor` are `null`, `pagination.has_more` is `false`, and the legacy `paging` object is empty (`{}`):

```json
{
  "channels": [],
  "links": { "next": null },
  "pagination": { "cursor": null, "has_more": false },
  "paging": {}
}
```

**`links` Object**

| Field  | Type   | Nullable | Description                                                                                                     |
| ------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `next` | string | ✅        | Relative path (beginning `/api/v1/...`) to the next page. `null` when there is no next page. Follow it verbatim |

> This endpoint is a forward-only feed, so `links` has no `prev` key.

**`pagination` Object**

| Field      | Type    | Nullable | Description                                                                               |
| ---------- | ------- | -------- | ----------------------------------------------------------------------------------------- |
| `cursor`   | string  | ✅        | Opaque cursor for the next page; pass it as the `before` parameter. `null` when exhausted |
| `has_more` | boolean | ❌        | `true` when another page exists right now                                                 |

> **Deprecated (legacy):** The `paging` object (with its `paging.next` URL, or `{}` when exhausted) is still returned during the migration window but is deprecated in favor of `links` + `pagination`. New integrations should ignore `paging`.

**Channel Fields**

| Field         | Type   | Nullable | Description                                                  |
| ------------- | ------ | -------- | ------------------------------------------------------------ |
| `id`          | string | ❌        | Encoded unique identifier. Use as `channel_id` in other APIs |
| `name`        | string | ✅        | Display name of the channel                                  |
| `username`    | string | ❌        | Unique username                                              |
| `avatar_url`  | string | ✅        | URL of the channel avatar image                              |
| `bio`         | string | ✅        | Channel biography/description                                |
| `business_id` | string | ❌        | Encoded ID of the owning business                            |
| `country`     | string | ❌        | Two-letter country code (e.g., `"US"`, `"CA"`)               |
| `locale`      | string | ❌        | Language locale (e.g., `"en"`, `"fr"`)                       |

#### 4.4. List Channels Error Responses

| Status Code        | Description                                                                                                 |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`  | Missing `business_id`, a non-integer `page_size`, a malformed cursor, or both `after` and `before` supplied |
| `401 Unauthorized` | Invalid or missing authentication token                                                                     |
| `403 Forbidden`    | Insufficient scope for OAuth app                                                                            |

**Error Response Format**:

```json
{
  "error": "Error Message"
}
```

#### 4.5. Examples

**CURL Request**

```bash
curl -X GET "https://api.firework.com/api/v1/channels?business_id=J1BA8n&page_size=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Paginated Request (older entries)**

Pass the `pagination.cursor` from the previous response as `before` (or simply follow `links.next`):

```bash
curl -X GET "https://api.firework.com/api/v1/channels?business_id=J1BA8n&page_size=10&before=eyJiZWZvcmVfaWQiOiI2MTZkT3AifQ" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Paginated Request (newer entries)**

```bash
curl -X GET "https://api.firework.com/api/v1/channels?business_id=J1BA8n&page_size=10&after=eyJzaW5jZV9pZCI6IjYxNmRPcCJ9" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

***

### 5. Update Channel

Update the metadata of a channel your token can access. Only the fields you include in the request body are modified; omitted fields are left unchanged. The token must have access to the business that owns the channel.

**Endpoint**: `PATCH /api/v1/channels/{id}` **Authentication**: Bearer token required (OAuth 2.0 Client Credentials) **Required Scope**: `channels:write` (for OAuth apps)

#### 5.1. Request Headers

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

#### 5.2. Path Parameters

| Parameter | Type   | Required | Description                         |
| --------- | ------ | -------- | ----------------------------------- |
| `id`      | string | ✅        | Encoded ID of the channel to update |

#### 5.3. Request Body

Send a JSON object with any subset of the updatable fields. All fields are optional; only the provided fields are updated.

| Field        | Type   | Required | Description                                                       |
| ------------ | ------ | -------- | ----------------------------------------------------------------- |
| `name`       | string | ❌        | Display name of the channel                                       |
| `bio`        | string | ❌        | Channel biography/description. Nullable — pass `null` to clear it |
| `country`    | string | ❌        | Two-letter country code (e.g., `"US"`, `"CA"`)                    |
| `locale`     | string | ❌        | Language locale (e.g., `"en"`, `"fr"`)                            |
| `avatar_key` | string | ❌        | S3 key of the channel avatar image                                |
| `cover_key`  | string | ❌        | S3 key of the channel cover image                                 |

#### 5.4. Update Channel Response

**Success Response**: `200 OK`

Returns the full updated channel object (same shape as the objects in the list endpoint).

```json
{
  "id": "616dOp",
  "name": "My Updated Channel",
  "username": "my_channel",
  "avatar_url": "https://asset.fireworktv.com/images/default_avatar.png",
  "bio": "Fresh new bio",
  "business_id": "J1BA8n",
  "country": "US",
  "locale": "en"
}
```

**Channel Fields**

| Field         | Type   | Nullable | Description                                                  |
| ------------- | ------ | -------- | ------------------------------------------------------------ |
| `id`          | string | ❌        | Encoded unique identifier. Use as `channel_id` in other APIs |
| `name`        | string | ✅        | Display name of the channel                                  |
| `username`    | string | ❌        | Unique username                                              |
| `avatar_url`  | string | ✅        | URL of the channel avatar image                              |
| `bio`         | string | ✅        | Channel biography/description                                |
| `business_id` | string | ❌        | Encoded ID of the owning business                            |
| `country`     | string | ✅        | Two-letter country code (e.g., `"US"`, `"CA"`)               |
| `locale`      | string | ✅        | Language locale (e.g., `"en"`, `"fr"`)                       |

#### 5.5. Update Channel Error Responses

| Status Code                | Description                                                            |
| -------------------------- | ---------------------------------------------------------------------- |
| `400 Bad Request`          | Malformed or invalid channel ID                                        |
| `401 Unauthorized`         | Invalid or missing authentication token                                |
| `403 Forbidden`            | Insufficient scope, or the token cannot access this channel's business |
| `404 Not Found`            | No channel exists with the given ID                                    |
| `422 Unprocessable Entity` | The update parameters failed validation                                |

**Error Response Format**:

```json
{
  "error": "Error Message"
}
```

#### 5.6. Examples

**CURL Request**

```bash
curl -X PATCH "https://api.firework.com/api/v1/channels/616dOp" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Updated Channel",
    "bio": "Fresh new bio",
    "country": "US",
    "locale": "en"
  }'
```