Media

The sdk.media namespace covers all operations on individual media items — browsing collections, semantic search, metadata management, and uploading new files.

`sdk.media.browse(collectionId, options?)`

List media items and folders inside a collection. Supports folder navigation, filtering, and pagination.

Parameters:

Parameter	Type	Required	Description
`collectionId`	string	Yes	The collection to browse
`options.path`	string	No	ltree path to list (e.g. `"collectionId.folderId"`). Defaults to collection root
`options.limit`	number	No	Max items to return (default: 20)
`options.offset`	number	No	Pagination offset
`options.type`	string	No	Filter: `"image"`, `"video"`, `"folder"`, or `"all"`
`options.dateFrom`	string	No	Filter from date (`YYYY-MM-DD`)
`options.dateTo`	string	No	Filter to date (`YYYY-MM-DD`)
`options.sortBy`	string	No	Sort field: `name`, `createdAt`, `type`
`options.sortDirection`	string	No	`"asc"` or `"desc"`
`options.tagFilters`	object	No	Filter by tags: `{ color: ['red', 'blue'] }`

Returns: Promise<BrowseResult>

// List root of a collection
const { media, pagination } = await sdk.media.browse('abc123');

// Navigate a subfolder
const { media } = await sdk.media.browse('abc123', {
  path: 'abc123.folder456',
  limit: 50,
  type: 'image',
});

// Filter by tags
const { media } = await sdk.media.browse('abc123', {
  tagFilters: { category: ['product'], season: ['spring'] },
});

BrowseResult

{
  media: Media[];
  pagination: {
    total: number;
    limit: number;
    offset: number;
    hasMore: boolean;
  };
}

Folder paths

Folder paths in CoreViz use the ltree format: collectionId.folderId.subFolderId. You can get these paths from the path field on items returned by browse().

`sdk.media.search(query, options?)`

Semantically search across all media in the organization using natural language. Powered by CLIP embeddings + text ranking.

Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	Natural language search query
`options.limit`	number	No	Max results (default: 20)

Returns: Promise<SearchResult[]>

const results = await sdk.media.search('red shoes on white background', { limit: 10 });

for (const r of results) {
  console.log(r.mediaName, r.blobUrl, r.rank);
  // r.objects — detected objects in the media
  // r.caption — AI-generated caption
}

SearchResult

Field	Type	Description
`mediaId`	string	Media item ID
`mediaName`	string	File name
`mediaType`	string	`"image"` or `"video"`
`blobUrl`	string	Public URL to the media
`objects`	MediaObject[]	Detected objects
`rank`	number	Relevance score
`caption`	string \| undefined	AI-generated caption

`sdk.media.get(mediaId)`

Fetch full details for a single media item, including tags, detected objects, frames, and version info.

Returns: Promise<Media>

const item = await sdk.media.get('mediaId123');

console.log(item.blob);          // Public URL
console.log(item.metadata?.tags); // { color: ['red'], category: ['product'] }
console.log(item.frames);        // Frame objects with objects[] and captions[]
console.log(item.width, item.height);

Media Object

Field	Type	Description
`id`	string	Unique media ID
`name`	string	File name
`type`	string	`"image"`, `"video"`, or `"folder"`
`blob`	string \| null	Public URL
`path`	string	ltree path
`width`	number \| undefined	Width in pixels
`height`	number \| undefined	Height in pixels
`sizeBytes`	number \| undefined	File size in bytes
`metadata`	object \| undefined	Tags, moderation, and custom metadata
`frames`	MediaFrame[] \| undefined	Processed frames with objects and captions
`createdAt`	string \| undefined	ISO 8601 creation timestamp

`sdk.media.rename(mediaId, name)`

Rename a media item.

Returns: Promise<Media>

const updated = await sdk.media.rename('mediaId123', 'hero-shot-final.jpg');

`sdk.media.move(mediaId, destinationPath)`

Move a media item or folder to a different location within the same collection.

Parameters:

Parameter	Type	Description
`mediaId`	string	ID of the item to move
`destinationPath`	string	ltree path of the destination folder

Returns: Promise<{ id: string; newPath: string }>

const result = await sdk.media.move('mediaId123', 'collectionId.archiveFolder');
console.log(result.newPath); // 'collectionId.archiveFolder.mediaId123'

Always use real paths

Never construct ltree paths manually. Use the path field from browse() results to ensure paths are accurate.

`sdk.media.addTag(mediaId, label, value)` / `removeTag(...)`

Add or remove a tag from a media item. Tags are organized as label (group) and value pairs.

// Add a tag
await sdk.media.addTag('mediaId123', 'color', 'red');
await sdk.media.addTag('mediaId123', 'category', 'product');

// Remove a tag
await sdk.media.removeTag('mediaId123', 'color', 'red');

Each media item can have multiple values per label (e.g., color: ['red', 'blue']). Adding a duplicate value returns a 409 conflict.

`sdk.media.findSimilar(collectionId, objectId, options?)`

Find media items visually similar to a specific detected object. Uses the object's embedding to rank results.

Parameters:

Parameter	Type	Required	Description
`collectionId`	string	Yes	Collection to search within
`objectId`	string	Yes	ID of a detected object (from `media.get()` frames or `search()` results)
`options.limit`	number	No	Max results to return
`options.model`	string	No	Similarity model: `"faces"`, `"objects"`, `"shoeprints"`

Returns: Promise<BrowseResult>

// First, get an object ID from a media item
const item = await sdk.media.get('mediaId123');
const objectId = item.frames?.[0]?.objects?.[0]?.id;

// Find similar items
const { media } = await sdk.media.findSimilar('collectionId', objectId, {
  limit: 20,
  model: 'faces',
});

`sdk.media.upload(file, options)`

Upload a photo or video file to a collection. Supports Node.js file paths, browser File objects, and Blob.

Parameters:

Parameter	Type	Required	Description
`file`	string \| File \| Blob	Yes	File path (Node.js), File, or Blob
`options.collectionId`	string	Yes	Target collection
`options.path`	string	No	Target folder path (e.g. `"collectionId.folderId"`). Defaults to collection root
`options.name`	string	No	Custom file name in CoreViz

Returns: Promise<UploadResult>

// Node.js — local file path
const result = await sdk.media.upload('/path/to/photo.jpg', {
  collectionId: 'abc123',
  path: 'abc123.campaignFolder',
  name: 'hero-shot.jpg',
});
console.log(result.mediaId, result.url);

// Browser — File input
const result = await sdk.media.upload(event.target.files[0], {
  collectionId: 'abc123',
});

UploadResult

Field	Type	Description
`mediaId`	string	ID of the newly created media item
`url`	string	Public blob URL (null if blocked by moderation)
`message`	string	Status message

Supported formats: JPEG, PNG, GIF, WebP, HEIC

React Native

File path strings are not supported on React Native / Expo. Pass a File or Blob object instead.

Next Steps

Collections: List and create collections
Folders & Tags: Create folders and aggregate tag groups
MCP Server: Use all of these from Claude Code via MCP

Media

On this page