Skip to content

Upload an asset

POST
/stores/{storeRef}/assets/upload
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/assets/upload \
--header 'Content-Type: multipart/form-data' \
--header 'x-api-key: <x-api-key>' \
--form asset_category=store \
--form 'metadata={ "alt": "Company logo", "description": "Main brand logo" }' \
--form file=@file

Uploads a file to the store’s asset library as multipart form data and returns the stored asset. Send the file in the file field and the library area in asset_category. Accepted types: JPEG, PNG, WebP, GIF, SVG, PDF, plain text, and MP4, MOV and WebM video. Images and documents may be up to 10 MB and videos up to 100 MB; the file’s content must match its declared type. Image dimensions are read automatically, and video metadata and thumbnails are generated. 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
asset_category
required

Asset category

string
Allowed values: store catalog cms

Example

store
metadata

Asset metadata

object

Example

{
"alt": "Company logo",
"description": "Main brand logo"
}
file
required

File to upload

string format: binary
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"
}