Livestreams

1. Overview

The Firework Livestream API lets you manage livestreams end to end. The public API supports the following workflows:

• Create: Schedule a single livestream through a public API endpoint

• Read: Fetch livestream details, current status, schedule, and thumbnail image

• Update: Modify mutable livestream metadata, schedule, trailer, and tagged products

• Write: Pin or unpin products in real time and force-end live sessions when needed

• Export: Download post-event interaction results and livestream comments

• List & report: List a channel's livestreams, page live/replay chat messages, and pull consolidated reporting stats

Use these endpoints to create interactive commerce moments while keeping operational control of every broadcast.

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

2. Authentication

The Firework Livestream API uses OAuth 2.0 for authentication. Before using this API, you must obtain an access token.

Authentication Method:

• 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
POST /api/v1/live_streams	livestreams:write	Create a single scheduled livestream
GET /api/v1/live_streams	livestreams:read	List a channel's primary livestreams (cursor)
GET /api/v1/live_streams/{live_stream_id}	livestreams:read	Get livestream info and export interaction IDs
GET /api/v1/live_streams/{live_stream_id}/products	livestreams:read	Get the complete configured product snapshot
GET /api/v1/live_streams/{live_stream_id}/messages	livestreams:read	List live/replay chat messages (cursor)
PATCH /api/v1/live_streams/{live_stream_id}	livestreams:write	Update mutable livestream fields
POST /api/v1/live_streams/{id}/pin_product	livestreams:write	Pin products during livestream
POST /api/v1/live_streams/{id}/unpin_product	livestreams:write	Unpin products during livestream
PATCH /api/v1/live_streams/{id}/end	livestreams:write	Force end an active livestream
GET /api/v1/live_streams/{live_stream_id}/interactions/{interaction_id}/responses_csv	livestreams:read	Download interaction response results as CSV
GET /api/v1/live_streams/{live_stream_id}/comments_csv	livestreams:read	Download livestream comments as CSV
GET /api/v1/stats/live_streams/{live_stream_id}	livestreams:read	Consolidated reporting stats (meta/live/replay)
GET /api/v1/live_streams/{live_stream_id}/detail	livestreams:read	Viewer-side livestream details (legacy)
GET /api/v1/live_streams/playlists/{playlist_id}/videos	livestreams:read	List a livestream playlist's videos (legacy, page)

---

4. Create Livestream

Schedule a single livestream through the public API.

Scope of v1: This endpoint is intentionally single-create only. If you need to create many livestreams, call this endpoint multiple times and respect the documented rate limit. A bulk/job-based create API is not part of this version of the spec.

Endpoint: POST /api/v1/live_streams Authentication: Bearer token required (OAuth 2.0 Client Credentials) Required Scope: livestreams:write (for OAuth apps) Rate Limit: 20 create requests per 5 minutes per channel Content Type: application/json Status: Implemented

Scope note: Creating the livestream requires livestreams:write. If you want to upload a custom trailer and pass it as s3_key, the upload step uses the public video upload APIs and requires videos:write.

4.1. Request Headers

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

4.2. Request Body

Field	Type	Required	Default	Description
caption	string	✅	None	Livestream title shown to viewers
channel_id	string	✅	None	Encoded channel ID where the livestream will be created
description	string	❌	None	Livestream description
scheduled_at	string	✅	None	ISO 8601 datetime when the livestream is scheduled to start
time_zone	string	❌	None	IANA timezone identifier for the scheduled event, for example America/New_York
stream_source	string	✅	None	Source of the livestream. Supported values for v1: "fw" and "external"
s3_key	string	❌	Firework default trailer	Pre-uploaded trailer key to use while the livestream is idle
business_store_id	string	❌	Use first one	Encoded business store ID used to resolve product_ids
product_ids	string[]	❌	[]	Initial products to tag to the livestream trailer/video
access_code	string / null	❌	null	Access code used to lock the video/livestream. Use null to leave it unlocked
announcement	string / null	❌	null	Announcement banner text shown to viewers
auto_response	string	❌	"disabled"	Chat auto-response mode. Supported values: "always_on", "moderated", "disabled"
chat_enabled	boolean	❌	true	Whether live chat is enabled
chat_in_replay_enabled	boolean	❌	true	Whether chat messages are displayed during replay
chat_moderation_enabled	boolean	❌	false	Whether chat moderation is enabled
hearts_count_enabled	boolean	❌	false	Whether like count is shown
fomo_product_viewing_enabled	boolean	❌	false	Whether real-time product-viewing FOMO cues are shown
replay_enabled	boolean	❌	true	Whether replay is available after the livestream ends
replay_interactions_enabled	boolean	❌	true	Whether replay interactions are enabled
replay_messaging_enabled	boolean	❌	false	Whether viewers can post messages during replay
replay_viewers_count_enabled	boolean	❌	false	Whether viewer count is shown during replay
trailer_announcement_enabled	boolean	❌	false	Whether the announcement is shown while viewers watch the trailer
trailer_messaging_enabled	boolean	❌	false	Whether viewers can post messages while watching the trailer
transcription_enabled	boolean	❌	false	Whether live transcription is enabled, when supported by the provider/source
viewers_count_enabled	boolean	❌	true	Whether viewer count is shown
viewers_count_mode	string	❌	"accumulated"	Viewer-count mode. Supported values: "accumulated" and "concurrent"

Request Rules:

• If s3_key is omitted, Firework uses the default livestream trailer.

• If you want a custom trailer, upload it first using the public upload APIs documented in Firework Video API - Public, then pass the returned key value as s3_key.

• product_ids follows the same identifier rules as POST /api/v1/videos.

• scheduled_at should be provided in UTC ISO 8601 format.

• stream_source is required at create time. It can only be updated before the livestream enters the 5-minute warmup window.

• stream_source can only be assigned when the livestream is scheduled more than 5 minutes in the future.

• Livestream instance settings do not update channel/feed-level display settings or AI copilot setup.

How to get s3_key:

1. Call POST /api/v1/upload_signatures for a single-request upload, or POST /api/v1/upload_multipart/signatures followed by POST /api/v1/upload_multipart/complete for multipart upload.

2. Upload the trailer file directly to S3 using the returned signature data.

3. Take the key from the upload API response.

4. Pass that exact value as s3_key in POST /api/v1/live_streams.

4.3. Create Livestream Response

Success Response: 201 Created

Field	Type	Nullable	Description
id	string	❌	Unique encoded identifier of the livestream
provider	string	❌	Streaming provider selected for the livestream
status	string	❌	Initial livestream state. Expected value: idle
event_name	string	❌	Name of the livestream event
event_description	string	✅	Description of the livestream event
thumbnail_url	string	✅	URL of the livestream thumbnail image
has_access_code	boolean	❌	Whether the video/livestream is locked by an access code
announcement	string	✅	Announcement banner text
auto_response	string	❌	Chat auto-response mode
chat_enabled	boolean	❌	Whether live chat is enabled
chat_in_replay_enabled	boolean	❌	Whether chat messages are displayed during replay
chat_moderation_enabled	boolean	❌	Whether chat moderation is enabled
hearts_count_enabled	boolean	❌	Whether like count is shown
fomo_product_viewing_enabled	boolean	❌	Whether real-time product-viewing FOMO cues are shown
replay_enabled	boolean	❌	Whether replay is available after the livestream ends
replay_interactions_enabled	boolean	❌	Whether replay interactions are enabled
replay_messaging_enabled	boolean	❌	Whether viewers can post messages during replay
replay_viewers_count_enabled	boolean	❌	Whether viewer count is shown during replay
trailer_announcement_enabled	boolean	❌	Whether the announcement is shown while viewers watch the trailer
trailer_messaging_enabled	boolean	❌	Whether viewers can post messages while watching the trailer
transcription_enabled	boolean	❌	Whether live transcription is enabled
viewers_count_enabled	boolean	❌	Whether viewer count is shown
viewers_count_mode	string	❌	Viewer-count mode: "accumulated" or "concurrent"
scheduled_at	string	✅	ISO 8601 datetime when livestream is scheduled to start
started_at	string	✅	ISO 8601 datetime when livestream actually started
ended_at	string	✅	ISO 8601 datetime when livestream ended
stream_key	string	✅	Publish stream key. Returned for stream_source: "external" on create
stream_url	string	✅	Publish RTMP URL. Returned for stream_source: "external" on create

Note: The create response mostly matches GET /api/v1/live_streams/{live_stream_id}. It additionally includes provider, and for stream_source: "external" it also returns stream_key and stream_url so clients can publish to the scheduled livestream.

4.4. Create Livestream Error Responses

Status Code	Description
400 Bad Request	Invalid request body, malformed datetime, unsupported stream_source, invalid s3_key, or maintenance window restriction
401 Unauthorized	Invalid or missing authentication token
402 Payment Required	Live events are not enabled for the business
403 Forbidden	The authenticated user or OAuth app does not have access to the channel
404 Not Found	Channel not found
422 Unprocessable Entity	Domain validation error from changesets, for example livestream scheduling constraints
429 Too Many Requests	Rate limit exceeded (20 create requests per 5 minutes per channel)

