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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The asset’s id.
Responses
Section titled “ Responses ”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
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.
Why the file couldn’t be read: the parser’s error message, or stored object missing for this asset. Sent only with unreadable.
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.
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.
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.
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.
Authentication 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