---
title: "Batch update asset properties"
method: POST
path: "/api/v1/assets/update"
tags: ["Asset Management"]
---

# Batch update asset properties

`POST /api/v1/assets/update`

## Request

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

Updates the published status, the collection and the tags of multiple assets.
Each field you send is applied to every listed asset; a field you omit is left alone.
`collection: ""` takes the assets out of their collection; `tags` replaces the whole list
(`[]` clears it). IDs that are not yours are skipped without an error: the answer is the assets
that were updated, as full records with the change applied.

`published: true` gives each asset its `publicUrl`, the full-size image on the CDN;
`published: false` takes it down within about two minutes.

USE THIS WHEN:
- Publishing or unpublishing one or more assets
- Putting assets in a different collection
- Tagging assets so GET /api/v1/assets?tag= finds them again

DO NOT USE WHEN:
- Permanently deleting assets → use POST /api/v1/assets/delete
- Renaming a whole collection → use POST /api/v1/assets/collections/rename

## Headers

- `Idempotency-Key` string

## Request body

- AssetBatchUpdateRequest: Batch update request with asset IDs and properties to update
  - `ids` string[], required: Asset IDs to update, at most 10000
  - `published` boolean: true publishes every listed asset (it gets a publicUrl), false takes them down; omit to leave them as they are
  - `collection` string: Collection to put the assets in; "" takes them out of theirs (at most 200 characters; names starting with job: are reserved)
  - `tags` string[]: Replace the assets' tags with this list ([] clears them; omit to leave them). Your own labels, matched exactly by GET /api/v1/assets?tag= (at most 50, each at most 100 characters)

## Response `200`

The updated assets, in request order

## Other responses

- `400`: - `invalid_param` on `ids` — missing, empty, or longer than 10000 - `invalid_param` on `collection` or `tags` — over a limit, a control character, or a collection starting with `job:` - `invalid_state` on `published` — `true` for an asset whose ingest FAILED: it holds no image to publish. `details.failed` lists them, and nothing in the request is written
- `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)