Fetching Assets

After an asset is stored, it can be fetched. Konifer offers powerful options to fetch your asset in a variety of ways using query selectors.

Ordering

Ordering is specified using the order query selector.

Order	Description	Default if not supplied
new	Order by last-created (stack semantics)	Yes
modified	Order by last-modified

Content Negotiation

Content format is specified in two ways, resolved in this order:

1. The format query parameter
2. The Accept header

Accept header is ignored completely if format is used. If no format is specified, Konifer selects the return format using Accept header values. Prioritization is respected. See the MDN Accept header documentation. If Accept: image/* is used, the original variant's format is returned.

If no format is acceptable using either method, a 400 Bad Request is returned.

Fetching Link (/link)

Fetches the asset's resolved delivery URL as well as any LQIP and alt fields. If no return format selector is supplied, link is the default.

Request

GET /assets/users/123/profile-picture/-/link

or

GET /assets/users/123/profile-picture

Response

HTTP/1.1 200
Content-Type: application/json
K-Cache-Status: "hit" or "miss" depending on whether variant was generated or fetched

{
  "url": "https://mydomain.com/assets/users/123/profile-picture/-/entry/0/content",
  "lqip": {
    "blurhash": "BASE64",
    "thumbhash": "BASE64"
  },
  "alt": "Your alt"
}

Field Name	Type	Description
url	String	The URL resolved by the path's delivery.strategy
expiresAt	ISO 8601	Populated for presigned URLs
lqip	LQIP	Low-Quality Image Placeholder (LQIP) values if enabled in path configuration
alt	String	The alt supplied when storing the asset

The example shows the default service strategy. A presigned or template strategy returns its resolved external URL in the same field.

Fetching Redirect (/redirect)

Request

GET /assets/users/123/profile-picture/-/redirect

Response

Returns a Temporary Redirect 307:

HTTP/1.1 307
Location: https://mydomain.com/assets/users/123/profile-picture/-/entry/0/content

The Location value is resolved with the same path-level delivery strategy used by link. The default service strategy redirects to the selected entry's /content endpoint; presigned and template can redirect directly to object storage or a CDN.

Fetching Asset Information

Request

GET /assets/users/123/profile-picture/-/info

Limit

Metadata is the only return format where multiple assets can be returned. Specify limit using the limit query parameter.

• Default: 1
• Fetch all at path: -1

Variant Generation

Transformation parameters cannot be supplied (i.e. h, r, blur, etc.) when requesting asset metadata. A 400 Bad Request is returned if any transformation parameters are supplied.

Response

HTTP/1.1 200
Content-Type: application/json
K-Cache-Status: "hit" or "miss" depending on whether variant was generated or fetched

{
  "class": "image",
  "alt": "The alt text for an image",
  "entryId": 1049,
  "labels": {
    "label-key": "label-value",
    "phone": "Android"
  },
  "tags": [ "cold", "verified" ],
  "source": "url",
  "sourceUrl": "https://yoururl.com/image.jpeg",
  "variants": [
    {
      "isOriginalVariant": true,
      "storeBucket": "assets",
      "storeKey": "d905170f-defd-47e4-b606-d01993ba7b42",
      "imageAttributes": {
        "height": 100,
        "width": 200,
        "mimeType": "image/jpeg"
      },
      "lqip": {
        "blurhash": "BASE64",
        "thumbhash": "BASE64"
      }
    },
    {
      "isOriginalVariant": false,
      "storeBucket": "assets",
      "storeKey": "64fffa7e-85d2-42db-a081-354c91ec7ef9.webp",
      "attributes": {
        "height": 2560,
        "width": 1752,
        "format": "webp",
        "pageCount": 1,
        "loop": 0,
        "colorSpace": "srgb"
      },
      "transformation": {
        "width": 2560,
        "height": 1752,
        "fit": "fit",
        "gravity": "center",
        "format": "webp",
        "rotate": "ninety",
        "flip": "none",
        "filter": "none",
        "blur": 0,
        "quality": 80,
        "padding": {
          "amount": 0,
          "color": []
        },
        "metadata": {
          "strip": [
            "exif", "xmp", "iptc"
          ],
        }
      },
      "lqip": {}
    }
  ],
  "createdAt": "2025-11-12T01:20:55"
}

Field Name	Type	Description
class	String	The type of the asset, currently always image
alt	String	The supplied alt text of your asset
entryId	Long	System-generated unique identifier of asset within path
labels	Object	Supplied key-value pairs associated with the asset
tags	Array	Supplied attributes associated with the asset
source	String	Either url or upload depending on how you provided asset content
sourceUrl	String	If URL source was used, then this is the supplied URL
variants	AssetVariant	Will only contain the original variant - the one supplied
createdAt	ISO 8601	Date asset was stored
modifiedAt	ISO 8601	Date asset was last modified (ignores variant generation)

AssetVariant

Field Name	Type	Description
isOriginalVariant	Boolean	Whether the variant is the original variant. Only one is true
storeBucket	String	The S3 bucket the asset is stored in - defined in path configuration
storeKey	String	The key of the asset in the object store
attributes	Attributes	Extracted attributes of the asset
transformation	Transformation	Normalized original variant transformation - not returned for original variants
lqip	LQIP	Low-Quality Image Placeholder (LQIP) values if enabled in path configuration

Attributes

Field Name	Type	Description
height	Integer	Height of variant
width	Integer	Width of variant
format	Format	Format of variant
pageCount	Integer	Number of pages in image (0 unless image is animated)
loop	Integer	For multi-paged images, specifies the amount of animated repetitions. Defaults to 0, -1 is continuous looping
colorSpace	String	srgb, p3, adobe_rgb, cymk, grayscale, the Description tag of the embedded ICC profile, or unknown if unable to determine color space

Transformation

Refer to the Image Transformation Reference for greater detail about available image transformations.

Field Name	Type	Description	Allowed Values
height	Integer	Height of variant in pixels	> 0
width	Integer	Width of variant in pixels	> 0
fit	Attributes	Fit	fit, fill, stretch
gravity	Gravity	Gravity	center, entropy, attention
format	Format	Format of variant	See Format
rotate	Rotate	Rotation	0, 90, 180, 270, auto
flip	Flip	Whether variant is flipped and across which axis	none, h, v
filter	Filter	Filter	none, black_white, grayscale, sepia
blur	Integer	Blur	0-150
quality	Integer	Compression quality (ignored for PNG)	1-100
colorSpace	ColorSpace	Color space	grayscale, srgb, p3
padding	Padding	Padding
metadata	Metadata	Image metadata

Padding

Field Name	Type	Description	Allowed Values
amount	Integer	Amount of padding in pixels	>= 0
color	Integer[]	Color pf padding in [R, G, B, A] integers

Metadata

Field Name	Type	Description	Allowed Values
strip	List	Which metadata was removed from the variant	exif, xmp, iptc

Fetching Content

Request

GET /assets/users/123/profile-picture/-/content

Response

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 45123
Etag: 123456
K-Alt: "Your defined alt, if any"
K-Cache-Status: "hit" or "miss" depending on whether variant was generated or fetched
K-LQIP-Blurhash: "BASE64 Blurhash, if enabled"
K-LQIP-Thumbhash: "BASE64 Thumbhash, if enabled"

<image bytes>

note

Etag is only returned for Content and Download return formats

Fetching Content Download

Same behavior as Content but with the addition of a Content-Disposition: attachment response header

Request

GET /assets/users/123/profile-picture/-/download

Response

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 45123
Etag: 123456
K-Alt: "Your defined alt, if any"
K-Cache-Status: "hit" or "miss" depending on whether variant was generated or fetched
K-LQIP-Blurhash: "BASE64 Blurhash, if enabled"
K-LQIP-Thumbhash: "BASE64 Thumbhash, if enabled"
Content-Disposition: attachment; filename*=UTF-8''profile-picture.jpeg