Upload an asset
const url = 'https://apibase.ecomweb.app/api/v1/stores/example/assets/upload';const form = new FormData();form.append('asset_category', 'store');form.append('metadata', '{ "alt": "Company logo", "description": "Main brand logo" }');form.append('file', 'file');
const options = {method: 'POST', headers: {'x-api-key': '<x-api-key>'}};
options.body = form;
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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=@fileUploads 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
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The store’s ref, as returned by GET /stores.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Asset category
Example
storeAsset metadata
object
Example
{ "alt": "Company logo", "description": "Main brand logo"}File to upload
Responses
Section titled “Responses”object
Uploaded asset details
object
Unique asset identifier
Owner type of the asset
Owner ID (user ID or store ID)
File name in storage
Original file name
MIME type of the file
File size in bytes
Storage provider
Storage bucket name
Storage path
Asset type
Public URL
CDN URL
File extension
Asset category
Image width in pixels
Image height in pixels
Video/audio duration in seconds
Asset metadata
object
Thumbnail URLs
object
Transformation settings
object
BlurHash for progressive loading
Dominant color in hex
Asset status
Asset visibility
Whether asset is approved
Moderation status
Moderation notes
Number of times asset has been accessed
Last access timestamp
Asset version number
Parent asset ID for versioning
External provider asset ID
External provider name
External provider metadata
object
Creation timestamp
Creator user ID
Last update timestamp
Last updater user ID
Deletion timestamp
Deleter user ID
Asset links (only included when include_links=true)
object
Link ID
Asset ID
Entity type (product, banner, store, etc.)
Entity ID
Field name (gallery, featured, logo, etc.)
Friendly name of the linked entity (product name, category name, etc.)
Sort order
Is primary asset
Extra metadata
object
Creator user ID
Creation timestamp
Success message
Error message
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.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The key is missing, invalid, revoked or expired.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
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.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}