Error Response Format:

Simple request/auth errors return:

{
  "error": "Error Message"
}

Validation errors from changesets return:

{
  "errors": {
    "field_name": ["validation message"]
  }
}

4.5. Examples

Example 1: Create Livestream with Default Trailer

curl -X POST "https://api.firework.com/api/v1/live_streams" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "X6Xqd6W",
    "caption": "Summer Sale Livestream",
    "description": "Join us for our scheduled commerce event",
    "scheduled_at": "2026-07-20T10:00:00.000000Z",
    "stream_source": "fw",
    "time_zone": "America/New_York"
  }'

Example 2: Create Livestream with Custom Trailer

curl -X POST "https://api.firework.com/api/v1/live_streams" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "X6Xqd6W",
    "caption": "Bajaj Daily Livestream",
    "scheduled_at": "2026-07-20T12:30:00.000000Z",
    "stream_source": "external",
    "s3_key": "medias/business/AbCdEfG/channel/HiJkLmN/videos/public/original/1738152000-abcdefgh-trailer.mp4",
    "product_ids": ["GeEk8y", "ABC123"]
  }'

Example 3: Create Livestream with Display Settings

curl -X POST "https://api.firework.com/api/v1/live_streams" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "X6Xqd6W",
    "caption": "Private VIP Livestream",
    "scheduled_at": "2026-07-20T12:30:00.000000Z",
    "stream_source": "fw",
    "access_code": "VIP123",
    "announcement": "Doors open in 5 minutes",
    "replay_enabled": true,
    "replay_viewers_count_enabled": true,
    "trailer_announcement_enabled": true,
    "viewers_count_enabled": true,
    "viewers_count_mode": "accumulated",
    "hearts_count_enabled": false,
    "fomo_product_viewing_enabled": false,
    "transcription_enabled": true
  }'

Example Response

{
  "id": "616dOp",
  "provider": "ivs",
  "status": "idle",
  "event_name": "Summer Sale Livestream",
  "event_description": "Join us for our scheduled commerce event",
  "thumbnail_url": "https://cdn.firework.com/live_streams/616dOp/thumbnail.jpg",
  "has_access_code": false,
  "announcement": null,
  "auto_response": "disabled",
  "chat_enabled": true,
  "chat_in_replay_enabled": true,
  "chat_moderation_enabled": false,
  "hearts_count_enabled": false,
  "fomo_product_viewing_enabled": false,
  "replay_enabled": true,
  "replay_interactions_enabled": true,
  "replay_messaging_enabled": false,
  "replay_viewers_count_enabled": false,
  "trailer_announcement_enabled": false,
  "trailer_messaging_enabled": false,
  "transcription_enabled": false,
  "viewers_count_enabled": true,
  "viewers_count_mode": "accumulated",
  "scheduled_at": "2026-07-20T10:00:00.000000Z",
  "started_at": null,
  "ended_at": null,
  "stream_key": null,
  "stream_url": null
}

---

5. Get Livestream Info

Retrieve information about a specific livestream room including its current status, event details, scheduling information, and thumbnail image.

Note: This is the endpoint for fetching livestream info.

Endpoint: GET /api/v1/live_streams/{live_stream_id} Authentication: Bearer token required (OAuth 2.0 Client Credentials) Required Scope: livestreams:read (for OAuth apps)

5.1. Request Headers

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅

5.2. Path Parameters

Parameter	Type	Required	Description
live_stream_id	string	✅	The unique identifier of the livestream

5.3. Get Livestream Response

Success Response: 200 OK

Field	Type	Nullable	Description
id	string	❌	Unique encoded identifier of the livestream
status	string	❌	Current livestream state (see Status Values below)
event_name	string	❌	Name of the livestream event
event_description	string	✅	Description of the livestream event
thumbnail_url	string	✅	URL of the livestream thumbnail image
has_access_code	boolean	❌	Whether the video/livestream is locked by an access code
announcement	string	✅	Announcement banner text
auto_response	string	❌	Chat auto-response mode
chat_enabled	boolean	❌	Whether live chat is enabled
chat_in_replay_enabled	boolean	❌	Whether chat messages are displayed during replay
chat_moderation_enabled	boolean	❌	Whether chat moderation is enabled
hearts_count_enabled	boolean	❌	Whether like count is shown
fomo_product_viewing_enabled	boolean	❌	Whether real-time product-viewing FOMO cues are shown
replay_enabled	boolean	❌	Whether replay is available after the livestream ends
replay_interactions_enabled	boolean	❌	Whether replay interactions are enabled
replay_messaging_enabled	boolean	❌	Whether viewers can post messages during replay
replay_viewers_count_enabled	boolean	❌	Whether viewer count is shown during replay
trailer_announcement_enabled	boolean	❌	Whether the announcement is shown while viewers watch the trailer
trailer_messaging_enabled	boolean	❌	Whether viewers can post messages while watching the trailer
transcription_enabled	boolean	❌	Whether live transcription is enabled
viewers_count_enabled	boolean	❌	Whether viewer count is shown
viewers_count_mode	string	❌	Viewer-count mode: "accumulated" or "concurrent"
scheduled_at	string	✅	ISO 8601 datetime when livestream is scheduled to start
started_at	string	✅	ISO 8601 datetime when livestream actually started
ended_at	string	✅	ISO 8601 datetime when livestream ended
interactions	object[]	❌	Non-deleted livestream interactions

Each interactions item includes:

Field	Type	Description
id	string	Interaction ID
interaction_type	string	Interaction type
prompt	string / null	Prompt shown to viewers, when applicable
interactive_url	string / null	URL used by link-style interactions
terms_and_conditions_url	string / null	Terms URL configured for the interaction
terms_acceptance_required	boolean	Whether terms acceptance is required
giveaway_celebration_emoji	string	Giveaway celebration emoji
giveaway_description	string / null	Giveaway description
giveaway_winners_count	integer / null	Configured winner count
collect_name	boolean	Whether the interaction collects viewer name
collect_email	boolean	Whether the interaction collects viewer email
collect_phone	boolean	Whether the interaction collects viewer phone
sort_id	integer / null	Display order
options	object[]	Interaction options
option_sets	object[]	Trivia/question option sets
video_id	string / null	Video ID when linked to a video
live_stream_id	string	Livestream ID
tally	object / null	Aggregate counts, when applicable
interaction_results	object[]	Always empty; use CSV export for result rows

The interactions array follows the livestream detail interaction shape and is used to discover interaction_id values for responses_csv. CSV URLs are not returned in this response.

Status Values

Status	Description
idle	Livestream not yet started
active	Livestream currently in progress
paused	Livestream paused by host
replay	Livestream ended, replay available
completed	Replay window ended
expired	Livestream never started

5.4. Get Livestream Error Responses

Status Code	Description
400 Bad Request	Invalid request format or malformed livestream ID
401 Unauthorized	Invalid or missing authentication token, or access denied to this livestream
404 Not Found	Livestream not found

Error Response Format:

{
  "error": "Error Message"
}

5.5. Examples

CURL Request

curl -X GET "https://api.firework.com/api/v1/live_streams/616dOp" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response (Scheduled Livestream)

{
  "id": "616dOp",
  "status": "idle",
  "event_name": "Product Launch Livestream",
  "event_description": "Join us for our exciting new product reveal!",
  "thumbnail_url": "https://cdn.firework.com/live_streams/616dOp/thumbnail.jpg",
  "has_access_code": false,
  "announcement": null,
  "auto_response": "disabled",
  "chat_enabled": true,
  "chat_in_replay_enabled": true,
  "chat_moderation_enabled": false,
  "hearts_count_enabled": false,
  "fomo_product_viewing_enabled": false,
  "replay_enabled": true,
  "replay_interactions_enabled": true,
  "replay_messaging_enabled": false,
  "replay_viewers_count_enabled": false,
  "trailer_announcement_enabled": false,
  "trailer_messaging_enabled": false,
  "transcription_enabled": false,
  "viewers_count_enabled": true,
  "viewers_count_mode": "accumulated",
  "scheduled_at": "2025-03-19T09:41:00.000000Z",
  "started_at": null,
  "ended_at": null,
  "interactions": []
}

Example Response (Active Livestream)

