---
title: "Update an album"
method: PATCH
path: "/api/albums/{album_id}"
tags: ["albums"]
---

# Update an album

`PATCH /api/albums/{album_id}`

Updates album metadata (name, description, and/or cover). Only the fields included in the request body are changed. To modify the contents of an album, use `add_assets_to_album` / `remove_assets_from_album` instead — this tool only changes album metadata.

## Path parameters

- `album_id` string, required — Album ID (with `album_` prefix) of the album to rename or re-describe.

## Request body

- AlbumUpdate
  - `name` string, nullable — New display name for the album. Omit to leave unchanged.
  - `description` string, nullable — New free-form description for the album. Pass `null` to clear the description. Omit to leave unchanged.
  - `album_cover_asset_id` string, nullable — Asset ID (with `asset_` prefix) to use as the album cover. Must be a live asset already in the album. Pass `null` to clear the explicit cover. Omit to leave unchanged.

## Response `200`

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/e71db45f5d4a/schema)