Skip to content

List assets

GET
/stores/{storeRef}/assets
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/stores/example/assets?owner_type=user&asset_category=product&status=active&page=1&limit=20&sort_by=created_at&sort_order=asc&include_links=false&filters=%5B%7B%22field%22%3A%22asset_type%22%2C%22operator%22%3A%22is%22%2C%22values%22%3A%5B%22image%22%5D%7D%5D' \
--header 'x-api-key: <x-api-key>'

Returns the store’s asset library, newest first by default. Filter by category, status, type, external provider or a search term on the file name, sort with sort_by and sort_order, or pass filters for list-view filters. Paginated with page and limit (default 20, at most 100); pass include_links=true to include where each asset is used.

Required scopes: read:assets

storeRef
required
string

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

owner_type
string
Allowed values: user store system

Has no effect: the library is always limited to the store’s own assets

owner_id
string

Has no effect: the library is always limited to the store’s own assets

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

Asset category filter

status
string
Allowed values: active processing failed archived deleted

Asset status filter

external_provider
string

External provider filter

asset_type
string

Asset type filter (image, video, document, etc.)

search
string

Search term for file names

page
number
default: 1 >= 1

Page number

limit
number
default: 20 >= 1 <= 100

Items per page

sort_by
string
default: created_at

Sort field

sort_order
string
default: desc
Allowed values: asc desc

Sort order

include_links
boolean

Include asset links information in the response

filters
string

Example

[{"field":"asset_type","operator":"is","values":["image"]}]

Admin list-view filters, a JSON array of {field, operator, values}. At most 10 clauses, at most 50 values each.

Media typeapplication/json
object
assets
required

List of assets

Array<object>
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
total
required

Total number of assets

number
page
required

Current page number

number
limit
required

Items per page

number
totalPages
required

Total number of pages

number

Example

{
"assets": [
{
"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"
}
]
}
],
"total": 100,
"page": 1,
"limit": 20,
"totalPages": 5
}

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"
}