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

{
  "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 ({}):

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

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

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

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)

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

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

{
  "error": "Error Message"
}

5.6. Examples

CURL Request

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"
  }'