Objects
Response shapes returned by the public API, including Asset, Library, Tag, SearchHit, and related objects. Shared across REST and MCP.
The objects below are the response shapes returned by the public API. REST and MCP share the same wire shape for each, and endpoint pages link here for the full definition.
Asset
The core media object. Returned by GET /libraries/:libraryId/assets,
GET /search/assets, 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, and other fields fill in once
processing completes. A null in sizes, blurhash, or width means the
asset is still processing; re-read it from the assets endpoint.
Uploader
Attribution metadata for an uploaded asset.
Prop
Type
Approval
An asset's approval, on Asset.approval. Set it with
PATCH …/assets/:assetId/approval
or the MCP set_asset_approval tool.
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. Each field is independent, and an asset
carries any subset of them: a screen recording has none, 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.
Prop
Type
Tag
A tag and its usage count. Returned by
GET /libraries/:libraryId/tags.
Prop
Type
SearchResult
The envelope returned by search operations. Returned by
GET /search/assets 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
variants is null on a search hit. Read the asset through
GET /libraries/:libraryId/assets
for its variants.
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