Asset Management

Batch update asset properties

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

Headers

Idempotency-Keystring

Optional. A client-generated unique key (typically a UUID). Same key + the same request (method, path, query string and body) replays the first response verbatim with Idempotency-Replayed: true, without executing again. Same key + a different one returns 409 idempotency_key_reuse. A repeat that arrives while the first is still running returns 409 request_in_progress, which is retryable. Keys are retained 24 hours. At most 255 characters; a longer one is a 400 invalid_param with param: "Idempotency-Key".

Request body

idsstring[] required

Asset IDs to update, at most 10000

publishedboolean

true publishes every listed asset (it gets a publicUrl), false takes them down; omit to leave them as they are

collectionstring

Collection to put the assets in; "" takes them out of theirs (at most 200 characters; names starting with job: are reserved)

tagsstring[]

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)

Example request

{
  "ids": [
    "ast_…",
    "ast_…"
  ],
  "published": true,
  "collection": "shoot-01"
}

Response

The updated assets, in request order

Changes

No recorded changes to this operation across all 1 revision of this API.