Resources
Create an image collection
Create a collection, optionally with images already in it.
POST /api/assets/collectionsRequires assets:create. Returns 201 with the new collection.
| Field | Required | Description |
|---|---|---|
workspace | Yes | Workspace slug or id. |
name | Yes | Collection name. Cannot be empty. Spaces at either end are trimmed. |
description | No | Free-form note. Spaces at either end are trimmed, and an empty note is stored as null. |
assetIds | No | Images to put in the collection. |
curl --request POST "https://app.kalpana.one/api/assets/collections" \
--header "x-api-key: $KALPANA_API_KEY" \
--header "content-type: application/json" \
--data '{"workspace":"acme","name":"Products","assetIds":["ASSET_ID"]}'Response
{
"id": "0192f8a4-6c1e-7c3a-9b0e-4d2f1a7e5c11",
"workspaceId": "ws_123",
"name": "Products",
"description": null,
"createdBy": "user_123",
"createdAt": "2026-09-01T10:00:00.000Z",
"updatedAt": "2026-09-01T10:00:00.000Z"
}Collection names are unique in a workspace, ignoring case. A name that is already taken, or one made only of spaces, is refused with 500 and Failed to create asset collection.
Errors
| Status | Cause |
|---|---|
400 | An image in assetIds is not in the workspace. The message is One or more selected assets do not exist. |
403 | Your role or key lacks assets:create. |
500 | The name is already taken, or empty once trimmed. |
Was this page helpful?
Updated 4 Nov 2026