---
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.

## Changes

- **2026-08-08** `815e0302a988` — 1 breaking, 1 info
  - response property `detail` list-of-types was widened by adding types `string` to media type `application/json` of response `422`
  - the response property `detail` became required for the status `422`
- **2026-08-05** `c3e15c78f2da` — 4 info
  - added the media type `application/json` for the response with the status `404`
  - added the non-success response with the status `401`
  - added the non-success response with the status `403`
  - added the non-success response with the status `429`
- **2026-07-21** `0de36cb170df` — 2 warning
  - the `description/anyOf[subschema #1]/` request property's maxLength was set to `8192`
  - the `name/anyOf[subschema #1]/` request property's maxLength was set to `255`

[Change history](https://skmtc.dev/gumnut-ai/apis/gumnut-api/changes/api/albums/post.md)

---

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