{
  "id": "616dOp",
  "status": "active",
  "event_name": "Product Launch Livestream",
  "event_description": "Join us for our exciting new product reveal!",
  "thumbnail_url": "https://cdn.firework.com/live_streams/616dOp/thumbnail.jpg",
  "has_access_code": false,
  "announcement": null,
  "auto_response": "disabled",
  "chat_enabled": true,
  "chat_in_replay_enabled": true,
  "chat_moderation_enabled": false,
  "hearts_count_enabled": false,
  "fomo_product_viewing_enabled": false,
  "replay_enabled": true,
  "replay_interactions_enabled": true,
  "replay_messaging_enabled": false,
  "replay_viewers_count_enabled": false,
  "trailer_announcement_enabled": false,
  "trailer_messaging_enabled": false,
  "transcription_enabled": false,
  "viewers_count_enabled": true,
  "viewers_count_mode": "accumulated",
  "scheduled_at": "2025-03-19T09:41:00.000000Z",
  "started_at": "2025-03-19T09:42:15.000000Z",
  "ended_at": null,
  "interactions": []
}

Example Response (Completed Livestream)

{
  "id": "616dOp",
  "status": "replay",
  "event_name": "Product Launch Livestream",
  "event_description": "Join us for our exciting new product reveal!",
  "thumbnail_url": "https://cdn.firework.com/live_streams/616dOp/thumbnail.jpg",
  "has_access_code": false,
  "announcement": null,
  "auto_response": "disabled",
  "chat_enabled": true,
  "chat_in_replay_enabled": true,
  "chat_moderation_enabled": false,
  "hearts_count_enabled": false,
  "fomo_product_viewing_enabled": false,
  "replay_enabled": true,
  "replay_interactions_enabled": true,
  "replay_messaging_enabled": false,
  "replay_viewers_count_enabled": false,
  "trailer_announcement_enabled": false,
  "trailer_messaging_enabled": false,
  "transcription_enabled": false,
  "viewers_count_enabled": true,
  "viewers_count_mode": "accumulated",
  "scheduled_at": "2025-03-19T09:41:00.000000Z",
  "started_at": "2025-03-19T09:42:15.000000Z",
  "ended_at": "2025-03-19T11:30:00.000000Z",
  "interactions": [
    {
      "id": "7YDaNq",
      "interaction_type": "giveaway",
      "prompt": "Enter your email for the launch giveaway",
      "interactive_url": null,
      "terms_and_conditions_url": null,
      "terms_acceptance_required": false,
      "giveaway_celebration_emoji": "🎉",
      "giveaway_description": null,
      "giveaway_winners_count": null,
      "collect_name": false,
      "collect_email": true,
      "collect_phone": false,
      "sort_id": 1,
      "options": [],
      "option_sets": [],
      "video_id": null,
      "live_stream_id": "616dOp",
      "tally": null,
      "interaction_results": []
    },
    {
      "id": "2wK9Qa",
      "interaction_type": "poll",
      "prompt": "Which product should we demo next?",
      "interactive_url": null,
      "terms_and_conditions_url": null,
      "terms_acceptance_required": false,
      "giveaway_celebration_emoji": "🎉",
      "giveaway_description": null,
      "giveaway_winners_count": null,
      "collect_name": false,
      "collect_email": false,
      "collect_phone": false,
      "sort_id": 2,
      "options": [
        {
          "text": "Vacuum",
          "confetti": null,
          "is_correct": null,
          "entry_condition": null,
          "keyword": null
        },
        {
          "text": "Air purifier",
          "confetti": null,
          "is_correct": null,
          "entry_condition": null,
          "keyword": null
        }
      ],
      "option_sets": [],
      "video_id": null,
      "live_stream_id": "616dOp",
      "tally": {
        "Vacuum": 257,
        "Air purifier": 166
      },
      "interaction_results": []
    }
  ]
}

---

6. Update Livestream

Update mutable fields on an existing livestream.

Scope of v1: This endpoint updates one livestream at a time. It is intended for metadata, display/settings, schedule, source, trailer, and tagged-product updates. It does not update live session state, streaming provider configuration, channel/feed-level settings, AI copilot setup, or real-time pinned products.

Endpoint: PATCH /api/v1/live_streams/{live_stream_id} Authentication: Bearer token required (OAuth 2.0 Client Credentials) Required Scope: livestreams:write (for OAuth apps) Content Type: application/json Status: Implemented

Scope note: Updating s3_key requires a trailer file that was already uploaded through the public video upload APIs. The upload step requires videos:write.

6.1. Request Headers

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

6.2. Path Parameters

Parameter	Type	Required	Description
live_stream_id	string	✅	The unique identifier of the livestream

6.3. Request Body

All fields are optional, but the request body must include at least one supported field.

Field	Type	Required	Before 5-minute warmup	After 5-minute warmup	Description
caption	string	❌	✅	✅	New livestream title shown to viewers
description	string / null	❌	✅	✅	New livestream description. Use null to clear the description
access_code	string / null	❌	✅	✅	Access code used to lock the video/livestream. Use null to unlock
announcement	string / null	❌	✅	✅	Announcement banner text shown to viewers. Use null or an empty string to clear it
auto_response	string	❌	✅	✅	Chat auto-response mode. Supported values: "always_on", "moderated", "disabled"
chat_enabled	boolean	❌	✅	✅	Whether live chat is enabled
chat_in_replay_enabled	boolean	❌	✅	✅	Whether chat messages are displayed during replay
chat_moderation_enabled	boolean	❌	✅	✅	Whether chat moderation is enabled
hearts_count_enabled	boolean	❌	✅	✅	Whether like count is shown
fomo_product_viewing_enabled	boolean	❌	✅	✅	Whether real-time product-viewing FOMO cues are shown
replay_enabled	boolean	❌	✅	✅	Whether replay is available after the livestream ends
replay_interactions_enabled	boolean	❌	✅	✅	Whether replay interactions are enabled
replay_messaging_enabled	boolean	❌	✅	✅	Whether viewers can post messages during replay
replay_viewers_count_enabled	boolean	❌	✅	✅	Whether viewer count is shown during replay
trailer_announcement_enabled	boolean	❌	✅	✅	Whether the announcement is shown while viewers watch the trailer
trailer_messaging_enabled	boolean	❌	✅	✅	Whether viewers can post messages while watching the trailer
transcription_enabled	boolean	❌	✅	✅	Whether live transcription is enabled, when supported by the provider/source
viewers_count_enabled	boolean	❌	✅	✅	Whether viewer count is shown
viewers_count_mode	string	❌	✅	✅	Viewer-count mode. Supported values: "accumulated" and "concurrent"
scheduled_at	string	❌	✅	❌	New UTC ISO 8601 datetime when the livestream is scheduled to start
time_zone	string / null	❌	✅	❌	IANA timezone identifier for the scheduled event, for example America/New_York
stream_source	string	❌	✅	❌	Source of the livestream. Supported values for v1: "fw" and "external"
s3_key	string	❌	✅	❌	Pre-uploaded trailer key to replace the idle trailer
business_store_id	string	❌	✅	❌	Encoded business store ID used to resolve product_ids
product_ids	string[]	❌	✅	❌	Full replacement list of products tagged to the livestream trailer/video. Use [] to remove all

Request Rules:

• This is a partial update. Omitted fields keep their current values.

• The 5-minute warmup window starts 5 minutes before scheduled_at.

• caption, description, access_code, and livestream instance settings can be updated before or after the livestream enters the warmup window.

• scheduled_at, time_zone, stream_source, s3_key, business_store_id, and product_ids can only be updated before the livestream enters the 5-minute warmup window.

• Livestream instance settings do not update channel/feed-level display settings or AI copilot setup.

• scheduled_at must be provided in UTC ISO 8601 format and must satisfy the same scheduling and maintenance-window restrictions as create.

• stream_source can only be changed when the resulting scheduled time is more than 5 minutes in the future.

• s3_key must be a valid uploaded video key owned by the target channel.

• product_ids replaces the full tagged-product list for the livestream trailer/video. Use the pin and unpin endpoints to change real-time highlighted products during an active livestream.

• product_ids follows the same identifier rules as POST /api/v1/videos and POST /api/v1/live_streams.

• channel_id, provider, stream_key, stream_url, status, started_at, and ended_at cannot be updated through this endpoint.

6.4. Update Livestream Response

Success Response: 200 OK

The response matches GET /api/v1/live_streams/{live_stream_id}. If the resulting livestream uses stream_source: "external", the response also includes publish credentials.

