# Channel

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

The Firework Channel API allows you to retrieve 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 this endpoint as the `channel_id` parameter when creating videos via `POST /api/v1/videos`.

> This API provides read-only access. Channels 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 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](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/channels` | `channels:read` | List channels for the authenticated business |

***

### 4. List Channels <a href="#id-4.-list-channels" id="id-4.-list-channels"></a>

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 <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                                                               |
| ------------- | ------- | -------- | ------------------------------------------------------------------------- |
| `business_id` | string  | ✅        | Encoded business ID to list channels for                                  |
| `page_size`   | integer | ❌        | Number of channels 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 Channels Response <a href="#id-4.3.-list-channels-response" id="id-4.3.-list-channels-response"></a>

**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"
    }],
    "paging":
    {
        "next": "/api/v1/channels?business_id=J1BA8n&page_size=10&before_id=616dOp"
    }
}
```

When no more results exist, `paging` will be an empty object: `{}`.

> **Note:** Use `before_id` to page through older entries (descending order by ID). Use `since_id` to get newer entries (ascending order by ID). Only one of `before_id` or `since_id` may be used per request.

**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 <a href="#id-4.4.-list-channels-error-responses" id="id-4.4.-list-channels-error-responses"></a>

| Status Code        | Description                                       |
| ------------------ | ------------------------------------------------- |
| `400 Bad Request`  | Missing `business_id` or invalid query parameters |
| `401 Unauthorized` | Invalid or missing authentication token           |
| `403 Forbidden`    | Insufficient scope for OAuth app                  |

**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/channels?business_id=J1BA8n&page_size=10>" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Paginated Request (older entries)**

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

**Paginated Request (newer entries)**

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