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.

Query Selectors

Query selectors are positional values specified after the path-separator, /-/. They are used to control the format and ordering of fetched assets.

Query selectors are specified in the following order:

1. Ordering: what asset(s) you want
2. Return format: how you want the asset(s) presented

Defaults

The following are the default values and can be omitted as selectors:

• Ordering: new
• Return Format: link

So this:

GET /assets/users/123/profile-picture

Is the same as:

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

Any default can be omitted for brevity

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

it is the same as:

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

Ordering

When fetching a single asset or multiple assets, you can specify the order.

• new (default): Return the most recently created asset. If limit is specified, return the n most recently created assets.
• modified: Return the most recently modified asset. If limit is specified, return the n most recently modified assets.

To specify an ordering, place it before the return format selector:

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

This also works if you are wanting the link of the newest asset in the path since link is the default return format:

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

Return format

You can return your asset in one of five different return formats:

link (default)

Returns the asset's resolved delivery URL. If you have any LQIPs enabled, these are returned as well.

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

Returns:

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

Asset Link Response

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 default service delivery strategy produces an absolute URL to the selected entry's /content endpoint, as shown above. The presigned and template strategies can instead produce an object-store or CDN URL.

content

Typically used when you want Konifer to apply transformations (e.g., resizing) and stream the result without exposing the underlying S3 URL.

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

Returns:

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 45123
K-Alt: "Your defined alt, if any"

download

Similar to content but sets the Content-Disposition header so that the asset triggers a "Save As" dialog in a browser.

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

Returns:

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 45123
Content-Disposition: attachment; filename*=UTF-8''profile-picture.jpeg

Note: the filename in the Content-Dipsosition headers is the alt if supplied, or else the path.

redirect

Returns a 307 Temporary Redirect to the same resolved delivery URL that the link response places in its url field.

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

Returns a Temporary Redirect 307:

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

With the default service strategy, the location is the selected entry's /content endpoint. This keeps the redirect selector useful with no delivery configuration.

Delivery Strategies

Delivery strategies are defined within Path Configuration and apply equally to link and redirect. The default strategy is service.

paths {
  "/**" {
    delivery {
      strategy = "service|presigned|template"
    }
  }
}

Service Delivery

The service strategy returns an absolute URL to the selected entry's content representation. Konifer uses http.public-url as the base when configured; otherwise it uses the incoming request's scheme, host, and port.

Presigned Delivery

Setting strategy to presigned causes a presigned URL from your configured object store to be generated and used in either the link response or the redirect Location header. This strategy is available for S3 and S3-compatible object stores that support presigned requests.

The in-memory and filesystem providers cannot generate presigned URLs. When either provider is used with presigned, Konifer falls back to the service delivery URL.

To set the TTL for the presigned URL, specify it within the presigned configuration block.

paths {
  "/**" {
    delivery {
      strategy = presigned
      presigned {
        ttl = 30m # default value
      }
    }
  }
}

Template Delivery

Template delivery lets you route clients through a CDN or expose a bucket directly. Define a template string, and Konifer uses it to resolve the delivery URL.

paths {
  "/**" {
    delivery {
      strategy = template
      template {
        string = "https://{bucket}.mydomain.com/{key}"
      }
    }
  }
}

Konifer substitutes the selected variant's stored {bucket} and {key} values. This remains correct when path configuration changes after an asset is stored. Any protocol is permitted except executable protocols such as javascript:, vbscript:, and data:.

info

A JSON response of the image and its properties, cached variants, and image attributes.

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

Returns:

{
  "class": "IMAGE",
  "alt": "The alt text for an image",
  "entryId": 1049,
  // Unique identifier scoped to the path
  "labels": {
    "label-key": "label-value",
    "phone": "Android"
  },
  "tags": [
    "cold",
    "verified"
  ],
  "source": "URL",
  // or UPLOAD if using multipart upload
  "sourceUrl": "https://yoururl.com/image.jpeg",
  "variants": [
    {
      "isOriginalVariant": true,
      "storeBucket": "assets",
      // Defined in configuration
      "storeKey": "d905170f-defd-47e4-b606-d01993ba7b42",
      // Generated by Konifer
      "imageAttributes": {
        "height": 100,
        "width": 200,
        "mimeType": "image/jpeg"
      },
      "lqip": {
        // Empty if LQIPs are disabled
        "blurhash": "BASE64",
        "thumbhash": "BASE64"
      }
    }
  ],
  "createdAt": "2025-11-12T01:20:55"
  // ISO 8601
}

Asset Metadata Response

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)

Limit

For info return formats, you can return more than one. To return the three most-recent assets, specify the limit query parameter, or -1 for all assets within the path:

GET /assets/users/123/profile-picture/-/new/info?limit=3

Entry ID

When an asset is stored within your path, it is assigned a unique entryId. This ID is an absolute reference to the asset within your path. It is guaranteed to be unique relative to the path. Assets can be fetched by their path + entryId using the entry query selector.

To fetch a specific asset (entryId of 42) using the default link return format:

GET /assets/users/123/profile-picture/-/entry/42

Additionally, you can specify the return format along with the entryId:

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

A URL with the entry selector is the absolute reference to the asset; therefore, ordering query selectors cannot be used with the entry selector.