Livestream

1. Overview

The Firework Livestream API lets you manage livestreams end to end. Two core workflows are supported:

• Read: Fetch livestream details, current status, schedule, and attached products

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

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 Methods Supported:

• Client Credentials: OAuth 2.0 Client Credentials flow for server-to-server authentication (machine-to-machine)

📖 See Authentication Documentation for the complete OAuth 2.0 flow

---

3. Endpoint Summary

Endpoint	Status	Notes
GET /api/v1/live_streams/{id}/detail	⚠️ Legacy	Get livestream details and status (New API will be designed to replace)
GET /api/v1/live_streams/playlists/{id}/videos	⚠️ Legacy	Get livestreams in a specific playlist (New API will be designed to replace)
POST /api/v1/live_streams/{id}/pin_product	✅ Available	Pin products during livestream
POST /api/v1/live_streams/{id}/unpin_product	✅ Available	Unpin products during livestream
PATCH /api/v1/live_streams/{id}/end	✅ Available	Force end an active livestream

---

4. Get Livestream Details

⚠️ Legacy API: This endpoint is marked as legacy. A new API will be designed to replace this endpoint.

Retrieve detailed information about a specific livestream including its current status, scheduling information, event details, and associated products.

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

4.1. Request Headers

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

4.2. Path Parameters

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

4.3. Get Livestream Response

Note: This API documents only the essential response fields required for typical livestream display use cases. Other fields may be present in the actual response but are omitted here.

Success Response: 200 OK

Field	Type	Nullable	Description
status	string	❌	Current livestream state (see status values above)
scheduled_at	string	✅	ISO 8601 datetime when livestream is scheduled
event_description	string	✅	Description of the livestream event
event_name	string	❌	Name of the livestream event
products	object[]	❌	Array of product objects (see Product Object)

Status Values

Status	Description	Web Player Behavior
idle	Livestream not yet started	Displays video trailer
active	Livestream currently in progress	Plays live stream
paused	Livestream paused by host	Displays last frame
replay	Livestream ended, replay available	Plays livestream replay
completed	Replay window ended	Displays video trailer
expired	Livestream never started	Displays video trailer

Product Object:

Field	Type	Description
id	string	Encoded product identifier
product_name	string	Name of the product
product_description	string	Product description
product_currency	string	ISO currency code (e.g., "USD")
product_images	object[]	Array of product image objects (see below)
product_units	object[]	Array of product variants (see below)

Product Image Object:

Field	Type	Description
id	string	Image identifier
image_src	string	Image URL
image_position	number	Display order/position

Product Unit Object (Variant/SKU):

Field	Type	Description
id	string	Variant identifier
unit_name	string	Variant name (e.g., "Large / Blue")
unit_price	number	Current price
unit_price_string	string	Formatted price with currency symbol
unit_ext_id	string	External variant ID from provider

4.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:

All error responses follow a consistent JSON structure:

{ "error": "Error Message" }

4.5. Examples

CURL Request

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

Example Response (Minimal)

{ "event_name": "Product Launch Livestream", "event_description": "Join us for our exciting new product reveal!", "products": [], "status": "idle", "scheduled_at": "2025-03-19T09:41:00.000000Z" }

Example Response (With Products)

{ "status": "active", "scheduled_at": "2025-03-19T09:41:00.000000Z", "event_name": "Product Launch Livestream", "event_description": "Join us for our exciting new product reveal!", "products": [ { "id": "GeEk8y", "product_name": "Wireless Bluetooth Headphones", "product_description": "Premium noise-canceling wireless headphones", "product_currency": "USD", "product_images": [ { "id": "082YOm", "image_src": "<https://cdn.example.com/image.jpg>", "image_position": 1 } ], "product_units": [ { "id": "082YOm", "unit_name": "Black / Standard", "unit_price": 149.99, "unit_price_string": "$149.99", "unit_ext_id": "variant-abc-123" } ] } ] }

---

5. Get Livestreams in Playlist

⚠️ Legacy API: This endpoint is marked as legacy. A new API will be designed to replace this endpoint.

Retrieve livestreams contained within a specific playlist with pagination support.

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

5.1. Request Headers

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

5.2. Path Parameters

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

5.3. Query Parameters

Parameter	Type	Required	Default	Description
page_size	number	❌	10	Number of livestreams to return per page
before_id	string	❌	None	Return entries with ID smaller than this value

5.4. Get Livestreams Response

Success Response: 200 OK

Note: The following fields are the primary fields included in the response. Other fields may be present in the actual response but are omitted here.

Field	Type	Nullable	Description
live_streams	object[]	❌	Array of livestream objects
paging	object	❌	Pagination information

Livestream Object:

Field	Type	Nullable	Description
id	string	❌	Unique identifier of the livestream
status	string	❌	Current livestream state (see status values)
scheduled_at	string	✅	ISO 8601 datetime when livestream is scheduled
event_description	string	✅	Description of the livestream event
event_name	string	❌	Name of the livestream event

Paging Object:

Field	Type	Nullable	Description
next	string	✅	The API path to fetch the next page

5.5. Examples

CURL Request

curl -X GET "<https://api.firework.com/api/v1/live_streams/playlists/5RyeZv/videos>" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response

{ "live_streams": [ { "event_description": "event description", "event_name": "event name", "id": "o8Gx75", "scheduled_at": "2022-12-02T06:30:00.000000Z", "status": "replay" } ], "paging": { "next": "/api/v1/live_streams/playlists/gKamd5/videos?before_id=24988" } }

---

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

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

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.

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

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

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

6.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" }

---

7. 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 Content Type: application/json

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

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

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

7.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" ] }

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

---

8. 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 Content Type: application/json

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

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

No request body is required.

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

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

8.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" }