Attach a variant file to an asset

POST

/assets/{id}/alternates

• Local development behind nginx (port 8088 by default)

Streams the variant body content-addressed into storage, then attaches it as a sibling alternate. Replaces any existing alternate with the same label (the old pin is removed). Pass the kind tag in X-Alternate-Kind so the UI can group + filter; kind-specific metadata travels as JSON in X-Alternate-Metadata.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Header Parameters

X-Alternate-Label

required

string

>= 1 characters <= 256 characters

Human label shown in alt-file lists. Unique per asset; an upload with an existing label replaces the previous variant.

X-Alternate-Kind

string

>= 1 characters <= 64 characters

Provenance tag — palette_swap | thumbnail | low_res | authored | transcode. Free-form so new generators don’t need a backend change; defaults to “authored”.

X-Alternate-Metadata

string

<= 8192 characters

JSON-encoded per-kind metadata. The sprite tool’s palette swap encodes its “from → to” colour map here; thumbnail workers encode dimensions. Opaque to the backend.

X-Content-Type

string

MIME type of the alternate bytes.

Request Body ^required

string format: binary

Responses

201

Alternate attached

A sibling-version variant of an asset (palette swap, transcode, thumbnail, authored variant). Where companions are sidecars the primary asset references, alternates stand on their own and can be downloaded individually.

object

id

required

string format: uuid

asset_id

required

string format: uuid

label

required

Human label shown in alt-file lists; unique per asset.

string

Example

walk — team-green palette

kind

required

Provenance tag — palette_swap | thumbnail | low_res | authored | transcode. Open-ended.

string

Example

palette_swap

content_type

required

string

Example

image/png

size_bytes

required

integer format: int64

origin_server_id

string format: uuid

nullable

created_by_user_ref

required

integer format: int64

nullable

created_at

required

string format: date-time

metadata

required

Kind-specific JSON. Sprite tool palette swaps store the colour remap here.

object

key

additional properties

any

400

Malformed request

object

error

required

Human-readable error summary

string

Example

the request could not be completed

401

Authentication required, missing, or invalid

object

error

required

Human-readable error summary

string

Example

the request could not be completed

Example

{
  "error": "authentication required: sign in and retry with a valid session or API token"
}

404

Resource not found

object

error

required

Human-readable error summary

string

Example

the request could not be completed

500

Unexpected server error

object

error

required

Human-readable error summary

string

Example

the request could not be completed