Field	Type	Nullable	Description
id	string	❌	Unique encoded identifier of the livestream
status	string	❌	Current livestream state
event_name	string	❌	Name of the livestream event
event_description	string	✅	Description of the livestream event
thumbnail_url	string	✅	URL of the livestream thumbnail image
has_access_code	boolean	❌	Whether the video/livestream is locked by an access code
announcement	string	✅	Announcement banner text
auto_response	string	❌	Chat auto-response mode
chat_enabled	boolean	❌	Whether live chat is enabled
chat_in_replay_enabled	boolean	❌	Whether chat messages are displayed during replay
chat_moderation_enabled	boolean	❌	Whether chat moderation is enabled
hearts_count_enabled	boolean	❌	Whether like count is shown
fomo_product_viewing_enabled	boolean	❌	Whether real-time product-viewing FOMO cues are shown
replay_enabled	boolean	❌	Whether replay is available after the livestream ends
replay_interactions_enabled	boolean	❌	Whether replay interactions are enabled
replay_messaging_enabled	boolean	❌	Whether viewers can post messages during replay
replay_viewers_count_enabled	boolean	❌	Whether viewer count is shown during replay
trailer_announcement_enabled	boolean	❌	Whether the announcement is shown while viewers watch the trailer
trailer_messaging_enabled	boolean	❌	Whether viewers can post messages while watching the trailer
transcription_enabled	boolean	❌	Whether live transcription is enabled
viewers_count_enabled	boolean	❌	Whether viewer count is shown
viewers_count_mode	string	❌	Viewer-count mode: "accumulated" or "concurrent"
scheduled_at	string	✅	ISO 8601 datetime when livestream is scheduled to start
started_at	string	✅	ISO 8601 datetime when livestream actually started
ended_at	string	✅	ISO 8601 datetime when livestream ended
stream_key	string	✅	Publish stream key. Returned when the resulting livestream uses stream_source: "external"
stream_url	string	✅	Publish RTMP URL. Returned when the resulting livestream uses stream_source: "external"

6.5. Update Livestream Error Responses

Status Code	Description
400 Bad Request	Invalid request body, no supported fields, malformed datetime, invalid s3_key, immutable field, or maintenance block
401 Unauthorized	Invalid or missing authentication token
403 Forbidden	The authenticated user or OAuth app does not have access to the livestream
404 Not Found	Livestream not found
422 Unprocessable Entity	Domain validation error, invalid products, or an update attempted outside the allowed livestream lifecycle

Error Response Format:

Simple request/auth errors return:

{
  "error": "Error Message"
}

Validation errors from changesets return:

{
  "errors": {
    "field_name": ["validation message"]
  }
}

6.6. Examples

Example 1: Update Livestream Metadata and Schedule

curl -X PATCH "https://api.firework.com/api/v1/live_streams/616dOp" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Summer Sale Livestream - Encore",
    "description": "Updated schedule and event details",
    "scheduled_at": "2026-07-21T10:00:00.000000Z",
    "time_zone": "America/New_York"
  }'

Example 2: Update Stream Source, Trailer, and Tagged Products

curl -X PATCH "https://api.firework.com/api/v1/live_streams/616dOp" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stream_source": "external",
    "s3_key": "medias/business/AbCdEfG/channel/HiJkLmN/videos/public/original/1738152000-abcdefgh-trailer-v2.mp4",
    "business_store_id": "QwErTy",
    "product_ids": ["GeEk8y", "ABC123"]
  }'

Example 3: Update Display Settings

curl -X PATCH "https://api.firework.com/api/v1/live_streams/616dOp" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "replay_enabled": true,
    "replay_viewers_count_enabled": true,
    "trailer_announcement_enabled": true,
    "viewers_count_enabled": true,
    "viewers_count_mode": "accumulated",
    "hearts_count_enabled": false,
    "fomo_product_viewing_enabled": false,
    "transcription_enabled": true,
    "access_code": "VIP123",
    "announcement": "Doors open in 5 minutes"
  }'

Example Response (Metadata and Schedule Update)

{
  "id": "616dOp",
  "status": "idle",
  "event_name": "Summer Sale Livestream - Encore",
  "event_description": "Updated schedule and event details",
  "thumbnail_url": "https://cdn.firework.com/live_streams/616dOp/thumbnail.jpg",
  "has_access_code": false,
  "announcement": null,
  "auto_response": "disabled",
  "chat_enabled": true,
  "chat_in_replay_enabled": true,
  "chat_moderation_enabled": false,
  "hearts_count_enabled": false,
  "fomo_product_viewing_enabled": false,
  "replay_enabled": true,
  "replay_interactions_enabled": true,
  "replay_messaging_enabled": false,
  "replay_viewers_count_enabled": false,
  "trailer_announcement_enabled": false,
  "trailer_messaging_enabled": false,
  "transcription_enabled": false,
  "viewers_count_enabled": true,
  "viewers_count_mode": "accumulated",
  "scheduled_at": "2026-07-21T10:00:00.000000Z",
  "started_at": null,
  "ended_at": null
}

Example Response (External Stream Source Update)

{
  "id": "616dOp",
  "status": "idle",
  "event_name": "Summer Sale Livestream",
  "event_description": "Join us for our scheduled commerce event",
  "thumbnail_url": "https://cdn.firework.com/live_streams/616dOp/thumbnail.jpg",
  "has_access_code": false,
  "announcement": null,
  "auto_response": "disabled",
  "chat_enabled": true,
  "chat_in_replay_enabled": true,
  "chat_moderation_enabled": false,
  "hearts_count_enabled": false,
  "fomo_product_viewing_enabled": false,
  "replay_enabled": true,
  "replay_interactions_enabled": true,
  "replay_messaging_enabled": false,
  "replay_viewers_count_enabled": false,
  "trailer_announcement_enabled": false,
  "trailer_messaging_enabled": false,
  "transcription_enabled": false,
  "viewers_count_enabled": true,
  "viewers_count_mode": "accumulated",
  "scheduled_at": "2026-07-20T10:00:00.000000Z",
  "started_at": null,
  "ended_at": null,
  "stream_key": "sk_live_abc123",
  "stream_url": "rtmps://global-live.mux.com:443/app"
}

6.7. Error Responses

// 400 Bad Request - No supported fields
{
  "error": "At least one supported field is required"
}

// 400 Bad Request - Immutable field
{
  "error": "status cannot be updated"
}

// 422 Unprocessable Entity - Livestream is too close to start
{
  "error": "scheduled_at, time_zone, stream_source, s3_key, business_store_id, product_ids can only be updated before the warmup window"
}

// 422 Unprocessable Entity - stream_source update too close to start
{
  "error": "stream_source cannot be changed less than 300 seconds prior to the livestream"
}

---

7. Pin Products to Livestream

Pin (highlight) one or more products during an active livestream. The pinned products will be prominently displayed to all viewers watching the livestream in real-time.

Endpoint: POST /api/v1/live_streams/{live_stream_id}/pin_product Authentication: Bearer token required (OAuth 2.0 Client Credentials) Required Scope: livestreams:write (for OAuth apps) Content Type: application/json

Important: This endpoint can only be used when the livestream status is active or paused. Products cannot be pinned to livestreams in idle, replay, completed, or expired status.

Note: The system supports up to 3 products pinned simultaneously(override).

7.1. Request Headers

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

7.2. Path Parameters

Parameter	Type	Required	Description
live_stream_id	string	✅	The unique identifier of the livestream

7.3. Request Body

Parameter	Type	Required	Description
product_ids	string[]	✅	Array of Firework product IDs or product unit IDs to pin

Note: Both Firework product IDs and product unit IDs are supported. You can obtain these IDs from the Firework product catalog or product management APIs. The array must contain at least 1 item and maximum 3 items per request.

7.4. Pin Products Response

Success Response: 200 OK

Field	Type	Description
pinned_product_ids	string[]	Array of product IDs that were pinned in this request

Note: Upon receiving this success response, all products have already been broadcasted to all viewers. There is no delay - the pins are live immediately.

7.5. Pin Products Error Responses

Status Code	Description
400 Bad Request	Invalid request format, missing product_ids, or malformed IDs
401 Unauthorized	Invalid or missing authentication token, or access denied to this livestream
404 Not Found	Livestream not found or no valid products found
422 Unprocessable Entity	Livestream is not active (must be in active or paused status)

7.6. Example Requests

Example 1: Pin Products

curl -X POST "https://api.firework.com/api/v1/live_streams/616dOp/pin_product" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": ["GeEk8y", "ABC123", "XYZ789"]
  }'

Success Response (200 OK)

{
  "pinned_product_ids": ["GeEk8y", "ABC123", "XYZ789"]
}

Example 2: Pin Product Unit (Variant/SKU)

curl -X POST "https://api.firework.com/api/v1/live_streams/616dOp/pin_product" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": ["082YOm"]
  }'

Success Response (200 OK)

{
  "pinned_product_ids": ["082YOm"]
}

Note: In this example, 082YOm is a product unit ID representing a specific variant (e.g., "Black / Standard"). Pinning a product unit highlights that specific variant during the livestream.

7.7. Error Responses

// 422 Unprocessable Entity - Livestream not active
{
  "error": "Livestream must be active or paused to pin products"
}

// 404 Not Found - Livestream not found
{
  "error": "Livestream not found"
}

// 400 Bad Request - Missing product_ids
{
  "error": "product_ids is required"
}

// 400 Bad Request - Empty array
{
  "error": "product_ids cannot be empty"
}

// 400 Bad Request - More than 3 products
{
  "error": "Maximum 3 products allowed per request"
}

---

8. Unpin Products from Livestream

