Searching Your Media

Search across all media in your organization using natural language queries. The search API uses AI-powered semantic search to find relevant content based on text descriptions, detected objects, and captions.

Endpoint

GET /api/search

Query Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query (natural language description)
`organizationId`	string	Yes	The unique identifier of your organization
`limit`	integer	No	Maximum number of results to return (default: 20)

Headers

Header	Value	Required
`x-api-key`	Your API key	Yes

Example Request

curl -H "x-api-key: YOUR_API_KEY" \
  "https://lab.coreviz.io/api/search?q=flower&organizationId=f4f635c4-779f-4e49-a85e-f45ccf7fbcf1"

Response

Status Code: 200 OK

Response Body:

{
  "results": [
    {
      "id": "20ef0254-6ef0-4baf-a2f7-e40df8b3a716",
      "timestamp": "0",
      "blob": "https://3vxmbaxifmu58irw.public.blob.vercel-storage.com/entities/bb59e55c-6786-4a72-93ca-4b958191abdb/media/b6b4bda5-2f71-4de0-8170-6ded7c46c48a/processed-Wgx2gmUiX4zmQxRI5tuxUJuzLdLdOd.jpg",
      "width": 1620,
      "height": 1080,
      "media": {
        "createdAt": "2025-10-03T06:52:08.780Z",
        "id": "b6b4bda5-2f71-4de0-8170-6ded7c46c48a",
        "name": "entities/bb59e55c-6786-4a72-93ca-4b958191abdb/media/2048x1365-Carols-pick-of-best-plants-for-colourful-containers-GettyImages-1185235271-0ee53ef.jpg",
        "type": "image",
        "blob": "https://3vxmbaxifmu58irw.public.blob.vercel-storage.com/entities/bb59e55c-6786-4a72-93ca-4b958191abdb/media/2048x1365-Carols-pick-of-best-plants-for-colourful-containers-GettyImages-1185235271-0ee53ef-5rZD4MHCjfenBsKHhZYvtQJjRPjn5f.jpg",
        "width": 2048,
        "height": 1365,
        "duration": null
      },
      "captions": [
        {
          "id": "25cf5f14-6d3d-45be-944f-a73d84a9d2f5",
          "text": "A close-up view of a cluster of purple flowers with light purple petals and darker purple veins. The flowers have white centers and are surrounded by green leaves. The image is slightly blurred, focusing on the flowers in the foreground."
        }
      ],
      "objects": [
        {
          "id": "67fa4cd2-4e3c-4501-b288-b3268c75bc4a",
          "type": "object",
          "label": "flower",
          "blob": "",
          "polygon": [
            { "x": 0.8100000023841858, "y": 0.5400000214576721 },
            { "x": 1619.1900634765625, "y": 0.5400000214576721 },
            { "x": 1619.1900634765625, "y": 1078.3800048828125 },
            { "x": 0.8100000023841858, "y": 1078.3800048828125 }
          ]
        }
      ],
      "rank": 0.243,
      "rankingMetrics": {
        "textRank": 0.087,
        "objectEmbeddingRank": 0.156,
        "totalRank": 0.243
      }
    }
  ],
  "query": "flower",
  "limit": 20,
  "totalResults": 20
}

Response Fields

Search Result Object

Field	Type	Description
`id`	string	Unique identifier for the frame result
`timestamp`	string	Timestamp within the video (or "0" for images)
`blob`	string	URL to the processed frame image
`width`	integer	Frame width in pixels
`height`	integer	Frame height in pixels
`media`	object	The parent media object (see Media Object below)
`captions`	array	Array of caption objects describing the frame
`objects`	array	Array of detected objects in the frame
`rank`	number	Overall relevance score (0-1, higher is more relevant)
`rankingMetrics`	object	Breakdown of ranking scores (see Ranking Metrics below)

Media Object

Field	Type	Description
`id`	string	Unique identifier for the media item
`name`	string	File path/name of the media
`type`	string	Media type: `image` or `video`
`blob`	string	URL to the original media file
`width`	integer	Original width in pixels
`height`	integer	Original height in pixels
`duration`	number \| null	Duration in seconds (for videos, null for images)
`createdAt`	string	ISO 8601 timestamp of creation

