# Livestreams

### 1. Overview <a href="#id-1.-overview" id="id-1.-overview"></a>

The Firework Livestreams 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 <a href="#id-2.-authentication" id="id-2.-authentication"></a>

The Firework Livestreams 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**](/firework-for-developers/api/authentication.md) for the complete OAuth 2.0 flow

***

### 3. Endpoint Summary <a href="#id-3.-endpoint-summary" id="id-3.-endpoint-summary"></a>

<table><thead><tr><th width="398.63671875">Endpoint</th><th width="117.76171875">Status</th><th>Notes</th></tr></thead><tbody><tr><td><code>GET /api/v1/live_streams/{id}/detail</code></td><td>⚠️ Legacy</td><td>Get livestream details and status (New API will be designed to replace)</td></tr><tr><td><code>POST /api/v1/live_streams/{id}/pin_product</code></td><td>✅ Available</td><td>Pin products during livestream</td></tr><tr><td><code>POST /api/v1/live_streams/{id}/unpin_product</code></td><td>✅ Available</td><td>Unpin products during livestream</td></tr><tr><td><code>PATCH /api/v1/live_streams/{id}/end</code></td><td>✅ Available</td><td>Force end an active livestream</td></tr></tbody></table>

***

### 4. Get Livestream Details <a href="#id-4.-get-livestream-details" id="id-4.-get-livestream-details"></a>

> ⚠️ **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 <a href="#id-4.1.-request-headers" id="id-4.1.-request-headers"></a>

| Name            | Description                           | Required |
| --------------- | ------------------------------------- | -------- |
| `Authorization` | Bearer token: `Bearer {ACCESS_TOKEN}` | ✅        |

#### 4.2. Path Parameters <a href="#id-4.2.-path-parameters" id="id-4.2.-path-parameters"></a>

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

#### 4.3. Get Livestream Response <a href="#id-4.3.-get-livestream-response" id="id-4.3.-get-livestream-response"></a>

> **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 <a href="#id-4.4.-get-livestream-error-responses" id="id-4.4.-get-livestream-error-responses"></a>

| 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 <a href="#id-4.5.-examples" id="id-4.5.-examples"></a>

**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. Pin Products to Livestream <a href="#id-6.-pin-products-to-livestream" id="id-6.-pin-products-to-livestream"></a>

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

#### 5.1. Request Headers <a href="#id-6.1.-request-headers" id="id-6.1.-request-headers"></a>

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

#### 5.2. Path Parameters <a href="#id-6.2.-path-parameters" id="id-6.2.-path-parameters"></a>

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

#### 5.3. Request Body <a href="#id-6.3.-request-body" id="id-6.3.-request-body"></a>

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

#### 5.4. Pin Products Response <a href="#id-6.4.-pin-products-response" id="id-6.4.-pin-products-response"></a>

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

#### 5.5. Pin Products Error Responses <a href="#id-6.5.-pin-products-error-responses" id="id-6.5.-pin-products-error-responses"></a>

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

#### 5.6. Example Requests <a href="#id-6.6.-example-requests" id="id-6.6.-example-requests"></a>

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

#### 5.7. Error Responses <a href="#id-6.7.-error-responses" id="id-6.7.-error-responses"></a>

```
// 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" }
```

***

### 6. Unpin Products from Livestream <a href="#id-7.-unpin-products-from-livestream" id="id-7.-unpin-products-from-livestream"></a>

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`

#### 6.1. Request Headers <a href="#id-7.1.-request-headers" id="id-7.1.-request-headers"></a>

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

#### 6.2. Path Parameters <a href="#id-7.2.-path-parameters" id="id-7.2.-path-parameters"></a>

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

#### 6.3. Request Body <a href="#id-7.3.-request-body" id="id-7.3.-request-body"></a>

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

#### 6.4. Unpin Products Response <a href="#id-7.4.-unpin-products-response" id="id-7.4.-unpin-products-response"></a>

**Success Response**: `200 OK`

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

#### 6.5. Unpin Products Error Responses <a href="#id-7.5.-unpin-products-error-responses" id="id-7.5.-unpin-products-error-responses"></a>

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

#### 6.6. Example Requests <a href="#id-7.6.-example-requests" id="id-7.6.-example-requests"></a>

**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" ] }
```

#### 6.7. Error Responses <a href="#id-7.7.-error-responses" id="id-7.7.-error-responses"></a>

```
// 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" }
```

***

### 7. End Livestream <a href="#id-8.-end-livestream" id="id-8.-end-livestream"></a>

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.

#### 7.1. Request Headers <a href="#id-8.1.-request-headers" id="id-8.1.-request-headers"></a>

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

#### 7.2. Path Parameters <a href="#id-8.2.-path-parameters" id="id-8.2.-path-parameters"></a>

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

#### 7.3. Request Body <a href="#id-8.3.-request-body" id="id-8.3.-request-body"></a>

No request body is required.

#### 7.4. End Livestream Response <a href="#id-8.4.-end-livestream-response" id="id-8.4.-end-livestream-response"></a>

**Success Response**: `200 OK`

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

#### 7.5. End Livestream Error Responses <a href="#id-8.5.-end-livestream-error-responses" id="id-8.5.-end-livestream-error-responses"></a>

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

#### 7.6. Examples <a href="#id-8.6.-examples" id="id-8.6.-examples"></a>

**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" }
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.firework.com/firework-for-developers/api/livestreams.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.