---
title: "Create asset collection"
method: POST
path: "/assets/collections"
tags: ["Assets"]
---

# Create asset collection

`POST /assets/collections`

Create asset collection for the authenticated user's fal Assets library.

## Headers

- `Idempotency-Key` string — Optional idempotency key for safe request retries

## Request body

- object
  - `name` string, required — Collection display name
  - `description` string, nullable — Optional collection description
  - `icon` string, nullable — Optional collection icon
  - `color` string, nullable — Optional collection color
  - `cover_image_url` string, uri, nullable — Optional fal-hosted cover image URL for the collection
  - `parent_collection_id` string, nullable — Optional parent collection ID to nest this collection under (manual collections only). Omit or null to create a top-level collection.
  - `filters` unknown

## Response `201`

Collection created

- object
  - `collection` object, required — Asset collection
    - `id` string, required — Collection ID
    - `type` 'manual' | 'smart' | 'character', required — Collection type
    - `name` string, required — Collection display name
    - `description` string, nullable, required — Collection description
    - `icon` string, nullable, required — Optional collection icon
    - `color` string, nullable, required — Optional collection color
    - `cover_image_url` string, nullable, required — Optional cover image URL for the collection
    - `character_identifier` string, nullable, required — Character @mention identifier for character collections
    - `parent_collection_id` string, nullable, required — Parent collection ID for a nested (manual) collection; null when top-level
    - `is_favorited` boolean, required — Whether the collection is favorited
    - `filters` unknown
    - `asset_count` number, nullable — Exact asset count when available; null for smart/character collections
    - `created_at` string, required — Collection creation time
    - `updated_at` string, required — Collection update time

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication required
- `403` — Access denied
- `404` — Resource not found
- `409` — Invalid request parameters
- `422` — Invalid request parameters
- `429` — Rate limit exceeded
- `500` — Internal server error
- `502` — Upstream asset service error

---

[API](https://skmtc.dev/fal/apis/platform-apis.md) · [All operations](https://skmtc.dev/fal/apis/platform-apis/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fal/platform-apis/revisions/0c7dabf80b00/schema)