Skip to content

List an asset's companion files

GET
/assets/{id}/companions

Lists the companion files attached to an asset, sorted by path. A companion is a supporting file that the asset’s main file needs, such as a texture or .mtl material library for a 3D model, or the frame data for a sprite sheet.

Companions belong to the asset: they aren’t assets of their own, and they aren’t the variants the server generates (see GET /assets/{id}/variants/{variant}) or alternates, which are other versions of the asset itself. The 3D viewer reads this list before loading a model and serves each texture or other file the model asks for from the matching companion. Download one with GET /assets/{id}/companions/{companion_id}.

Any signed-in account can read the list for any asset that isn’t in the trash. The asset’s access rules aren’t checked, so the paths, types and sizes of files attached to a draft or restricted asset are visible too.

An unknown or deleted asset gets 404, unless the server still holds its list from an earlier request: lists are cached per asset, and deleting the asset doesn’t clear that cache. An id that isn’t a UUID gets a plain-text 400, and a database failure a plain-text 500.

id
required
string format: uuid

The asset’s id.

The companions, sorted by path. An empty array if there are none.

Array<object>

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

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