Concepts
Libraries, assets, and understanding.
A library isolates its assets. Searches only return assets within that library.
Libraries and assets
An asset has a stable asset_id. Its public_id names it in delivery URLs and may contain path segments. The asset_folder organizes assets; moving folders does not change public_id. Listing assets by asset_folder matches that level only, not its subfolders; an empty string is the root. The display_name is a label and does not determine delivery URLs. Audio uses resource_type=video and is_audio=true.
Library names are at most 64 characters and may repeat; libraries are identified by library_id. Updating an asset’s tags or context, or a library’s labels, replaces the whole value: what you send becomes the complete new content, and (or [] for tags) clears it.
A zero-byte upload returns 400 FILE_EMPTY. A file declared or detected as an image whose dimensions cannot be read (for example, a truncated file) returns 400 Invalid image file. Any other file is stored as raw.
Understanding
Understanding produces captions, tags, recognized image text, transcripts, and video-frame content. Segments include start and end times. Records are immutable; newer versions can supersede older records, excluded by default.
Overall states are pending, processing, ready, partial, and failed. Individual kinds use pending, running, ready, failed, unsupported, or skipped. Disabled understanding or unsupported content does not prevent original-file access.
Semantic search
Assets become searchable when semantic is ready. Default hybrid search combines keywords and semantics; semantic-only search is also available. Hits include matching content and millisecond timestamps for audio/video segments. Assets that have never completed understanding are excluded; an asset being reprocessed keeps its previous results in search until the new ones are ready.
Documents and other files (raw)
Raw files such as PDF and text are stored without understanding. Their semantic state is unavailable, they are not part of semantic search, and expression search can match only their metadata (public_id, display_name, tags, context, and so on). To search document text, use Knowledge.
Deletion and recovery
Deletion makes content immediately invisible. Libraries can be restored within 7 days; recovery is unavailable afterward. Individual assets have no restore endpoint.
File Library compared
File Library stores files. Media Library additionally organizes, understands, and searches content. Importing creates a copy. Later changes or deletion of either copy do not affect the other.