Skip to main content

Media

Product images and other media assets are managed through a centralized media system with support for multiple storage backends.

Media URLs​

All media URLs in API responses are fully resolved. The API prepends the configured Storage.BaseUrl to relative paths:

Stored in DB:  product-images/ct-white.png
Returned:      https://quarkapi.yourdomain.com/media/product-images/ct-white.png

No URL construction is needed on the client side — just use the imageUrl fields directly.

Product Images​

Product images are attached to variants, not products. Each variant can have multiple images:

{
  "variant": {
    "id": "guid",
    "images": [
      {
        "id": "guid",
        "url": "https://api.example.com/media/product-images/ct-white-1.png",
        "sortOrder": 0
      },
      {
        "id": "guid",
        "url": "https://api.example.com/media/product-images/ct-white-2.png",
        "sortOrder": 1
      }
    ]
  }
}
Image Strategy

Color variants of the same product often share the same images across sizes. For example, "White / S" and "White / M" will reference the same image set, while "Red / S" will have different images.

Derived Assets​

Media records can have derived assets (e.g., thumbnails, WebP conversions). These are returned alongside the original:

{
  "url": "https://api.example.com/media/product-images/ct-white.png",
  "derivedAssets": [
    {
      "tag": "thumbnail",
      "url": "https://api.example.com/media/product-images/ct-white-thumb.webp"
    }
  ]
}

Media Folders​

Media is organized into folders (e.g., product-images, brand-logos, banners). The folder slug determines the URL path segment. This is an internal organizational detail — you'll always receive fully resolved URLs.