---
title: "Add existing assets to an album"
method: POST
path: "/api/albums/{album_id}/assets"
tags: ["albums"]
---

# Add existing assets to an album

`POST /api/albums/{album_id}/assets`

## Request

- Base URL: `https://api.gumnut.ai`
- URL: `https://api.gumnut.ai/api/albums/{album_id}/assets`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Adds one or more existing assets to the specified album. Assets must already be in the same library as the album (this tool does not upload new assets). Assets already in the album are silently skipped and returned separately as `duplicate_assets`; missing or different-library IDs are skipped and returned as `not_found_assets`. Idempotent: calling with the same IDs twice leaves the album in the same state.

## Path parameters

- `album_id` string, required: Album ID (with `album_` prefix) of the album to add the assets to.

## Request body

- AlbumAssetAssociation
  - `asset_ids` string[], required: Asset IDs (with `asset_` prefix) to associate with the album. Up to 200 ids per request.

## Response `200`

Successful Response

- AddAssetsToAlbumResponse
  - `added_assets` string[], required: Asset IDs newly added to the album by this call.
  - `duplicate_assets` string[], required: Asset IDs that were already in the album and were skipped (idempotent no-op, not an error).
  - `not_found_assets` string[], required: Asset IDs that were skipped because they do not exist or do not belong to the album's library.

## 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
- `409`: Clerk sign-in could not be associated with the existing account. Resolve the identity conflict before retrying sign-in; repeated requests with unchanged verification and identity state will not resolve it.
- `422`: Validation Error
- `429`: Rate limit exceeded, or too many of your requests are already in progress. Retry after the interval in the `Retry-After` header.
- `503`: Authentication provider temporarily unavailable. Retry sign-in later.

## Changes

- **2026-10-16** `7c2860d9eb88`: 2 info
  - added the non-success response with the status `409`
  - added the non-success response with the status `503`
- **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`

[Operation history](https://skmtc.dev/gumnut-ai/apis/gumnut-api/changes/api/albums/:album_id/assets/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.dev/gumnut-ai/apis/gumnut-api/revisions/285ec2f6cd93?raw)
