Skip to content

Check which companion files a model still needs

GET
/assets/{id}/companion-requirements

Reads an asset’s stored model file, lists the external files it refers to, and shows which of them are attached as companions and which are still missing.

Only glTF, GLB, FBX and OBJ files are read. For glTF and GLB that means buffer and image URIs, for FBX the file names of its textures and videos, and for OBJ only the .mtl material libraries on its mtllib lines. The textures an OBJ uses are named inside those .mtl files, which this operation never reads, not even after you attach them; that’s what partial marks.

status says how far it got. ok means the file was read. unsupported means another format, or no file at all, and says nothing about whether companions are needed. unreadable means a supported file that couldn’t be parsed, or whose stored bytes are missing, with the reason in detail. All three come back as 200, and only ok fills the lists.

A declared path counts as attached only when a companion exists at exactly that path, including case. Only the companion records are compared, not the stored files, so ok with an empty missing doesn’t prove the model will render. A companion at a path the model doesn’t name appears in neither list.

Nothing is attached or changed. The upload page uses this answer to pair files dropped with a model, then attaches them itself with POST /assets/{id}/companions.

Unlike the companion list, this needs read access to the asset’s content: the same check as GET /assets/{id}/file (sensitivity tier, then mature rating). A refusal gets the same 404 as an unknown or deleted asset. The parsed list is cached per stored file, failed parses included, while the attached and missing split is worked out on every request. An id that isn’t a UUID gets a plain-text 400, and a storage failure other than missing bytes a plain-text 500.

id
required
string format: uuid

The asset’s id.

What the model refers to and which of those files are attached, whatever the status.

The external files a stored model refers to, and which of them have a companion attached. Reading it changes nothing.

object
asset_id
required
string format: uuid
status
required

ok: the file was read and declared is its list (for OBJ, its .mtl libraries only; see partial). unsupported: a format this operation doesn’t read, or no file at all; this doesn’t mean the file needs nothing. unreadable: a supported file that couldn’t be parsed, or whose stored bytes are missing; detail says which.

string
Allowed values: ok unsupported unreadable
detail

Why the file couldn’t be read: the parser’s error message, or stored object missing for this asset. Sent only with unreadable.

string
partial
required

True for OBJ files: the list holds the .mtl libraries but not the textures named inside them, and attaching the .mtl files doesn’t change that. Always false with unsupported.

boolean
declared
required

The external files the parser found in the model (for OBJ, only its .mtl libraries; see partial), as relative paths with forward slashes, without duplicates. Embedded data, web addresses, absolute paths and paths that leave the model’s folder are left out of this check. Empty unless status is ok.

Array<string>
missing
required

The paths in declared with no companion at exactly that path. It’s empty whenever status isn’t ok, so check status and partial before reading an empty list as complete.

Array<string>
attached
required

The paths in declared that have a companion at exactly that path. A companion at a path the model doesn’t name appears in neither list.

Array<string>

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