Skip to main content

Fetching Assets

Fetch requests use query selectors to choose an asset entry and its response format. Introduce selectors with a standalone - path segment. Hyphens within ordinary segments belong to the asset path; empty selector sections return 400 Bad Request. See Path rules.

Ordering​

Ordering is specified using the order query selector.

OrderDescriptionDefault if not supplied
newOrder by last-created (stack semantics)Yes
modifiedOrder by last-modified

Label filters​

Unknown query parameters are ignored and do not filter labels.

Prefix each label query parameter with label:. For example, fetch the newest entry with the label phone=iphone:

curl --fail-with-body \
'http://localhost:8080/assets/user/123/profile-picture/-/new/info?label:phone=iphone'

Pass ordinary label keys to matchingLabels(...) in Kotlin and Java; the client adds the query prefix. Keep ordinary keys in upload/update JSON and response label maps. See Labels for filtering and label limits.

Timestamps​

Konifer returns createdAt, modifiedAt, and non-null expiresAt values as RFC 3339 timestamps in UTC, ending in Z. For example: 2026-10-24T14:30:00.123456Z. Fractional-second precision can vary; parse these values as instants rather than assuming a fixed string length.

The Kotlin client exposes these fields as kotlin.time.Instant. Its timestamp parser accepts explicit UTC offsets, including Z and +00:00, and rejects strings without an offset. Update the client with the server when upgrading from the older offset-less timestamp format.

HTTP Last-Modified headers retain the HTTP-date format, such as Sat, 24 Oct 2026 14:30:00 GMT.

Content Negotiation​

Konifer resolves the output format in this order:

  1. The format query parameter
  2. The format defined in a requested variant profile
  3. A recognized image MIME type in the Accept header

The Accept header does not override an explicit or profile format. Otherwise, Konifer selects a recognized image format using the header's priorities. See the MDN Accept header documentation. If Accept: image/* is used, the original variant's format is returned.

If none of these selects a format, Konifer retains the original variant's format. Request raw pixels with format=pixels or a profile that defines it; Accept: application/octet-stream does not select pixel output.

Fetches the asset's resolved delivery URL, the selected variant's attributes, and 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

Example​

curl --fail-with-body \
'http://localhost:8080/assets/user/123/profile-picture/-/link'

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?format=jpg&height=100&width=200",
"lqip": {
"blurhash": "BASE64",
"thumbhash": "BASE64"
},
"alt": "Your alt",
"attributes": {
"height": 100,
"width": 200,
"format": "jpg",
"rotate": "0",
"horizontalFlip": false,
"colorSpace": "srgb",
"pageCount": 1
}
}
Field NameTypeDescription
urlStringThe URL resolved by the path's delivery.strategy
expiresAtRFC 3339Populated for presigned URLs
lqipLQIPLow-Quality Image Placeholder (LQIP) values if enabled in path configuration
altStringThe alt supplied when storing the asset
attributesAttributesAttributes of the selected variant

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

Service URLs include the selected entry and resolved transformation, including the format selected through Accept. Fetch the returned URL as supplied, without repeating the original header. With URL signing enabled, Konifer signs the destination URL, including the service fallback for unsupported presigned delivery. Service URL examples here omit some default transformation parameters for readability.

After cache eviction, Konifer can regenerate the variant from its URL, subject to current path policy and transformation limits. In profile_only mode, the URL includes the profile name and equivalent explicit parameters. See Service Delivery.

Fetching Redirect (/redirect)​

Request​

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

Example​

The curl example shows the redirect headers without following the redirect, as in the Bruno request. The clients follow the redirect and save its content using ContentDelivery.FOLLOW_REDIRECT. To obtain the delivery URL without downloading content, use fetchLink() from the Link example.

FOLLOW_REDIRECT returns an AssetContent with bytes and null attributes, alt, and lqip fields. The client does not decode Konifer metadata from the redirect destination, even if it supplies matching header names. Streaming returns an AssetContentMetadata with the same null fields. Use fetchLink() for metadata when using external delivery, or fetch through Konifer to receive content attribute headers.

curl --fail-with-body \
--dump-header - \
--output /dev/null \
'http://localhost:8080/assets/user/123/profile-picture/-/redirect'

# Follow the redirect and save the image instead:
curl --fail-with-body \
--location \
--output profile-picture.png \
'http://localhost:8080/assets/user/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?format=jpg&height=100&width=200

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

Example​

curl --fail-with-body \
'http://localhost:8080/assets/user/123/profile-picture/-/info'

Variant Generation​

Transformation parameters cannot be supplied (i.e. height, rotate, 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",
"externalSourceAddress": "https://yoururl.com/image.jpeg",
"sourceUrl": "https://yoururl.com/image.jpeg",
"variants": [
{
"isOriginalVariant": true,
"storeBucket": "assets",
"storeKey": "d905170f-defd-47e4-b606-d01993ba7b42",
"attributes": {
"height": 100,
"width": 200,
"format": "jpg",
"colorSpace": "srgb",
"pageCount": 1,
"rotate": "0",
"horizontalFlip": false
},
"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",
"rotate": "0",
"horizontalFlip": false
},
"transformation": {
"width": 2560,
"height": 1752,
"fit": "fit",
"gravity": "center",
"format": "webp",
"rotate": "90",
"flip": "none",
"filter": "none",
"blur": 0,
"quality": 80,
"padding": {
"amount": 0,
"color": []
},
"metadata": {
"strip": ["exif", "xmp", "iptc"]
},
"colorSpace": "srgb"
},
"lqip": {}
}
],
"createdAt": "2025-11-12T01:20:55Z",
"modifiedAt": "2025-11-12T01:20:55Z"
}
Field NameTypeDescription
classStringThe type of the asset, currently always image
altStringThe supplied alt text of your asset
entryIdLongSystem-generated unique identifier of asset within path
labelsObjectSupplied key-value pairs associated with the asset
tagsArraySupplied attributes associated with the asset
sourceStringupload, url, or arn, according to how you supplied the content
externalSourceAddressStringSupplied URL or ARN for an external source
sourceUrlStringDeprecated alias for externalSourceAddress
variantsAssetVariantOriginal and cached generated variants
createdAtRFC 3339 UTCDate asset was stored
modifiedAtRFC 3339 UTCDate asset was last modified (ignores variant generation)

AssetVariant​

Field NameTypeDescription
isOriginalVariantBooleanWhether the variant is the original variant. Only one is true
storeBucketStringThe S3 bucket the asset is stored in - defined in path configuration
storeKeyStringThe key of the asset in the object store
attributesAttributesExtracted attributes of the asset
transformationTransformationNormalized original variant transformation - not returned for original variants
lqipLQIPLow-Quality Image Placeholder (LQIP) values if enabled in path configuration
Attributes​
Field NameTypeDescription
heightIntegerHeight of variant
widthIntegerWidth of variant
formatFormatFormat of variant
pageCountIntegerNumber of pages in image; single-page content reports 1
loopIntegerFor multi-paged images, specifies the amount of animated repetitions. Defaults to 0, -1 is continuous looping
colorSpaceStringsrgb, p3, adobe_rgb, cymk, grayscale, the Description tag of the embedded ICC profile, or unknown if unable to determine color space
pixelsObjectPixel attributes for format=pixels; absent or null for encoded image formats
rotateStringClockwise rotation still needed for display: 0, 90, 180, or 270; never auto
horizontalFlipBooleanWhether to flip horizontally after applying the remaining rotation

These attributes describe the selected variant's stored bytes. For a source whose EXIF orientation has not been applied, rotate and horizontalFlip describe how to orient it for display. Orientation-normalized output reports "rotate": "0" and "horizontalFlip": false. Avoid applying these operations again if your image decoder already honors the source orientation.

Pixel attributes​
Field NameTypeDescription
channelsStringLowercase channel order, such as rgb, bgra, or gray
layoutStringinterleaved or planar; gray reports interleaved
dataTypeStringuint8: one unsigned byte (0–255) per sample

These fields also appear under attributes.pixels in a pixel variant's link response. Use the selected variant's width and height to interpret the raw body. Pixel output has no file header containing this information.

Content and download responses carry the same attributes in HTTP headers.

Transformation​

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

Field NameTypeDescriptionAllowed Values
heightIntegerHeight of variant in pixels> 0
widthIntegerWidth of variant in pixels> 0
fitAttributesFitfit, fill, stretch
gravityGravityGravitycenter, entropy, attention
formatFormatFormat of variantSee Format
rotateRotateRotation0, 90, 180, 270, auto
flipFlipWhether variant is flipped and across which axisnone, h, v
filterFilterFilternone, black_white, grayscale, sepia
blurIntegerBlur0-150
qualityIntegerCompression quality (ignored for PNG and pixels)1-100
colorSpaceColorSpaceColor spacegrayscale, srgb, p3
paddingPaddingPadding
metadataMetadataImage metadata
Padding​
Field NameTypeDescriptionAllowed Values
amountIntegerAmount of padding in pixels>= 0
colorInteger[]Color pf padding in [R, G, B, A] integers
Metadata​
Field NameTypeDescriptionAllowed Values
stripListWhich metadata was removed from the variantexif, xmp, iptc

