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 (sync, default)

POST /api/v1/videos

videos:write

Video creation from URL (async: "async":true)

POST /api/v1/videos

videos:write

Video creation from S3 key (application/json)

GET /api/v1/videos/imports/{id}

videos:read

Get video import job status

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:

┌──────────┐     1. Get Signature      ┌──────────────┐
│  Client  │ ─────────────────────────▶│  Firework    │
│          │◀───────────────────────── │  API         │
└──────────┘   (signature + S3 key)    └──────────────┘
     │
     │  2. Upload file to S3
     │     (using signature)
     ▼
┌──────────┐
│  AWS S3  │
└──────────┘
     │
     │  3. Create video with S3 key
     ▼
┌──────────┐                           ┌──────────────┐
│  Client  │ ─────────────────────────▶│  Firework    │
│          │◀───────────────────────── │  API         │
└──────────┘      (video created)      └──────────────┘

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

curl -X POST "<https://api.firework.com/api/v1/upload_signatures>" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "product_demo.mp4",
    "mime_type": "video/mp4",
    "channel_id": "X6Xqdmn"
  }'

Get Signature Response

{
  "key": "medias/business/AbCDeF/channel/HiJkmN/videos/public/original/1738152000-abcdefgh-product_demo.mp4",
  "post_url": "<https://firework-assets.s3-accelerate.amazonaws.com>",
  "policy": "M0LUhNaXRpb25zIjpbey...",
  "signature": "a1b2c3d4e5f6g7h8i9j0...",
  "date": "20250129T120000Z",
  "credential": "AKIAIOSFDAIJQEXAMPLE/20250129/us-west-2/s3/aws4_request",
  "algorithm": "AWS4-HMAC-SHA256",
  "acl": "private"
}

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:

curl -X POST "{post_url}" \
  -F "key=medias/business/AbCDeF/channel/HiJkmN/videos/public/original/1738152000-abcdefgh-product_demo.mp4" \
  -F "acl=private" \
  -F "X-Amz-Algorithm=AWS4-HMAC-SHA256" \
  -F "X-Amz-Credential=AKIAIOSFDAIJQEXAMPLE/20250129/us-west-2/s3/aws4_request" \
  -F "X-Amz-Date=20250129T120000Z" \
  -F "Policy=M0LUhNaXRpb25zIjpbey..." \
  -F "X-Amz-Signature=a1b2c3d4e5f6g7h8i9j0..." \
  -F "Content-Type=video/mp4" \
  -F "file=@/path/to/product_demo.mp4"

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:

┌──────────┐  1. Initiate Multipart     ┌──────────────┐
│  Client  │ ──────────────────────────▶│  Firework    │
│          │◀────────────────────────── │  API         │
└──────────┘  (key, upload_id, parts    └──────────────┘
               with presigned URLs)
     │
     │  2. Upload each part to S3
     │     (using presigned PUT URLs)
     │     ← can be done in parallel →
     ▼
┌──────────┐
│  AWS S3  │  ← returns ETag per part
└──────────┘
     │
     │  3. Complete multipart upload
     ▼
┌──────────┐                            ┌──────────────┐
│  Client  │ ──────────────────────────▶│  Firework    │
│          │◀────────────────────────── │  API         │
└──────────┘      (204 No Content)      └──────────────┘
     │
     │  4. Create video with S3 key
     ▼
┌──────────┐                            ┌──────────────┐
│  Client  │ ──────────────────────────▶│  Firework    │
│          │◀────────────────────────── │  API         │
└──────────┘      (video created)       └──────────────┘

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:

curl -X PUT "{part.signature.put_url}" \
  -H "Content-Type: video/mp4" \
  --data-binary @part_file

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

curl -X POST "<https://api.firework.com/api/v1/upload_multipart/signatures>" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "large_product_demo.mp4",
    "mime_type": "video/mp4",
    "channel_id": "X6Xqd6W",
    "parts_count": 3
  }'

Response:

