Read the preview variant ladder
GET /previews
Returns the configured preview variants in the operator’s stored order.
Signed-out callers need public mode to be on. Any valid signed-in identity can read the ladder; no extra permission is checked. Each entry gives its key, fit, maximum dimension and configured format. Encoder quality and upscaling settings are left out.
An absent, null or empty variant list gives the four shipped defaults: col, preview, screen and hires. A nonempty list is returned as stored, without revalidating its entries on this read. An error reading or decoding the configuration fails the request. This is the complete configuration list with no pagination, not an inventory of any asset’s stored images.
When choosing image URLs, combine these keys with each asset’s preview_available and ladder_available hints. Those hints come from separate reads and may use a cached key list. Neither this response nor those database-backed hints promise that a later byte request succeeds.
max_dim is a size limit, not necessarily the file’s width. A contain image can be narrower because of its aspect ratio or skipped upscaling, so don’t use that number alone as an exact srcset width descriptor. The web client fetches the ladder once per page load, separates cover and contain entries, and falls back to its col path when it can’t get usable entries.
Responses
Section titled “ Responses ”The configured preview rungs, or the shipped defaults for an empty configuration.
The installation-wide preview configuration as clients see it. It describes the configured rungs, not the stored files or permissions of any one asset.
object
The complete rung list in stored order. The shipped defaults are used when the stored list is absent or empty.
One configured preview variant. The read endpoint returns these settings without revalidating a nonempty stored list.
object
Variant key used in /assets/{id}/variants/{key}. Discover the configured keys instead of assuming the four shipped defaults.
cover crops to a square; contain keeps the picture’s aspect ratio within the configured size. Choose a contain rung when the original shape matters.
Configured size limit in pixels: the square edge for cover, or the longest edge for contain. It isn’t necessarily the generated file’s width, especially for portrait images or when upscaling is skipped.
Configured output format for this rung. It reports the setting and doesn’t inspect how an existing stored variant is encoded.