Skip to content

Upload a video

POST
/stores/{storeRef}/assets/videos/upload
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/assets/videos/upload \
--header 'Content-Type: multipart/form-data' \
--header 'x-api-key: <x-api-key>' \
--form file=@file \
--form asset_category=catalog \
--form 'metadata={}'

Uploads a video to the store’s asset library as multipart form data. Limits: MP4/MOV/WebM, max 100MB, 1-300 seconds, max 1920x1920px. Video metadata is read and thumbnails are generated automatically. Uploads that would exceed the plan’s storage allowance are refused with 403.

Required scopes: write:assets

storeRef
required
string

The store’s ref, as returned by GET /stores.

Media typemultipart/form-data
object
file
required

Video file (MP4/MOV/WebM, max 100MB, 1-300 seconds, max 1920x1920px)

string format: binary
asset_category

Asset category: catalog for products, cms for content, store for branding. Defaults to catalog.

string
default: catalog
Allowed values: catalog cms store
metadata

Optional metadata to store with the asset, such as alt text or a caption.

object
Media typeapplication/json
object
asset

Uploaded asset details

object
id
required

Unique asset identifier

string
owner_type
required

Owner type of the asset

string
Allowed values: user store system
owner_id
required

Owner ID (user ID or store ID)

string
file_name
required

File name in storage

string
original_name
required

Original file name

string
mime_type
required

MIME type of the file

string
file_size
required

File size in bytes

number
storage_provider
required

Storage provider

string
storage_bucket
required

Storage bucket name

string
storage_path
required

Storage path

string
asset_type
required

Asset type

string
Allowed values: image video document audio other
public_url

Public URL

string
cdn_url

CDN URL

string
file_extension

File extension

string
asset_category

Asset category

string
Allowed values: product banner logo favicon blog category avatar content
width

Image width in pixels

number
height

Image height in pixels

number
duration

Video/audio duration in seconds

number
metadata
required

Asset metadata

object
thumbnails
required

Thumbnail URLs

object
transformations
required

Transformation settings

object
blurhash

BlurHash for progressive loading

string
dominant_color

Dominant color in hex

string
status
required

Asset status

string
Allowed values: active processing failed archived deleted
visibility
required

Asset visibility

string
Allowed values: public private protected
is_approved
required

Whether asset is approved

boolean
moderation_status

Moderation status

string
moderation_notes

Moderation notes

string
usage_count
required

Number of times asset has been accessed

number
last_accessed_at

Last access timestamp

string
version
required

Asset version number

number
parent_asset_id

Parent asset ID for versioning

string
external_id

External provider asset ID

string
external_provider

External provider name

string
external_metadata
required

External provider metadata

object
created_at
required

Creation timestamp

string
created_by

Creator user ID

string
updated_at
required

Last update timestamp

string
updated_by

Last updater user ID

string
deleted_at

Deletion timestamp

string
deleted_by

Deleter user ID

string
links

Asset links (only included when include_links=true)

Array<object>
object
id
required

Link ID

string
asset_id
required

Asset ID

string
entity_type
required

Entity type (product, banner, store, etc.)

string
entity_id
required

Entity ID

string
field
required

Field name (gallery, featured, logo, etc.)

string
friendly_name

Friendly name of the linked entity (product name, category name, etc.)

string
sort_order
required

Sort order

number
is_primary
required

Is primary asset

boolean
extra
required

Extra metadata

object
created_by

Creator user ID

string
created_at
required

Creation timestamp

string
message

Success message

string
error

Error message

string

Example

{
"asset": {
"id": "uuid-string",
"owner_type": "user",
"owner_id": "123",
"file_name": "logo-1234567890.png",
"original_name": "company-logo.png",
"mime_type": "image/png",
"file_size": 1024000,
"storage_provider": "supabase",
"storage_bucket": "public-cdn",
"storage_path": "stores/store_123/branding/logo-1234.png",
"asset_type": "image",
"public_url": "https://example.com/image.png",
"cdn_url": "https://cdn.example.com/image.png",
"file_extension": "png",
"asset_category": "product",
"width": 1200,
"height": 800,
"duration": 120,
"metadata": {
"alt": "Company logo",
"tags": [
"branding"
]
},
"thumbnails": {
"small": "url1",
"medium": "url2",
"large": "url3"
},
"transformations": {
"width": 800,
"height": 600,
"quality": 90
},
"blurhash": "LKO2?U%2Tw=w]~RBVZRi};RPxuwH",
"dominant_color": "#3B82F6",
"status": "active",
"visibility": "public",
"is_approved": true,
"moderation_status": "approved",
"moderation_notes": "Content is appropriate",
"usage_count": 5,
"last_accessed_at": "2024-01-01T12:00:00Z",
"version": 1,
"parent_asset_id": "parent-uuid",
"external_id": "canva-design-id",
"external_provider": "canva",
"external_metadata": {
"type": "design",
"design": {
"id": "canva-id"
}
},
"created_at": "2024-01-01T12:00:00Z",
"created_by": "user-uuid",
"updated_at": "2024-01-01T12:00:00Z",
"updated_by": "user-uuid",
"deleted_at": null,
"deleted_by": null,
"links": [
{
"id": "12345",
"asset_id": "uuid-string",
"entity_type": "product",
"entity_id": "123",
"field": "gallery",
"friendly_name": "Premium Leather Wallet",
"sort_order": 0,
"is_primary": false,
"extra": {
"alt": "Product image"
},
"created_by": "user-uuid",
"created_at": "2024-01-01T12:00:00Z"
}
]
},
"message": "Upload successful",
"error": "File too large"
}

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}