{
  "key": "medias/business/AbCdEfG/channel/HiJkLmN/videos/public/original/1738152000-abcdefgh-large_product_demo.mp4",
  "upload_id": "VFkIEl2vciBlbHEIGZXBZpbmcncyBtsb",
  "parts": [
    {
      "part": 1,
      "signature": {
        "put_url": "<https://firework-assets.s3-accelerate.amazonaws.com/medias/...?uploadId=VXBsb2...&partNumber=1&X-Amz-Signature=abc123...>",
        "key": "medias/business/AbCdEfG/channel/HiJkLmN/videos/public/original/1738152000-abcdefgh-large_product_demo.mp4"
      }
    },
    {
      "part": 2,
      "signature": {
        "put_url": "<https://firework-assets.s3-accelerate.amazonaws.com/medias/...?uploadId=VXBsb2...&partNumber=2&X-Amz-Signature=def456...>",
        "key": "medias/business/AbCdEfG/channel/HiJkLmN/videos/public/original/1738152000-abcdefgh-large_product_demo.mp4"
      }
    },
    {
      "part": 3,
      "signature": {
        "put_url": "<https://firework-assets.s3-accelerate.amazonaws.com/medias/...?uploadId=VXBsb2...&partNumber=3&X-Amz-Signature=ghi789...>",
        "key": "medias/business/AbCdEfG/channel/HiJkLmN/videos/public/original/1738152000-abcdefgh-large_product_demo.mp4"
      }
    }
  ]
}

Step 2: Upload Parts to S3 (can be parallel)

Split your file and upload each part using its presigned URL:

# Upload part 1
curl -X PUT "<https://firework-assets.s3-accelerate.amazonaws.com/medias/...?uploadId=VXBsb2...&partNumber=1&X-Amz-Signature=abc123...>" \
  -H "Content-Type: video/mp4" \
  --data-binary @part1.bin
# Save ETag from response headers: "a1b2c3d4..."

# Upload part 2 (in parallel)
curl -X PUT "<https://firework-assets.s3-accelerate.amazonaws.com/medias/...?uploadId=VXBsb2...&partNumber=2&X-Amz-Signature=def456...>" \
  -H "Content-Type: video/mp4" \
  --data-binary @part2.bin
# Save ETag from response headers: "e5f6g7h8..."

# Upload part 3 (in parallel)
curl -X PUT "<https://firework-assets.s3-accelerate.amazonaws.com/medias/...?uploadId=VXBsb2...&partNumber=3&X-Amz-Signature=ghi789...>" \
  -H "Content-Type: video/mp4" \
  --data-binary @part3.bin
# Save ETag from response headers: "i9j0k1l2..."

Tip: To get the ETag from curl, use -i or -D - to include response headers in the output.

Step 3: Complete Multipart Upload

curl -X POST "<https://api.firework.com/api/v1/upload_multipart/complete>" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "medias/business/AbCdEfG/channel/HiJkLmN/videos/public/original/1738152000-abcdefgh-large_product_demo.mp4",
    "upload_id": "VFkIEl2vciBlbHEIGZXBZpbmcncyBtsb",
    "parts": [
      {"part": 1, "etag": "\"a1b2c3d4...\""},
      {"part": 2, "etag": "\"e5f6g7h8...\""},
      {"part": 3, "etag": "\"i9j0k1l2...\""}
    ]
  }'

Response: 204 No Content

Step 4: Create Video with S3 Key

Use the key from the initiate step to create the video:

curl -X POST "<https://api.firework.com/api/v1/videos>" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "s3_key": "medias/business/AbCdEfG/channel/HiJkLmN/videos/public/original/1738152000-abcdefgh-large_product_demo.mp4",
    "channel_id": "ABiFAn",
    "caption": "Large Product Demo",
    "access": "public"
  }'

See section 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. Supports two modes:

Sync mode (default): The file is downloaded and uploaded to S3 within the request. Returns 201 Created with a video object. Best for small files, but may time out on large files or slow URLs.
Async mode ("async": true): Returns 202 Accepted immediately with a video import tracking object. The file is downloaded and processed in the background. Recommended for large files or unreliable URLs.

How to choose:

Scenario

Mode

Why

Small files (< 100 MB), fast URLs

Sync (default)

Simpler flow, video available immediately

Large files (100 MB+)

Async

Avoids gateway timeouts

Unreliable/slow URLs

Async

Background retry on failure

Batch / fire-and-forget imports

Async

No need to wait for each video to finish

Parameter

Type

Required

Default

Description

url

string

✅

None

Video URL to import

All other fields from metadata schema

See metadata schema section

URL Validation Rules:

Must be http:// or https:// scheme
Must have a valid hostname (with at least one dot)
Must have a path component
The remote server must respond with a Content-Type header of video/mp4, video/quicktime, or application/octet-stream. When application/octet-stream is returned, the URL path must end with a video file extension (.mp4 or .mov)
The remote server must include a Content-Length header
Maximum file size: 5 GB
Video duration: 3 seconds to 1 hour

Sync mode ("async" omitted or false): Returns 201 Created with a video object (same as file upload / S3 key). See Section File Upload / S3 Key / URL Import Sync Response.

