Videos
The Videos APIs allow you to programmatically ingest, update, and query videos on the Firework platform at scale.
It also supports annotating videos with rich metadata, such as product associations and external social media attributions.
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
Endpoint Summary
Base URL: https://api.firework.com
Endpoint
Scope
Notes
POST /api/v1/upload_signatures
videos:write
Get pre-signed credentials for S3 upload
POST /api/v1/upload_multipart/signatures
videos:write
Initiate multipart upload and get signed parts
POST /api/v1/upload_multipart/complete
videos:write
Complete a multipart upload with ETags
POST /api/v1/videos
videos:write
Video creation with file upload
POST /api/v1/videos
videos:write
Video creation from URL (application/json)
POST /api/v1/videos
videos:write
Video creation from S3 key (application/json)
GET /api/v1/videos/{id}
videos:read
Get video by ID
PATCH /api/v1/videos/{id}
videos:write
Video updates
Upload Signature (Single File)
Get pre-signed credentials to upload a video directly to AWS S3 using a single POST request. This enables a two-step upload process suitable for files under ~100MB.
For files over 100MB, use the Multipart Upload API instead, which supports parallel and resumable uploads.
Upload Flow:
Endpoint: POST /api/v1/upload_signatures Authentication: Bearer token required Scope: videos:write
Request Headers
Name
Description
Required
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
Content-Type
Must be application/json
✅
Request Body
Parameter
Type
Required
Description
filename
string
✅
The name of the video file (e.g., "my_video.mp4")
mime_type
string
✅
The MIME type of the video: video/mp4 or video/quicktime
channel_id
string
✅
The encoded channel ID where the video will be uploaded
Video Limits
The upload signature enforces the following limits:
Limit
Value
Minimum file size
25 KB
Maximum file size
5 GB
Minimum duration
3 seconds
Maximum duration
1 hour
Upload Signature Response
Success Response: 201 Created
Field
Type
Description
key
string
The S3 object key where the file will be stored. Save this for video creation
post_url
string
The S3 URL to POST the file to
policy
string
Base64-encoded policy document
signature
string
The AWS Signature V4 value (X-Amz-Signature)
date
string
The signing date (X-Amz-Date), e.g., "20250129T120000Z"
credential
string
The AWS credential scope (X-Amz-Credential)
algorithm
string
Always "AWS4-HMAC-SHA256"
acl
string
Always "private"
Upload Signature Error Responses
Status Code
Description
400 Bad Request
Invalid mime_type - only video/mp4 and video/quicktime allowed
401 Unauthorized
Invalid or missing authentication token
403 Forbidden
Insufficient permissions to upload to the specified channel
404 Not Found
Channel not found
Uploading to S3
After receiving the signature, upload the file directly to S3 using a multipart/form-data POST request.
⚠️ Important: The form fields must be sent in the correct order, with the file field last.
Required Form Fields (in order):
Field
Value
key
From signature response
acl
From signature response
X-Amz-Algorithm
From signature algorithm
X-Amz-Credential
From signature credential
X-Amz-Date
From signature date
Policy
From signature policy
X-Amz-Signature
From signature signature
Content-Type
Same as request mime_type
file
The video file (must be last)
S3 Response:
Status
Description
204
Success - file uploaded
400
Bad request - file size outside limits (< 25 KB or > 5 GB), or form error
403
Forbidden - signature invalid or expired (expires after 60 min)
Upload Signature Examples
Get Signature Request
Get Signature Response
Upload to S3
Use the post_url from the Get Signature response as the upload endpoint. Submit a POST request with the signature fields and your video file:
Multipart Upload
Upload large video files (100MB+) to AWS S3 using multipart upload. This splits the file into multiple parts that can be uploaded in parallel and resumed if a part fails, avoiding gateway timeouts.
⚠️ AWS S3 Part Size Requirements:
Each part (except the last) must be ≥ 5 MB (5,242,880 bytes)
Last part can be any size
Maximum 100 parts per upload
If parts are too small, the complete step will fail with "Multipart upload failed"
Multipart Upload Flow:
Initiate Multipart Upload
Start a multipart upload session. Returns an upload_id and presigned URLs for each part.
Endpoint: POST /api/v1/upload_multipart/signatures Authentication: Bearer token required Scope: videos:write
Request Headers
Name
Description
Required
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
Content-Type
Must be application/json
✅
Request Body
Parameter
Type
Required
Description
filename
string
✅
The name of the video file (e.g., "my_video.mp4")
mime_type
string
✅
The MIME type of the video: video/mp4 or video/quicktime
channel_id
string
✅
The encoded channel ID where the video will be uploaded
parts_count
integer
✅
Number of parts to split the file into (1-100)
Choosing parts_count: Calculate based on your file size to ensure each part is ≥ 5 MB:
Formula: parts_count = file_size_mb / 5 (round down)
Example 1: 100 MB file → max 20 parts (100 / 5 = 20)
Example 2: 500 MB file → max 100 parts (500 / 5 = 100)
Example 3: 15 MB file → max 3 parts (15 / 5 = 3)
Important: Each part (except last) must be ≥ 5 MB, or upload will fail
Initiate Response
Success Response: 201 Created
Field
Type
Description
key
string
The S3 object key where the file will be stored. Save this for video creation
upload_id
string
The multipart upload session ID. Required for uploading parts and completion
parts
array
Array of part objects, one per requested part
Each element in parts:
Field
Type
Description
part
integer
The part number (1-based)
signature
object
Signature object containing the presigned PUT URL
signature.put_url
string
Presigned URL to PUT-upload this part directly to S3
signature.key
string
The S3 object key
Initiate Error Responses
Status Code
Description
400 Bad Request
Invalid mime_type - only video/mp4 and video/quicktime allowed
400 Bad Request
Invalid parts_count - must be between 1 and 100
401 Unauthorized
Invalid or missing authentication token
403 Forbidden
Insufficient permissions to upload to the specified channel
404 Not Found
Channel not found
Upload Parts to S3
After initiating the multipart upload, upload each part directly to S3 using the presigned PUT URLs from the response.
Parts can be uploaded in parallel for faster uploads. Each part returns an ETag header that you must save for the completion step.
For each part:
S3 Response:
Status
Description
200
Success - part uploaded. Save the ETag response header.
403
Forbidden - signature invalid or expired
Important: The ETag header value returned by S3 for each part is required for the completion step. It is typically a quoted MD5 hash, e.g., "d41d8c8427ede980000b204f998ec98f".
Complete Multipart Upload
After all parts have been uploaded to S3, call this endpoint to assemble them into the final file.
Endpoint: POST /api/v1/upload_multipart/complete Authentication: Bearer token required Scope: videos:write
Request Headers
Name
Description
Required
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
Content-Type
Must be application/json
✅
Request Body
Parameter
Type
Required
Description
key
string
✅
The S3 key returned from the initiate step
upload_id
string
✅
The upload session ID returned from the initiate step
parts
array
✅
Array of completed part objects (see below)
Each element in parts:
Field
Type
Required
Description
part
integer
✅
The part number (1-100, must match the initiate response, no duplicates)
etag
string
✅
The ETag returned by S3 when the part was uploaded (non-empty)
Validation Rules: The parts array must be non-empty, contain at most 100 elements, have no duplicate part numbers, and each etag must be a non-empty string.
File Size Validation
After assembly, the server validates the total file size against the same limits used for single-file uploads:
Limit
Value
Minimum file size
25 KB
Maximum file size
5 GB
If the assembled file is outside these bounds, the server deletes the object from S3 and returns an error with a descriptive message: "File too small (min 25KB)" (400) or "File too large (max 5GB)" (413).
Complete Response
Success Response: 204 No Content
No response body. The file has been assembled on S3 and is ready to be used with the Create Video API using the s3_key parameter.
Complete Error Responses
Status Code
Error Message
Description
400 Bad Request
Invalid or missing parameters (key, upload_id, or parts), empty parts list, duplicate part numbers, invalid part numbers (must be 1-100), or empty etag values
400 Bad Request
"File too small (min 25KB)"
Assembled file is below minimum size (25 KB)
400 Bad Request
"Multipart upload failed"
AWS rejected the upload (e.g., parts < 5 MB)
401 Unauthorized
Invalid or missing authentication token
403 Forbidden
Insufficient permissions
413 Request Entity Too Large
"File too large (max 5GB)"
Assembled file exceeds the maximum size (5 GB)
500 Internal Server Error
Unexpected server error during upload completion - retry the request
⚠️ Common Failure: If you receive "Multipart upload failed" with a 400 status, it's usually because one or more parts (except the last) were smaller than 5 MB. Recalculate parts_count to ensure each part is at least 5 MB. A 500 status indicates a transient server issue - retry the request.
Multipart Upload Examples
Step 1: Initiate Multipart Upload
Response:
Step 2: Upload Parts to S3 (can be parallel)
Split your file and upload each part using its presigned URL:
Tip: To get the ETag from curl, use -i or -D - to include response headers in the output.
Step 3: Complete Multipart Upload
Response: 204 No Content
Step 4: Create Video with S3 Key
Use the key from the initiate step to create the video:
See Section 6. Create Video for full details on video creation.
Create Video
Upload a new video to the Firework platform. Supports direct file upload, video import from URL, and creation from pre-uploaded S3 key.
Endpoint: POST /api/v1/videos Authentication: Bearer token required Scope: videos:write Rate Limit: 20 videos per 5 minutes per channel Content Type: multipart/form-data or application/json
Supported Video Files
MIME Types: video/mp4, video/quicktime
File Extensions: .mp4, .mov
Maximum Size: 5GB
Request Headers
Name
Description
Required
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
Content-Type
multipart/form-data (file upload) or application/json (URL import / S3 key upload)
✅
Request Body
Option 1: File Upload (multipart/form-data)
Upload the video file directly. Best for small files (under 100MB).
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)
Import a video from a publicly accessible URL.
Parameter
Type
Required
Default
Description
url
string
✅
None
Video URL to import
All other fields from metadata schema
See metadata schema section
Option 3: S3 Key Upload (application/json) - Recommended for Large Files
Create a video from a file already uploaded to S3 via the Upload Signature API or the Multipart Upload API. Recommended for files over 100MB to avoid gateway timeouts.
Parameter
Type
Required
Default
Description
s3_key
string
✅
None
The S3 key returned from Upload Signature API
All other fields from metadata schema
See metadata schema section
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
audio_disabled
boolean
❌
false
Whether audio is disabled for the video
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
custom_fields
object
❌
{}
Custom key-value metadata
See Metafields spec
display_social_attributions
boolean
❌
false
Display social media attribution on video
Requires external_media when true
external_media
object
❌
None
Social media source metadata
See External Media Schema below
poster_url
string
❌
None
URL to a custom poster image
Set to null or "" to remove. See Custom Poster section
Custom Poster
The poster_url field allows you to specify a custom poster image for the video instead of using the auto-generated one.
Supported Formats:
jpg, png
Validation Rules:
Must be a valid, publicly accessible URL
URL must have a valid image file extension (.jpg, .png)
The image will be downloaded and stored on Firework's CDN
Behavior:
When provided during video creation, the custom poster replaces the auto-generated poster
When provided during video update, the custom poster replaces any existing poster
To remove a custom poster, set poster_url to null or an empty string ""
Omit the field entirely to preserve the existing poster
Examples:
Set a custom poster:
Remove the custom poster:
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.
Examples:
Example 1: Tag products using external IDs
This will tag 3 products to the video in the specified order.
Example 2: Tag products using Firework product IDs
This will tag 2 products using their encoded Firework IDs.
Example 3: Mix of identifier types
This uses external ID, GTIN, and Firework ID respectively.
Example 4: Replace existing product tags
Example 5: Untag all products
This removes all product tags from the video.
Example 6: Using product unit identifiers
Even though these are unit IDs, only the related product get tagged to the video not product unit.
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)
External Media Schema
Used for social media attribution. Required when display_social_attributions is true.
Field
Type
Required
Description
source
string
✅
Platform: "tiktok", "instagram", "youtube", etc
url
string
✅
URL to the original social media post
username
string
✅
Creator's username/handle
Example:
Validation Rules:
When display_social_attributions is true, external_media must be provided with at least source and url
For updates: validation passes if the video already has an existing external_media association
Create Video Response
Success Response: 201 Created
Field
Type
Nullable
Description
id
string
❌
Encoded video ID
access
string
❌
Video visibility level ("public", "private", "unlisted")
audio_disabled
boolean
❌
Whether audio is disabled for the video (default: false)
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
custom_fields
object
❌
Custom key-value metadata
display_social_attributions
boolean
❌
Whether social attribution is displayed
external_media
object
✅
Social media source metadata (see External Media Schema)
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)
Examples
Option 1: File Upload (multipart/form-data)
CURL Request
HTTP Request
Option 2: URL Import (application/json)
CURL Request
HTTP Request
Option 3: S3 Key Upload (application/json) - Recommended for Large Files
First, get an upload signature and upload the file to S3 (see Sections "Upload Signature" or "Multipart Upload"), then create the video with the S3 key.
CURL Request
HTTP Request
Success Response
Update Video
Update an existing video's data on the Firework platform.
Endpoint: PATCH /api/v1/videos/{video_id} Authentication: Bearer token required Scope: videos:write Content Type: application/json
Request Headers
Name
Description
Required
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
Content-Type
Must be application/json
✅
URL Parameters
Parameter
Type
Required
Description
video_id
string
✅
Firework encoded video ID
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
audio_disabled
boolean
❌
Whether audio is disabled for the video
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
custom_fields
object
❌
Custom key-value metadata (replace mode)
display_social_attributions
boolean
❌
Display social media attribution on video
external_media
object
❌
Social media source metadata (see External Media Schema)
poster_url
string
❌
URL to custom poster. Set to null or "" to remove. Omit to preserve.
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
audio_disabled
boolean
❌
Whether audio is disabled for the video
hashtags
string[]
❌
Array of hashtag strings (empty if none provided)
product_ids
string[]
❌
Array of firework encoded product id
custom_fields
object
❌
Custom key-value metadata
display_social_attributions
boolean
❌
Whether social attribution is displayed
external_media
object
✅
Social media source metadata (see External Media Schema)
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)
Update Examples
CURL Request
HTTP Request
Success Response
Remove Custom Poster
To remove a custom poster from a video, set poster_url to null or an empty string:
Or with an empty string:
Get Video
Retrieve a video's details from the Firework platform.
Endpoint: GET /api/v1/videos/{video_id} Authentication: Bearer token required Scope: videos:read Content Type: N/A (no request body)
Request Headers
Name
Description
Required
Authorization
Bearer token: Bearer {ACCESS_TOKEN}
✅
URL Parameters
Parameter
Type
Required
Description
video_id
string
✅
Firework encoded video ID
Get 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
audio_disabled
boolean
❌
Whether audio is disabled for the video
hashtags
string[]
❌
Array of hashtag strings (empty if none)
product_ids
string[]
❌
Array of firework encoded product IDs
custom_fields
object
❌
Custom key-value metadata
display_social_attributions
boolean
❌
Whether social attribution is displayed
external_media
object
✅
Social media source metadata (see External Media Schema)
Get Video Error Responses
Status Code
Description
401 Unauthorized
Invalid or missing authentication token
403 Forbidden
Insufficient permissions
404 Not Found
Video not found
Get Video Examples
CURL Request
HTTP Request
Success Response
Custom Fields Extension
The Video API supports custom metadata through the custom_fields parameter. This allows you to attach arbitrary key-value pairs to videos for tracking and analytics purposes.
Key Usage:
Replace Mode: Providing custom_fields replaces ALL existing custom fields
Preserve Existing: Omit custom_fields from request to keep existing values
Clear All: Use custom_fields: {} to remove all custom fields
Validation: Keys must match ^[a-z0-9_]{1,255}$, values max 1024 characters
Example with Custom Fields:
Last updated
Was this helpful?