Skip to content

Attach an alternate file to an asset

POST
/assets/{id}/alternates

Uploads a file and attaches it to an asset as an alternate under a label, such as a palette swap or a smaller copy.

Send the file’s raw bytes as the request body and the label in X-Alternate-Label. Labels are unique per asset and compared exactly: uploading under a label that’s already in use replaces that alternate, whatever its kind. The old one is removed before the new file is stored, so if a later step fails, the label can be left empty. The replacement gets a new id and time.

X-Alternate-Kind is a free-form tag and X-Alternate-Metadata carries extra JSON; the server stores both and acts on neither. X-Content-Type is recorded as given, but GET /assets/{id}/alternates/{alternate_id} always sends the bytes as application/octet-stream.

Any signed-in account can attach alternates to any asset that isn’t in the trash; ownership and edit rights aren’t checked yet. created_by_user_ref records the account that made the upload.

A missing or empty label, or an id that isn’t a UUID, gets a plain-text 400 before the request reaches this operation. The JSON 400 below covers a label over 256 bytes, a kind over 64 bytes, and metadata over 8,192 bytes or not valid JSON. Storage and database failures get a plain-text 500.

id
required
string format: uuid

The asset’s id.

X-Alternate-Label
required
string
>= 1 characters <= 256 characters

The alternate’s name, shown in lists, for example team green palette. Trimmed, then at most 256 bytes. Unique per asset: reusing a label replaces that alternate.

X-Alternate-Kind
string
>= 1 characters <= 64 characters

A free-form tag, such as palette_swap, thumbnail or transcode; any text up to 64 bytes. Defaults to authored when absent or empty. The Sprite Viewer uses palette_swap.

X-Alternate-Metadata
string
<= 8192 characters

Extra JSON stored with the alternate and returned as metadata, at most 8,192 bytes. It doesn’t have to be an object, but only an object comes back as an object: other values come back as {}, and null as null. The Sprite Viewer stores its colour remap here as {"remap": [{"from": "#rrggbb", "to": "#rrggbb"}]}.

X-Content-Type
string

The file’s media type, recorded as given and returned as content_type. Defaults to application/octet-stream. Downloads don’t use it.

string format: binary

The alternate as stored.

A file attached to an asset as another version of it, such as a palette swap, under a label that is unique for that asset.

object
id
required

The alternate’s id, used to download or remove it. Replacing an alternate gives it a new one.

string format: uuid
asset_id
required
string format: uuid
label
required

The alternate’s name, unique for its asset.

string
Example
walk — team-green palette
kind
required

A free-form tag, such as palette_swap, thumbnail, low_res, authored or transcode; authored when none was given.

string
Example
palette_swap
content_type
required

The media type sent in X-Content-Type at upload, recorded as given. Downloads don’t use it.

string
Example
image/png
size_bytes
required

The file’s size in bytes.

integer format: int64
origin_server_id

Left out for alternates attached on this instance, which is currently all of them.

string format: uuid
nullable
created_by_user_ref
required

The account that uploaded this alternate, or null if none was recorded.

integer format: int64
nullable
created_at
required

When the alternate was attached. Lists are sorted by it, newest first.

string format: date-time
metadata
required

The JSON sent in X-Alternate-Metadata, or {} if none was sent. An object comes back as an object, though key order and spacing may change; other JSON comes back as {}, and null as null. The Sprite Viewer stores its colour remap here.

object
key
additional properties
any

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

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

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed