Skip to main content

Assets

An asset combines image content with information such as alt text, labels, and tags. Konifer stores information in the configured data store and image content in the configured object store.

You can create and fetch assets or update their information. Image content remains immutable so caches can identify a stored entry by its content.

API​

Create an asset with POST /assets/{your/defined/path}. Choose paths that match your application's domain. An application with user-generated images might organize paths by user:

POST /assets/users/123/profile-picture
POST /assets/users/234/background

If they were blog-oriented:

POST /assets/blog/123/post/5

Multiple assets can share a path. Send another POST to create a new entry at that path. A fetch request returns the newest entry by default; query selectors can select a different entry or ordering.

Path rules​

Use a standalone - segment to separate the asset path from selectors. Ordinary path segments may contain or end with hyphens:

GET /assets/album-/photo
GET /assets/album-/-/info
GET /assets/album-/photo/-/entry/42/content

The first request selects an asset at album-/photo using the default selectors. The second requests metadata at album-. The third requests the content of entry 42 at album-/photo.

You cannot use a standalone - segment in an asset path. Supply a nonempty selector section after the separator, and use at most one separator. Konifer returns 400 Bad Request for paths such as /assets/album/-, /assets/album/-/, or /assets/album/-/info/-/entry/42. Omit the separator to use the default selection. Store requests cannot include selectors.

Earlier versions also interpreted segments ending in - as selector boundaries. Hyphenated segments now remain part of the asset path; empty selector sections return 400 Bad Request.

Content​

The following content types are currently supported by Konifer:

NameContent-TypeFormatAnimated Format Supported
JPEGimage/jpegjpgN/A
PNGimage/pngpngNo (apng)
WEBPimage/webpwebpYes
AVIFimage/avifavifNo
JPEG_XLimage/jxljxlN/A
HEICimage/heicheicN/A
GIFimage/gifgifYes

Metadata​

An asset can have the following information supplied when creating or updating an asset:

  • alt
  • labels
  • tags

Alt​

An alt is intended to populate the alt attribute of an HTML tag such as <img>. It is returned within asset information but is also returned in the K-Alt response header when requesting asset content. To comply with general limits set by screen readers, the maximum length of an alt is 125 characters.

When requesting asset link, alt is returned in the response JSON.

Labels​

Labels are key-value pairs used to define custom attributes to the asset. They are optional. Up to 50 labels can be associated with an asset. To specify them when storing or updating an asset, use the labels field in the request.

{
"labels": {
"label-key": "label-value",
"phone": "Android"
}
}

Querying​

To query for assets by label, prefix each label query parameter with label:. Use this prefix for label filters in fetch and delete URLs.

GET /assets/users/123?label:label-key=label-value&label:phone=Android

Combine labels with query selectors to fetch up to five of the newest entries containing phone=iphone:

GET /assets/users/123/-/new/entries?label:phone=iphone&limit=5

Deleting​

Use labels to filter exact-path or recursive bulk deletion. To delete a bounded selection, first fetch the matching entries, then delete each returned entry ID:

GET /assets/users/123/-/new/entries?label:phone=iphone&limit=5
DELETE /assets/users/123/-/entry/42

Replace 42 with an ID from the response's entries array and repeat the DELETE for the other returned IDs. Retain the IDs for retries; the fetch and deletions are separate requests. See Deleting Assets.

Delete all with label(s)​

To delete all assets at a particular path, set your limit to -1 and supply the labels.

DELETE /assets/users/123?label:phone=iphone&limit=-1

Recursively delete​

Recursive deletes can be performed with labels as well. To delete assets at and underneath a path, supply the label(s) and the recursive selector.

DELETE /assets/users/123/-/recursive?label:phone=iphone

Reserved words​

Use label: for label query parameters, including names that overlap transformation parameters. For example, filter by the label width=wide and request a 100-pixel-wide image with:

GET /assets/users/123/-/new/content?label:width=wide&width=100

Keep ordinary label keys, such as width, in POST/PUT JSON and response label maps. In the Kotlin and Java clients, pass ordinary keys to matchingLabels(...); the client adds label: when building the URL. See label filter examples.

Rules​

  • Maximum number of labels: 50
  • Maximum label key length: 128 characters
  • Maximum label value length: 256 characters

Tags​

Tags are similar to labels in that they are custom attributes assignable to an asset but differ in the following ways:

  • They are value-only and do not contain any key-value structure
  • They cannot be used to query or delete assets

To specify tags when storing or updating an asset, use the tags field in the request.

{
"tags": [
"happy",
"smiling",
"bread"
]
}

Rules​

  • Maximum number of tags: 50
  • Maximum tag value length: 256