Objects
Response shapes returned by the public API — Asset, Library, Tag, SearchHit, and related objects. Shared across REST, GraphQL, and MCP.
The objects below are the response shapes returned by the public API. REST, GraphQL, and MCP share the same wire shape for each — endpoint pages link here for the full definition. Any transport-specific exception is called out inline.
Asset
The core media object. Returned by GET /libraries/:libraryId/assets,
GET /search/assets, the GraphQL
assets and
searchAssets queries, and the
MCP list_assets / search_assets tools.
Prop
Type
Timestamps anywhere in the response are returned as unix milliseconds
(a number).
Detecting in-flight processing
Some Asset fields populate asynchronously after upload (the upload
response carries the permanent CDN url immediately; other fields fill
in once processing completes). Check for null on sizes,
blurhash, or width to detect "still processing" and re-read via
the assets endpoint.
GraphQL-only deprecated fields
The GraphQL Asset also carries thumbUrl and thumbHighUrl, both
deprecated. Each is derived from sizes — thumbUrl from the standard
size, thumbHighUrl from the largest — and falls back to url.
Prefer sizes (and blurhash for placeholders). REST and MCP return sizes.
Uploader
Attribution metadata for an uploaded asset.
Prop
Type
AssetMetadata
Everything read from an asset's own bytes, on Asset.metadata.
capture is shared across file types; the technical block beside it is specific
to one. null on assets uploaded before this data was captured.
Prop
Type
VideoStream
A video's technical stream details, on AssetMetadata.video.
Prop
Type
AssetCapture
How an asset was captured, on AssetMetadata.capture, read
from the container's metadata tags. Every field is independent: an asset carries
an arbitrary subset, so a screen recording has none of these and a phone clip has
all of them.
Prop
Type
latitude and longitude are always returned together. A coordinate whose
pair is missing is dropped rather than published.
codec and hasAudio are always present within the object. Read the object
itself for null to tell "not analyzed" from hasAudio: false, which means the
video was analyzed and has no audio track.
AssetVariant
Non-destructive variant of an asset (e.g. a crop or color adjustment).
Prop
Type
Library
A collection of assets within an organization. Returned by
GET /libraries and the GraphQL
libraries query.
Prop
Type
Tag
A tag and its usage count. Returned by
GET /libraries/:libraryId/tags
and the GraphQL tags query.
Prop
Type
SearchResult
The envelope returned by search operations. Returned by
GET /search/assets, the GraphQL
searchAssets query, and the
MCP search_assets tool.
Prop
Type
SearchHit
An Asset extended with search-result metadata. Every field on
Asset is present on SearchHit; the two additional fields below are
search-specific.
Prop
Type
duration and metadata are null on a search hit. Read the asset through
GET /libraries/:libraryId/assets
for those.
SearchHitHighlights
Matched-term snippets returned alongside each SearchHit. Optional. The
name snippet wraps matched terms in <mark> tags; the tags snippet
is the matched tag strings.
Prop
Type