Create and Update Videos

The Create and Update Videos API allows you to ingest and update videos on the Firework platform programmatically. This API supports video file uploads with rich metadata including product associations.

1. Authentication

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

See Authentication Documentation for the complete OAuth 2.0 flow including application registration, authorization, and token management.

2. Endpoint Summary

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

Endpoint	Notes
POST /api/v1/videos	Video creation with file upload
POST /api/v1/videos	Video creation from URL (application/json)
PATCH /api/v1/videos/{id}	Video updates

3. Create Video

Upload a new video to the Firework platform. Supports both direct file upload and video import from URL.

Endpoint: POST /api/v1/videos Authentication: Bearer token required Rate Limit: 20 videos per 5 minutes per channel Content Type: multipart/form-data or application/json

3.1 Supported Video Files

• MIME Types: video/mp4, video/quicktime

• File Extensions: .mp4, .mov

3.2 Request Headers

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅
Content-Type	multipart/form-data (file upload) or application/json (URL import)	✅

3.3 Request Body

Option 1: File Upload (multipart/form-data)

Parameter	Type	Required	Description
metadata	string	✅	JSON-encoded video metadata (see schema below)
file	file	✅	Video file to upload

Option 2: URL Import (application/json)

When using application/json, send the following fields as parameter.

Parameter	Type	Required	Default	Description
url	string	✅	None	Video URL to import
All other fields from metadata schema				See metadata schema section

3.4 Metadata Schema

Field	Type	Required	Default	Description	Remarks
channel_id	string	✅	None	Encoded channel ID where video will be uploaded
caption	string	✅	None	Video title/caption
description	string	❌	None	Video description
access	string	❌	"public"	Video visibility: "public" or "private"
archived_at	string	❌	None	ISO 8601 timestamp when video was archived
hashtags	string[]	❌	[]	Array of hashtag strings
business_store_id	string	❌	use first one	Encoded business store ID	See products tagging rules
product_ids	string[]	❌	[]	Array of product identifiers	See products tagging rules
social_media_url	string	❌	None	URL to social media content for metadata fetching	Support later - Instagram and TikTok only

3. 5 Product Identifiers

The product_ids array accepts product identifiers that can be:

• Encoded Firework product ID

• External product ID

• External product unit ID

• Product unit GTIN

• Product unit SKU

• Product unit MPN

Product Tagging Rules:

• When product_ids is provided:

  • While you can use product unit identifiers, it will only tag the product to the video

  • It will replace existing products with the specified ones. For example, if a video is currently tagged with product A (external ID "123") and product B (external ID "234"), using product_ids: ["123", "567"] will:

    • Keep product A tagged to the video

    • Untag product B from the video

    • Tag product C (external ID "567") to the video

  • An empty array product_ids: [] will untag all products from the video

  • If the system cannot find a specified product, it will return a 422 Unprocessable Entity response

  • The order of products will follow the order of the array. The sort ID will be set to match the order of the product_ids array.

• business_store_id behavior:

  • Optional. If absent, the system will use the first business store of the business

  • If provided, the system will use the specified business store to find the product(s)

Product Tagging Rules Examples:

Example 1: Tag products using external IDs

{ "product_ids": ["SHOE-001", "SHIRT-123", "BAG-456"], "business_store_id": "encoded_store_id" }

This will tag 3 products to the video in the specified order.

Example 2: Tag products using Firework product IDs

{ "product_ids": ["abc123", "def456"], "business_store_id": "encoded_store_id" }

This will tag 2 products using their encoded Firework IDs.

Example 3: Mix of identifier types

{ "product_ids": ["SHOE-001", "071249656457", "abc123"], "business_store_id": "encoded_store_id" }

This uses external ID, GTIN, and Firework ID respectively.

Example 4: Replace existing product tags

// Video currently has products: ["OLD-001", "OLD-002"] { "product_ids": ["NEW-001", "OLD-001"], "business_store_id": "encoded_store_id" } // Result: Video will have products ["NEW-001", "OLD-001"] only // "OLD-002" gets untagged, "NEW-001" gets added

Example 5: Untag all products

{ "product_ids": [], "business_store_id": "encoded_store_id" }

This removes all product tags from the video.

Example 6: Using product unit identifiers

{ "product_ids": ["UNIT-External-ID-1", "UNIT-External-ID-2"], "business_store_id": "encoded_store_id" }

Even though these are unit IDs, only the related product get tagged to the video not product unit.

3.6 Create Video Response

Success Response: 201 Created

Field	Type	Nullable	Description
id	string	❌	Encoded video ID
access	string	❌	Video visibility level ("public", "private", "unlisted")
caption	string	❌	Video title/caption
description	string	✅	Video description
hashtags	string[]	❌	Array of hashtag strings (empty if none provided)
archived_at	string	✅	ISO 8601 timestamp when video was archived
product_ids	string[]	❌	Array of firework encoded product id

3.7 Create Video Error Responses

Status Code	Description
400 Bad Request	Invalid request parameters, malformed JSON, unsupported file type, file size exceeds 5GB limit, etc
401 Unauthorized	Invalid or missing authentication token
403 Forbidden	Insufficient permissions
404 Not Found	Channel not found or membership not found
422 Unprocessable Entity	Video validation errors (e.g., caption too long, invalid values)
429 Too Many Requests	Rate limit exceeded (20 videos per 5 minutes per channel)

