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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The asset’s id.
Header Parameters
Section titled “Header Parameters ”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.
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.
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"}]}.
The file’s media type, recorded as given and returned as content_type. Defaults to application/octet-stream. Downloads don’t use it.
Request Body required
Section titled “Request Body required ”Responses
Section titled “ Responses ”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
The alternate’s id, used to download or remove it. Replacing an alternate gives it a new one.
The alternate’s name, unique for its asset.
Example
walk — team-green paletteA free-form tag, such as palette_swap, thumbnail, low_res,
authored or transcode; authored when none was given.
Example
palette_swapThe media type sent in X-Content-Type at upload, recorded as given. Downloads don’t use it.
Example
image/pngThe file’s size in bytes.
Left out for alternates attached on this instance, which is currently all of them.
The account that uploaded this alternate, or null if none was recorded.
When the alternate was attached. Lists are sorted by it, newest first.
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
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Resource not found
object
Human-readable error summary
Example
the request could not be completedUnexpected server error
object
Human-readable error summary
Example
the request could not be completed