Caption Object

Field	Type	Description
`id`	string	Unique identifier for the caption
`text`	string	The caption text describing the content

Object Detection Object

Field	Type	Description
`id`	string	Unique identifier for the detected object
`type`	string	Object type: `object`, `face`, `frame`, `text`, etc.
`label`	string	The detected label (e.g., "flower", "person", "face")
`blob`	string	URL to cropped object image (if available, empty string otherwise)
`polygon`	array	Array of coordinate points defining the bounding box

Polygon Point Object

Field	Type	Description
`x`	number	X coordinate in pixels
`y`	number	Y coordinate in pixels

Ranking Metrics Object

Field	Type	Description
`textRank`	number	Relevance score based on text/caption matching (0-1)
`objectEmbeddingRank`	number	Relevance score based on object detection and embeddings (0-1)
`totalRank`	number	Combined relevance score (0-1, higher is more relevant)

Response Metadata

Field	Type	Description
`query`	string	The search query that was executed
`limit`	integer	Maximum number of results requested
`totalResults`	integer	Total number of results found

Error Responses

401 Unauthorized

Invalid or missing API key:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

400 Bad Request

Invalid query parameters:

{
  "error": "Bad Request",
  "message": "Invalid query parameters"
}

404 Not Found

Organization not found:

{
  "error": "Not Found",
  "message": "Organization not found"
}

Example Usage

JavaScript/TypeScript

const organizationId = 'f4f635c4-779f-4e49-a85e-f45ccf7fbcf1';
const apiKey = 'YOUR_API_KEY';
const query = 'flower';

const response = await fetch(
  `https://lab.coreviz.io/api/search?q=${encodeURIComponent(query)}&organizationId=${organizationId}`,
  {
    headers: {
      'x-api-key': apiKey,
    },
  }
);

const data = await response.json();
console.log(`Found ${data.totalResults} results for "${data.query}"`);
data.results.forEach((result, index) => {
  console.log(`Result ${index + 1}: ${result.media.name} (rank: ${result.rank})`);
});

Python

import requests

organization_id = 'f4f635c4-779f-4e49-a85e-f45ccf7fbcf1'
api_key = 'YOUR_API_KEY'
query = 'flower'

response = requests.get(
    'https://lab.coreviz.io/api/search',
    headers={'x-api-key': api_key},
    params={
        'q': query,
        'organizationId': organization_id,
        'limit': 20
    }
)

data = response.json()
print(f"Found {data['totalResults']} results for '{data['query']}'")
for idx, result in enumerate(data['results'], 1):
    print(f"Result {idx}: {result['media']['name']} (rank: {result['rank']})")

Search Tips

Effective Queries

The search API uses semantic search, meaning it understands the meaning of your query rather than just matching keywords:

Good Examples:

"red car in parking lot" - Descriptive and specific
"person wearing blue shirt" - Clear object and attribute
"sunset over mountains" - Scene description
"dog playing in water" - Action and subject

Less Effective:

"car" - Too generic
"image" - Not descriptive
"photo" - Too broad

Understanding Results

Ranking:

Results are sorted by relevance score (rank field)
Higher scores (closer to 1.0) indicate better matches
The rankingMetrics object shows how the score was calculated

Frame-Level Results:

Search returns frame-level results, not just media items
Each result includes the specific frame that matched
The media object contains information about the parent media item

Object Detection:

The objects array shows all detected objects in the frame
Objects with matching labels contribute to the relevance score
Polygon coordinates define bounding boxes for detected objects

Captions:

AI-generated captions describe the visual content
Caption text is used for text-based matching
Multiple captions may exist for a single frame

Notes

Search is performed across all datasets in the specified organization
Results are ranked by relevance, with the most relevant results first
The search combines multiple signals: text matching, object detection, and semantic embeddings
Frame-level results allow you to find specific moments within videos
Object detection polygons use pixel coordinates relative to the frame dimensions
The blob URLs in results are publicly accessible and can be used directly in your applications

Searching Your Media

On this page