Fetching Asset Entry Information​

Request​

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

Example​

Fetch up to 20 entries. The client accepts only positive limits; HTTP's limit=-1 has no client equivalent.

curl --fail-with-body \
'http://localhost:8080/assets/user/123/profile-picture/-/entries?limit=20'

Limit​

Supply the limit query parameter once. Its allowed values depend on the return format:

Return formatDefaultAllowed values
entries201 through 2147483647, or -1 for all matching entries at the exact path
info, link, content, download, redirect11

To fetch all matching entries over HTTP:

GET /assets/users/123/profile-picture/-/entries?limit=-1

Blank, malformed, overflowing, zero, below--1, or repeated limit values return 400 Bad Request. A limit other than 1 also returns 400 for a singular representation. Konifer applies a default only when you omit the parameter.

The Kotlin and Java fetchEntries(limit) methods accept positive integer limits. For deletion, use the DELETE limit rules: limit=-1 selects exact-path bulk deletion, and entry or recursive selectors require you to omit the limit.

Response​

HTTP/1.1 200
Content-Type: application/json
{
"entries": [
{
"class": "image",
"alt": "The alt text for an image",
"entryId": 1049,
"labels": {
"label-key": "label-value",
"phone": "Android"
},
"tags": ["cold", "verified"],
"source": "url",
"externalSourceAddress": "https://yoururl.com/image.jpeg",
"sourceUrl": "https://yoururl.com/image.jpeg",
"variants": [
{
"isOriginalVariant": true,
"storeBucket": "assets",
"storeKey": "d905170f-defd-47e4-b606-d01993ba7b42",
"attributes": {
"height": 100,
"width": 200,
"format": "jpg",
"colorSpace": "srgb",
"pageCount": 1,
"rotate": "0",
"horizontalFlip": false
},
"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",
"rotate": "0",
"horizontalFlip": false
},
"transformation": {
"width": 2560,
"height": 1752,
"fit": "fit",
"gravity": "center",
"format": "webp",
"rotate": "90",
"flip": "none",
"filter": "none",
"blur": 0,
"quality": 80,
"padding": {
"amount": 0,
"color": []
},
"metadata": {
"strip": ["exif", "xmp", "iptc"]
},
"colorSpace": "srgb"
},
"lqip": {}
}
],
"createdAt": "2025-11-12T01:20:55Z",
"modifiedAt": "2025-11-12T01:20:55Z"
}
]
}

Fetching Content​

Request​

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

Example: original content​

These examples buffer the original image before saving it locally.

curl --fail-with-body \
--output profile-picture.png \
'http://localhost:8080/assets/user/123/profile-picture/-/content'

Client content results​

fetchContent() returns KoniferResult<AssetContent>. Read the buffered body from bytes and the decoded response metadata from attributes, alt, and lqip. The attribute headers describe the bytes from that request, including dimensions, pixel layout, and remaining display orientation.

The metadata fields can be null. attributes is null if the server sends no attribute headers; a partial set or invalid value returns KoniferResult.Failure.InvalidResponse. alt is null if its header is absent, and lqip is null if neither placeholder header is present. Redirect delivery leaves all metadata null.

Streaming content​

Use fetchAndWriteContentTo() for larger bodies. It returns KoniferResult<AssetContentMetadata> after the transfer, with the same metadata fields as AssetContent.

In Kotlin, supply a ByteWriteChannel and consume it concurrently to handle backpressure. The client flushes and closes the write side on success, or terminates it on failure or cancellation. In Java, supply an OutputStream; you control flushing and closing. Transfer failures can leave partial bytes in either destination.

import java.nio.file.Files;
import java.nio.file.Path;

try (var output = Files.newOutputStream(Path.of("profile-picture.png"))) {
var metadata = client.assets(path)
.originalVariant()
.fetchAndWriteContentTo(output)
.valueOrThrow();
System.out.println(metadata.getAttributes());
}

Example: WebP thumbnail​

Request a 256×256 thumbnail, cropping around the most important part of the image.

curl --fail-with-body \
--output profile-picture.webp \
'http://localhost:8080/assets/user/123/profile-picture/-/content?width=256&height=256&format=webp&fit=fill&gravity=attention'

Example: raw pixels​

Fetch a 224×224 BGR buffer in planar layout for an image-processing input. This produces 150,528 unsigned 8-bit samples. The curl example uses entry 0; replace it with the entryId returned by your upload. Read attributes from the content response headers, or from the client's AssetContent, to interpret the bytes from the same request.