Remove one or more pinned (highlighted) products from a livestream. This clears the product highlights for all viewers.

Endpoint: POST /api/v1/live_streams/{live_stream_id}/unpin_product Authentication: Bearer token required (OAuth 2.0 Client Credentials) Required Scope: livestreams:write (for OAuth apps) Content Type: application/json

8.1. Request Headers

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

8.2. Path Parameters

Parameter	Type	Required	Description
live_stream_id	string	✅	The unique identifier of the livestream

8.3. Request Body

Parameter	Type	Required	Description
product_ids	string[]	✅	Array of Firework product IDs or product unit IDs to unpin

Note: Provide the Firework product IDs or product unit IDs (variant/SKU IDs) you want to remove from the highlighted set. The array must contain at least 1 item and maximum 3 items per request.

8.4. Unpin Products Response

Success Response: 200 OK

Field	Type	Description
unpinned_product_ids	string[]	Array of product IDs that were unpinned in this request

8.5. Unpin Products Error Responses

Status Code	Description
400 Bad Request	Invalid request format or malformed livestream ID
401 Unauthorized	Invalid or missing authentication token, or access denied to this livestream
404 Not Found	Livestream not found or no valid products found

8.6. Example Requests

Example 1: Unpin Products

curl -X POST "https://api.firework.com/api/v1/live_streams/616dOp/unpin_product" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": ["GeEk8y", "ABC123", "XYZ789"]
  }'

Success Response (200 OK)

{
  "unpinned_product_ids": ["GeEk8y", "ABC123", "XYZ789"]
}

Example 2: Unpin Product Unit (Variant/SKU)

curl -X POST "https://api.firework.com/api/v1/live_streams/616dOp/unpin_product" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": ["082YOm"]
  }'

Success Response (200 OK)

{
  "unpinned_product_ids": ["082YOm"]
}

8.7. Error Responses

// 404 Not Found - Livestream not found
{
  "error": "Livestream not found"
}

// 404 Not Found - No valid products found
{
  "error": "No valid products found to unpin"
}

// 400 Bad Request - Missing product_ids
{
  "error": "product_ids is required"
}

// 400 Bad Request - Empty array
{
  "error": "product_ids cannot be empty"
}

---

9. End Livestream

End an active or paused livestream. The livestream status will transition to replay.

Endpoint: PATCH /api/v1/live_streams/{live_stream_id}/end Authentication: Bearer token required (OAuth 2.0 Client Credentials) Required Scope: livestreams:write (for OAuth apps) Content Type: application/json

Important: This action is irreversible. Once ended, the livestream cannot return to active status.

9.1. Request Headers

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

9.2. Path Parameters

Parameter	Type	Required	Description
live_stream_id	string	✅	The unique identifier of the livestream

9.3. Request Body

No request body is required.

9.4. End Livestream Response

Success Response: 200 OK

Field	Type	Description
live_stream_id	string	The livestream that was ended
status	string	Always "ended" once the operation succeeds

9.5. End Livestream Error Responses

Status Code	Description
400 Bad Request	Livestream already ended or in a non-active state
401 Unauthorized	Invalid or missing authentication token, or access denied to this livestream
404 Not Found	Livestream not found

9.6. Examples

Example 1: End an Active Livestream

CURL Request

curl -X PATCH "https://api.firework.com/api/v1/live_streams/616dOp/end" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Success Response (200 OK)

{
  "live_stream_id": "616dOp",
  "status": "ended"
}

Error Response Examples

// 404 Not Found - Livestream not found
{
  "error": "Livestream not found"
}

// 400 Bad Request - Livestream already ended
{
  "error": "Livestream must be active or paused to end"
}

10. Export Livestream Engagement Results

Export interaction results and livestream comments after a livestream has ended. These endpoints mirror the result-download use case that is currently available in CMS, while keeping interaction setup and moderation workflows in CMS.

Status: Implemented Authentication: Bearer token required (OAuth 2.0 Client Credentials) Required Scope: livestreams:read (for OAuth apps)

Scope note: Engagement exports can contain viewer-entered data such as emails, names, answers, and comments. Grant livestreams:read only to OAuth apps that are allowed to export post-event livestream result data.

Availability note: CSV result downloads are available only after the livestream has ended. If the livestream is still scheduled, idle, active, paused, or otherwise not ended, the CSV endpoints return 409 Conflict.

10.1. Recommended Workflow

1. Create and manage the livestream through the existing livestream APIs.

2. End the livestream through CMS or PATCH /api/v1/live_streams/{live_stream_id}/end.

3. Call GET /api/v1/live_streams/{live_stream_id} and read the interactions array.

4. Download each interaction result file by calling responses_csv with the livestream ID and interaction ID.

5. Download chat/comment history by calling comments_csv with the livestream ID when comment data is needed.

10.2. Download Interaction Responses CSV

Download stored response rows for a single livestream interaction.

Endpoint: GET /api/v1/live_streams/{live_stream_id}/interactions/{interaction_id}/responses_csv Authentication: Bearer token required (OAuth 2.0 Client Credentials) Required Scope: livestreams:read Response Content Type: text/csv

Request Headers

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅

Path Parameters

Parameter	Type	Required	Description
live_stream_id	string	✅	The unique identifier of the livestream
interaction_id	string	✅	The unique identifier of the interaction

CSV Columns

Column	Description
id	Interaction response row ID
interaction_id	Interaction ID
interaction_type	Interaction type
prompt	Interaction prompt
response	Viewer response value, such as poll choice or question answer
email	Viewer email, when collected
name	Viewer name, when collected
guest_id	Guest identifier
user_id	Registered user identifier, when available
country	Viewer country, when available
terms_accepted	Whether the viewer accepted terms for the interaction
winner	Whether the row is marked as a giveaway winner, when applicable
is_correct	Whether the trivia answer is correct, when applicable
live_stream_status	Whether the response was submitted during active or replay
submitted_at	ISO 8601 timestamp when the response was submitted

Example

curl -X GET "https://api.firework.com/api/v1/live_streams/616dOp/interactions/7YDaNq/responses_csv" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

id,interaction_id,interaction_type,prompt,response,email,name,guest_id,user_id,country,terms_accepted,winner,is_correct,live_stream_status,submitted_at
81NmQp,7YDaNq,giveaway,Enter your email for the launch giveaway,,[e-mail],Jamie,guest_123,,US,true,true,,active,2026-05-11T14:25:08Z

10.3. Download Livestream Comments CSV

Download chat/comment history for an ended livestream. Use this endpoint for comment exports and for reviewing comment-giveaway source messages.

Endpoint: GET /api/v1/live_streams/{live_stream_id}/comments_csv Authentication: Bearer token required (OAuth 2.0 Client Credentials) Required Scope: livestreams:read Response Content Type: text/csv

Request Headers

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅

Path Parameters

Parameter	Type	Required	Description
live_stream_id	string	✅	The unique identifier of the livestream

CSV Columns

Column	Description
message_id	Livestream chat message ID
elapsed_time	Elapsed livestream time when the message was sent
user_type	Sender type
private_thread_owner_id	Private-thread owner ID, when applicable
guest_id	Guest identifier
user_id	Registered user identifier, when available
username	Display name
title	Livestream title
original_text	Original comment text
reply_to_message_id	Parent message ID, when this message is a reply
reply_to_message_text	Parent message text, when available
reply_to_message_username	Parent message sender, when available
inserted_at	ISO 8601 timestamp when the message was created
status	Message moderation status
live_stream_status	Whether the message was sent during live or replay

Example

curl -X GET "https://api.firework.com/api/v1/live_streams/616dOp/comments_csv" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

message_id,elapsed_time,user_type,private_thread_owner_id,guest_id,user_id,username,title,original_text,reply_to_message_id,reply_to_message_text,reply_to_message_username,inserted_at,status,live_stream_status
msg_123,00:04:18,viewer,,guest_123,,Jamie,Spring Launch,Love this product!,,,,2026-05-11T14:18:42Z,approved,live

10.4. Error Responses

Status Code	Description
400 Bad Request	Invalid request, unsupported interaction type, or malformed ID
401 Unauthorized	Invalid or missing authentication token
403 Forbidden	Missing livestreams:read scope or access denied to this business livestream
404 Not Found	Livestream not found, or interaction not found on the specified livestream
409 Conflict	Livestream has not ended yet, so result exports are not available

Error Response Examples

// 403 Forbidden - Missing livestreams:read scope
{
  "error": "insufficient_scope",
  "required_scope": "livestreams:read"
}

// 404 Not Found - Interaction does not belong to livestream
{
  "error": "Interaction not found"
}

// 409 Conflict - Livestream has not ended yet
{
  "error": "Livestream engagement results are available only after the livestream has ended"
}

---

11. List Livestreams

List the livestreams that belong to a channel. Only primary, non-showroom livestreams are returned. Archived livestreams are excluded by default; set archived=true to return only archived livestreams. Use this endpoint to discover id values to feed into the reporting stats endpoint (section 13) and the per-livestream read/export endpoints.

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

11.1. Request Headers

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅

11.2. Query Parameters

Parameter	Type	Required	Description
channel_id	string	✅	Encoded channel ID to list livestreams for
statuses	string	❌	Comma-separated status filter, for example active,replay. Every value must be a valid livestream status (see Status Values in section 5.3); an unrecognized value returns 400.
archived	boolean	❌	Omitted or false returns only non-archived livestreams; true returns only archived livestreams
after	string	❌	Opaque cursor for the next page, taken from pagination.cursor or links.next of a previous response. Ascending order.
before	string	❌	Opaque cursor for the previous page. Descending order. Mutually exclusive with after.
page_size	integer	❌	Items per page. Range 1–100, default 10. Values above the max are clamped.

Pagination: This endpoint is cursor-paginated. Follow links.next verbatim (it is null when there is no next page) or pass the opaque pagination.cursor back as after/before. after and before are mutually exclusive.

11.3. List Livestreams Response

Success Response: 200 OK

Field	Type	Nullable	Description
live_streams	object[]	❌	Livestream summaries (see item fields below)
links	object	❌	Pagination links. next is always present (null on the last page)
pagination	object	❌	Pagination state: cursor (opaque, null when exhausted), has_more

Each live_streams item matches the GET /api/v1/live_streams/{live_stream_id} response (section 5.3) plus video_id, channel_id, and stream_source, and without the interactions array:

Field	Type	Nullable	Description
id	string	❌	Unique encoded identifier of the livestream
video_id	string	❌	Encoded identifier of the backing video
channel_id	string	❌	Encoded identifier of the channel
status	string	❌	Current livestream state (see Status Values, section 5.3)
stream_source	string	❌	Source of the livestream: fw, external, or prerecorded
event_name	string	✅	Name of the livestream event
event_description	string	✅	Description of the livestream event
thumbnail_url	string	✅	URL of the livestream thumbnail image
has_access_code	boolean	❌	Whether the video/livestream is locked by an access code
announcement	string	✅	Announcement banner text
auto_response	string	✅	Chat auto-response mode
chat_enabled	boolean	❌	Whether live chat is enabled
chat_in_replay_enabled	boolean	❌	Whether chat messages are displayed during replay
chat_moderation_enabled	boolean	❌	Whether chat moderation is enabled
hearts_count_enabled	boolean	❌	Whether like count is shown
fomo_product_viewing_enabled	boolean	❌	Whether real-time product-viewing FOMO cues are shown
replay_enabled	boolean	❌	Whether replay is available after the livestream ends
replay_interactions_enabled	boolean	❌	Whether replay interactions are enabled
replay_messaging_enabled	boolean	❌	Whether viewers can post messages during replay
replay_viewers_count_enabled	boolean	❌	Whether viewer count is shown during replay
trailer_announcement_enabled	boolean	❌	Whether the announcement is shown while viewers watch the trailer
trailer_messaging_enabled	boolean	❌	Whether viewers can post messages while watching the trailer
transcription_enabled	boolean	❌	Whether live transcription is enabled
viewers_count_enabled	boolean	❌	Whether viewer count is shown
viewers_count_mode	string	✅	Viewer-count mode: "accumulated" or "concurrent"
scheduled_at	string	✅	ISO 8601 datetime when livestream is scheduled to start
started_at	string	✅	ISO 8601 datetime when livestream actually started
ended_at	string	✅	ISO 8601 datetime when livestream ended

11.4. List Livestreams Error Responses

Status Code	Description
400 Bad Request	Missing channel_id, or an unrecognized value in statuses
401 Unauthorized	Invalid or missing authentication token
403 Forbidden	The authenticated user or OAuth app does not have access to the channel
404 Not Found	Channel not found

Error Response Format:

{
  "error": "Error Message"
}

11.5. Example

CURL Request

curl -X GET "https://api.firework.com/api/v1/live_streams?channel_id=X6Xqd6W&statuses=active,replay&page_size=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response

{
  "live_streams": [
    {
      "id": "616dOp",
      "video_id": "9aQ2Kp",
      "channel_id": "X6Xqd6W",
      "status": "replay",
      "stream_source": "fw",
      "event_name": "Product Launch Livestream",
      "event_description": "Join us for our exciting new product reveal!",
      "thumbnail_url": "https://cdn.firework.com/live_streams/616dOp/thumbnail.jpg",
      "has_access_code": false,
      "announcement": null,
      "auto_response": "disabled",
      "chat_enabled": true,
      "chat_in_replay_enabled": true,
      "chat_moderation_enabled": false,
      "hearts_count_enabled": false,
      "fomo_product_viewing_enabled": false,
      "replay_enabled": true,
      "replay_interactions_enabled": true,
      "replay_messaging_enabled": false,
      "replay_viewers_count_enabled": true,
      "trailer_announcement_enabled": false,
      "trailer_messaging_enabled": false,
      "transcription_enabled": false,
      "viewers_count_enabled": true,
      "viewers_count_mode": "accumulated",
      "scheduled_at": "2026-03-19T09:41:00.000000Z",
      "started_at": "2026-03-19T09:42:15.000000Z",
      "ended_at": "2026-03-19T11:30:00.000000Z"
    }
  ],
  "links": {
    "next": "/api/v1/live_streams?channel_id=X6Xqd6W&statuses=active,replay&after=cursor456&page_size=50"
  },
  "pagination": {
    "cursor": "cursor456",
    "has_more": true
  }
}

---

12. List Livestream Chat Messages

Cursor-paginated chat messages for a livestream. Messages are available while the livestream is live (active) or in replay (replay, i.e. ended):

• Live (active) — forward paging only. The first request (no cursor) starts from a trailing window near the live edge, and the response always returns an after cursor and a non-null links.next — even at the live edge — so the client can keep polling. Backward paging (before / until) is rejected.

• Replay (replay) — both forward (after / since) and backward (before / until) paging are supported, defaulting to forward from the start. When paging reaches the end, pagination.cursor and links.next become null.

Any other status returns 400.

Endpoint: GET /api/v1/live_streams/{live_stream_id}/messages Authentication: Bearer token required (OAuth 2.0 Client Credentials) Required Scope: livestreams:read (for OAuth apps)

12.1. Request Headers

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅

12.2. Path Parameters

Parameter	Type	Required	Description
live_stream_id	string	✅	The unique identifier of the livestream

12.3. Query Parameters

Parameter	Type	Required	Description
after	string	❌	Opaque forward cursor from a previous response (pagination.cursor / links.next). Ascending order.
before	string	❌	Opaque backward cursor (replay only). Descending order. Mutually exclusive with after.
since	number	❌	Elapsed-time window start, in seconds from the start of the stream. Returns messages at/after this offset, ascending.
until	number	❌	Elapsed-time window end, in seconds. Returns messages before this offset, descending (replay only).
page_size	integer	❌	Items per page. Range 1–100, default 10. Values above the max are clamped.

Parameter Rules:

• after / before are opaque cursors the server issued; since / until are elapsed-time values you supply. They are not interchangeable.

• Provide at most one paging direction per request. after and before are mutually exclusive; conflicting or otherwise invalid combinations return 400.

• since / after page forward (ascending); until / before page backward (descending).

• Backward paging (before / until) is only valid in replay mode. Requesting it while the livestream is live returns 400.

• since / until must parse as numbers.

12.4. List Messages Response

Success Response: 200 OK

Field	Type	Nullable	Description
messages	object[]	❌	Chat messages for the page (see item fields below)
links	object	❌	Pagination links. next is the path to the next page, or null
pagination	object	❌	Pagination state: cursor (opaque, null when exhausted), has_more

Each messages item:

Field	Type	Nullable	Description
id	string	❌	Chat message ID
elapsed_time	number	❌	Seconds from the start of the stream
username	string	❌	Display name of the sender
text	string	❌	Message text
inserted_at	string	❌	ISO 8601 timestamp when the message was created

Client Polling Semantics

For live feeds, the pair (links.next, pagination.has_more) tells the client what to do next:

links.next	has_more	Meaning	Action
null	—	No more data ever (e.g. replay ended)	Stop.
present	true	More pages available now	Fetch links.next immediately.
present	false	Caught up to the live edge	Save links.next, fetch after a poll interval.

12.5. List Messages Error Responses

Status Code	Description
400 Bad Request	Livestream is not live or in replay, conflicting/invalid pagination params, backward paging while live, or non-numeric since/until
401 Unauthorized	Invalid or missing authentication token
403 Forbidden	The authenticated user or OAuth app does not have access to this livestream
404 Not Found	Livestream not found

Error Response Format:

{
  "error": "Error Message"
}

12.6. Example

CURL Request

curl -X GET "https://api.firework.com/api/v1/live_streams/616dOp/messages?after=cursor123&page_size=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response

