Channel

1. Overview

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

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

---

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

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

Success Response: 200 OK

{
    "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

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

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"