Async mode ("async": true): Returns 202 Accepted with a video import object. See Section URL Import Async.

Async Processing Flow:
API validates the URL format, creates a video import job, and enqueues a background worker
Returns 202 Accepted with the import job id and status: "running"
Background worker downloads the file to S3, creates the video record, and triggers transcoding. The video_id is populated at this point while status remains "running"
When transcoding completes: status becomes "completed" and completed_at is set
If processing fails (e.g., download error, invalid format, duration out of range): status becomes "errored"
Tracking progress:
Webhooks (recommended): Configure video_created, video_updated, and video_import_failed webhooks to receive push notifications. The webhook payload includes the import_id so you can correlate events back to this import job.
Polling: Use GET /api/v1/videos/imports/{id} to poll for status. We recommend polling at 5–10 second intervals.

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

video_hidden

boolean

❌

false

Hide video from PDP (Product Detail Page)

Applies to all product listings. See Product Tagging Rules

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:

{
  "channel_id": "X6Xqd6W",
  "caption": "My Video",
  "poster_url": "<https://example.com/my-custom-poster.jpg>"
}

Remove the custom poster:

{
  "channel_id": "X6Xqd6W",
  "caption": "My Video",
  "poster_url": null
}

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 a specified product identifier cannot be found in the business store, it will be silently skipped. Only the valid, resolvable products will be tagged to the video. No error is returned for unrecognized product IDs.
- Duplicate product identifiers (including the same product referenced by different identifier types) will be silently deduplicated
- 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

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

Example 7: Create video with hidden products (hide from PDP)

{
    "product_ids": ["SHOE-001", "SHIRT-123"],
    "business_store_id": "encoded_store_id",
    "video_hidden": true
}

This tags products to the video but hides it from the Product Detail Page.

Example 8: Hide existing video from PDP (update without replacing products)

{
    "video_hidden": true
}

When sent to PATCH /api/v1/videos/{id} without product_ids, this bulk-updates all existing product listings to be hidden.

Example 9: Un-hide video on PDP

{
    "video_hidden": false
}

Sets all existing product listings back to visible on PDP.

video_hidden behavior:
- When video_hidden is provided with product_ids, all created/replaced product listings will be marked with the given value
- When video_hidden is provided without product_ids (update only), it bulk-updates all existing product listings for the video
- When product_ids are provided without video_hidden, existing product listings preserve their current video_hidden state; newly added products default to false (visible)
- The hidden field is not returned in the Video API response. It is returned in the Product API (GET /api/v1/products/:id/videos), scoped to the queried product
- Default is false (visible on PDP)
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:

{
  "display_social_attributions": true,
  "external_media": {
    "source": "tiktok",
    "url": "<https://www.tiktok.com/@username/video/1234567890>",
    "username": "creator_handle"
  }
}

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

Two different response shapes depending on the creation method:

File Upload / S3 Key / URL Import Sync Response (`201 Created`)

For file upload, S3 key, and URL import (sync mode), the video is created synchronously and returns immediately.

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)

URL Import Async Response (`202 Accepted`)

When "async": true is set, the video file is downloaded and processed asynchronously. The response returns a video import object — not a video. The video will be created in the background.

Tracking progress: Configure webhooks to receive video_created, video_updated, and video_import_failed events (recommended), or poll with GET /api/v1/videos/imports/{id} at 5–10 second intervals. Webhook payloads include import_id to correlate events to this job.

Field

Type

Nullable

Description

id

string

❌

Encoded import job ID. Use with GET /api/v1/videos/imports/{id}

status

string

❌

Import status (see Import Status Values below)

video_id

string

✅

Encoded video ID. null initially, populated once the video record is created (before transcoding completes)

created_at

string

❌

ISO 8601 timestamp when the import was created

completed_at

string

✅

ISO 8601 timestamp when the import completed. null while running

Import Status Values

Status

Description

running

Import is in progress: downloading URL, uploading to S3, creating video, or waiting for transcoding. video_id may already be populated during this phase

completed

Transcoding finished successfully. The video is fully ready

errored

Import failed (download error, invalid format, duration out of range, transcode error)

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

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",
    "audio_disabled": false,
    "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",
  "audio_disabled": false,
  "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--

Option 2a: URL Import — Sync (default)

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",
    "audio_disabled": false,
    "hashtags": ["product", "demo", "fashion"],
    "business_store_id": "encoded_store_id",
    "product_ids": ["product_id_1"],
    "poster_url": "<https://example.com/my-custom-poster.jpg>"
  }'

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",
  "audio_disabled": false,
  "hashtags": ["product", "demo", "fashion"],
  "business_store_id": "encoded_store_id",
  "product_ids": ["product_id_1"],
  "poster_url": "<https://example.com/my-custom-poster.jpg>"
}

