Skip to content

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.

id
required
string format: uuid

The asset’s id.

X-Companion-Path
required
string
>= 1 characters <= 512 characters

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.

X-Content-Type
string

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.

string format: binary

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
id
required

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

string format: uuid
asset_id
required
string format: uuid
path
required

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.

string
Example
textures/character-a.png
content_type
required

The media type sent in X-Content-Type when the file was attached. It isn’t checked against the bytes.

string
Example
image/png
size_bytes
required

The file’s size in bytes.

integer format: int64
created_at
required

When the file was attached.

string format: date-time

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