# Save dimensions and pixel attributes alongside the buffer:
curl --fail-with-body \
--dump-header profile-picture.headers \
--output profile-picture.bin \
'http://localhost:8080/assets/user/123/profile-picture/-/entry/0/content?format=pixels&width=224&height=224&fit=fill&color-space=srgb&pixel-channels=BGR&pixel-layout=planar'

The content response includes the following attribute headers:

K-Attr-Width: 224
K-Attr-Height: 224
K-Attr-Format: pixels
K-Attr-Rotate: 0
K-Attr-Horizontal-Flip: false
K-Attr-Color-Space: srgb
K-Attr-Page-Count: 1
K-Attr-Pixels-Channels: bgr
K-Attr-Pixels-Layout: planar
K-Attr-Pixels-Data-Type: uint8

Content responses use Content-Type: application/octet-stream. The body contains pixel bytes without a header; the download selector uses a .bin filename. fetchContent() buffers the whole response and returns AssetContent. For larger buffers, use fetchAndWriteContentTo() with a Kotlin ByteWriteChannel or a Java OutputStream; its result contains AssetContentMetadata after the transfer.

See Raw Pixel Output for channel validation, color space, alpha handling, and grayscale behavior.

Example: a specific entry​

Use the entryId returned by an upload to fetch that entry even after a newer image is stored at the same path. Replace 0 in the curl URL with that entry ID.

curl --fail-with-body \
--output profile-picture-entry.png \
'http://localhost:8080/assets/user/123/profile-picture/-/entry/0/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"
K-Attr-Width: 200
K-Attr-Height: 100
K-Attr-Format: jpg
K-Attr-Rotate: 0
K-Attr-Horizontal-Flip: false
K-Attr-Color-Space: srgb
K-Attr-Page-Count: 1

<image bytes>
note

Etag is only returned for Content and Download return formats

Content attribute headers​

Successful content and download responses include the selected variant's attributes in K-Attr-* headers. These describe the body you receive, including requested transformations, on both cache hits and generated variants. The body remains image or raw pixel bytes; it does not include a JSON envelope.

HeaderAttributeValuePresence
K-Attr-WidthwidthWidth of the returned image buffer, in pixelsAlways
K-Attr-HeightheightHeight of the returned image buffer, in pixelsAlways
K-Attr-FormatformatFormat identifier, such as jpg, webp, or pixelsAlways
K-Attr-RotaterotateRemaining clockwise display rotation: 0, 90, 180, or 270Always
K-Attr-Horizontal-FliphorizontalFliptrue or false; apply after the remaining rotationAlways
K-Attr-Color-SpacecolorSpaceColor-space name, such as srgb, p3, or grayscaleAlways
K-Attr-Page-CountpageCountNumber of pages or frames; 1 for single-page contentWhen available
K-Attr-LooploopAnimation loop valueWhen applicable
K-Attr-Pixels-Channelspixels.channelsLowercase channel order, such as rgb, bgra, or grayPixel output only
K-Attr-Pixels-Layoutpixels.layoutinterleaved or planarPixel output only
K-Attr-Pixels-Data-Typepixels.dataTypeuint8Pixel output only

Optional attributes have no header when they are absent. HTTP header names are case-insensitive. The existing K-Alt, K-LQIP-Blurhash, and K-LQIP-Thumbhash headers still carry asset metadata when present.

K-Attr-Rotate and K-Attr-Horizontal-Flip describe the orientation still needed for display. They do not repeat the requested rotate and flip parameters. For output whose orientation Konifer has normalized, such as a rotate=auto variant, they are 0 and false. Width and height describe the returned buffer before any remaining display rotation.

The same attributes appear in JSON link and asset-information responses. Redirect destinations such as object storage do not receive these Konifer response headers. The client leaves metadata null in FOLLOW_REDIRECT mode; use THROUGH_KONIFER to receive metadata with content. See Client content results for return types and streaming behavior.

Fetching Content Download​

Same behavior as Content, including attribute headers, with the addition of a Content-Disposition: attachment response header.

Request​

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

Example​

The curl request uses /download, which adds an attachment header. The clients save bytes from /content; they do not expose a separate /download operation. These examples buffer the image in memory.

curl --fail-with-body \
--output profile-picture-download.png \
'http://localhost:8080/assets/user/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

Error codes​

API failures return JSON with a stable code and an optional message. See Error Responses for the codes, HTTP statuses, and client compatibility behavior.