Response: 201 Created — same as file upload (see Success Response (File Upload / S3 Key))

Option 2b: URL Import — Async

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/large-product-demo.mp4",
    "async": true,
    "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"],
    "poster_url": "https://example.com/my-custom-poster.jpg"
  }'

Response: 202 Accepted — see Success Response (URL Import Async)

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

curl -X POST "<https://api.firework.com/api/v1/videos>" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "s3_key": "medias/AbCdEfG/HiJkLmN/1738152000-abcdefgh/original/product_demo.mp4",
    "channel_id": "X6Xqd6W",
    "caption": "My Amazing Product Demo",
    "description": "Check out this awesome product in action!",
    "access": "public",
    "audio_disabled": false,
    "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]

{
  "s3_key": "medias/AbCdEfG/HiJkLmN/1738152000-abcdefgh/original/product_demo.mp4",
  "channel_id": "X6Xqd6W",
  "caption": "My Amazing Product Demo",
  "description": "Check out this awesome product in action!",
  "access": "public",
  "audio_disabled": false,
  "hashtags": ["product", "demo", "fashion"],
  "business_store_id": "encoded_store_id",
  "product_ids": ["product_id_1"]
}

Success Response (File Upload / S3 Key) - 201 Created

{
  "id": "encoded_video_id_xyz123",
  "access": "public",
  "audio_disabled": false,
  "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"],
  "custom_fields": {},
  "display_social_attributions": false,
  "external_media": null
}

Success Response (URL Import Async) - 202 Accepted

{
  "id": "encoded_import_abc123",
  "status": "running",
  "video_id": null,
  "created_at": "2025-01-29T12:00:00.000000Z",
  "completed_at": null
}

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.

video_hidden

boolean

❌

Hide video from PDP. With product_ids: applies to all listings. Without: bulk-updates existing. Omit to preserve existing state

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

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!",
    "audio_disabled": true,
    "hashtags": ["updated", "product", "demo", "trending"],
    "business_store_id": "encode_store_id",
    "product_ids": ["product_id_1", "SKU-67890"]
  }'

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!",
  "audio_disabled": true,
  "hashtags": ["updated", "product", "demo", "trending"],
  "business_store_id": "encode_store_id",
  "product_ids": ["product_id_1", "SKU-67890"]
}

Success Response

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

Remove Custom Poster

To remove a custom poster from a video, set poster_url to null or an empty string:

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 '{
    "poster_url": null
  }'

Or with an empty string:

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 '{
    "poster_url": ""
  }'

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)

video_posters

array

❌

Array of video poster images (empty if none). See Video Poster Schema

Video Poster Schema

Each object in the video_posters array contains:

Field

Type

Nullable

Description

url

string

❌

CDN URL for the poster image

aspect_ratio

string

❌

Aspect ratio (e.g. "9:16", "16:9", "1:1")

format

string

❌

Image format ("jpg", "webp", "gif", "png")

width

integer

❌

Image width in pixels

height

integer

❌

Image height in pixels

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

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

HTTP Request

GET /api/v1/videos/encoded_video_id_xyz123 HTTP/1.1
Host: api.firework.com
Authorization: Bearer YOUR_ACCESS_TOKEN

Success Response

{
  "id": "encoded_video_id_xyz123",
  "caption": "My Amazing Product Demo",
  "description": "Check out this awesome product in action!",
  "access": "public",
  "archived_at": null,
  "audio_disabled": false,
  "hashtags": ["product", "demo", "fashion"],
  "product_ids": ["product_id_1", "product_id_2"],
  "custom_fields": {
    "creator_id": "2436372",
    "tracking_id": "390724V"
  },
  "display_social_attributions": true,
  "external_media": {
    "source": "tiktok",
    "url": "<https://www.tiktok.com/@username/video/1234567890>",
    "username": "creator_handle"
  }
}

Get Video Import Status

Track the status of an async URL import.

Use this endpoint to check the progress of a video import initiated via the URL import method. Once the import completes successfully, the response includes the video_id which can be used with the Get Video and Update Video endpoints.

Tip: For real-time notifications instead of polling, configure webhooks. The video_created, video_updated, and video_import_failed events include import_id so you can correlate events back to this import job.

Endpoint: GET /api/v1/videos/imports/{id} Authentication: Bearer token required Scope: videos:read

