Attach a companion file to an asset
POST /assets/{id}/companions
Uploads a file and attaches it to an asset as a companion, at the
relative path the asset’s main file uses for it, such as
textures/wood.png.
Send the file’s raw bytes as the request body, not a form, and the
path in X-Companion-Path. The request’s own Content-Type isn’t
read; send the file’s type in X-Content-Type. The path is trimmed
of surrounding spaces and then stored exactly as sent, so to count
as attached in GET /assets/{id}/companion-requirements it has to
match the model’s reference character for character, including case.
Subfolders are fine; a path that starts with / or contains ..
anywhere is refused.
Attaching at a path that’s already in use replaces that companion. The old one is removed before the new file is stored, so if a later step fails, the path can be left empty. The replacement gets a new id.
Any signed-in account can attach files to any asset that isn’t in the trash. Ownership, edit rights and the asset’s type aren’t checked yet. Attaching a file doesn’t re-render previews: the asset’s preview job uses its companions the next time it runs.
A missing or empty X-Companion-Path, or an id that isn’t a UUID,
gets a plain-text 400 before the request reaches this operation; a
path that is too long or not relative gets the JSON 400 below.
Storage and database failures get a plain-text 500, not the JSON
shown.
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 relative path the asset’s main file uses for this file, for
example textures/wood.png. Trimmed, then at most 512 bytes; it
can’t start with / or contain ... Stored exactly as sent.
The file’s media type, recorded as given and returned as
content_type. Defaults to application/octet-stream when absent
or empty. It isn’t checked against the bytes.
Request Body required
Section titled “Request Body required ”Responses
Section titled “ Responses ”The companion as stored.
A supporting file attached to an asset at a relative path, such as a texture a 3D model refers to.
object
The companion’s id, used to download or remove it. Replacing a companion gives it a new one.
The relative path the asset’s main file uses for this file, such as
character.mtl next to an OBJ or textures/wood.png in a
subfolder. Surrounding whitespace is trimmed and the rest is stored
as sent.
Example
textures/character-a.pngThe media type sent in X-Content-Type when the file was attached. It isn’t checked against the bytes.
Example
image/pngThe file’s size in bytes.
When the file was attached.
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