{
  "messages": [
    {
      "id": "b3f1Xy",
      "elapsed_time": 132.5,
      "username": "jane_doe",
      "text": "Is this available in size M?",
      "inserted_at": "2026-06-12T12:04:03.986000Z"
    }
  ],
  "links": {
    "next": "/api/v1/live_streams/616dOp/messages?after=cursor456&page_size=100"
  },
  "pagination": {
    "cursor": "cursor456",
    "has_more": true
  }
}

---

13. Livestream Reporting Stats

Consolidated reporting stats for a single livestream, in a meta / live / replay shape. meta carries identity and event metadata, live holds the active broadcast's metrics (or null when the livestream is not currently live), and replay is an array of per-day replay metric rows.

Endpoint: GET /api/v1/stats/live_streams/{live_stream_id} Authentication: Bearer token required (OAuth 2.0 Client Credentials) Required Scope: livestreams:read (for OAuth apps)

Note: The live_stream_id values returned by GET /api/v1/live_streams (section 11) are the inputs to this endpoint.

13.1. Request Headers

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅

13.2. Path Parameters

Parameter	Type	Required	Description
live_stream_id	string	✅	The unique identifier of the livestream

13.3. Query Parameters

Parameter	Type	Required	Description
from	string	❌	Replay-window start as an ISO date (YYYY-MM-DD, e.g. 2026-01-31). Bounds only the replay array.
to	string	❌	Replay-window end as an ISO date. Bounds only the replay array.

Parameter Rules:

• from / to bound only the replay array. meta and live are never dropped by the date window.

• All rows are capped at the previous UTC day (current date − 1), so the current, partial day is excluded.

• A from / to value that is not a valid ISO date (including a bracketed from[]=... form) returns 400.

13.4. Reporting Stats Response

Success Response: 200 OK

Field	Type	Nullable	Description
meta	object	❌	Livestream identity and event metadata (see below)
live	object / null	✅	Metrics for the active broadcast, or null when the livestream is not live
replay	object[]	❌	Per-day replay metric rows (see metrics fields below)

meta fields:

Field	Type	Nullable	Description
live_stream_id	string	❌	Encoded livestream ID
video_id	string	❌	Encoded backing video ID
business_id	string	❌	Encoded business ID
channel_id	string	❌	Encoded channel ID
start_date	string	✅	Report date of the active row (ISO date), or null
live_stream_name	string	✅	Livestream/event name
is_human_hosted	boolean	✅	Whether the event was human-hosted
is_restream	boolean	✅	Whether the event was a restream
event_length_mins	number	✅	Event length in minutes

The live object contains the shared metrics fields below plus two live-only fields:

Field	Type	Nullable	Description
peak_concurrent_viewer_count	integer	❌	Peak concurrent viewers of the broadcast
total_reactions	integer	❌	Total reactions during the broadcast

Shared metrics fields (present on live and on each replay row):

Field	Type	Nullable	Description
report_date	string	❌	Report date (ISO date)
unique_viewers_count	integer	❌	Unique viewers for the day
viewer_watch_time_breakdown	object	❌	Viewer counts bucketed by watch time (fields below)
viewer_watch_time_breakdown.num_watched_0_mins	integer	❌	Viewers who watched ~0 minutes
viewer_watch_time_breakdown.num_watched_0_to_1_mins	integer	❌	Viewers who watched 0–1 minutes
viewer_watch_time_breakdown.num_watched_1_to_10_mins	integer	❌	Viewers who watched 1–10 minutes
viewer_watch_time_breakdown.num_watched_10_to_30_mins	integer	❌	Viewers who watched 10–30 minutes
viewer_watch_time_breakdown.num_watched_30_to_end_mins	integer	❌	Viewers who watched 30 minutes to the end
total_watched_seconds	number	❌	Total watch time in seconds
engaged_viewers	integer	❌	Engaged viewers for the day
total_video_views	integer	❌	Total video views
total_chats	integer	❌	Total chat messages
total_shares	integer	❌	Total shares
share_targets	object	❌	Map of share target (e.g. facebook) → count; {} when none
total_product_clicks	integer	❌	Total product clicks
total_7d_attributed_gmv	object	❌	Map of currency code → 7-day attributed GMV; {} when none
total_7d_attributed_orders	object	❌	Map of currency code → 7-day attributed order count; {} when none

13.5. Reporting Stats Error Responses

Status Code	Description
400 Bad Request	from / to is not a valid ISO date
401 Unauthorized	Invalid or missing authentication token
403 Forbidden	Access denied to this business livestream
404 Not Found	Livestream not found

Error Response Format:

{
  "error": "Error Message"
}

13.6. Example

CURL Request

curl -X GET "https://api.firework.com/api/v1/stats/live_streams/616dOp?from=2026-03-19&to=2026-03-25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response

{
  "meta": {
    "live_stream_id": "616dOp",
    "video_id": "9aQ2Kp",
    "business_id": "Bz1QwE",
    "channel_id": "X6Xqd6W",
    "start_date": "2026-03-19",
    "live_stream_name": "Product Launch Livestream",
    "is_human_hosted": true,
    "is_restream": false,
    "event_length_mins": 108.0
  },
  "live": null,
  "replay": [
    {
      "report_date": "2026-03-20",
      "unique_viewers_count": 1423,
      "viewer_watch_time_breakdown": {
        "num_watched_0_mins": 210,
        "num_watched_0_to_1_mins": 512,
        "num_watched_1_to_10_mins": 480,
        "num_watched_10_to_30_mins": 180,
        "num_watched_30_to_end_mins": 41
      },
      "total_watched_seconds": 1875400.0,
      "engaged_viewers": 902,
      "total_video_views": 1610,
      "total_chats": 388,
      "total_shares": 57,
      "share_targets": { "facebook": 31, "x": 26 },
      "total_product_clicks": 214,
      "total_7d_attributed_gmv": { "USD": 4820.5 },
      "total_7d_attributed_orders": { "USD": 62 }
    }
  ]
}

---

14. Get Livestream Detail (Legacy)

Fetch the viewer-side detail payload for a livestream — the same data the player/embed uses to render playback, products, interactions, and replays.

Legacy endpoint: This route is served by the viewer-side controller (NabooWeb.OauthApp.LiveStreamController) and is retained for backward compatibility. Its response is a large, loosely-typed viewer payload whose exact shape is defined by the internal player view (NabooWeb.LiveStreamView) and may include additional fields not listed here. For host/management and reporting use cases, prefer GET /api/v1/live_streams/{live_stream_id} (section 5) and the stats endpoint (section 13).

Endpoint: GET /api/v1/live_streams/{live_stream_id}/detail Authentication: Bearer token required (OAuth 2.0 Client Credentials) Required Scope: livestreams:read (for OAuth apps)

14.1. Request Headers

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅

14.2. Path Parameters

Parameter	Type	Required	Description
live_stream_id	string	✅	The unique identifier of the livestream

14.3. Livestream Detail Response

Success Response: 200 OK

The response is a loosely-typed viewer object. Representative top-level fields (non-exhaustive):

Field	Type	Nullable	Description
status	string	❌	Current livestream state (see Status Values, section 5.3)
stream_source	string	❌	Source of the livestream: fw, external, or prerecorded
provider	string	❌	Streaming provider
event_name	string	❌	Name of the livestream event
event_description	string	✅	Description of the livestream event
playback_url	string	✅	Live playback URL
replay_url	string	✅	Replay playback URL
scheduled_at	string	✅	ISO 8601 datetime when the livestream is scheduled to start
started_at	string	✅	ISO 8601 datetime when the livestream started
ended_at	string	✅	ISO 8601 datetime for the scheduled/actual end
announcement	string	✅	Announcement banner text
chat_enabled	boolean	❌	Whether live chat is enabled
chat_in_replay_enabled	boolean	❌	Whether chat is displayed during replay
chat_moderation_enabled	boolean	❌	Whether chat moderation is enabled
hearts_count_enabled	boolean	❌	Whether like count is shown
fomo_product_viewing_enabled	boolean	❌	Whether real-time product-viewing FOMO cues are shown
replay_enabled	boolean	❌	Whether replay is available
replay_interactions_enabled	boolean	❌	Whether replay interactions are enabled
viewers_count_enabled	boolean	❌	Whether viewer count is shown
viewers_count_mode	string	✅	Viewer-count mode
transcription_enabled	boolean	❌	Whether live transcription is enabled
products	object[]	❌	Tagged/pinned products and their key moments
interactions	object[]	❌	Polls, quizzes, questions, and giveaways
deals	object[]	❌	Livestream deals
insights	object	❌	Aggregate counts (likes, viewers)
subtitles	object[]	❌	Subtitle tracks
video_id	string	❌	Encoded backing video ID
test_mode	boolean	❌	Whether the livestream is in test mode
time_zone	string	✅	IANA timezone identifier for the event