Request Headers

Name

Description

Required

Authorization

Bearer token: Bearer {ACCESS_TOKEN}

✅

URL Parameters

Parameter

Type

Required

Description

id

string

✅

Encoded import job ID (from the 202 response)

Get Import Status Response

Success Response: 200 OK

Field

Type

Nullable

Description

id

string

❌

Encoded import job ID

status

string

❌

Import status: "running", "completed", or "errored"

video_id

string

✅

Encoded video ID. null initially, populated once the video record is created (may appear while still running)

created_at

string

❌

ISO 8601 timestamp when the import was created

completed_at

string

✅

ISO 8601 timestamp when the import completed. null while running

Get Import Status Error Responses

Status Code

Description

401 Unauthorized

Invalid or missing authentication token

403 Forbidden

Insufficient permissions

404 Not Found

Import job not found

Get Import Status Examples

CURL Request

curl -X GET "https://api.firework.com/api/v1/videos/imports/encoded_import_abc123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response (Running)

{
  "id": "encoded_import_abc123",
  "status": "running",
  "video_id": null,
  "created_at": "2025-01-29T12:00:00.000000Z",
  "completed_at": null
}

Response (Completed)

{
  "id": "encoded_import_abc123",
  "status": "completed",
  "video_id": "encoded_video_id_xyz123",
  "created_at": "2025-01-29T12:00:00.000000Z",
  "completed_at": "2025-01-29T12:02:30.000000Z"
}

Next step: Use the video_id with GET /api/v1/videos/{video_id} to get the full video details.

Response (Errored)

{
  "id": "encoded_import_abc123",
  "status": "errored",
  "video_id": null,
  "created_at": "2025-01-29T12:00:00.000000Z",
  "completed_at": null
}

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:

curl -X PATCH "<https://api.firework.com/api/v1/videos/xyz123>" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Product Demo",
    "custom_fields": {
      "creator_id": "3247236",
      "publisher_id": "5323645",
      "tracking_id": "724V390"
    }
  }'

PreviousAuthentication NextLivestreams

Last updated 9 days ago

Was this helpful?

hashtagAuthentication

hashtagEndpoint Summary

hashtagUpload Signature (Single File)

hashtagRequest Headers

hashtagRequest Body

hashtagVideo Limits

hashtagUpload Signature Response

hashtagUpload Signature Error Responses

hashtagUploading to S3

hashtagUpload Signature Examples

hashtagMultipart Upload

hashtagInitiate Multipart Upload

hashtagUpload Parts to S3

hashtagComplete Multipart Upload

hashtagMultipart Upload Examples

hashtagCreate Video

hashtagSupported Video Files

hashtagRequest Headers

hashtagRequest Body

hashtagMetadata Schema

hashtagCustom Poster

hashtagProduct Identifiers:

hashtagExternal Media Schema

hashtagCreate Video Response

hashtagFile Upload / S3 Key / URL Import Sync Response (201 Created)

hashtagURL Import Async Response (202 Accepted)

hashtagCreate Video Error Responses

hashtagExamples

hashtagUpdate Video

hashtagRequest Headers

hashtagURL Parameters

hashtagRequest Body

hashtagUpdate Video Response

hashtagUpdate Video Error Responses

hashtagUpdate Examples

hashtagGet Video

hashtagGet Video Response

hashtagVideo Poster Schema

hashtagGet Video Error Responses

hashtagGet Video Examples

hashtagGet Video Import Status

hashtagGet Import Status Response

hashtagGet Import Status Error Responses

hashtagGet Import Status Examples

hashtagCustom Fields Extension

Authentication

Endpoint Summary

Upload Signature (Single File)

Request Headers

Request Body

Video Limits

Upload Signature Response

Upload Signature Error Responses

Uploading to S3

Upload Signature Examples

Multipart Upload

Initiate Multipart Upload

Upload Parts to S3

Complete Multipart Upload

Multipart Upload Examples

Create Video

Supported Video Files

Request Headers

Request Body

Metadata Schema

Custom Poster

Product Identifiers:

External Media Schema

Create Video Response

File Upload / S3 Key / URL Import Sync Response (`201 Created`)

URL Import Async Response (`202 Accepted`)

Create Video Error Responses

Examples

Update Video

Request Headers

URL Parameters

Request Body

Update Video Response

Update Video Error Responses

Update Examples

Get Video

Get Video Response

Video Poster Schema

Get Video Error Responses

Get Video Examples

Get Video Import Status

Get Import Status Response

Get Import Status Error Responses

Get Import Status Examples

Custom Fields Extension