Browse & Search Media

A single endpoint handles both browsing (listing folders and media) and semantic search within a collection. The mode is determined by which query parameters you provide.

Endpoint

GET /api/dataset/{collectionId}/media

Authentication

Accepts x-api-key header or Authorization: Bearer token. See Getting Started for details.

Path Parameters

Parameter	Type	Description
`collectionId`	string	UUID (hyphens stripped) of the collection

Query Parameters

Browse / Filter Parameters

Parameter	Type	Default	Description
`path`	string	collection root	ltree path to list (e.g. `collectionId.folderId`). One level deep by default
`recursive`	boolean	`false`	If `true`, returns all descendants instead of one level
`limit`	integer	`10`	Max items per page
`offset`	integer	`0`	Pagination offset
`type`	string	`all`	Filter by type: `image`, `video`, `folder`, or `all`
`dateFrom`	string	—	Filter from date (`YYYY-MM-DD`, inclusive)
`dateTo`	string	—	Filter to date (`YYYY-MM-DD`, inclusive)
`sortBy`	string	`createdAt`	Sort field: `name`, `createdAt`, `type`, `description`, `prompt`
`sortDirection`	string	`desc`	`asc` or `desc`
`tags`	string	—	Comma-separated tag values (legacy flat filter)
`tagFilters`	JSON	—	Per-group filter: `{"color":["red","blue"],"season":["spring"]}`. AND between groups, OR within a group
`mediaId`	string	—	Return only the specific media item with this ID
`clusterId`	string	—	Filter to items whose objects belong to this cluster

Search / Similarity Parameters

When either q or similarToObjectId is provided, the endpoint switches to scored mode — results are ranked by relevance and include _score.

Parameter	Type	Description
`q`	string	Natural language search query (uses CLIP + text ranking)
`similarToObjectId`	string	Object ID to use as embedding query (finds visually similar items)
`similarToObjectModel`	string	Embedding model for similarity: `faces`, `objects`, `shoeprints`
`minScore`	number	Minimum relevance score to include (default: `0.05`)

Example Requests

Browse collection root

curl -H "x-api-key: YOUR_API_KEY" \
  "https://lab.coreviz.io/api/dataset/COLLECTION_ID/media?limit=20&sortDirection=desc"

Navigate a subfolder

curl -H "x-api-key: YOUR_API_KEY" \
  "https://lab.coreviz.io/api/dataset/COLLECTION_ID/media?path=COLLECTION_ID.FOLDER_ID&limit=50"

Semantic search

curl -H "x-api-key: YOUR_API_KEY" \
  "https://lab.coreviz.io/api/dataset/COLLECTION_ID/media?q=red+shoes+on+white+background&limit=20"

Filter by tags

curl -H "x-api-key: YOUR_API_KEY" \
  "https://lab.coreviz.io/api/dataset/COLLECTION_ID/media?tagFilters=%7B%22color%22%3A%5B%22red%22%5D%7D"

Find visually similar items

curl -H "x-api-key: YOUR_API_KEY" \
  "https://lab.coreviz.io/api/dataset/COLLECTION_ID/media?similarToObjectId=OBJECT_ID&limit=10"

Response

Status Code: 200 OK

{
  "media": [
    {
      "id": "abc123def456",
      "name": "hero-shot.jpg",
      "type": "image",
      "blob": "https://blob.vercel-storage.com/.../hero-shot.jpg",
      "path": "collectionId.folderId.abc123def456",
      "datasetId": "collectionId",
      "width": 2400,
      "height": 1600,
      "duration": null,
      "sizeBytes": 184320,
      "createdAt": "2026-03-10T14:22:00.000Z",
      "updatedAt": "2026-03-10T14:22:00.000Z",
      "status": "active",
      "metadata": {
        "tags": {
          "color": ["red"],
          "category": ["product"]
        }
      },
      "totalVersions": 1,
      "frameObjectId": "frameObjId123",
      "folderItemCount": null,
      "folderPreviews": null,
      "frames": [
        {
          "id": "frameId123",
          "timestamp": "0",
          "blob": "https://blob.vercel-storage.com/.../processed.jpg",
          "width": 2400,
          "height": 1600,
          "objects": [
            {
              "id": "objectId456",
              "type": "object",
              "label": "shoe",
              "blob": ""
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "total": 142,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Scored mode extra fields

In search or similarity mode, each item additionally includes:

Field	Type	Description
`_score`	number	Combined relevance score (text + embedding)
`_matchingFrames`	array	Frame-level match highlights (reserved for future use)

Folder items

Folders (type: "folder") include two extra fields:

Field	Type	Description
`folderItemCount`	integer	Total image/video count under this folder
`folderPreviews`	string[] \| null	Up to 3 preview blob URLs from the folder's contents

Response Fields

Media Object

Field	Type	Description
`id`	string	UUID without hyphens
`name`	string	File name
`type`	string	`"image"`, `"video"`, or `"folder"`
`blob`	string	Public URL to the file (or `"folder"` for folders)
`path`	string	ltree path
`datasetId`	string	Parent collection ID
`width`	integer \| null	Width in pixels
`height`	integer \| null	Height in pixels
`duration`	number \| null	Duration in seconds (videos only)
`sizeBytes`	integer	File size in bytes
`createdAt`	string	ISO 8601 timestamp
`metadata`	object	JSONB metadata including `tags`, `description`, `moderation`
`totalVersions`	integer	Version count (1 for originals)
`frames`	Frame[]	Processed frames with detected objects

Error Responses

Status	Description
`400`	Invalid parameters (e.g. bad date format, malformed `tagFilters`)
`401`	Missing or invalid authentication
`403`	Authenticated but no access to this collection
`404`	Collection not found
`500`	Internal server error

JavaScript Example

const collectionId = 'COLLECTION_ID';
const apiKey = 'YOUR_API_KEY';

// Browse
const { media, pagination } = await fetch(
  `https://lab.coreviz.io/api/dataset/${collectionId}/media?limit=20`,
  { headers: { 'x-api-key': apiKey } }
).then(r => r.json());

// Semantic search
const { media: results } = await fetch(
  `https://lab.coreviz.io/api/dataset/${collectionId}/media?q=${encodeURIComponent('red shoes')}&limit=10`,
  { headers: { 'x-api-key': apiKey } }
).then(r => r.json());

Python Example

import requests, json

api_key = 'YOUR_API_KEY'
collection_id = 'COLLECTION_ID'
headers = {'x-api-key': api_key}

# Browse with tag filter
response = requests.get(
    f'https://lab.coreviz.io/api/dataset/{collection_id}/media',
    headers=headers,
    params={
        'limit': 20,
        'tagFilters': json.dumps({'category': ['product']}),
    }
)
data = response.json()

Browse & Search Media

On this page