3.8 Examples

3.8.1 Option 1: File Upload (multipart/form-data)

CURL Request

curl -X POST "<https://api.firework.com/api/v1/videos>" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: multipart/form-data" \ -F 'metadata={ "channel_id": "X6Xqd6W", "caption": "My Amazing Product Demo", "description": "Check out this awesome product in action!", "access": "public", "hashtags": ["product", "demo", "fashion"], "business_store_id": "encoded_store_id", "product_ids": ["product_id_1"] }' \ -F "file=@/path/to/your/video.mp4;type=video/mp4"

HTTP Request

POST /api/v1/videos HTTP/1.1 Host: api.firework.com Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Length: [calculated_length] ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="metadata" Content-Type: application/json { "channel_id": "X6Xqd6W", "caption": "My Amazing Product Demo", "description": "Check out this awesome product in action!", "access": "public", "hashtags": ["product", "demo", "fashion"], "business_store_id": "encoded_store_id", "product_ids": ["product_id_1"] } ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="file"; filename="demo_video.mp4" Content-Type: video/mp4 [binary video file data] ------WebKitFormBoundary7MA4YWxkTrZu0gW--

3.8.2 Option 2: URL Import (application/json)

CURL Request

curl -X POST "<https://api.firework.com/api/v1/videos>" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "url": "<https://example.com/videos/demo-video.mp4>", "channel_id": "X6Xqd6W", "caption": "My Amazing Product Demo", "description": "Check out this awesome product in action!", "access": "public", "hashtags": ["product", "demo", "fashion"], "business_store_id": "encoded_store_id", "product_ids": ["product_id_1"] }'

HTTP Request

POST /api/v1/videos HTTP/1.1 Host: api.firework.com Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json Content-Length: [calculated_length] { "url": "<https://example.com/videos/demo-video.mp4>", "channel_id": "X6Xqd6W", "caption": "My Amazing Product Demo", "description": "Check out this awesome product in action!", "access": "public", "hashtags": ["product", "demo", "fashion"], "business_store_id": "encoed_store_id", "product_ids": ["product_id_1"] }

3.8.3 Success Response

{ "id": "encoded_video_id_xyz123", "access": "public", "caption": "My Amazing Product Demo", "description": "Check out this awesome product in action!", "hashtags": ["product", "demo", "fashion"], "archived_at": null, "product_ids": ["product_id_1"] }

4. Update Video

Update an existing video's data on the Firework platform.

Endpoint: PATCH /api/v1/videos/{video_id} Authentication: Bearer token required Content Type: application/json

4.1 Request Headers

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

4.2 URL Parameters

Parameter	Type	Required	Description
video_id	string	✅	Firework encoded video ID

4.3 Request Body

Parameter	Type	Required	Description
caption	string	❌	Video title/caption
description	string	❌	Video description
access	string	❌	Video visibility: "public" or "private"
archived_at	string	❌	ISO 8601 timestamp when video was archived
hashtags	string[]	❌	Array of hashtag strings
business_store_id	string	❌	Encoded business store ID
product_ids	string[]	❌	Array of product identifiers, see products tagging rules

4.4 Update Video Response

Success Response: 200 OK

Field	Type	Nullable	Description
id	string	❌	Encoded video ID
caption	string	❌	Video title/caption
description	string	✅	Video description
access	string	❌	Video visibility level ("public", "private", "unlisted")
archived_at	string	✅	ISO 8601 timestamp when video was archived
hashtags	string[]	❌	Array of hashtag strings (empty if none provided)
product_ids	string[]	❌	Array of firework encoded product id

4.5 Update Video Error Responses

Status Code	Description
400 Bad Request	Invalid request parameters, malformed JSON, or validation errors
401 Unauthorized	Invalid or missing authentication token
403 Forbidden	Insufficient permissions
404 Not Found	Video not found
422 Unprocessable Entity	Video validation errors (e.g., caption too long, invalid values)

4.6 Update Examples

4.6.1 CURL Request

curl -X PATCH "<https://api.firework.com/api/v1/videos/encoded_video_id_xyz123>" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "caption": "Updated Amazing Product Demo", "description": "This updated description showcases even more amazing features!", "hashtags": ["updated", "product", "demo", "trending"], "business_store_id": "encoed_store_id", "product_ids": ["product_id_1", "SKU-67890"] }'

4.6.2 HTTP Request

PATCH /api/v1/videos/encoded_video_id_xyz123 HTTP/1.1 Host: api.firework.com Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json Content-Length: [calculated_length] { "caption": "Updated Amazing Product Demo", "description": "This updated description showcases even more amazing features!", "hashtags": ["updated", "product", "demo", "trending"], "business_store_id": "encode_store_id", "product_ids": ["prodcut_id_1", "SKU-67890"] }

4.6.3 Success Response

{ "id": "encoded_video_id_xyz123", "caption": "Updated Amazing Product Demo", "description": "This updated description showcases even more amazing features!", "access": "public", "hashtags": ["updated", "product", "demo", "trending"], "archived_at": null, "product_ids": ["product_id_1", "product_id_2"] }