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
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 ass3_key, the upload step uses the public video upload APIs and requiresvideos:write.
4.1. Request Headers
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
Content-Type
Must be application/json
✅
4.2. Request Body
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_keyis 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
keyvalue ass3_key.product_idsfollows the same identifier rules asPOST /api/v1/videos.scheduled_atshould be provided in UTC ISO 8601 format.stream_sourceis required at create time. It can only be updated before the livestream enters the 5-minute warmup window.stream_sourcecan 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:
Call
POST /api/v1/upload_signaturesfor a single-request upload, orPOST /api/v1/upload_multipart/signaturesfollowed byPOST /api/v1/upload_multipart/completefor multipart upload.Upload the trailer file directly to S3 using the returned signature data.
Take the
keyfrom the upload API response.Pass that exact value as
s3_keyinPOST /api/v1/live_streams.
4.3. Create Livestream Response
Success Response: 201 Created
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 includesprovider, and forstream_source: "external"it also returnsstream_keyandstream_urlso clients can publish to the scheduled livestream.
4.4. Create Livestream Error Responses
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:
Validation errors from changesets return:
4.5. Examples
Example 1: Create Livestream with Default Trailer
Example 2: Create Livestream with Custom Trailer
Example 3: Create Livestream with Display Settings
Example Response
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
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
5.2. Path Parameters
live_stream_id
string
✅
The unique identifier of the livestream
5.3. Get Livestream Response
Success Response: 200 OK
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:
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
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
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:
5.5. Examples
CURL Request
Example Response (Scheduled Livestream)
Example Response (Active Livestream)
Example Response (Completed Livestream)
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_keyrequires a trailer file that was already uploaded through the public video upload APIs. The upload step requiresvideos:write.
6.1. Request Headers
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
Content-Type
Must be application/json
✅
6.2. Path Parameters
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.
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, andproduct_idscan 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_atmust be provided in UTC ISO 8601 format and must satisfy the same scheduling and maintenance-window restrictions as create.stream_sourcecan only be changed when the resulting scheduled time is more than 5 minutes in the future.s3_keymust be a valid uploaded video key owned by the target channel.product_idsreplaces 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_idsfollows the same identifier rules asPOST /api/v1/videosandPOST /api/v1/live_streams.channel_id,provider,stream_key,stream_url,status,started_at, andended_atcannot 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.
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
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:
Validation errors from changesets return:
6.6. Examples
Example 1: Update Livestream Metadata and Schedule
Example 2: Update Stream Source, Trailer, and Tagged Products
Example 3: Update Display Settings
Example Response (Metadata and Schedule Update)
Example Response (External Stream Source Update)
6.7. Error Responses
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
activeorpaused. Products cannot be pinned to livestreams inidle,replay,completed, orexpiredstatus.
Note: The system supports up to 3 products pinned simultaneously(override).
7.1. Request Headers
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
Content-Type
Must be application/json
✅
7.2. Path Parameters
live_stream_id
string
✅
The unique identifier of the livestream
7.3. Request Body
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
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
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
Success Response (200 OK)
Example 2: Pin Product Unit (Variant/SKU)
Success Response (200 OK)
Note: In this example,
082YOmis 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
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
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
Content-Type
Must be application/json
✅
8.2. Path Parameters
live_stream_id
string
✅
The unique identifier of the livestream
8.3. Request Body
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
unpinned_product_ids
string[]
Array of product IDs that were unpinned in this request
8.5. Unpin Products Error Responses
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
Success Response (200 OK)
Example 2: Unpin Product Unit (Variant/SKU)
Success Response (200 OK)
8.7. Error Responses
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
activestatus.
9.1. Request Headers
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
Content-Type
Must be application/json
✅
9.2. Path Parameters
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
live_stream_id
string
The livestream that was ended
status
string
Always "ended" once the operation succeeds
9.5. End Livestream Error Responses
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
Success Response (200 OK)
Error Response Examples
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:readonly 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
Create and manage the livestream through the existing livestream APIs.
End the livestream through CMS or
PATCH /api/v1/live_streams/{live_stream_id}/end.Call
GET /api/v1/live_streams/{live_stream_id}and read theinteractionsarray.Download each interaction result file by calling
responses_csvwith the livestream ID and interaction ID.Download chat/comment history by calling
comments_csvwith 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
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
Path Parameters
live_stream_id
string
✅
The unique identifier of the livestream
interaction_id
string
✅
The unique identifier of the interaction
CSV Columns
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
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
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
Path Parameters
live_stream_id
string
✅
The unique identifier of the livestream
CSV Columns
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
10.4. Error Responses
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
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
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
11.2. Query Parameters
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.nextverbatim (it isnullwhen there is no next page) or pass the opaquepagination.cursorback asafter/before.afterandbeforeare mutually exclusive.
11.3. List Livestreams Response
Success Response: 200 OK
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:
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
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:
11.5. Example
CURL Request
Example Response
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 anaftercursor and a non-nulllinks.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.cursorandlinks.nextbecomenull.
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
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
12.2. Path Parameters
live_stream_id
string
✅
The unique identifier of the livestream
12.3. Query Parameters
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/beforeare opaque cursors the server issued;since/untilare elapsed-time values you supply. They are not interchangeable.Provide at most one paging direction per request.
afterandbeforeare mutually exclusive; conflicting or otherwise invalid combinations return400.since/afterpage forward (ascending);until/beforepage backward (descending).Backward paging (
before/until) is only valid in replay mode. Requesting it while the livestream is live returns400.since/untilmust parse as numbers.
12.4. List Messages Response
Success Response: 200 OK
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:
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
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:
12.6. Example
CURL Request
Example Response
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_idvalues returned byGET /api/v1/live_streams(section 11) are the inputs to this endpoint.
13.1. Request Headers
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
13.2. Path Parameters
live_stream_id
string
✅
The unique identifier of the livestream
13.3. Query Parameters
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/tobound only thereplayarray.metaandliveare 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/tovalue that is not a valid ISO date (including a bracketedfrom[]=...form) returns400.
13.4. Reporting Stats Response
Success Response: 200 OK
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:
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:
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):
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
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:
13.6. Example
CURL Request
Example Response
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, preferGET /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
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
14.2. Path Parameters
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):
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
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:
14.5. Example
CURL Request
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 modernlinks+paginationobjects alongside the deprecatedpagingobject; new integrations should readlinks/paginationand ignorepaging.
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
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
15.2. Path Parameters
playlist_id
string
✅
The unique identifier of the playlist
15.3. Query Parameters
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
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):
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
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:
15.6. Example
CURL Request
Example Response
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
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
16.2. Path Parameters
live_stream_id
string
✅
Encoded Firework livestream ID
16.3. Livestream Products Response
Success Response: 200 OK
products
object[]
❌
Complete configured product snapshot in livestream order; empty when no products are configured
Each entry in products contains:
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:
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
When no products are configured, the response is:
16.4. Livestream Products Error Responses
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
Last updated
Was this helpful?