---
title: "Create an album"
method: POST
path: "/api/albums"
tags: ["albums"]
---

# Create an album

`POST /api/albums`

Creates a new, empty album in a library (with optional name and description) and returns it. The album starts empty — follow up with `add_assets_to_album` to populate it. To rename an existing album, use `update_album` instead of creating a new one.

## Request body

- AlbumCreate
  - `name` string, nullable — Display name for the new album. Optional; callers that need to name an album can set it here or via `update_album` after creation.
  - `description` string, nullable — Optional free-form description shown alongside the album name.
  - `library_id` string, nullable — Library to create the album in. Optional if the user has a single live (non-trashed) library; required when they have multiple.

## Response `201`

Successful Response

- AlbumResponse — Represents a collection of assets organized by the user.
  - `id` string, required — Unique album identifier with 'album_' prefix
  - `name` string, required — Display name of the album
  - `description` string, nullable — Optional description text for the album
  - `asset_count` integer, required — Total number of assets in this album
  - `album_cover_asset_id` string, nullable — ID of the asset displayed as the album cover. May be a server-selected default when the album has no explicit cover set, or null when the album has no live assets.
  - `asset_urls` object, nullable — Asset variants for the album cover: 'thumbnail'
  - `start_date` string, date-time, nullable — The oldest asset date (local_datetime) in the album, or null if empty
  - `end_date` string, date-time, nullable — The newest asset date (local_datetime) in the album, or null if empty
  - `created_at` string, date-time, required — When this album was created
  - `updated_at` string, date-time, required — When this album was last updated

## Other responses

- `401` — Missing, invalid, or expired credentials.
- `403` — The credentials are valid but not authorized for this operation — for example an API key whose action or library scope excludes it, or a credential type this operation does not accept.
- `404` — Not found
- `422` — Validation Error
- `429` — Rate limit exceeded. Retry after the interval in the `Retry-After` header.

---

[API](https://skmtc.net/gumnut-ai/apis/gumnut-api.md) · [All operations](https://skmtc.net/gumnut-ai/apis/gumnut-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gumnut-ai/gumnut-api/revisions/bf08b1e1d8bd/schema)