Asset Management

Finalize file uploads

Creates one asset per staged object whose bytes were PUT to the staged URL.

Send only what the caller knows: which staged object, the file's name and, optionally, a collection and tags — [{"objectId": "…", "name": "photo.jpg", "collection": "shoot-01"}]. The type comes from the name's extension (the rule stage-upload signed the PUT with); size, dimensions and SHA-1 are measured by ingest; the source is always upload. Every asset starts PROCESSING — poll POST /api/v1/assets/status until it is DONE.

Every item is checked before any is written, so one bad item fails the whole request and creates nothing. At most 500 objects per request. The asset limit is checked here, and this is the check that counts — stage-upload's is advisory.

USE THIS WHEN:

  • Finalizing file uploads after uploading to staged URLs (single or batch)

DO NOT USE WHEN:

  • Staging the upload → use POST /api/v1/assets/stage-upload
  • The image is at a public URL → use POST /api/v1/assets/from-url
post/api/v1/assets/finish-upload

Request

  • Base URL: https://api.imagestep.dev
  • URL: https://api.imagestep.dev/api/v1/assets/finish-upload
  • 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

objectIdstring required

The objectId stage-upload returned for this file

namestring required

The file's name; its extension decides the type, and the asset is named after its stem, cut to 200 characters

collectionstring

Optional collection to put the asset in: an opaque name, no hierarchy, at most 200 characters; names starting with job: are reserved

tagsstring[]

Optional tags for the new asset: your own labels, matched exactly by GET /api/v1/assets?tag= (at most 50, each at most 100 characters)

retentionDaysinteger

Keep the asset this many days instead of your plan's retention — shorter only; more is kept for the plan's time (imagestep#591). Its expiresAt says what was stamped.

Example request

[
  {
    "name": "vacation-photo.jpg",
    "collection": "shoot-01",
    "tags": [
      "hero",
      "spring-sale"
    ],
    "retentionDays": 7
  }
]

Response

One new asset per object, in request order

Changes

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