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

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.

Up to 200 ids per request; over-cap requests return 422.

## 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
- `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)