---
title: "Rename a collection"
method: POST
path: "/api/v1/assets/collections/rename"
tags: ["Asset Management"]
---

# Rename a collection

`POST /api/v1/assets/collections/rename`

## Request

- Base URL: `https://api.imagestep.dev`
- URL: `https://api.imagestep.dev/api/v1/assets/collections/rename`
- Auth: API key in header `Authorization`

Moves every one of your assets in `from` to `to`, in one statement — the way to rename a
collection, or with `to: ""` to take its assets out of any collection. Renaming onto a name
that is already in use merges the two. `updated` is how many assets moved; a name nothing is in
moves nothing and is not an error. Both names are checked like any other collection name, and
a chain job's `job:` collections cannot be renamed.

USE THIS WHEN:
- Renaming, merging or dissolving a collection

DO NOT USE WHEN:
- Moving some assets, not all of a collection → use POST /api/v1/assets/update with `collection`

## Headers

- `Idempotency-Key` string

## Request body

- RenameCollectionRequest: Rename a collection: every asset in `from` moves to `to`
  - `from` string, required: The collection as it is named now
  - `to` string, required: Its new name; "" takes the assets out of any collection (at most 200 characters; names starting with job: are reserved)

## Response `200`

What moved

## Other responses

- `400`: - `invalid_param` on `from` — missing or empty, or not a name a collection can have (too long, a control character, starting with `job:`) - `invalid_param` on `to` — missing (send `""` to take the assets out of any collection), or not a name a collection can have
- `409`: Conflict — `error.code` is `idempotency_key_reuse` (the key already means a different request) or `request_in_progress` (the first request under this key has not settled yet; retryable).
- `429`: Rate limited — `error.code` is `rate_limited` and `retryable` is true. `Retry-After` says how many seconds to wait.

---

[API](https://skmtc.dev/imagestep/apis/imagestep-api.md) · [All operations](https://skmtc.dev/imagestep/apis/imagestep-api/llms.txt) · [OpenAPI document](https://skmtc.dev/imagestep/apis/imagestep-api/revisions/5e8e922a3085?raw)