Kalpana Docs

GET /api/assets

Requires assets:read. The id of an asset, or its file name, is what an image layer takes in modifications. See Modifications.

Query parameters

Name	Type	Required	Description
`workspace`	string	Yes	Workspace slug or id.
`search`	string	No	Case-insensitive match on part of the file name. A file extension at the end, such as `.jpg`, is ignored.
`collectionId`	string	No	An image collection id, or `uncategorized` for images in no collection. Any other value that is not a UUID returns `400`.
`contentTypes`	string or array	No	A MIME prefix such as `image/`, an exact type such as `image/png`, or `all`. A value without `/`, such as `image`, is read as `image/`. Defaults to `image/`.
`keys`	array	No	Only assets with these storage keys, up to 100.
`page`	number	No	Page number. Defaults to 1.
`limit`	number	No	Items per page. Defaults to 12, from 1 to 100.

curl "https://app.kalpana.one/api/assets?workspace=acme&search=logo&limit=24" \
  --header "x-api-key: $KALPANA_API_KEY"

Response

{
  "images": [
    {
      "id": "0b0f5a3e-5b1c-4d65-9a5e-3f7d2f2f6c11",
      "workspaceId": "ws_123",
      "filename": "logo.png",
      "contentType": "image/png",
      "sizeBytes": 20480,
      "contentHash": "…",
      "storageKey": "…",
      "meta": { "width": 512, "height": 512 },
      "uploadedBy": "user_123",
      "status": "ready",
      "createdAt": "2026-09-01T10:00:00.000Z",
      "updatedAt": "2026-09-01T10:00:00.000Z",
      "collectionIds": [],
      "url": "https://cdn.example/temporary-url"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 12
}

The result key is images even when contentTypes selects other types. Assets are ordered by last update, newest first. Only finished uploads are listed, so status is always ready. Internal template previews are excluded. meta holds the pixel width and height when they are known. collectionIds lists the image collections the asset is in. url is a temporary link.

Images are added with Upload an asset, Upload from a URL or Upload assets directly, all limited to 5 MB per image. To find many images by name at once, use Find assets by name.

To list image collections with their item counts, use List image collections.

List assets

Query parameters

Response

On this page