Note: The full payload also includes additional viewer-oriented fields (moderation config, message rate limits, replay playlists, share URLs, and more). Treat unlisted fields as forward-compatible additions.

14.4. Livestream Detail Error Responses

Status Code	Description
401 Unauthorized	Invalid or missing authentication token
403 Forbidden	The authenticated user or OAuth app does not have access to this livestream
404 Not Found	Livestream not found

Error Response Format:

{
  "error": "Error Message"
}

14.5. Example

CURL Request

curl -X GET "https://api.firework.com/api/v1/live_streams/616dOp/detail" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

---

15. List Livestream Playlist Videos (Legacy)

List the videos (livestreams) contained in a livestream playlist. Unlike the other list endpoints, this endpoint uses page-based pagination (page / page_size), not cursors.

Legacy endpoint: Served by the viewer-side controller (NabooWeb.OauthApp.LiveStreamController) and slated for migration to the standard cursor pagination shape. During the migration window the response carries the modern links + pagination objects alongside the deprecated paging object; new integrations should read links / pagination and ignore paging.

Endpoint: GET /api/v1/live_streams/playlists/{playlist_id}/videos Authentication: Bearer token required (OAuth 2.0 Client Credentials) Required Scope: livestreams:read (for OAuth apps)

15.1. Request Headers

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅

15.2. Path Parameters

Parameter	Type	Required	Description
playlist_id	string	✅	The unique identifier of the playlist

15.3. Query Parameters

Parameter	Type	Required	Description
page	integer	❌	1-based page number. Default 1.
page_size	integer	❌	Items per page. Range 1–100, default 10. Values above the max are clamped.
status	string	❌	Filter to a single livestream status (see Status Values, section 5.3).
test_mode	string	❌	Filter test-mode livestreams (true / false).
archived	boolean	❌	Omitted or false returns only non-archived livestreams; true returns only archived livestreams

15.4. Playlist Videos Response

Success Response: 200 OK

Field	Type	Nullable	Description
live_streams	object[]	❌	Livestream detailed summaries (see item fields below)
links	object	❌	Pagination links (next, prev)
pagination	object	❌	Pagination state for the page strategy: page, has_more (and page metadata)
paging	object	❌	Deprecated — legacy { next, prev } URL object. Use links / pagination instead.

Each live_streams item is a loosely-typed livestream detailed summary. Representative fields (non-exhaustive):

Field	Type	Nullable	Description
id	string	❌	Encoded livestream ID
parent_live_stream_id	string	✅	Encoded parent livestream ID, when applicable
status	string	❌	Current livestream state (see Status Values)
scheduled_at	string	✅	ISO 8601 datetime when scheduled to start
started_at	string	✅	ISO 8601 datetime when started
ended_at	string	✅	ISO 8601 datetime when ended
scheduled_end_at	string	✅	ISO 8601 datetime for the scheduled end
duration	number	✅	Duration in seconds
event_name	string	❌	Name of the livestream event
event_description	string	✅	Description of the livestream event
likes_count	integer	❌	Aggregate like count
viewers_count	integer	❌	Aggregate viewer count
video_posters	object[]	❌	Poster images for the livestream
trailer	object	❌	The backing video object

Note: The full item also includes formatted date fields and other viewer-oriented attributes. Treat unlisted fields as forward-compatible additions.

15.5. Playlist Videos Error Responses

Status Code	Description
401 Unauthorized	Invalid or missing authentication token
403 Forbidden	The authenticated user or OAuth app does not have access to the playlist
404 Not Found	Playlist not found

Error Response Format:

{
  "error": "Error Message"
}

15.6. Example

CURL Request

curl -X GET "https://api.firework.com/api/v1/live_streams/playlists/QwErTy/videos?page=1&page_size=20&status=replay" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response

{
  "live_streams": [
    {
      "id": "616dOp",
      "parent_live_stream_id": null,
      "status": "replay",
      "scheduled_at": "2026-03-19T09:41:00.000000Z",
      "started_at": "2026-03-19T09:42:15.000000Z",
      "ended_at": "2026-03-19T11:30:00.000000Z",
      "scheduled_end_at": "2026-03-19T11:41:00.000000Z",
      "duration": 6705.0,
      "event_name": "Product Launch Livestream",
      "event_description": "Join us for our exciting new product reveal!",
      "likes_count": 3820,
      "viewers_count": 1423,
      "video_posters": [],
      "trailer": {}
    }
  ],
  "links": {
    "next": "/api/v1/live_streams/playlists/QwErTy/videos?page=2&page_size=20&status=replay",
    "prev": null
  },
  "pagination": {
    "page": 1,
    "has_more": true
  },
  "paging": {
    "next": "/api/v1/live_streams/playlists/QwErTy/videos?page=2&page_size=20&status=replay",
    "prev": null
  }
}

---

16. List Livestream Products

Retrieve the complete configured product snapshot for a livestream, in configured order. This endpoint is intentionally unpaginated: it returns every configured product entry and does not include links, pagination, or the deprecated paging object. Supported public write operations allow at most 100 product-listing entries, but this endpoint does not truncate an existing snapshot that exceeds that limit.

The snapshot includes scheduled, active, and expired deals attached to the configured products. Deals attached to product units that are not configured on the livestream are omitted.

Endpoint: GET /api/v1/live_streams/{live_stream_id}/products Authentication: Bearer token required Required Scope: livestreams:read (livestreams:write also satisfies this)

16.1. Request Headers

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅

16.2. Path Parameters

Parameter	Type	Required	Description
live_stream_id	string	✅	Encoded Firework livestream ID

16.3. Livestream Products Response

Success Response: 200 OK

Field	Type	Nullable	Description
products	object[]	❌	Complete configured product snapshot in livestream order; empty when no products are configured

Each entry in products contains:

Field	Type	Nullable	Description
product	object	❌	Full public Product object; see the Product Object Reference
selected_product_unit_ids	string[]	❌	Encoded IDs of the product units selected for this livestream, in configured order
deals	object[]	❌	Deals associated with the configured product or its configured units, ordered by deal ID

Every deal contains all of the following keys, with nullable values represented explicitly as null:

Field	Type	Nullable	Description
id	string	❌	Encoded deal ID
product_unit_id	string	✅	Encoded product-unit ID, or null when the deal applies to the whole product
product_unit_external_id	string	✅	External product-unit ID
coupon_code	string	✅	Coupon code associated with the deal
discount_type	string	✅	percentage, fixed_amount, or null
discount_amount	string	✅	Decimal discount value serialized as a string
starts_at	string	✅	ISO 8601 start time
ends_at	string	✅	ISO 8601 end time

{
  "products": [
    {
      "product": {
        "id": "vWKDjg",
        "external_id": "SHOE-001",
        "name": "Classic Running Shoe",
        "description": "Lightweight running shoe for everyday training",
        "currency": "USD",
        "handle": "https://example.com/products/classic-running-shoe",
        "options": ["color", "size"],
        "category": "Footwear",
        "hide_price": false,
        "brand": "RunCo",
        "subtitle": "Everyday training shoe",
        "shipping": "Free shipping over $50",
        "custom_cta": null,
        "business_store_id": "y8PDj8",
        "images": [
          {
            "id": "mK9x2p",
            "external_id": "IMG-001",
            "url": "https://example.com/images/shoe-gray.jpg",
            "position": 0,
            "unit_external_ids": ["SHOE-001-GR-10"]
          }
        ],
        "units": [
          {
            "id": "nP3qRv",
            "external_id": "SHOE-001-GR-10",
            "name": "Gray / Size 10",
            "price": 129.99,
            "original_price": 149.99,
            "url": "https://example.com/products/classic-running-shoe?variant=gray-10",
            "position": 0,
            "quantity": 25,
            "options": [
              { "name": "color", "value": "Gray" },
              { "name": "size", "value": "10" }
            ],
            "sku": "SKU-SHOE-GR10",
            "gtin": "071249656457",
            "mpn": null,
            "barcode": null
          }
        ]
      },
      "selected_product_unit_ids": ["nP3qRv"],
      "deals": [
        {
          "id": "dE4lQp",
          "product_unit_id": "nP3qRv",
          "product_unit_external_id": "SHOE-001-GR-10",
          "coupon_code": "LIVE10",
          "discount_type": "fixed_amount",
          "discount_amount": "10",
          "starts_at": "2026-08-24T10:00:00Z",
          "ends_at": "2026-08-24T12:00:00Z"
        }
      ]
    }
  ]
}

When no products are configured, the response is:

{
  "products": []
}

16.4. Livestream Products Error Responses

Status Code	Description
400 Bad Request	Malformed live_stream_id
401 Unauthorized	Missing/invalid authentication token, or the OAuth app cannot access the livestream
403 Forbidden	Missing livestreams:read scope
404 Not Found	Livestream not found

16.5. Example

curl -X GET "https://api.firework.com/api/v1/live_streams/encoded_live_stream_id/products" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"