From d11a6767143a45735be432830a3ff88ce0b357c4 Mon Sep 17 00:00:00 2001
From: Om Gate <om@videodb.io>
Date: Thu, 23 Jul 2026 14:23:29 +0530
Subject: [PATCH 1/5] feat: indexing v2

---
 src/constants.ts                |  60 +++
 src/core/collection.ts          | 491 +++++++++++++++++++++--
 src/core/connection.ts          | 158 ++++++++
 src/core/editor.ts              |  35 ++
 src/core/indexManifest.ts       | 330 +++++++++++++++
 src/core/job.ts                 | 179 +++++++++
 src/core/rtstream.ts            | 683 +++++++++++++++++++++++++++++++-
 src/core/sandbox.ts             | 156 ++++++++
 src/core/sandboxModels.ts       |  27 ++
 src/core/scene.ts               |   8 +-
 src/core/search/responses.ts    | 127 ++++++
 src/core/search/searchResult.ts |  54 ++-
 src/core/shot.ts                |  36 +-
 src/core/timeline.ts            |  37 +-
 src/core/understanding.ts       | 406 +++++++++++++++++++
 src/core/video.ts               | 602 +++++++++++++++++++++++++++-
 src/core/voiceClone.ts          |  93 +++++
 src/index.ts                    |  49 ++-
 src/interfaces/core.ts          |   6 +-
 src/types/config.ts             |   1 +
 src/types/response.ts           |   1 +
 src/utils/error.ts              |  27 +-
 src/utils/httpClient.ts         | 110 +++--
 src/utils/index.ts              | 111 ++++--
 src/utils/upload.ts             |  37 ++
 25 files changed, 3691 insertions(+), 133 deletions(-)
 create mode 100644 src/core/indexManifest.ts
 create mode 100644 src/core/job.ts
 create mode 100644 src/core/sandbox.ts
 create mode 100644 src/core/sandboxModels.ts
 create mode 100644 src/core/search/responses.ts
 create mode 100644 src/core/understanding.ts
 create mode 100644 src/core/voiceClone.ts

diff --git a/src/constants.ts b/src/constants.ts
index 28c33ef..545ee06 100644
--- a/src/constants.ts
+++ b/src/constants.ts
@@ -70,12 +70,68 @@ export const ApiPath = {
   start: 'start',
   stop: 'stop',
   export: 'export',
+  // indexing-v2 additions
+  indexes: 'indexes',
+  records: 'records',
+  understand: 'understand',
+  ask: 'ask',
+  semantic_search: 'semantic-search',
+  query: 'query',
+  aggregate: 'aggregate',
+  job: 'job',
+  sandbox: 'sandbox',
+  voice_clone: 'voice_clone',
+  identities: 'identities',
+  merge: 'merge',
+  split: 'split',
+  async_response: 'async-response',
+} as const;
+
+/**
+ * Retrieval capabilities an index can be built for (the `use_for` values).
+ */
+export const IndexCapability = {
+  semantic: 'semantic',
+  query: 'query',
+  aggregate: 'aggregate',
+} as const;
+
+/**
+ * Field groups that map artifact fields to retrieval capabilities.
+ */
+export const FieldGroup = {
+  semantic: 'semantic',
+  fts: 'fts',
+  filter: 'filter',
+  aggregate: 'aggregate',
+  sort: 'sort',
+} as const;
+
+/**
+ * Compute tier a sandbox can be provisioned at.
+ */
+export const SandboxTier = {
+  small: 'small',
+  medium: 'medium',
+} as const;
+
+/**
+ * Lifecycle status of a sandbox.
+ */
+export const SandboxStatus = {
+  provisioning: 'provisioning',
+  active: 'active',
+  stopping: 'stopping',
+  stopped: 'stopped',
+  failed: 'failed',
+  alert: 'alert',
 } as const;
 
 export const ResponseStatus = {
   processing: 'processing',
   in_progress: 'in progress',
   success: 'success',
+  complete: 'complete',
 } as const;
 
 export const MeetingStatus = {
@@ -190,6 +246,10 @@ export const HttpClientDefaultValues = {
   max_retries: 3,
   timeout: 60 * 1000,
   backoff_factor: 0.1,
+  /** Max time (ms) to poll an async output URL before timing out. */
+  maxPollTime: 500 * 1000,
+  /** Interval (ms) between polls of an async output URL. */
+  pollInterval: 5 * 1000,
 } as const;
 
 export const MaxSupported = {
diff --git a/src/core/collection.ts b/src/core/collection.ts
index ea9bcef..b154e9e 100644
--- a/src/core/collection.ts
+++ b/src/core/collection.ts
@@ -25,8 +25,9 @@ import type {
   AudioResponse,
   ImageResponse,
 } from '@/types/response';
+import type { SearchResponse as SearchApiResponse } from '@/types/response';
 import { HttpClient } from '@/utils/httpClient';
-import { uploadToServer } from '@/utils/upload';
+import { uploadToServer, uploadBytes } from '@/utils/upload';
 import {
   DefaultSearchType,
   DefaultIndexType,
@@ -34,14 +35,25 @@ import {
 } from '@/core/config';
 import { SearchFactory } from './search';
 import { SearchResult } from './search/searchResult';
+import {
+  AskResponse,
+  SearchResponse,
+  warnLegacySearchOnce,
+  type AskResponseData,
+  type SearchResponseData,
+} from './search/responses';
 import { Video } from './video';
 import { Audio } from './audio';
 import { Image } from './image';
 import { Meeting } from './meeting';
 import { CaptureSession } from './captureSession';
 import { RTStream, RTStreamSearchResult, RTStreamShot } from './rtstream';
+import { GenerationJob, type JobData } from './job';
+import { VoiceClone, type VoiceCloneBase } from './voiceClone';
 import { VideodbError } from '@/utils/error';
 
+const MAX_GENERATE_TEXT_PAYLOAD_SIZE = 250 * 1024;
+
 const {
   video,
   audio,
@@ -55,8 +67,46 @@ const {
   title,
   meeting,
   record,
+  ask,
+  semantic_search,
+  query: queryPath,
+  aggregate,
+  voice_clone,
 } = ApiPath;
 
+/**
+ * Options for {@link Collection.search}. Combines new-style (v2) params with
+ * legacy-shaped params; passing any legacy param (or `namespace: "rtstream"`)
+ * routes the call to {@link Collection.legacySearch}.
+ */
+export interface CollectionSearchOptions {
+  // legacy-shaped
+  searchType?: SearchType;
+  indexType?: IndexType;
+  resultThreshold?: number;
+  scoreThreshold?: number;
+  dynamicScorePercentage?: number;
+  filter?: Array<Record<string, unknown>>;
+  sortDocsOn?: string;
+  namespace?: string;
+  sceneIndexId?: string;
+  indexId?: string;
+  algorithm?: string;
+  // new (v2)
+  topK?: number;
+  mode?: string;
+  returnFields?: unknown[] | Record<string, unknown> | string;
+  includeClip?: boolean;
+  sessionId?: string;
+  config?: Record<string, unknown>;
+  // unsupported in search()
+  indexName?: string;
+  indexNames?: string[] | string;
+  indexIds?: string[] | string;
+  // internal — rejected
+  deepsearchConfig?: unknown;
+}
+
 /**
  * The base VideoDB class
  * @remarks
@@ -243,7 +293,227 @@ export class Collection implements ICollection {
    * @param sceneIndexId - [optional] Filter by specific scene index
    * @returns SearchResult or RTStreamSearchResult object
    */
+  /**
+   * Search this collection.
+   *
+   * New search is used by default. Calls that pass legacy-shaped parameters
+   * (or `namespace: "rtstream"`) are routed to {@link legacySearch} with a
+   * one-time warning.
+   * @param query - Search query
+   * @param options - Search options (new-style or legacy-shaped)
+   */
   public search = async (
+    query: string,
+    options: CollectionSearchOptions = {}
+  ): Promise<SearchResponse | SearchResult | RTStreamSearchResult> => {
+    const oldParams: (keyof CollectionSearchOptions)[] = [
+      'searchType',
+      'indexType',
+      'resultThreshold',
+      'dynamicScorePercentage',
+      'sceneIndexId',
+      'indexId',
+      'algorithm',
+      'sortDocsOn',
+      'namespace',
+    ];
+    const newParams: (keyof CollectionSearchOptions)[] = [
+      'topK',
+      'mode',
+      'returnFields',
+      'includeClip',
+      'sessionId',
+      'config',
+    ];
+    const unsupported: (keyof CollectionSearchOptions)[] = [
+      'indexName',
+      'indexNames',
+      'indexId',
+      'indexIds',
+    ];
+
+    const hasOld = oldParams.some(
+      k => options[k] !== undefined && options[k] !== null
+    );
+    const hasNew = newParams.some(
+      k => options[k] !== undefined && options[k] !== null
+    );
+    const hasUnsupported = unsupported.some(
+      k => options[k] !== undefined && options[k] !== null
+    );
+
+    if (options.deepsearchConfig != null) {
+      throw new VideodbError(
+        'deepsearchConfig is internal and cannot be passed to search().'
+      );
+    }
+    if (hasOld && (hasNew || hasUnsupported)) {
+      throw new VideodbError(
+        'Cannot mix legacy search params with new search params. ' +
+          'Use search(...) for new search or legacySearch(...) for legacy search.'
+      );
+    }
+    if (hasUnsupported) {
+      throw new VideodbError(
+        'indexName/indexNames/indexId/indexIds are not supported in search(). ' +
+          'Use semanticSearch(), query(), or aggregate() for index-specific calls.'
+      );
+    }
+
+    if (hasOld) {
+      warnLegacySearchOnce();
+      return this.legacySearch(
+        query,
+        options.searchType,
+        options.indexType,
+        options.resultThreshold,
+        options.scoreThreshold,
+        options.dynamicScorePercentage,
+        options.filter,
+        options.sortDocsOn,
+        options.namespace,
+        options.sceneIndexId
+      );
+    }
+
+    return this.#newSearch(query, options);
+  };
+
+  #newSearch = async (
+    query: string,
+    options: CollectionSearchOptions
+  ): Promise<SearchResponse> => {
+    const payload: Record<string, unknown> = { query };
+    if (options.topK != null) payload.top_k = options.topK;
+    if (options.mode != null) payload.mode = options.mode;
+    if (options.returnFields != null)
+      payload.return_fields = options.returnFields;
+    if (options.includeClip != null) payload.include_clip = options.includeClip;
+    if (options.sessionId != null) payload.session_id = options.sessionId;
+    if (options.config != null) payload.config = options.config;
+    const res = await this.#vhttp.post<Record<string, unknown>, typeof payload>(
+      [collection, this.id, search, 'v2'],
+      payload
+    );
+    return new SearchResponse(this.#vhttp, res.data as SearchResponseData);
+  };
+
+  /**
+   * Ask a question and get an answer generated from retrieved collection context.
+   */
+  public ask = async (
+    question: string,
+    topK: number = 15,
+    mode: string = 'default',
+    includeSources: boolean = false
+  ): Promise<AskResponse> => {
+    const res = await this.#vhttp.post<Record<string, unknown>, object>(
+      [collection, this.id, ask],
+      { question, top_k: topK, mode, include_sources: includeSources }
+    );
+    return new AskResponse(this.#vhttp, res.data as AskResponseData);
+  };
+
+  /** Semantic search across one or more indexes in this collection. */
+  public semanticSearch = async (
+    query: string,
+    options: {
+      indexNames?: string[] | string;
+      topK?: number;
+      scoreThreshold?: number;
+      filter?: unknown[] | Record<string, unknown>;
+      returnFields?: unknown[] | Record<string, unknown> | string;
+      indexIds?: string[] | string;
+    } = {}
+  ): Promise<SearchResult> => {
+    const res = await this.#vhttp.post<SearchApiResponse, object>(
+      [collection, this.id, semantic_search],
+      {
+        query,
+        index_names: options.indexNames,
+        index_ids: options.indexIds,
+        top_k: options.topK ?? 10,
+        score_threshold: options.scoreThreshold,
+        filter: options.filter,
+        return_fields: options.returnFields,
+      }
+    );
+    return new SearchResult(this.#vhttp, res.data);
+  };
+
+  /** Structured query against an index in this collection. */
+  public query = async (
+    options: {
+      indexName?: string;
+      filter?: unknown[] | Record<string, unknown>;
+      limit?: number;
+      returnFields?: unknown[] | Record<string, unknown> | string;
+      sort?: string | [string, string][];
+      indexId?: string;
+    } = {}
+  ): Promise<SearchResult> => {
+    const res = await this.#vhttp.post<SearchApiResponse, object>(
+      [collection, this.id, queryPath],
+      {
+        index_name: options.indexName,
+        index_id: options.indexId,
+        filter: options.filter,
+        limit: options.limit ?? 100,
+        return_fields: options.returnFields,
+        sort: options.sort,
+      }
+    );
+    return new SearchResult(this.#vhttp, res.data);
+  };
+
+  /** Aggregate over an index in this collection. */
+  public aggregate = async (
+    options: {
+      indexName?: string;
+      filter?: unknown[] | Record<string, unknown>;
+      groupBy?: string;
+      metric?: string;
+      limit?: number;
+      sort?: string | [string, string][];
+      indexId?: string;
+    } = {}
+  ): Promise<Record<string, unknown> | Record<string, unknown>[]> => {
+    // convert:false — aggregate buckets are keyed by user field names/values.
+    const res = await this.#vhttp.post<
+      Record<string, unknown> | Record<string, unknown>[],
+      object
+    >(
+      [collection, this.id, aggregate],
+      {
+        index_name: options.indexName,
+        index_id: options.indexId,
+        filter: options.filter,
+        group_by: options.groupBy,
+        metric: options.metric ?? 'count',
+        limit: options.limit ?? 100,
+        sort: options.sort,
+      },
+      undefined,
+      { convert: false }
+    );
+    return res.data;
+  };
+
+  /**
+   * Legacy search (pre-v2), including RTStream namespace search.
+   * @param query - Search query
+   * @param searchType - [optional] Type of search to be performed
+   * @param indexType - [optional] Index Type
+   * @param resultThreshold - [optional] Result Threshold
+   * @param scoreThreshold - [optional] Score Threshold
+   * @param dynamicScorePercentage - [optional] Percentage of dynamic score to consider
+   * @param filter - [optional] Additional metadata filters
+   * @param sortDocsOn - [optional] Sort docs within each video by "score" or "start"
+   * @param namespace - [optional] Search namespace ("rtstream" to search RTStreams)
+   * @param sceneIndexId - [optional] Filter by specific scene index
+   * @returns SearchResult or RTStreamSearchResult object
+   */
+  public legacySearch = async (
     query: string,
     searchType?: SearchType,
     indexType?: IndexType,
@@ -259,7 +529,8 @@ export class Collection implements ICollection {
     if (namespace === 'rtstream') {
       const data: Record<string, unknown> = { query };
       if (sceneIndexId !== undefined) data.scene_index_id = sceneIndexId;
-      if (resultThreshold !== undefined) data.result_threshold = resultThreshold;
+      if (resultThreshold !== undefined)
+        data.result_threshold = resultThreshold;
       if (scoreThreshold !== undefined) data.score_threshold = scoreThreshold;
       if (dynamicScorePercentage !== undefined)
         data.dynamic_score_percentage = dynamicScorePercentage;
@@ -414,15 +685,41 @@ export class Collection implements ICollection {
   public generateImage = async (
     prompt: string,
     aspectRatio: '1:1' | '9:16' | '16:9' | '4:3' | '3:4' = '1:1',
-    callbackUrl?: string
-  ): Promise<Image | undefined> => {
-    const res = await this.#vhttp.post<ImageBase, object>(
+    callbackUrl?: string,
+    options: {
+      modelName?: string;
+      config?: Record<string, unknown>;
+      sandboxId?: string;
+      wait?: boolean;
+      pollInterval?: number;
+      timeout?: number;
+    } = {}
+  ): Promise<Image | GenerationJob | JobData | undefined> => {
+    const body: Record<string, unknown> = {
+      prompt,
+      aspect_ratio: aspectRatio,
+      callback_url: callbackUrl,
+    };
+    if (options.modelName != null) body.model_name = options.modelName;
+    if (options.config != null) body.config = options.config;
+    if (options.sandboxId != null) body.sandbox_id = options.sandboxId;
+
+    const res = await this.#vhttp.post<JobData, typeof body>(
       [collection, this.id, generate, image],
-      { prompt, aspect_ratio: aspectRatio, callback_url: callbackUrl }
+      body
     );
-    if (res.data) {
-      return new Image(this.#vhttp, res.data);
+    const data = res.data;
+    if (!data) return undefined;
+    if (data.jobId || data.job_id) {
+      const job = GenerationJob.fromData(this.#vhttp, data, 'image');
+      return options.wait
+        ? ((await job.wait(
+            options.timeout ?? 600,
+            options.pollInterval ?? 5
+          )) as Image | JobData)
+        : job;
     }
+    return new Image(this.#vhttp, data as unknown as ImageBase);
   };
 
   /**
@@ -462,7 +759,13 @@ export class Collection implements ICollection {
   ): Promise<Audio | undefined> => {
     const res = await this.#vhttp.post<AudioBase, object>(
       [collection, this.id, generate, audio],
-      { prompt, duration, audio_type: 'sound_effect', config, callback_url: callbackUrl }
+      {
+        prompt,
+        duration,
+        audio_type: 'sound_effect',
+        config,
+        callback_url: callbackUrl,
+      }
     );
     if (res.data) {
       return new Audio(this.#vhttp, res.data);
@@ -481,15 +784,53 @@ export class Collection implements ICollection {
     textContent: string,
     voiceName: string = 'Default',
     config: Record<string, unknown> = {},
-    callbackUrl?: string
-  ): Promise<Audio | undefined> => {
-    const res = await this.#vhttp.post<AudioBase, object>(
+    callbackUrl?: string,
+    options: {
+      modelName?: string;
+      sandboxId?: string;
+      voiceCloneId?: string;
+      cloneVoiceId?: string;
+      wait?: boolean;
+      pollInterval?: number;
+      timeout?: number;
+    } = {}
+  ): Promise<Audio | GenerationJob | JobData | undefined> => {
+    if (
+      options.voiceCloneId != null &&
+      options.cloneVoiceId != null &&
+      options.voiceCloneId !== options.cloneVoiceId
+    ) {
+      throw new VideodbError(
+        'voiceCloneId and cloneVoiceId must match when both are provided'
+      );
+    }
+    const resolvedVoiceCloneId = options.voiceCloneId ?? options.cloneVoiceId;
+
+    const res = await this.#vhttp.post<JobData, object>(
       [collection, this.id, generate, audio],
-      { text: textContent, audio_type: 'voice', voice_name: voiceName, config, callback_url: callbackUrl }
+      {
+        text: textContent,
+        audio_type: 'voice',
+        voice_name: voiceName,
+        model_name: options.modelName ?? 'elevenlabs',
+        config,
+        callback_url: callbackUrl,
+        sandbox_id: options.sandboxId,
+        voice_clone_id: resolvedVoiceCloneId,
+      }
     );
-    if (res.data) {
-      return new Audio(this.#vhttp, res.data);
+    const data = res.data;
+    if (!data) return undefined;
+    if (data.jobId || data.job_id) {
+      const job = GenerationJob.fromData(this.#vhttp, data, 'audio');
+      return options.wait
+        ? ((await job.wait(
+            options.timeout ?? 600,
+            options.pollInterval ?? 5
+          )) as Audio | JobData)
+        : job;
     }
+    return new Audio(this.#vhttp, data as unknown as AudioBase);
   };
 
   /**
@@ -522,20 +863,102 @@ export class Collection implements ICollection {
    */
   public generateText = async (
     prompt: string,
-    modelName: 'basic' | 'pro' | 'ultra' = 'basic',
-    responseType: 'text' | 'json' = 'text'
+    modelName: string = 'basic',
+    responseType: 'text' | 'json' = 'text',
+    options: {
+      wait?: boolean;
+      callbackUrl?: string;
+      sandboxId?: string;
+      maxTokens?: number;
+      temperature?: number;
+      modelConfig?: Record<string, unknown>;
+    } = {}
   ): Promise<string | Record<string, unknown>> => {
-    const res = await this.#vhttp.post<
-      string | Record<string, unknown>,
-      object
-    >([collection, this.id, generate, text], {
+    const wait = options.wait ?? true;
+    const payload: Record<string, unknown> = {
       prompt,
       model_name: modelName,
       response_type: responseType,
-    });
+      callback_url: options.callbackUrl,
+      sandbox_id: options.sandboxId,
+      max_tokens: options.maxTokens,
+      temperature: options.temperature,
+      model_config: options.modelConfig,
+    };
+
+    // Large prompts are uploaded via a presigned URL and sent as prompt_url.
+    const payloadSize = Buffer.byteLength(JSON.stringify(payload), 'utf-8');
+    if (payloadSize > MAX_GENERATE_TEXT_PAYLOAD_SIZE) {
+      const promptUrl = await uploadBytes(
+        this.#vhttp,
+        prompt,
+        `generate_text_prompt_${Date.now()}.txt`,
+        'text/plain; charset=utf-8',
+        this.id
+      );
+      delete payload.prompt;
+      payload.prompt_url = promptUrl;
+    }
+
+    const res = await this.#vhttp.post<
+      string | Record<string, unknown>,
+      typeof payload
+    >([collection, this.id, generate, text], payload, undefined, { wait });
     return res.data;
   };
 
+  /**
+   * Create a reusable cloned voice from a reference audio asset.
+   */
+  public createVoiceClone = async (
+    refAudioId: string,
+    name?: string,
+    description?: string,
+    refText?: string,
+    language?: string
+  ): Promise<VoiceClone> => {
+    const res = await this.#vhttp.post<VoiceCloneBase, object>([voice_clone], {
+      ref_audio_id: refAudioId,
+      name,
+      description,
+      ref_text: refText,
+      language,
+      collection_id: this.id,
+    });
+    return new VoiceClone(this.#vhttp, res.data);
+  };
+
+  /** Fetch a voice clone by ID. */
+  public getVoiceClone = async (voiceCloneId: string): Promise<VoiceClone> => {
+    const res = await this.#vhttp.get<VoiceCloneBase>([
+      voice_clone,
+      voiceCloneId,
+    ]);
+    return new VoiceClone(this.#vhttp, res.data);
+  };
+
+  /** List voice clones. */
+  public listVoiceClones = async (
+    page: number = 1,
+    pageSize: number = 20,
+    language?: string
+  ): Promise<VoiceClone[]> => {
+    const params: Record<string, unknown> = { page, page_size: pageSize };
+    if (language) params.language = language;
+    const res = await this.#vhttp.get<{ voiceClones?: VoiceCloneBase[] }>(
+      [voice_clone],
+      { params }
+    );
+    return (res.data?.voiceClones || []).map(
+      v => new VoiceClone(this.#vhttp, v)
+    );
+  };
+
+  /** Delete a voice clone by ID. */
+  public deleteVoiceClone = async (voiceCloneId: string): Promise<void> => {
+    await this.#vhttp.delete([voice_clone, voiceCloneId]);
+  };
+
   /**
    * Dub a video to another language
    * @param videoId - ID of the video to dub
@@ -550,7 +973,11 @@ export class Collection implements ICollection {
   ): Promise<Video | undefined> => {
     const res = await this.#vhttp.post<VideoBase, object>(
       [collection, this.id, generate, video, dub],
-      { video_id: videoId, language_code: languageCode, callback_url: callbackUrl }
+      {
+        video_id: videoId,
+        language_code: languageCode,
+        callback_url: callbackUrl,
+      }
     );
     if (res.data) {
       return new Video(this.#vhttp, res.data);
@@ -696,12 +1123,19 @@ export class Collection implements ICollection {
   ): Promise<CaptureSession> => {
     const res = await this.#vhttp.get<
       CaptureSessionBase & { rtstreams?: Array<Record<string, unknown>> }
-    >([ApiPath.collection, this.id, ApiPath.capture, ApiPath.session, sessionId]);
+    >([
+      ApiPath.collection,
+      this.id,
+      ApiPath.capture,
+      ApiPath.session,
+      sessionId,
+    ]);
 
     const responseData = res.data as Record<string, unknown>;
 
     // Normalize rtstreams before passing to CaptureSession
-    const rtstreams = (responseData.rtstreams as Array<Record<string, unknown>>) || [];
+    const rtstreams =
+      (responseData.rtstreams as Array<Record<string, unknown>>) || [];
     for (const rts of rtstreams) {
       if (rts && typeof rts === 'object') {
         if ('rtstream_id' in rts && !('id' in rts)) {
@@ -743,7 +1177,9 @@ export class Collection implements ICollection {
 
     const res = await this.#vhttp.get<{
       sessions: Array<Record<string, unknown>>;
-    }>([ApiPath.collection, this.id, ApiPath.capture, ApiPath.session], { params });
+    }>([ApiPath.collection, this.id, ApiPath.capture, ApiPath.session], {
+      params,
+    });
 
     const sessions: CaptureSession[] = [];
     for (const sessionData of res.data?.sessions || []) {
@@ -754,7 +1190,8 @@ export class Collection implements ICollection {
       delete sessionData.session_id;
 
       // Normalize rtstreams
-      const rtstreams = (sessionData.rtstreams as Array<Record<string, unknown>>) || [];
+      const rtstreams =
+        (sessionData.rtstreams as Array<Record<string, unknown>>) || [];
       for (const rts of rtstreams) {
         if (rts && typeof rts === 'object') {
           if ('rtstream_id' in rts && !('id' in rts)) {
diff --git a/src/core/connection.ts b/src/core/connection.ts
index dc3598c..6d6883d 100644
--- a/src/core/connection.ts
+++ b/src/core/connection.ts
@@ -24,6 +24,11 @@ import {
   type HttpClientOptions,
 } from '@/utils/httpClient';
 import { uploadToServer } from '@/utils/upload';
+import { Sandbox, type SandboxBase } from '@/core/sandbox';
+import { VoiceClone, type VoiceCloneBase } from '@/core/voiceClone';
+import { GenerationJob, fetchJobStatus, type JobStatus } from '@/core/job';
+import type { Audio } from '@/core/audio';
+import type { Image } from '@/core/image';
 
 const {
   collection,
@@ -41,6 +46,9 @@ const {
   websocket,
   capture,
   session,
+  sandbox,
+  voice_clone,
+  async_response,
 } = ApiPath;
 
 class VdbHttpClient extends HttpClient {
@@ -574,4 +582,154 @@ export class Connection {
     );
     return res.data.token;
   };
+
+  /**
+   * Fetch the normalized status of a generation job.
+   * @param jobId - ID of the generation job
+   */
+  public getJobStatus = async (jobId: string): Promise<JobStatus> => {
+    return fetchJobStatus(this.vhttp, jobId);
+  };
+
+  /**
+   * Poll a generation job until it completes and return the generated asset.
+   * @param jobId - ID of the generation job
+   * @param timeout - Maximum seconds to wait (default 600)
+   * @param interval - Seconds between polls (default 5)
+   * @param resultType - Expected asset type (`"audio"` or `"image"`)
+   */
+  public waitForJob = async (
+    jobId: string,
+    timeout: number = 600,
+    interval: number = 5,
+    resultType?: string
+  ): Promise<Audio | Image | Record<string, unknown>> => {
+    const job = new GenerationJob(this.vhttp, { jobId, resultType });
+    return job.wait(timeout, interval);
+  };
+
+  /**
+   * Create a persistent GPU sandbox.
+   * @param tier - Compute tier (see {@link SandboxTier})
+   * @param name - Human-readable name
+   * @param callbackUrl - URL to notify on provisioning events
+   */
+  public createSandbox = async (
+    tier?: string,
+    name?: string,
+    callbackUrl?: string
+  ): Promise<Sandbox> => {
+    const res = await this.vhttp.post<SandboxBase, object>([sandbox], {
+      tier,
+      name,
+      callback_url: callbackUrl,
+    });
+    return new Sandbox(this.vhttp, res.data);
+  };
+
+  /**
+   * Fetch a sandbox by ID.
+   * @param sandboxId - ID of the sandbox
+   */
+  public getSandbox = async (sandboxId: string): Promise<Sandbox> => {
+    const res = await this.vhttp.get<SandboxBase>([sandbox, sandboxId]);
+    return new Sandbox(this.vhttp, res.data);
+  };
+
+  /**
+   * List sandboxes, optionally filtered by status.
+   * @param status - Filter by sandbox status (see {@link SandboxStatus})
+   */
+  public listSandboxes = async (status?: string): Promise<Sandbox[]> => {
+    const res = await this.vhttp.get<{ sandboxes?: SandboxBase[] }>(
+      [sandbox],
+      status ? { params: { status } } : undefined
+    );
+    return (res.data?.sandboxes || []).map(s => new Sandbox(this.vhttp, s));
+  };
+
+  /**
+   * Create a reusable cloned voice.
+   * @param refAudioId - ID of the reference audio asset
+   * @param name - Name for the voice clone
+   * @param description - Description of the voice clone
+   * @param refText - Reference transcript for the audio
+   * @param language - Language code
+   * @param collectionId - Collection to create the clone in
+   */
+  public createVoiceClone = async (
+    refAudioId: string,
+    name?: string,
+    description?: string,
+    refText?: string,
+    language?: string,
+    collectionId?: string
+  ): Promise<VoiceClone> => {
+    const res = await this.vhttp.post<VoiceCloneBase, object>([voice_clone], {
+      ref_audio_id: refAudioId,
+      name,
+      description,
+      ref_text: refText,
+      language,
+      collection_id: collectionId,
+    });
+    return new VoiceClone(this.vhttp, res.data);
+  };
+
+  /**
+   * Fetch a voice clone by ID.
+   * @param voiceCloneId - ID of the voice clone
+   */
+  public getVoiceClone = async (voiceCloneId: string): Promise<VoiceClone> => {
+    const res = await this.vhttp.get<VoiceCloneBase>([
+      voice_clone,
+      voiceCloneId,
+    ]);
+    return new VoiceClone(this.vhttp, res.data);
+  };
+
+  /**
+   * List voice clones.
+   * @param page - Page number (default 1)
+   * @param pageSize - Page size (default 20)
+   * @param language - Filter by language code
+   */
+  public listVoiceClones = async (
+    page: number = 1,
+    pageSize: number = 20,
+    language?: string
+  ): Promise<VoiceClone[]> => {
+    const params: Record<string, unknown> = { page, page_size: pageSize };
+    if (language) params.language = language;
+    const res = await this.vhttp.get<{ voiceClones?: VoiceCloneBase[] }>(
+      [voice_clone],
+      { params }
+    );
+    return (res.data?.voiceClones || []).map(
+      v => new VoiceClone(this.vhttp, v)
+    );
+  };
+
+  /**
+   * Delete a voice clone by ID.
+   * @param voiceCloneId - ID of the voice clone
+   */
+  public deleteVoiceClone = async (voiceCloneId: string): Promise<void> => {
+    await this.vhttp.delete([voice_clone, voiceCloneId]);
+  };
+
+  /**
+   * Fetch a stored async response by ID without polling.
+   * @param id - ID of the async response
+   */
+  public getAsyncResponse = async (
+    id: string
+  ): Promise<Record<string, unknown>> => {
+    const res = await this.vhttp.get<Record<string, unknown>>(
+      [async_response, id],
+      undefined,
+      { wait: false }
+    );
+    return res.data;
+  };
 }
diff --git a/src/core/editor.ts b/src/core/editor.ts
index 2e0d9f5..590de7b 100644
--- a/src/core/editor.ts
+++ b/src/core/editor.ts
@@ -1,4 +1,6 @@
 import { ApiPath } from '@/constants';
+import { buildIframeEmbedCode } from '@/utils';
+import { VideodbError } from '@/utils/error';
 import { HttpClient } from '@/utils/httpClient';
 import type { Connection } from './connection';
 
@@ -838,4 +840,37 @@ export class EditorTimeline {
     );
     return res.data;
   }
+
+  /**
+   * Generate an HTML iframe embed code for the editor timeline.
+   * @param width - Width of the iframe (default `"100%"`)
+   * @param height - Height of the iframe in pixels (default `405`)
+   * @param title - Title attribute (default `"VideoDB Player"`)
+   * @param allowFullscreen - Whether to allow fullscreen (default `true`)
+   * @param autoGenerate - If true and playerUrl is missing, auto-generate it (default `true`)
+   * @throws {VideodbError} If the player URL is not available.
+   */
+  async getEmbedCode(
+    width: string = '100%',
+    height: number = 405,
+    title: string = 'VideoDB Player',
+    allowFullscreen: boolean = true,
+    autoGenerate: boolean = true
+  ): Promise<string> {
+    if (!this.playerUrl && autoGenerate) {
+      await this.generateStream();
+    }
+    if (!this.playerUrl) {
+      throw new VideodbError(
+        'player_url not available. Call generateStream() first or set autoGenerate=true.'
+      );
+    }
+    return buildIframeEmbedCode(
+      this.playerUrl,
+      width,
+      height,
+      title,
+      allowFullscreen
+    );
+  }
 }
diff --git a/src/core/indexManifest.ts b/src/core/indexManifest.ts
new file mode 100644
index 0000000..969d61d
--- /dev/null
+++ b/src/core/indexManifest.ts
@@ -0,0 +1,330 @@
+import { ApiPath } from '@/constants';
+import { RequestTimeoutError } from '@/utils/error';
+import { HttpClient } from '@/utils/httpClient';
+import { sleep } from '@/utils';
+
+const { video, indexes, records } = ApiPath;
+
+export const INDEX_TERMINAL_STATUSES = new Set(['ready', 'failed']);
+
+/** Schema details for a single indexed field. */
+export interface FieldSchemaData {
+  type?: string;
+  groups?: string[];
+  operators?: string[];
+}
+
+/**
+ * Schema details for a single indexed field.
+ * Mirrors `videodb.index.FieldSchema`.
+ */
+export class FieldSchema {
+  public type?: string;
+  public groups: string[];
+  public operators: string[];
+
+  constructor(data: FieldSchemaData = {}) {
+    this.type = data.type;
+    this.groups = data.groups || [];
+    this.operators = data.operators || [];
+  }
+
+  public toString(): string {
+    return `FieldSchema(type=${this.type}, groups=[${this.groups.join(', ')}], operators=[${this.operators.join(', ')}])`;
+  }
+}
+
+/** Camelcased wire shape of a single index record. */
+export interface IndexRecordData {
+  videoId?: string;
+  understandingId?: string;
+  sceneId?: string;
+  start?: number;
+  end?: number;
+  data?: Record<string, unknown>;
+  segmentId?: string;
+  startSec?: number;
+  endSec?: number;
+}
+
+/**
+ * A single indexed record (one temporal scene of an index).
+ * Mirrors `videodb.index.IndexRecord`, preserving the deprecated
+ * `segmentId` / `startSec` / `endSec` aliases.
+ */
+export class IndexRecord {
+  public videoId?: string;
+  public understandingId?: string;
+  public sceneId?: string;
+  public start?: number;
+  public end?: number;
+  public data: Record<string, unknown>;
+  public segmentId?: string;
+  public startSec?: number;
+  public endSec?: number;
+
+  constructor(data: IndexRecordData = {}) {
+    this.videoId = data.videoId;
+    this.understandingId = data.understandingId;
+    this.sceneId = data.sceneId ?? data.segmentId;
+    this.start = data.start ?? data.startSec;
+    this.end = data.end ?? data.endSec;
+    this.data = data.data || {};
+    // Deprecated aliases, mirrored bidirectionally for wire compatibility.
+    this.segmentId = this.sceneId;
+    this.startSec = this.start;
+    this.endSec = this.end;
+  }
+
+  public toString(): string {
+    return `IndexRecord(videoId=${this.videoId}, sceneId=${this.sceneId}, start=${this.start}, end=${this.end})`;
+  }
+}
+
+/**
+ * A page of indexed records returned by {@link Index.records}.
+ * Mirrors `videodb.index.RecordPage` (iterable over its records).
+ */
+export class RecordPage implements Iterable<IndexRecord> {
+  public records: IndexRecord[];
+  public nextCursor?: string;
+
+  constructor(recordsList: IndexRecord[] = [], nextCursor?: string) {
+    this.records = recordsList;
+    this.nextCursor = nextCursor;
+  }
+
+  [Symbol.iterator](): Iterator<IndexRecord> {
+    return this.records[Symbol.iterator]();
+  }
+
+  public get length(): number {
+    return this.records.length;
+  }
+
+  public toString(): string {
+    return `RecordPage(records=${this.records.length}, nextCursor=${this.nextCursor})`;
+  }
+}
+
+/** Camelcased public shape of an index manifest (typing convenience). */
+export interface IndexData {
+  indexId?: string;
+  name?: string;
+  status?: string;
+  error?: string;
+  useFor?: string[];
+  source?: unknown;
+  recordCount?: number;
+  fields?: Record<string, string[]>;
+  fieldSchema?: Record<string, FieldSchemaData>;
+}
+
+/**
+ * Raw wire shape of an index manifest (snake_case). Read verbatim so
+ * user-defined `field_schema` keys and `fields` values are preserved.
+ */
+export interface RawIndexManifest {
+  index_id?: string;
+  name?: string;
+  status?: string;
+  error?: string;
+  use_for?: string[];
+  source?: unknown;
+  record_count?: number;
+  fields?: Record<string, string[]>;
+  field_schema?: Record<
+    string,
+    { type?: string; groups?: string[]; operators?: string[] }
+  >;
+  video_id?: string;
+  collection_id?: string;
+}
+
+/** Raw wire shape of a single record (snake_case; `data` map preserved verbatim). */
+export interface RawIndexRecord {
+  video_id?: string;
+  understanding_id?: string;
+  scene_id?: string;
+  start?: number;
+  end?: number;
+  data?: Record<string, unknown>;
+  segment_id?: string;
+  start_sec?: number;
+  end_sec?: number;
+}
+
+interface RawRecordsResponse {
+  records?: RawIndexRecord[];
+  next_cursor?: string;
+}
+
+/**
+ * Index manifest for a retrieval-ready index built from an understanding artifact.
+ * Mirrors `videodb.index.Index`.
+ *
+ * Users should not construct this directly — use {@link Video.index},
+ * {@link Video.getIndex}, or {@link Video.listIndexes}.
+ */
+export class Index {
+  public videoId: string;
+  public collectionId?: string;
+  public indexId?: string;
+  public name?: string;
+  public status?: string;
+  public error?: string;
+  public useFor: string[] = [];
+  public source?: unknown;
+  public recordCount?: number;
+  public fields: Record<string, string[]> = {};
+  public fieldSchema: Record<string, FieldSchema> = {};
+  #vhttp: HttpClient;
+
+  constructor(
+    http: HttpClient,
+    videoId: string,
+    collectionId?: string,
+    data: RawIndexManifest = {}
+  ) {
+    this.#vhttp = http;
+    this.videoId = videoId;
+    this.collectionId = collectionId;
+    this.updateFromResponse(data);
+  }
+
+  /**
+   * Hydrate from a RAW (snake_case) manifest. Opaque maps — `field_schema`
+   * keys and `fields` values (user-defined field names) — are preserved verbatim.
+   */
+  public updateFromResponse(data: RawIndexManifest = {}): Index {
+    this.indexId = data.index_id ?? this.indexId;
+    this.name = data.name;
+    this.status = data.status;
+    this.error = data.error;
+    this.useFor = data.use_for ?? [];
+    this.source = data.source;
+    this.recordCount = data.record_count;
+    this.fields = data.fields ?? {};
+    this.fieldSchema = {};
+    for (const [field, schema] of Object.entries(data.field_schema ?? {})) {
+      this.fieldSchema[field] = new FieldSchema({
+        type: schema?.type,
+        groups: schema?.groups,
+        operators: schema?.operators,
+      });
+    }
+    return this;
+  }
+
+  /** True when the index build is in a terminal status (`ready`/`failed`). */
+  public get isComplete(): boolean {
+    return (
+      this.status !== undefined && INDEX_TERMINAL_STATUSES.has(this.status)
+    );
+  }
+
+  /** True when the index build completed successfully. */
+  public get isSuccessful(): boolean {
+    return this.status === 'ready';
+  }
+
+  #collectionParams = (): { params: { collection_id: string } } | undefined =>
+    this.collectionId
+      ? { params: { collection_id: this.collectionId } }
+      : undefined;
+
+  /** Refresh the index manifest and build status from the API. */
+  public refresh = async (): Promise<Index> => {
+    const res = await this.#vhttp.get<RawIndexManifest>(
+      [video, this.videoId, indexes, this.indexId ?? ''],
+      this.#collectionParams(),
+      { convert: false }
+    );
+    // convert:false — res.data is raw snake at runtime; the client's return
+    // type wrongly assumes camelCase, so read it as the raw shape.
+    return this.updateFromResponse(res.data as unknown as RawIndexManifest);
+  };
+
+  /**
+   * Poll this index until it reaches a terminal status (`ready`/`failed`).
+   *
+   * @param timeout - Maximum time to wait, in seconds (default 1800)
+   * @param pollInterval - Seconds between status checks (default 10)
+   * @throws {RequestTimeoutError} If the build does not complete before timeout
+   */
+  public waitUntilComplete = async (
+    timeout: number = 1800,
+    pollInterval: number = 10
+  ): Promise<Index> => {
+    const deadline = Date.now() + timeout * 1000;
+    for (;;) {
+      await this.refresh();
+      if (this.isComplete) return this;
+      if (Date.now() >= deadline) {
+        throw new RequestTimeoutError(
+          `Index ${this.indexId} did not complete within ${timeout}s`
+        );
+      }
+      await sleep(pollInterval * 1000);
+    }
+  };
+
+  /**
+   * Preview the records stored in the index (paginated via a cursor).
+   *
+   * @param limit - Maximum number of records to return (default 20)
+   * @param cursor - Cursor returned by a previous page
+   */
+  public records = async (
+    limit: number = 20,
+    cursor?: string
+  ): Promise<RecordPage> => {
+    const params: Record<string, unknown> = {
+      limit,
+      collection_id: this.collectionId,
+    };
+    if (cursor !== undefined) params.cursor = cursor;
+    for (const key of Object.keys(params)) {
+      if (params[key] === undefined || params[key] === null) delete params[key];
+    }
+    // convert:false — keep each record's opaque `data` map keys verbatim.
+    const res = await this.#vhttp.get<RawRecordsResponse>(
+      [video, this.videoId, indexes, this.indexId ?? '', records],
+      { params },
+      { convert: false }
+    );
+    // convert:false — res.data is raw snake at runtime (types assume camel).
+    const recordsData = res.data as unknown as RawRecordsResponse;
+    if (!recordsData) return new RecordPage();
+    const recordList = (recordsData.records ?? []).map(
+      r =>
+        new IndexRecord({
+          videoId: r.video_id,
+          understandingId: r.understanding_id,
+          sceneId: r.scene_id,
+          start: r.start,
+          end: r.end,
+          data: r.data,
+          segmentId: r.segment_id,
+          startSec: r.start_sec,
+          endSec: r.end_sec,
+        })
+    );
+    return new RecordPage(recordList, recordsData.next_cursor);
+  };
+
+  /**
+   * Delete the index. Removes the index's retrieval structures only — it does
+   * not delete the original video or stored understanding artifacts.
+   */
+  public delete = async (): Promise<void> => {
+    await this.#vhttp.delete(
+      [video, this.videoId, indexes, this.indexId ?? ''],
+      this.#collectionParams()
+    );
+  };
+
+  public toString(): string {
+    return `Index(indexId=${this.indexId}, videoId=${this.videoId}, name=${this.name}, status=${this.status}, useFor=[${this.useFor.join(', ')}], recordCount=${this.recordCount})`;
+  }
+}
diff --git a/src/core/job.ts b/src/core/job.ts
new file mode 100644
index 0000000..883a1aa
--- /dev/null
+++ b/src/core/job.ts
@@ -0,0 +1,179 @@
+import { ApiPath } from '@/constants';
+import { InvalidRequestError, RequestTimeoutError } from '@/utils/error';
+import { HttpClient } from '@/utils/httpClient';
+import { sleep } from '@/utils';
+import { Audio } from '@/core/audio';
+import { Image } from '@/core/image';
+import type { AudioBase, ImageBase } from '@/interfaces/core';
+
+const { job } = ApiPath;
+
+/** Normalized job-status envelope, mirroring `Connection.get_job_status`. */
+export interface JobStatus {
+  success: boolean;
+  status: string;
+  data: Record<string, unknown>;
+  message?: string;
+}
+
+export type JobData = Record<string, unknown> & {
+  id?: string;
+  jobId?: string;
+  jobType?: string;
+  status?: string;
+  outputUrl?: string;
+};
+
+/**
+ * Fetch and normalize the status of a generation job.
+ * Mirrors `Connection.get_job_status` — reads the raw `/job/{id}` envelope
+ * without polling and synthesizes a status when the server omits one.
+ */
+export const fetchJobStatus = async (
+  http: HttpClient,
+  jobId: string
+): Promise<JobStatus> => {
+  const res = await http.get<JobData>([job, jobId], undefined, { wait: false });
+  const envelope = res as unknown as {
+    success?: boolean;
+    status?: string;
+    message?: string;
+  };
+  const data = (res.data as JobData) || {};
+  const success = Boolean(envelope.success);
+  let status = envelope.status || data.status;
+  if (!status) {
+    status = success ? 'done' : 'failed';
+  }
+  return { success, status, data, message: envelope.message };
+};
+
+/** Config accepted by the {@link GenerationJob} constructor. */
+export interface GenerationJobConfig {
+  jobId: string;
+  outputUrl?: string;
+  status?: string;
+  resultType?: string;
+  data?: JobData;
+}
+
+/**
+ * A self-inference generation job.
+ * Mirrors `videodb.job.GenerationJob`.
+ *
+ * OmniVoice TTS and FLUX image generation return a VideoDB job after the
+ * initial server-side async task dispatches work to inference-core. Use
+ * {@link wait} to poll until the final asset is ready.
+ */
+export class GenerationJob {
+  public id: string;
+  public jobId: string;
+  public outputUrl?: string;
+  public status: string;
+  public resultType?: string;
+  public data: JobData;
+  #vhttp: HttpClient;
+
+  constructor(http: HttpClient, config: GenerationJobConfig) {
+    this.#vhttp = http;
+    this.id = config.jobId;
+    this.jobId = config.jobId;
+    this.outputUrl = config.outputUrl;
+    this.status = config.status || 'processing';
+    this.resultType = config.resultType;
+    this.data = config.data || {};
+  }
+
+  /**
+   * Create a job from an API job payload (camelCased response data).
+   */
+  static fromData(
+    http: HttpClient,
+    data: JobData,
+    resultType?: string
+  ): GenerationJob {
+    const payload = data || {};
+    const jobId = payload.jobId || payload.id;
+    if (!jobId) {
+      throw new InvalidRequestError(
+        'Invalid generation job response: missing job_id'
+      );
+    }
+    let inferredResultType = resultType;
+    if (!inferredResultType) {
+      if (payload.jobType === 'tts') inferredResultType = 'audio';
+      else if (payload.jobType === 'image') inferredResultType = 'image';
+    }
+    return new GenerationJob(http, {
+      jobId,
+      outputUrl: payload.outputUrl,
+      status: (payload.status as string) || 'processing',
+      resultType: inferredResultType,
+      data: payload,
+    });
+  }
+
+  /**
+   * Refresh this job's status from VideoDB.
+   */
+  public refresh = async (): Promise<GenerationJob> => {
+    const jobStatus = await fetchJobStatus(this.#vhttp, this.jobId);
+    this.status = jobStatus.status || this.status;
+    this.data = (jobStatus.data as JobData) || {};
+    this.outputUrl = this.data.outputUrl ?? this.outputUrl;
+    if (!this.resultType) {
+      if (this.data.jobType === 'tts') this.resultType = 'audio';
+      else if (this.data.jobType === 'image') this.resultType = 'image';
+    }
+    return this;
+  };
+
+  /**
+   * Poll this job until it completes and return the generated asset.
+   *
+   * @param timeout - Maximum seconds to wait (default 600)
+   * @param interval - Seconds between polls (default 5)
+   * @returns An {@link Audio}, {@link Image}, or the final job data if the
+   *   result type cannot be inferred.
+   * @throws {RequestTimeoutError} If the job does not complete in time
+   * @throws {InvalidRequestError} If the job ends in the `failed` status
+   */
+  public wait = async (
+    timeout: number = 600,
+    interval: number = 5
+  ): Promise<Audio | Image | JobData> => {
+    const deadline = Date.now() + timeout * 1000;
+    for (;;) {
+      await this.refresh();
+      if (this.status !== 'processing') break;
+      if (Date.now() >= deadline) {
+        throw new RequestTimeoutError(
+          `Generation job ${this.jobId} did not complete within ${timeout} seconds`
+        );
+      }
+      await sleep(interval * 1000);
+    }
+
+    if (this.status === 'failed') {
+      throw new InvalidRequestError(`Generation job ${this.jobId} failed`);
+    }
+
+    return this.#toAsset();
+  };
+
+  #toAsset = (): Audio | Image | JobData => {
+    const data = this.data || {};
+    const assetId = data.id;
+    if (this.resultType === 'audio' || assetId?.startsWith('a-')) {
+      return new Audio(this.#vhttp, data as unknown as AudioBase);
+    }
+    if (this.resultType === 'image' || assetId?.startsWith('img-')) {
+      return new Image(this.#vhttp, data as unknown as ImageBase);
+    }
+    return data;
+  };
+
+  public toString(): string {
+    return `GenerationJob(jobId=${this.jobId}, status=${this.status}, resultType=${this.resultType})`;
+  }
+}
diff --git a/src/core/rtstream.ts b/src/core/rtstream.ts
index 97d1d10..cab271b 100644
--- a/src/core/rtstream.ts
+++ b/src/core/rtstream.ts
@@ -10,22 +10,96 @@ import type {
   IndexSpokenWordsConfig,
 } from '@/types/capture';
 import { HttpClient } from '@/utils/httpClient';
-import { playStream } from '@/utils';
+import { playStream, buildIframeEmbedCode } from '@/utils';
+import { VideodbError } from '@/utils/error';
+
+/** Constructor input for {@link RTStreamSceneIndex} (adds self-hosted sandbox id). */
+interface RTStreamSceneIndexData extends RTStreamSceneIndexBase {
+  /** Sandbox ID used for self-hosted inference */
+  sandboxId?: string;
+}
+
+/** Constructor input for {@link RTStreamUnderstanding}. */
+interface RTStreamUnderstandingBase {
+  id?: string;
+  understandingId?: string;
+  rtstreamId?: string;
+  status?: string;
+  store?: boolean;
+  segmentation?: Record<string, unknown>;
+  analyzers?: Record<string, unknown>[];
+  outputs?: Record<string, unknown>;
+}
+
+/** Constructor input for {@link RTStreamIndex}. */
+interface RTStreamIndexBase {
+  id?: string;
+  indexId?: string;
+  rtstreamId?: string;
+  name?: string;
+  status?: string;
+  useFor?: string[];
+  sourceUnderstandingId?: string;
+  output?: string;
+}
 
 /**
  * Result of exporting an RTStream recording
  */
-export interface RTStreamExportResult {
+export class RTStreamExportResult {
   /** ID of the exported video or audio asset */
-  videoId: string;
+  public videoId: string;
   /** URL to stream the exported asset (may be undefined for audio) */
-  streamUrl?: string;
+  public streamUrl?: string;
   /** URL to play the exported asset in a player (may be undefined for audio) */
-  playerUrl?: string;
+  public playerUrl?: string;
   /** Name of the exported recording */
-  name?: string;
+  public name?: string;
   /** Duration of the exported recording in seconds (may be undefined on idempotent calls) */
-  duration?: number;
+  public duration?: number;
+
+  constructor(data: {
+    videoId: string;
+    streamUrl?: string;
+    playerUrl?: string;
+    name?: string;
+    duration?: number;
+  }) {
+    this.videoId = data.videoId;
+    this.streamUrl = data.streamUrl;
+    this.playerUrl = data.playerUrl;
+    this.name = data.name;
+    this.duration = data.duration;
+  }
+
+  /**
+   * Generate an HTML iframe embed code for the exported recording.
+   * @param width - Width of the iframe (default `"100%"`)
+   * @param height - Height of the iframe in pixels (default `405`)
+   * @param title - Title attribute for the iframe (default `"VideoDB Player"`)
+   * @param allowFullscreen - Whether to allow fullscreen (default `true`)
+   * @returns HTML iframe string
+   * @throws {VideodbError} If `playerUrl` is not available
+   */
+  public getEmbedCode = (
+    width: string = '100%',
+    height: number = 405,
+    title: string = 'VideoDB Player',
+    allowFullscreen: boolean = true
+  ): string => {
+    if (!this.playerUrl) {
+      throw new VideodbError(
+        'player_url not available. Export may have failed or returned audio-only content.'
+      );
+    }
+    return buildIframeEmbedCode(
+      this.playerUrl,
+      width,
+      height,
+      title,
+      allowFullscreen
+    );
+  };
 }
 
 export interface RTStreamPlayerConfig {
@@ -94,6 +168,40 @@ export class RTStreamShot {
     }
     return null;
   };
+
+  /**
+   * Generate an HTML iframe embed code for the rtstream shot.
+   * @param width - Width of the iframe (default `"100%"`)
+   * @param height - Height of the iframe in pixels (default `405`)
+   * @param title - Title attribute for the iframe (default `"VideoDB Player"`)
+   * @param allowFullscreen - Whether to allow fullscreen (default `true`)
+   * @param autoGenerate - If `true` and `playerUrl` is missing, auto-generate it (default `true`)
+   * @returns HTML iframe string
+   * @throws {VideodbError} If `playerUrl` is not available
+   */
+  public getEmbedCode = async (
+    width: string = '100%',
+    height: number = 405,
+    title: string = 'VideoDB Player',
+    allowFullscreen: boolean = true,
+    autoGenerate: boolean = true
+  ): Promise<string> => {
+    if (!this.playerUrl && autoGenerate) {
+      await this.generateStream();
+    }
+    if (!this.playerUrl) {
+      throw new VideodbError(
+        'player_url not available. Call generateStream() first or set autoGenerate=true.'
+      );
+    }
+    return buildIframeEmbedCode(
+      this.playerUrl,
+      width,
+      height,
+      title,
+      allowFullscreen
+    );
+  };
 }
 
 /**
@@ -128,9 +236,11 @@ export class RTStreamSceneIndex {
   public prompt?: string;
   public name?: string;
   public status?: string;
+  /** Sandbox ID used for self-hosted inference */
+  public sandboxId?: string;
   #vhttp: HttpClient;
 
-  constructor(http: HttpClient, data: RTStreamSceneIndexBase) {
+  constructor(http: HttpClient, data: RTStreamSceneIndexData) {
     this.#vhttp = http;
     this.rtstreamIndexId = data.rtstreamIndexId;
     this.rtstreamId = data.rtstreamId;
@@ -139,6 +249,7 @@ export class RTStreamSceneIndex {
     this.prompt = data.prompt;
     this.name = data.name;
     this.status = data.status;
+    this.sandboxId = data.sandboxId;
   }
 
   /**
@@ -339,6 +450,350 @@ export class RTStreamSceneIndex {
   };
 }
 
+/**
+ * RTStreamUnderstanding class to interact with a continuous understanding job.
+ *
+ * Produced by {@link RTStream.understand}. It runs VLM analysis over stream
+ * windows and, when `store=true`, persists the output so it can be indexed
+ * later. Understanding is independent of scene indexing.
+ */
+export class RTStreamUnderstanding {
+  /** Understanding id (`und-...`) */
+  public id: string;
+  /** ID of the parent RTStream */
+  public rtstreamId: string;
+  /** Job status (`running` | `stopped` | `failed`) */
+  public status?: string;
+  /** Whether output is persisted for later indexing */
+  public store: boolean;
+  /** Time segmentation, e.g. `{ type: 'time', window: '10s' }` */
+  public segmentation: Record<string, unknown>;
+  /** Analyzer specs for this understanding */
+  public analyzers: Record<string, unknown>[];
+  /** Named output source descriptors, e.g. `outputs.scene` */
+  public outputs: Record<string, unknown>;
+  #vhttp: HttpClient;
+
+  constructor(http: HttpClient, data: RTStreamUnderstandingBase) {
+    this.#vhttp = http;
+    this.id = (data.understandingId ?? data.id) as string;
+    this.rtstreamId = data.rtstreamId as string;
+    this.status = data.status;
+    this.store = data.store ?? true;
+    this.segmentation = data.segmentation ?? {};
+    this.analyzers = data.analyzers ?? [];
+    this.outputs = data.outputs ?? {};
+  }
+
+  /**
+   * Reload this understanding from the server.
+   * @returns This understanding, updated
+   */
+  public refresh = async (): Promise<RTStreamUnderstanding> => {
+    const res = await this.#vhttp.get<RTStreamUnderstandingBase>([
+      ApiPath.rtstream,
+      this.rtstreamId,
+      ApiPath.understand,
+      this.id,
+    ]);
+    const data = res.data;
+    if (data) {
+      this.id = data.understandingId ?? data.id ?? this.id;
+      this.rtstreamId = data.rtstreamId ?? this.rtstreamId;
+      this.status = data.status;
+      this.store = data.store ?? true;
+      this.segmentation = data.segmentation ?? {};
+      this.analyzers = data.analyzers ?? [];
+      this.outputs = data.outputs ?? {};
+    }
+    return this;
+  };
+
+  /**
+   * Resume processing new stream windows.
+   */
+  public start = async (): Promise<void> => {
+    await this.#vhttp.patch(
+      [
+        ApiPath.rtstream,
+        this.rtstreamId,
+        ApiPath.understand,
+        this.id,
+        ApiPath.status,
+      ],
+      { action: 'start' }
+    );
+    this.status = 'running';
+  };
+
+  /**
+   * Pause processing new stream windows. Existing records remain available.
+   */
+  public stop = async (): Promise<void> => {
+    await this.#vhttp.patch(
+      [
+        ApiPath.rtstream,
+        this.rtstreamId,
+        ApiPath.understand,
+        this.id,
+        ApiPath.status,
+      ],
+      { action: 'stop' }
+    );
+    this.status = 'stopped';
+  };
+
+  /**
+   * Get understanding output records for a time range.
+   * @param start - Start Unix timestamp
+   * @param end - End Unix timestamp
+   * @param output - Analyzer output name (default: `"scene"`)
+   * @param page - Page number (default: 1)
+   * @param pageSize - Records per page (default: 100)
+   * @returns Records payload with `records` and `nextPage`
+   */
+  public getRecords = async (
+    start: number,
+    end: number,
+    output: string = 'scene',
+    page: number = 1,
+    pageSize: number = 100
+  ): Promise<Record<string, unknown>> => {
+    const rawParams: Record<string, unknown> = {
+      start,
+      end,
+      output,
+      page,
+      page_size: pageSize,
+    };
+    const params: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(rawParams)) {
+      if (value !== undefined && value !== null) params[key] = value;
+    }
+
+    const res = await this.#vhttp.get<Record<string, unknown>>(
+      [
+        ApiPath.rtstream,
+        this.rtstreamId,
+        ApiPath.understand,
+        this.id,
+        ApiPath.records,
+      ],
+      { params }
+    );
+    return res.data || {};
+  };
+}
+
+/**
+ * RTStreamIndex — a continuous index over an understanding output.
+ *
+ * Produced by {@link RTStream.index}. Materializes an understanding's stored
+ * output into a searchable index; has its own lifecycle, separate from the
+ * understanding.
+ */
+export class RTStreamIndex {
+  /** Index id (`idx-...`) */
+  public id: string;
+  /** ID of the parent RTStream */
+  public rtstreamId: string;
+  /** Index name */
+  public name?: string;
+  /** `running` | `stopped` | `failed` */
+  public status?: string;
+  /** Index capabilities, e.g. `['semantic']` */
+  public useFor: string[];
+  /** Understanding this index consumes */
+  public sourceUnderstandingId?: string;
+  /** Analyzer output name being indexed (e.g. `"scene"`) */
+  public output: string;
+  #vhttp: HttpClient;
+
+  constructor(http: HttpClient, data: RTStreamIndexBase) {
+    this.#vhttp = http;
+    this.id = (data.indexId ?? data.id) as string;
+    this.rtstreamId = data.rtstreamId as string;
+    this.name = data.name;
+    this.status = data.status;
+    this.useFor = data.useFor ?? ['semantic'];
+    this.sourceUnderstandingId = data.sourceUnderstandingId;
+    this.output = data.output ?? 'scene';
+  }
+
+  /**
+   * Reload this index from the server.
+   * @returns This index, updated
+   */
+  public refresh = async (): Promise<RTStreamIndex> => {
+    const res = await this.#vhttp.get<RTStreamIndexBase>([
+      ApiPath.rtstream,
+      this.rtstreamId,
+      ApiPath.indexes,
+      this.id,
+    ]);
+    const data = res.data;
+    if (data) {
+      this.id = data.indexId ?? data.id ?? this.id;
+      this.rtstreamId = data.rtstreamId ?? this.rtstreamId;
+      this.name = data.name;
+      this.status = data.status;
+      this.useFor = data.useFor ?? ['semantic'];
+      this.sourceUnderstandingId = data.sourceUnderstandingId;
+      this.output = data.output ?? 'scene';
+    }
+    return this;
+  };
+
+  /**
+   * Resume materializing new understanding output into the index.
+   */
+  public start = async (): Promise<void> => {
+    await this.#vhttp.patch(
+      [
+        ApiPath.rtstream,
+        this.rtstreamId,
+        ApiPath.indexes,
+        this.id,
+        ApiPath.status,
+      ],
+      { action: 'start' }
+    );
+    this.status = 'running';
+  };
+
+  /**
+   * Pause materializing. Existing indexed records remain searchable.
+   */
+  public stop = async (): Promise<void> => {
+    await this.#vhttp.patch(
+      [
+        ApiPath.rtstream,
+        this.rtstreamId,
+        ApiPath.indexes,
+        this.id,
+        ApiPath.status,
+      ],
+      { action: 'stop' }
+    );
+    this.status = 'stopped';
+  };
+
+  /**
+   * Get materialized index records.
+   * @param start - Start Unix timestamp (optional)
+   * @param end - End Unix timestamp (optional)
+   * @param page - Page number (default: 1)
+   * @param pageSize - Records per page (default: 100)
+   * @returns Records payload
+   */
+  public getRecords = async (
+    start?: number,
+    end?: number,
+    page: number = 1,
+    pageSize: number = 100
+  ): Promise<Record<string, unknown>> => {
+    const params: Record<string, unknown> = { page, page_size: pageSize };
+    if (start !== undefined && start !== null) params.start = start;
+    if (end !== undefined && end !== null) params.end = end;
+
+    const res = await this.#vhttp.get<Record<string, unknown>>(
+      [
+        ApiPath.rtstream,
+        this.rtstreamId,
+        ApiPath.indexes,
+        this.id,
+        ApiPath.records,
+      ],
+      { params }
+    );
+    return res.data || {};
+  };
+
+  /**
+   * Attach an event alert to this index.
+   * @param eventId - ID of the event
+   * @param callbackUrl - URL to receive the alert callback
+   * @param wsConnectionId - WebSocket connection ID for real-time alerts (optional)
+   * @returns Alert ID
+   */
+  public createAlert = async (
+    eventId: string,
+    callbackUrl: string,
+    wsConnectionId?: string
+  ): Promise<string | null> => {
+    const data: Record<string, unknown> = {
+      event_id: eventId,
+      callback_url: callbackUrl,
+    };
+    if (wsConnectionId) data.ws_connection_id = wsConnectionId;
+
+    const res = await this.#vhttp.post<{ alertId: string }, typeof data>(
+      [
+        ApiPath.rtstream,
+        this.rtstreamId,
+        ApiPath.indexes,
+        this.id,
+        ApiPath.alert,
+      ],
+      data
+    );
+    return res.data?.alertId || null;
+  };
+
+  /**
+   * List all alerts on this index.
+   * @returns List of alerts
+   */
+  public listAlerts = async (): Promise<unknown[]> => {
+    const res = await this.#vhttp.get<{ alerts: unknown[] }>([
+      ApiPath.rtstream,
+      this.rtstreamId,
+      ApiPath.indexes,
+      this.id,
+      ApiPath.alert,
+    ]);
+    return res.data?.alerts || [];
+  };
+
+  /**
+   * Enable an alert on this index.
+   * @param alertId - ID of the alert
+   */
+  public enableAlert = async (alertId: string): Promise<void> => {
+    await this.#vhttp.patch(
+      [
+        ApiPath.rtstream,
+        this.rtstreamId,
+        ApiPath.indexes,
+        this.id,
+        ApiPath.alert,
+        alertId,
+        ApiPath.status,
+      ],
+      { action: 'enable' }
+    );
+  };
+
+  /**
+   * Disable an alert on this index.
+   * @param alertId - ID of the alert
+   */
+  public disableAlert = async (alertId: string): Promise<void> => {
+    await this.#vhttp.patch(
+      [
+        ApiPath.rtstream,
+        this.rtstreamId,
+        ApiPath.indexes,
+        this.id,
+        ApiPath.alert,
+        alertId,
+        ApiPath.status,
+      ],
+      { action: 'disable' }
+    );
+  };
+}
+
 /**
  * RTStream class to interact with the RTStream
  */
@@ -415,13 +870,13 @@ export class RTStream {
       typeof data
     >([ApiPath.rtstream, this.id, ApiPath.export], data);
 
-    return {
+    return new RTStreamExportResult({
       videoId: res.data.videoId,
       streamUrl: res.data.streamUrl,
       playerUrl: res.data.playerUrl,
       name: res.data.name,
       duration: res.data.duration,
-    };
+    });
   };
 
   /**
@@ -457,6 +912,40 @@ export class RTStream {
     return this.playerUrl || null;
   };
 
+  /**
+   * Generate an HTML iframe embed code for the rtstream.
+   *
+   * Note: Unlike other objects, RTStream does not support autoGenerate because
+   * `generateStream()` requires start and end parameters. Call
+   * `generateStream(start, end)` first to populate `playerUrl`.
+   *
+   * @param width - Width of the iframe (default `"100%"`)
+   * @param height - Height of the iframe in pixels (default `405`)
+   * @param title - Title attribute for the iframe (default `"VideoDB Player"`)
+   * @param allowFullscreen - Whether to allow fullscreen (default `true`)
+   * @returns HTML iframe string
+   * @throws {VideodbError} If `playerUrl` is not available
+   */
+  public getEmbedCode = (
+    width: string = '100%',
+    height: number = 405,
+    title: string = 'VideoDB Player',
+    allowFullscreen: boolean = true
+  ): string => {
+    if (!this.playerUrl) {
+      throw new VideodbError(
+        'player_url not available. Call generateStream(start, end) first to generate a stream.'
+      );
+    }
+    return buildIframeEmbedCode(
+      this.playerUrl,
+      width,
+      height,
+      title,
+      allowFullscreen
+    );
+  };
+
   /**
    * Index scenes from the rtstream (flexible base method)
    *
@@ -499,6 +988,7 @@ export class RTStream {
     modelConfig?: Record<string, unknown>;
     name?: string;
     wsConnectionId?: string;
+    sandboxId?: string;
   }): Promise<RTStreamSceneIndex | null> => {
     const {
       extractionType = 'time_based',
@@ -508,6 +998,7 @@ export class RTStream {
       modelConfig = {},
       name,
       wsConnectionId,
+      sandboxId,
     } = config;
 
     const data: Record<string, unknown> = {
@@ -520,8 +1011,9 @@ export class RTStream {
     };
 
     if (wsConnectionId) data.ws_connection_id = wsConnectionId;
+    if (sandboxId) data.sandbox_id = sandboxId;
 
-    const res = await this.#vhttp.post<RTStreamSceneIndexBase, typeof data>(
+    const res = await this.#vhttp.post<RTStreamSceneIndexData, typeof data>(
       [ApiPath.rtstream, this.id, ApiPath.index, ApiPath.scene],
       data
     );
@@ -536,6 +1028,7 @@ export class RTStream {
       prompt: res.data.prompt,
       name: res.data.name,
       status: res.data.status,
+      sandboxId: res.data.sandboxId,
     });
   };
 
@@ -554,7 +1047,7 @@ export class RTStream {
    * @returns RTStreamSceneIndex object
    */
   public indexVisuals = async (
-    config: Partial<IndexVisualsConfig> = {}
+    config: Partial<IndexVisualsConfig> & { sandboxId?: string } = {}
   ): Promise<RTStreamSceneIndex | null> => {
     let extractionType: string | undefined;
     let extractionConfig: Record<string, unknown> | undefined;
@@ -580,8 +1073,9 @@ export class RTStream {
     };
 
     if (config.socketId) data.ws_connection_id = config.socketId;
+    if (config.sandboxId) data.sandbox_id = config.sandboxId;
 
-    const res = await this.#vhttp.post<RTStreamSceneIndexBase, typeof data>(
+    const res = await this.#vhttp.post<RTStreamSceneIndexData, typeof data>(
       [ApiPath.rtstream, this.id, ApiPath.index, ApiPath.scene],
       data
     );
@@ -596,6 +1090,7 @@ export class RTStream {
       prompt: res.data.prompt,
       name: res.data.name,
       status: res.data.status,
+      sandboxId: res.data.sandboxId,
     });
   };
 
@@ -605,7 +1100,7 @@ export class RTStream {
    */
   public listSceneIndexes = async (): Promise<RTStreamSceneIndex[]> => {
     const res = await this.#vhttp.get<{
-      sceneIndexes: RTStreamSceneIndexBase[];
+      sceneIndexes: RTStreamSceneIndexData[];
     }>([ApiPath.rtstream, this.id, ApiPath.index, ApiPath.scene]);
 
     return (res.data?.sceneIndexes || []).map(
@@ -618,6 +1113,7 @@ export class RTStream {
           prompt: index.prompt,
           name: index.name,
           status: index.status,
+          sandboxId: index.sandboxId,
         })
     );
   };
@@ -630,7 +1126,7 @@ export class RTStream {
   public getSceneIndex = async (
     indexId: string
   ): Promise<RTStreamSceneIndex> => {
-    const res = await this.#vhttp.get<RTStreamSceneIndexBase>([
+    const res = await this.#vhttp.get<RTStreamSceneIndexData>([
       ApiPath.rtstream,
       this.id,
       ApiPath.index,
@@ -645,6 +1141,7 @@ export class RTStream {
       prompt: res.data.prompt,
       name: res.data.name,
       status: res.data.status,
+      sandboxId: res.data.sandboxId,
     });
   };
 
@@ -663,7 +1160,7 @@ export class RTStream {
    * @returns RTStreamSceneIndex object
    */
   public indexAudio = async (
-    config: Partial<IndexSpokenWordsConfig> = {}
+    config: Partial<IndexSpokenWordsConfig> & { sandboxId?: string } = {}
   ): Promise<RTStreamSceneIndex | null> => {
     let extractionConfig: Record<string, unknown> | undefined;
 
@@ -685,8 +1182,9 @@ export class RTStream {
     };
 
     if (config.socketId) data.ws_connection_id = config.socketId;
+    if (config.sandboxId) data.sandbox_id = config.sandboxId;
 
-    const res = await this.#vhttp.post<RTStreamSceneIndexBase, typeof data>(
+    const res = await this.#vhttp.post<RTStreamSceneIndexData, typeof data>(
       [ApiPath.rtstream, this.id, ApiPath.index, ApiPath.scene],
       data
     );
@@ -701,6 +1199,7 @@ export class RTStream {
       prompt: res.data.prompt,
       name: res.data.name,
       status: res.data.status,
+      sandboxId: res.data.sandboxId,
     });
   };
 
@@ -784,6 +1283,156 @@ export class RTStream {
     return res.data || {};
   };
 
+  /**
+   * Start a continuous VLM understanding job on the stream.
+   *
+   * Understanding is independent of indexing: it produces VLM output per
+   * stream window and (when `store=true`) persists it so it can be indexed
+   * later.
+   *
+   * @param options - Understanding configuration
+   * @param options.segmentation - Time segmentation, e.g. `{ type: 'time', window: '10s' }`
+   * @param options.analyzers - Analyzer specs (initially one `vlm` analyzer)
+   * @param options.store - Persist output for later indexing (default: `true`)
+   * @param options.wsConnectionId - WebSocket connection ID for real-time updates (optional)
+   * @returns The understanding job, RTStreamUnderstanding object
+   */
+  public understand = async (
+    options: {
+      segmentation?: Record<string, unknown>;
+      analyzers?: Record<string, unknown>[];
+      store?: boolean;
+      wsConnectionId?: string;
+    } = {}
+  ): Promise<RTStreamUnderstanding | null> => {
+    const data: Record<string, unknown> = {
+      segmentation: options.segmentation ?? {},
+      analyzers: options.analyzers ?? [],
+      store: options.store ?? true,
+    };
+    if (options.wsConnectionId) data.ws_connection_id = options.wsConnectionId;
+
+    const res = await this.#vhttp.post<RTStreamUnderstandingBase, typeof data>(
+      [ApiPath.rtstream, this.id, ApiPath.understand],
+      data
+    );
+
+    if (!res.data) return null;
+
+    const understandingData = res.data;
+    understandingData.rtstreamId = understandingData.rtstreamId ?? this.id;
+    return new RTStreamUnderstanding(this.#vhttp, understandingData);
+  };
+
+  /**
+   * Get an understanding job by id.
+   * @param understandingId - ID of the understanding job
+   * @returns The understanding job, RTStreamUnderstanding object
+   */
+  public getUnderstanding = async (
+    understandingId: string
+  ): Promise<RTStreamUnderstanding | null> => {
+    if (!understandingId) {
+      throw new VideodbError('understanding_id is required');
+    }
+    const res = await this.#vhttp.get<RTStreamUnderstandingBase>([
+      ApiPath.rtstream,
+      this.id,
+      ApiPath.understand,
+      understandingId,
+    ]);
+
+    if (!res.data) return null;
+
+    const understandingData = res.data;
+    understandingData.rtstreamId = understandingData.rtstreamId ?? this.id;
+    return new RTStreamUnderstanding(this.#vhttp, understandingData);
+  };
+
+  /**
+   * List all understanding jobs on the stream.
+   * @returns List of RTStreamUnderstanding objects
+   */
+  public listUnderstanding = async (): Promise<RTStreamUnderstanding[]> => {
+    const res = await this.#vhttp.get<{
+      understandings: RTStreamUnderstandingBase[];
+    }>([ApiPath.rtstream, this.id, ApiPath.understand]);
+
+    return (res.data?.understandings ?? []).map(item => {
+      item.rtstreamId = item.rtstreamId ?? this.id;
+      return new RTStreamUnderstanding(this.#vhttp, item);
+    });
+  };
+
+  /**
+   * Materialize an understanding output into a searchable index.
+   * @param options - Index configuration
+   * @param options.source - Understanding output descriptor, e.g. `understanding.outputs.scene`
+   * @param options.name - Index name (optional)
+   * @param options.useFor - Capabilities; defaults server-side to `['semantic']`
+   * @returns The index, RTStreamIndex object
+   */
+  public index = async (options: {
+    source: Record<string, unknown>;
+    name?: string;
+    useFor?: string[];
+  }): Promise<RTStreamIndex | null> => {
+    const data: Record<string, unknown> = { source: options.source };
+    if (options.name !== undefined) data.name = options.name;
+    if (options.useFor !== undefined) data.use_for = options.useFor;
+
+    const res = await this.#vhttp.post<RTStreamIndexBase, typeof data>(
+      [ApiPath.rtstream, this.id, ApiPath.indexes],
+      data
+    );
+
+    if (!res.data) return null;
+
+    const indexData = res.data;
+    indexData.rtstreamId = indexData.rtstreamId ?? this.id;
+    return new RTStreamIndex(this.#vhttp, indexData);
+  };
+
+  /**
+   * Get an index by id.
+   * @param indexId - ID of the index
+   * @returns RTStreamIndex object
+   */
+  public getIndex = async (indexId: string): Promise<RTStreamIndex | null> => {
+    if (!indexId) {
+      throw new VideodbError('index_id is required');
+    }
+    const res = await this.#vhttp.get<RTStreamIndexBase>([
+      ApiPath.rtstream,
+      this.id,
+      ApiPath.indexes,
+      indexId,
+    ]);
+
+    if (!res.data) return null;
+
+    const indexData = res.data;
+    indexData.rtstreamId = indexData.rtstreamId ?? this.id;
+    return new RTStreamIndex(this.#vhttp, indexData);
+  };
+
+  /**
+   * List all indexes on the stream.
+   * @returns List of RTStreamIndex objects
+   */
+  public listIndexes = async (): Promise<RTStreamIndex[]> => {
+    const res = await this.#vhttp.get<{ indexes: RTStreamIndexBase[] }>([
+      ApiPath.rtstream,
+      this.id,
+      ApiPath.indexes,
+    ]);
+
+    return (res.data?.indexes ?? []).map(item => {
+      item.rtstreamId = item.rtstreamId ?? this.id;
+      return new RTStreamIndex(this.#vhttp, item);
+    });
+  };
+
   /**
    * Search across scene index records for the rtstream
    * @param config - Search configuration
diff --git a/src/core/sandbox.ts b/src/core/sandbox.ts
new file mode 100644
index 0000000..fb9dda6
--- /dev/null
+++ b/src/core/sandbox.ts
@@ -0,0 +1,156 @@
+import { ApiPath, SandboxStatus } from '@/constants';
+import { RequestTimeoutError, VideodbError } from '@/utils/error';
+import { HttpClient } from '@/utils/httpClient';
+import { sleep } from '@/utils';
+
+const { sandbox } = ApiPath;
+
+const TERMINAL_STATUSES: string[] = [
+  SandboxStatus.stopped,
+  SandboxStatus.failed,
+];
+
+/**
+ * Plain-data shape a {@link Sandbox} is constructed from (camelCase).
+ */
+export interface SandboxBase {
+  id?: string;
+  sandboxId?: string;
+  tier?: string;
+  status?: string;
+  name?: string;
+  createdAt?: string;
+  startedAt?: string;
+  stoppedAt?: string;
+}
+
+/**
+ * A persistent GPU compute pool for running inference jobs.
+ * Mirrors `videodb.sandbox.Sandbox`.
+ *
+ * Create/list/get via {@link Connection}.
+ */
+export class Sandbox {
+  public id?: string;
+  public tier?: string;
+  public status?: string;
+  public name?: string;
+  public createdAt?: string;
+  public startedAt?: string;
+  public stoppedAt?: string;
+  #vhttp: HttpClient;
+
+  constructor(http: HttpClient, data: SandboxBase = {}) {
+    this.#vhttp = http;
+    this.id = data.sandboxId ?? data.id;
+    this.tier = data.tier;
+    this.status = data.status;
+    this.name = data.name;
+    this.createdAt = data.createdAt;
+    this.startedAt = data.startedAt;
+    this.stoppedAt = data.stoppedAt;
+  }
+
+  #update = (data?: SandboxBase): void => {
+    if (!data) return;
+    this.id = data.sandboxId ?? data.id ?? this.id;
+    this.tier = data.tier ?? this.tier;
+    this.status = data.status ?? this.status;
+    this.name = data.name ?? this.name;
+    this.createdAt = data.createdAt ?? this.createdAt;
+    this.startedAt = data.startedAt ?? this.startedAt;
+    this.stoppedAt = data.stoppedAt ?? this.stoppedAt;
+  };
+
+  /**
+   * Fetch latest sandbox state from the server.
+   */
+  public refresh = async (): Promise<Sandbox> => {
+    const res = await this.#vhttp.get<SandboxBase>([sandbox, this.id ?? '']);
+    this.#update(res.data);
+    return this;
+  };
+
+  /**
+   * Poll until the sandbox is active.
+   *
+   * @param timeout - Maximum seconds to wait (default 300)
+   * @param interval - Seconds between polls (default 5)
+   * @throws {RequestTimeoutError} If timeout is exceeded
+   * @throws {InvalidRequestError} If the sandbox enters a terminal state
+   */
+  public waitForReady = async (
+    timeout: number = 300,
+    interval: number = 5
+  ): Promise<Sandbox> => {
+    const deadline = Date.now() + timeout * 1000;
+    for (;;) {
+      await this.refresh();
+      if (this.status === SandboxStatus.active) return this;
+      if (this.status && TERMINAL_STATUSES.includes(this.status)) {
+        throw new VideodbError(
+          `Sandbox ${this.id} entered terminal state: ${this.status}`
+        );
+      }
+      if (Date.now() >= deadline) {
+        throw new RequestTimeoutError(
+          `Sandbox ${this.id} not ready within ${timeout}s`
+        );
+      }
+      await sleep(interval * 1000);
+    }
+  };
+
+  /**
+   * Stop this sandbox.
+   *
+   * @param grace - Wait for running jobs to finish before teardown (default true)
+   */
+  public stop = async (grace: boolean = true): Promise<Sandbox> => {
+    const res = await this.#vhttp.post<
+      { data?: SandboxBase },
+      { grace: boolean }
+    >([sandbox, this.id ?? '', ApiPath.stop], { grace });
+    this.#update(res.data?.data);
+    return this;
+  };
+
+  /**
+   * Poll until the sandbox is stopped.
+   *
+   * @param timeout - Maximum seconds to wait (default 120)
+   * @param interval - Seconds between polls (default 5)
+   * @throws {RequestTimeoutError} If timeout is exceeded
+   */
+  public waitForStop = async (
+    timeout: number = 120,
+    interval: number = 5
+  ): Promise<Sandbox> => {
+    const deadline = Date.now() + timeout * 1000;
+    for (;;) {
+      await this.refresh();
+      if (this.status && TERMINAL_STATUSES.includes(this.status)) return this;
+      if (Date.now() >= deadline) {
+        throw new RequestTimeoutError(
+          `Sandbox ${this.id} did not stop within ${timeout}s`
+        );
+      }
+      await sleep(interval * 1000);
+    }
+  };
+
+  public get isActive(): boolean {
+    return this.status === SandboxStatus.active;
+  }
+
+  public get isReady(): boolean {
+    return (
+      this.status === SandboxStatus.provisioning ||
+      this.status === SandboxStatus.active
+    );
+  }
+
+  public toString(): string {
+    return `Sandbox(id=${this.id}, tier=${this.tier}, status=${this.status}, name=${this.name})`;
+  }
+}
diff --git a/src/core/sandboxModels.ts b/src/core/sandboxModels.ts
new file mode 100644
index 0000000..1626a62
--- /dev/null
+++ b/src/core/sandboxModels.ts
@@ -0,0 +1,27 @@
+/**
+ * Model identifiers runnable on VideoDB sandbox compute.
+ * Mirrors `videodb.sandbox_models.SandboxModel`.
+ *
+ * Note: in the Python `str, Enum`, `OMNIVOICE_CANONICAL`/`FLUX_CANONICAL`
+ * are aliases of `OMNIVOICE`/`FLUX` (duplicate values). Here they are kept as
+ * distinct keys sharing the same string value.
+ */
+export const SandboxModel = {
+  // GenAI
+  FLUX: 'black-forest-labs/FLUX.1-dev',
+  OMNIVOICE: 'k2-fsa/OmniVoice',
+  // Small tier
+  GEMMA_4_E2B: 'google/gemma-4-E2B-it',
+  QWEN_9B: 'Qwen/Qwen3.5-9B',
+  WHISPER_LARGE_V3_TURBO: 'openai/whisper-large-v3-turbo',
+  OMNIVOICE_CANONICAL: 'k2-fsa/OmniVoice',
+  STABLE_AUDIO_OPEN: 'stabilityai/stable-audio-open-1.0',
+  // Medium tier
+  GEMMA_4_26B: 'google/gemma-4-26B-A4B-it',
+  QWEN_27B: 'Qwen/Qwen3.5-27B',
+  FLUX_CANONICAL: 'black-forest-labs/FLUX.1-dev',
+  GEMMA_4_31B: 'google/gemma-4-31B-it',
+} as const;
+
+export type SandboxModelValue =
+  (typeof SandboxModel)[keyof typeof SandboxModel];
diff --git a/src/core/scene.ts b/src/core/scene.ts
index 04d8479..4187b9d 100644
--- a/src/core/scene.ts
+++ b/src/core/scene.ts
@@ -40,13 +40,19 @@ export class Scene {
     this.#vhttp = http;
   }
 
-  public async describe(prompt?: string, modelName?: string, modelConfig?: Record<string, unknown>): Promise<string> {
+  public async describe(
+    prompt?: string,
+    modelName?: string,
+    modelConfig?: Record<string, unknown>,
+    sandboxId?: string
+  ): Promise<string> {
     const response = await this.#vhttp.post<{ description: string }, object>(
       [ApiPath.video, this.videoId, ApiPath.scene, this.id, ApiPath.describe],
       {
         prompt,
         model_name: modelName,
         model_config: modelConfig,
+        sandbox_id: sandboxId,
       }
     );
     this.description = response.data.description;
diff --git a/src/core/search/responses.ts b/src/core/search/responses.ts
new file mode 100644
index 0000000..892f5dc
--- /dev/null
+++ b/src/core/search/responses.ts
@@ -0,0 +1,127 @@
+import type { Shot } from '@/core/shot';
+import type { SearchResponse as RawSearchResponse } from '@/types/response';
+import type { SnakeKeysToCamelCase } from '@/utils';
+import { HttpClient } from '@/utils/httpClient';
+import { SearchResult } from './searchResult';
+
+type SearchResponseCamel = SnakeKeysToCamelCase<RawSearchResponse>;
+
+const _LEGACY_SEARCH_WARNING =
+  'Legacy search parameters detected. This call is routed to legacy search. ' +
+  'Use legacySearch(...) to keep legacy behavior, or update to the new search interface.';
+let _legacySearchWarningEmitted = false;
+
+/** Emit the legacy-search deprecation warning at most once per process. */
+export const warnLegacySearchOnce = (): void => {
+  if (_legacySearchWarningEmitted) return;
+  _legacySearchWarningEmitted = true;
+  // eslint-disable-next-line no-console
+  console.warn(_LEGACY_SEARCH_WARNING);
+};
+
+/** Data accepted by the {@link AskResponse} constructor (camelCased). */
+export interface AskResponseData {
+  answer?: string;
+  sources?: unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * Response returned by `ask()`.
+ * Mirrors `videodb.search.AskResponse`.
+ */
+export class AskResponse {
+  public answer: string;
+  public sources: Shot[];
+
+  constructor(http: HttpClient, data: AskResponseData = {}) {
+    this.answer = data.answer || '';
+    this.sources = new SearchResult(http, {
+      results: (data.sources || []) as SearchResponseCamel['results'],
+    }).shots;
+  }
+
+  public toString(): string {
+    return `AskResponse(answer=${JSON.stringify(this.answer)}, sources=[${this.sources.length}])`;
+  }
+}
+
+const SHOTS_TYPES = new Set(['shots', 'deepsearch']);
+
+/** Data accepted by the {@link SearchResponse} constructor (camelCased). */
+export interface SearchResponseData {
+  responseType?: string;
+  sessionId?: string;
+  waitingFor?: string;
+  clarification?: unknown;
+  trace?: unknown;
+  results?: unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * Envelope returned by high-level Search v2.
+ * Mirrors `videodb.search.SearchResponse`.
+ *
+ * For `responseType` of `shots`/`deepsearch`, `results` is a {@link SearchResult}.
+ * For `aggregate`, `results` is the aggregate dict/list returned by the server.
+ */
+export class SearchResponse implements Iterable<unknown> {
+  public responseType?: string;
+  public sessionId?: string;
+  public waitingFor: string;
+  public clarification?: unknown;
+  public trace?: unknown;
+  public results: unknown;
+  public shots: Shot[];
+
+  constructor(http: HttpClient, data: SearchResponseData = {}) {
+    this.responseType = data.responseType;
+    this.sessionId = data.sessionId;
+    this.waitingFor = (data.waitingFor as string) || 'none';
+    this.clarification = data.clarification;
+    this.trace = data.trace;
+    const rawResults = data.results ?? [];
+    if (this.responseType && SHOTS_TYPES.has(this.responseType)) {
+      const result = new SearchResult(http, {
+        results: rawResults as SearchResponseCamel['results'],
+      });
+      this.results = result;
+      this.shots = result.shots;
+    } else {
+      this.results = rawResults;
+      this.shots = [];
+    }
+  }
+
+  #isShots(): boolean {
+    return (
+      this.responseType !== undefined && SHOTS_TYPES.has(this.responseType)
+    );
+  }
+
+  [Symbol.iterator](): Iterator<unknown> {
+    if (this.#isShots()) {
+      return (this.results as SearchResult)[Symbol.iterator]();
+    }
+    if (Array.isArray(this.results)) {
+      return this.results[Symbol.iterator]();
+    }
+    return [this.results][Symbol.iterator]();
+  }
+
+  public get length(): number {
+    if (this.#isShots()) return (this.results as SearchResult).length;
+    if (Array.isArray(this.results)) return this.results.length;
+    return this.results !== null && this.results !== undefined ? 1 : 0;
+  }
+
+  public getShots = (): Shot[] => this.shots;
+
+  public toString(): string {
+    if (this.responseType === 'deepsearch') {
+      return `SearchResponse(responseType=${this.responseType}, sessionId=${JSON.stringify(this.sessionId)}, waitingFor=${JSON.stringify(this.waitingFor)}, clarification=${JSON.stringify(this.clarification)}, results=${String(this.results)})`;
+    }
+    return `SearchResponse(responseType=${this.responseType}, results=${String(this.results)})`;
+  }
+}
diff --git a/src/core/search/searchResult.ts b/src/core/search/searchResult.ts
index 804dbee..6c65a8d 100644
--- a/src/core/search/searchResult.ts
+++ b/src/core/search/searchResult.ts
@@ -1,14 +1,14 @@
 import { Shot } from '@/core/shot';
 import type { GenerateStreamResponse, SearchResponse } from '@/types/response';
 import type { SnakeKeysToCamelCase } from '@/utils';
-import { playStream } from '@/utils';
+import { buildIframeEmbedCode, playStream } from '@/utils';
 import { VideodbError } from '@/utils/error';
 import { HttpClient } from '@/utils/httpClient';
 
 /** Camelcase version of SearchResponse for internal use */
 type SearchResponseCamel = SnakeKeysToCamelCase<SearchResponse>;
 
-export class SearchResult {
+export class SearchResult implements Iterable<Shot> {
   #vhttp: HttpClient;
   #searchResponse: SearchResponseCamel;
   public shots: Shot[];
@@ -24,9 +24,9 @@ export class SearchResult {
   }
 
   #formatResults = () => {
-    for (const result of this.#searchResponse.results) {
+    for (const result of this.#searchResponse.results ?? []) {
       if (result.collectionId) this.collectionId = result.collectionId;
-      for (const doc of result.docs) {
+      for (const doc of result.docs ?? []) {
         this.shots.push(
           new Shot(this.#vhttp, {
             end: doc.end,
@@ -39,7 +39,7 @@ export class SearchResult {
             sceneIndexId: doc.sceneIndexId,
             sceneIndexName: doc.sceneIndexName,
             metadata: doc.metadata,
-            streamUrl: doc.streamLink,
+            streamUrl: doc.streamLink ?? doc.streamUrl,
             playerUrl: doc.playerUrl,
           })
         );
@@ -47,6 +47,16 @@ export class SearchResult {
     }
   };
 
+  [Symbol.iterator](): Iterator<Shot> {
+    return this.shots[Symbol.iterator]();
+  }
+
+  public get length(): number {
+    return this.shots.length;
+  }
+
+  public getShots = (): Shot[] => this.shots;
+
   compile = async () => {
     if (this.streamUrl) return this.streamUrl;
     else if (this.shots.length) {
@@ -75,4 +85,38 @@ export class SearchResult {
     }
     return playStream(this.streamUrl);
   };
+
+  /**
+   * Generate an HTML iframe embed code for the search result.
+   *
+   * @param width - Width of the iframe (default `"100%"`)
+   * @param height - Height of the iframe in pixels (default `405`)
+   * @param title - Title attribute (default `"VideoDB Player"`)
+   * @param allowFullscreen - Whether to allow fullscreen (default `true`)
+   * @param autoGenerate - If true and playerUrl is missing, auto-compile it (default `true`)
+   * @throws {VideodbError} If the player URL is not available.
+   */
+  getEmbedCode = async (
+    width: string = '100%',
+    height: number = 405,
+    title: string = 'VideoDB Player',
+    allowFullscreen: boolean = true,
+    autoGenerate: boolean = true
+  ): Promise<string> => {
+    if (!this.playerUrl && autoGenerate) {
+      await this.compile();
+    }
+    if (!this.playerUrl) {
+      throw new VideodbError(
+        'player_url not available. Call compile() first or set autoGenerate=true.'
+      );
+    }
+    return buildIframeEmbedCode(
+      this.playerUrl,
+      width,
+      height,
+      title,
+      allowFullscreen
+    );
+  };
 }
diff --git a/src/core/shot.ts b/src/core/shot.ts
index 10b6fe7..6f0a68b 100644
--- a/src/core/shot.ts
+++ b/src/core/shot.ts
@@ -2,7 +2,8 @@ import { ApiPath } from '@/constants';
 import type { IShot, ShotBase } from '@/interfaces/core';
 import type { GenerateStreamResponse } from '@/types/response';
 import type { Timeline } from '@/types/video';
-import { playStream } from '@/utils';
+import { buildIframeEmbedCode, playStream } from '@/utils';
+import { VideodbError } from '@/utils/error';
 import { HttpClient } from '@/utils/httpClient';
 
 const { video, stream } = ApiPath;
@@ -74,4 +75,37 @@ export class Shot implements IShot {
     const streamUrl = await this.generateStream();
     return playStream(streamUrl);
   };
+
+  /**
+   * Generate an HTML iframe embed code for the shot.
+   * @param width - Width of the iframe (default `"100%"`)
+   * @param height - Height of the iframe in pixels (default `405`)
+   * @param title - Title attribute (default `"VideoDB Player"`)
+   * @param allowFullscreen - Whether to allow fullscreen (default `true`)
+   * @param autoGenerate - If true and playerUrl is missing, auto-generate it (default `true`)
+   * @throws {VideodbError} If the player URL is not available.
+   */
+  getEmbedCode = async (
+    width: string = '100%',
+    height: number = 405,
+    title: string = 'VideoDB Player',
+    allowFullscreen: boolean = true,
+    autoGenerate: boolean = true
+  ): Promise<string> => {
+    if (!this.playerUrl && autoGenerate) {
+      await this.generateStream();
+    }
+    if (!this.playerUrl) {
+      throw new VideodbError(
+        'player_url not available. Call generateStream() first or set autoGenerate=true.'
+      );
+    }
+    return buildIframeEmbedCode(
+      this.playerUrl,
+      width,
+      height,
+      title,
+      allowFullscreen
+    );
+  };
 }
diff --git a/src/core/timeline.ts b/src/core/timeline.ts
index 7865660..23093a2 100644
--- a/src/core/timeline.ts
+++ b/src/core/timeline.ts
@@ -1,5 +1,7 @@
 import { ApiPath } from '@/constants';
 import { GenerateStreamResponse } from '@/types/response';
+import { buildIframeEmbedCode } from '@/utils';
+import { VideodbError } from '@/utils/error';
 import { HttpClient } from '@/utils/httpClient';
 import { AudioAsset, VideoAsset, ImageAsset, TextAsset } from './asset';
 import { Connection } from './connection';
@@ -21,7 +23,7 @@ export class Timeline implements ITimeline {
   constructor(connection: Connection) {
     console.warn(
       'Timeline from videodb/core/timeline is deprecated and will be removed in a future release. ' +
-      'Use EditorTimeline from videodb/core/editor instead.'
+        'Use EditorTimeline from videodb/core/editor instead.'
     );
     this.#vhttp = connection.vhttp;
     this.timeline = [];
@@ -80,4 +82,37 @@ export class Timeline implements ITimeline {
     this.playerUrl = streamDataRes.data.playerUrl;
     return this.streamUrl;
   }
+
+  /**
+   * Generate an HTML iframe embed code for the timeline.
+   * @param width - Width of the iframe (default `"100%"`)
+   * @param height - Height of the iframe in pixels (default `405`)
+   * @param title - Title attribute (default `"VideoDB Player"`)
+   * @param allowFullscreen - Whether to allow fullscreen (default `true`)
+   * @param autoGenerate - If true and playerUrl is missing, auto-generate it (default `true`)
+   * @throws {VideodbError} If the player URL is not available.
+   */
+  async getEmbedCode(
+    width: string = '100%',
+    height: number = 405,
+    title: string = 'VideoDB Player',
+    allowFullscreen: boolean = true,
+    autoGenerate: boolean = true
+  ): Promise<string> {
+    if (!this.playerUrl && autoGenerate) {
+      await this.generateStream();
+    }
+    if (!this.playerUrl) {
+      throw new VideodbError(
+        'player_url not available. Call generateStream() first or set autoGenerate=true.'
+      );
+    }
+    return buildIframeEmbedCode(
+      this.playerUrl,
+      width,
+      height,
+      title,
+      allowFullscreen
+    );
+  }
 }
diff --git a/src/core/understanding.ts b/src/core/understanding.ts
new file mode 100644
index 0000000..9e98517
--- /dev/null
+++ b/src/core/understanding.ts
@@ -0,0 +1,406 @@
+import { ApiPath } from '@/constants';
+import { RequestTimeoutError } from '@/utils/error';
+import { HttpClient } from '@/utils/httpClient';
+import { sleep } from '@/utils';
+
+const { video, understand } = ApiPath;
+
+export const UNDERSTANDING_TERMINAL_STATUSES = new Set(['done', 'failed']);
+export const ANALYZER_TERMINAL_STATUSES = new Set([
+  'done',
+  'failed',
+  'skipped',
+  'cancelled',
+]);
+
+export const ANALYZER_TYPE_ALIASES: Record<string, string> = {
+  spoken_words: 'speech_transcription',
+};
+
+export const DEFAULT_ANALYZER_NAMES: Record<string, string> = {
+  speech_transcription: 'transcript',
+  object_detection: 'objects',
+  vlm: 'scene',
+  ocr: 'text',
+  brand_detection: 'brands',
+  activity_recognition: 'activity',
+  location_detection: 'location',
+};
+
+/** A user-provided analyzer spec passed to `Video.understand`. */
+export interface AnalyzerSpec {
+  type?: string;
+  name?: string;
+  [key: string]: unknown;
+}
+
+/** Camelcased wire shape of an analyzer inside an understanding run. */
+export interface AnalyzerData {
+  id?: string;
+  name?: string;
+  type?: string;
+  status?: string;
+  [key: string]: unknown;
+}
+
+/** Map a friendly analyzer type to the server contract name. */
+export const normalizeAnalyzerType = (analyzerType: string): string =>
+  ANALYZER_TYPE_ALIASES[analyzerType] ?? analyzerType;
+
+/** Stable default output name for a built-in analyzer, or undefined. */
+export const defaultAnalyzerName = (analyzerType: string): string | undefined =>
+  DEFAULT_ANALYZER_NAMES[normalizeAnalyzerType(analyzerType)];
+
+/**
+ * Normalize analyzer payloads to the server contract.
+ * Mirrors `videodb.understanding.normalize_understanding_analyzers`.
+ *
+ * @throws {Error} On empty list, missing type, or duplicate/ambiguous names.
+ */
+export const normalizeUnderstandingAnalyzers = (
+  analyzers: AnalyzerSpec[]
+): AnalyzerSpec[] => {
+  if (!Array.isArray(analyzers) || analyzers.length === 0) {
+    throw new Error('analyzers must be a non-empty list');
+  }
+
+  const normalized: AnalyzerSpec[] = [];
+  const names = new Set<string>();
+  const generatedNames = new Set<string>();
+
+  analyzers.forEach((analyzer, index) => {
+    if (
+      typeof analyzer !== 'object' ||
+      analyzer === null ||
+      Array.isArray(analyzer)
+    ) {
+      throw new Error(`analyzers[${index}] must be a dict`);
+    }
+    if (!analyzer.type) {
+      throw new Error(`analyzers[${index}].type is required`);
+    }
+
+    const item: AnalyzerSpec = { ...analyzer };
+    const originalType = item.type as string;
+    item.type = normalizeAnalyzerType(originalType);
+
+    if (!item.name) {
+      const generatedName = defaultAnalyzerName(originalType);
+      if (generatedName) {
+        if (generatedNames.has(generatedName)) {
+          throw new Error(
+            `Multiple analyzers would use default name '${generatedName}'. Provide explicit analyzer names.`
+          );
+        }
+        item.name = generatedName;
+        generatedNames.add(generatedName);
+      }
+    }
+
+    if (item.name) {
+      if (names.has(item.name)) {
+        throw new Error(`Duplicate analyzer name: ${item.name}`);
+      }
+      names.add(item.name);
+    }
+
+    normalized.push(item);
+  });
+
+  return normalized;
+};
+
+/**
+ * Analyzer status and output handle for one analyzer in an understanding run.
+ * Mirrors `videodb.understanding.UnderstandingAnalyzer`.
+ */
+export class UnderstandingAnalyzer {
+  public understanding: Understanding;
+  public id?: string;
+  public name?: string;
+  public type?: string;
+  public status?: string;
+  public extra: Record<string, unknown>;
+
+  constructor(understanding: Understanding, data: AnalyzerData = {}) {
+    const { id, name, type, status, ...extra } = data;
+    this.understanding = understanding;
+    this.id = id;
+    this.name = name;
+    this.type = type;
+    this.status = status;
+    this.extra = extra;
+  }
+
+  /** True when the analyzer is in a terminal status. */
+  public get isComplete(): boolean {
+    return (
+      this.status !== undefined && ANALYZER_TERMINAL_STATUSES.has(this.status)
+    );
+  }
+
+  /** True when the analyzer completed successfully. */
+  public get isSuccessful(): boolean {
+    return this.status === 'done';
+  }
+
+  /** Refresh this analyzer's status from the API. */
+  public refresh = async (): Promise<UnderstandingAnalyzer> => {
+    const analyzer = await this.understanding.getAnalyzer(
+      this.name || this.id || '',
+      true
+    );
+    this.id = analyzer.id;
+    this.name = analyzer.name;
+    this.type = analyzer.type;
+    this.status = analyzer.status;
+    this.extra = analyzer.extra;
+    return this;
+  };
+
+  /**
+   * Poll this analyzer until it reaches a terminal status.
+   *
+   * @param timeout - Maximum time to wait, in seconds (default 1800)
+   * @param pollInterval - Seconds between status checks (default 10)
+   * @throws {RequestTimeoutError} If the analyzer does not complete before timeout
+   */
+  public waitUntilComplete = async (
+    timeout: number = 1800,
+    pollInterval: number = 10
+  ): Promise<UnderstandingAnalyzer> => {
+    const deadline = Date.now() + timeout * 1000;
+    for (;;) {
+      await this.refresh();
+      if (this.isComplete) return this;
+      if (Date.now() >= deadline) {
+        throw new RequestTimeoutError(
+          `Analyzer ${this.name || this.id} did not complete within ${timeout}s`
+        );
+      }
+      await sleep(pollInterval * 1000);
+    }
+  };
+
+  /** Return this analyzer's output (segments output). */
+  public getOutput = async (): Promise<unknown> => {
+    const identifier = this.name || this.id;
+    if (!identifier) {
+      throw new Error('Analyzer id or name is required');
+    }
+    return this.understanding.getAnalyzerOutput(identifier);
+  };
+
+  /**
+   * Serialize this analyzer as an index `source` reference (ids + type).
+   * The server re-fetches the analyzer output from its own store.
+   *
+   * @throws {Error} If the analyzer has no id or its understanding id is unknown.
+   */
+  public toIndexSource = (): {
+    understanding_id: string;
+    analyzer_id: string;
+    analyzer_type?: string;
+  } => {
+    const understandingId = this.understanding.id;
+    if (!understandingId || !this.id) {
+      throw new Error(
+        'analyzer source requires understanding id and analyzer id'
+      );
+    }
+    return {
+      understanding_id: understandingId,
+      analyzer_id: this.id,
+      analyzer_type: this.type,
+    };
+  };
+
+  public toString(): string {
+    return `UnderstandingAnalyzer(id=${this.id}, name=${this.name}, type=${this.type}, status=${this.status})`;
+  }
+}
+
+/** Camelcased wire shape of an understanding run. */
+export interface UnderstandingData {
+  understandingId?: string;
+  id?: string;
+  videoId?: string;
+  collectionId?: string;
+  status?: string;
+  outputUrl?: string;
+  analyzers?: AnalyzerData[];
+  [key: string]: unknown;
+}
+
+/**
+ * A video understanding run.
+ * Mirrors `videodb.understanding.Understanding`.
+ */
+export class Understanding {
+  public videoId: string;
+  public collectionId?: string;
+  public id?: string;
+  public status?: string;
+  public outputUrl?: string;
+  public extra: Record<string, unknown>;
+  public analyzers: UnderstandingAnalyzer[];
+  #vhttp: HttpClient;
+
+  constructor(http: HttpClient, videoId: string, data: UnderstandingData = {}) {
+    const {
+      understandingId,
+      id,
+      videoId: _videoId,
+      collectionId,
+      status,
+      outputUrl,
+      analyzers,
+      ...extra
+    } = data;
+    this.#vhttp = http;
+    this.videoId = _videoId ?? videoId;
+    this.collectionId = collectionId;
+    this.id = understandingId ?? id;
+    this.status = status;
+    this.outputUrl = outputUrl;
+    this.extra = extra;
+    this.analyzers = (analyzers ?? []).map(item => this.createAnalyzer(item));
+  }
+
+  /** True when the understanding run is in a terminal status. */
+  public get isComplete(): boolean {
+    return (
+      this.status !== undefined &&
+      UNDERSTANDING_TERMINAL_STATUSES.has(this.status)
+    );
+  }
+
+  /** True when the understanding run completed successfully. */
+  public get isSuccessful(): boolean {
+    return this.status === 'done';
+  }
+
+  public createAnalyzer(data: AnalyzerData = {}): UnderstandingAnalyzer {
+    return new UnderstandingAnalyzer(this, data || {});
+  }
+
+  public updateFromResponse(data: UnderstandingData = {}): Understanding {
+    this.status = data.status ?? this.status;
+    if (data.understandingId || data.id) {
+      this.id = data.understandingId ?? data.id;
+    }
+    if (data.videoId) this.videoId = data.videoId;
+    if (data.collectionId) this.collectionId = data.collectionId;
+    if (data.outputUrl) this.outputUrl = data.outputUrl;
+    if ('analyzers' in data) {
+      this.analyzers = (data.analyzers ?? []).map(item =>
+        this.createAnalyzer(item)
+      );
+    }
+    return this;
+  }
+
+  /** Refresh understanding and analyzer statuses from the API. */
+  public refresh = async (): Promise<Understanding> => {
+    const res = await this.#vhttp.get<UnderstandingData>([
+      video,
+      this.videoId,
+      understand,
+      this.id ?? '',
+    ]);
+    return this.updateFromResponse(res.data);
+  };
+
+  /**
+   * Poll this understanding until it reaches a terminal status (`done`/`failed`).
+   *
+   * @param timeout - Maximum time to wait, in seconds (default 1800)
+   * @param pollInterval - Seconds between status checks (default 10)
+   * @throws {RequestTimeoutError} If the run does not complete before timeout
+   */
+  public waitUntilComplete = async (
+    timeout: number = 1800,
+    pollInterval: number = 10
+  ): Promise<Understanding> => {
+    const deadline = Date.now() + timeout * 1000;
+    for (;;) {
+      await this.refresh();
+      if (this.isComplete) return this;
+      if (Date.now() >= deadline) {
+        throw new RequestTimeoutError(
+          `Understanding ${this.id} did not complete within ${timeout}s`
+        );
+      }
+      await sleep(pollInterval * 1000);
+    }
+  };
+
+  /** Return analyzers in this understanding run. */
+  public listAnalyzers = (): UnderstandingAnalyzer[] => [...this.analyzers];
+
+  /**
+   * Return an analyzer by user-facing name or internal analyzer id.
+   *
+   * @param nameOrId - Analyzer name (e.g. `"transcript"`) or id (e.g. `"an_..."`)
+   * @param refresh - When true, fetch the latest analyzer status first
+   * @throws {Error} If no analyzer matches
+   */
+  public getAnalyzer = async (
+    nameOrId: string,
+    refresh: boolean = false
+  ): Promise<UnderstandingAnalyzer> => {
+    if (refresh) {
+      const res = await this.#vhttp.get<UnderstandingData>(
+        [video, this.videoId, understand, this.id ?? ''],
+        { params: { analyzer: nameOrId } }
+      );
+      const data = res.data ?? {};
+      this.status = data.status ?? this.status;
+      const analyzerData = (data.analyzers ?? [])[0];
+      if (analyzerData) {
+        const refreshed = this.createAnalyzer(analyzerData);
+        for (let i = 0; i < this.analyzers.length; i++) {
+          if (
+            this.analyzers[i].name === refreshed.name ||
+            this.analyzers[i].id === refreshed.id
+          ) {
+            this.analyzers[i] = refreshed;
+            return refreshed;
+          }
+        }
+        this.analyzers.push(refreshed);
+        return refreshed;
+      }
+    }
+
+    for (const analyzer of this.analyzers) {
+      if (analyzer.name === nameOrId || analyzer.id === nameOrId) {
+        return analyzer;
+      }
+    }
+    throw new Error(`Analyzer not found: ${nameOrId}`);
+  };
+
+  /** Return output for an analyzer by name or id. */
+  public getAnalyzerOutput = async (nameOrId: string): Promise<unknown> => {
+    const res = await this.#vhttp.get<unknown>([
+      video,
+      this.videoId,
+      understand,
+      this.id ?? '',
+      'analyzers',
+      nameOrId,
+      'output',
+    ]);
+    return res.data;
+  };
+
+  /** Delete this understanding run. */
+  public delete = async (): Promise<void> => {
+    await this.#vhttp.delete([video, this.videoId, understand, this.id ?? '']);
+  };
+
+  public toString(): string {
+    return `Understanding(id=${this.id}, videoId=${this.videoId}, status=${this.status}, analyzers=${this.analyzers.length})`;
+  }
+}
diff --git a/src/core/video.ts b/src/core/video.ts
index 892c31f..cf8901e 100644
--- a/src/core/video.ts
+++ b/src/core/video.ts
@@ -13,6 +13,13 @@ import type {
   ImageBase,
 } from '@/interfaces/core';
 import { Frame, Image } from '@/core/image';
+import { Index, type RawIndexManifest } from '@/core/indexManifest';
+import {
+  Understanding,
+  normalizeUnderstandingAnalyzers,
+  type AnalyzerSpec,
+  type UnderstandingData,
+} from '@/core/understanding';
 import { Scene, SceneCollection } from '@/core/scene';
 import {
   ListSceneIndex,
@@ -26,7 +33,12 @@ import {
   NoDataResponse,
 } from '@/types/response';
 import type { Timeline, Transcript } from '@/types/video';
-import { fromCamelToSnake, playStream, SnakeKeysToCamelCase } from '@/utils';
+import {
+  buildIframeEmbedCode,
+  fromCamelToSnake,
+  playStream,
+  SnakeKeysToCamelCase,
+} from '@/utils';
 import { HttpClient } from '@/utils/httpClient';
 import {
   DefaultIndexType,
@@ -37,6 +49,14 @@ import {
 } from '@/core/config';
 import { SearchFactory } from './search';
 import { SearchResult } from './search/searchResult';
+import {
+  AskResponse,
+  SearchResponse,
+  warnLegacySearchOnce,
+  type AskResponseData,
+  type SearchResponseData,
+} from './search/responses';
+import type { SearchResponse as SearchApiResponse } from '@/types/response';
 import {
   ExtractSceneConfig,
   IndexSceneConfig,
@@ -64,9 +84,59 @@ const {
   compile,
   collection,
   clip,
+  understand,
+  indexes,
+  ask,
+  semantic_search,
+  query: queryPath,
+  aggregate,
+  search: searchPath,
 } = ApiPath;
 
-const VALID_SEGMENTERS: Set<string> = new Set([Segmenter.word, Segmenter.sentence, Segmenter.time]);
+const VALID_SEGMENTERS: Set<string> = new Set([
+  Segmenter.word,
+  Segmenter.sentence,
+  Segmenter.time,
+]);
+
+/**
+ * Options for {@link Video.search}. Combines new-style (v2) params with
+ * legacy-shaped params; passing any legacy param routes the call to
+ * {@link Video.legacySearch}.
+ */
+export interface VideoSearchOptions {
+  // legacy-shaped
+  searchType?: SearchType;
+  indexType?: IndexType;
+  resultThreshold?: number;
+  scoreThreshold?: number;
+  dynamicScorePercentage?: number;
+  filter?: Array<Record<string, unknown>>;
+  sortDocsOn?: string;
+  sceneIndexId?: string;
+  indexId?: string;
+  algorithm?: string;
+  namespace?: string;
+  // new (v2)
+  topK?: number;
+  mode?: string;
+  returnFields?: unknown[] | Record<string, unknown> | string;
+  includeClip?: boolean;
+  sessionId?: string;
+  config?: Record<string, unknown>;
+  // unsupported in search() — surfaced for a clear error
+  indexName?: string;
+  indexNames?: string[] | string;
+  indexIds?: string[] | string;
+  // internal — rejected
+  deepsearchConfig?: unknown;
+}
+
+/** Accepted `source` shapes for {@link Video.index}. */
+export type IndexSource =
+  | { toIndexSource: () => Record<string, unknown> }
+  | Record<string, unknown>
+  | unknown[];
 
 /**
  * The base Video class
@@ -80,9 +150,9 @@ export class Video implements IVideo {
   public name: string;
   public readonly description?: string;
   public readonly size: string;
-  public readonly streamUrl: string;
+  public streamUrl: string;
   public readonly userId: string;
-  public readonly playerUrl: string;
+  public playerUrl: string;
   public thumbnail?: string;
   public transcript?: Transcript;
   #vhttp: HttpClient;
@@ -107,7 +177,220 @@ export class Video implements IVideo {
   }
 
   /**
-   * Search for a query in the video
+   * Search this video.
+   *
+   * New search is used by default. Calls that pass legacy-shaped parameters are
+   * routed to {@link legacySearch} with a one-time warning.
+   * @param query - Search query
+   * @param options - Search options (new-style, or legacy-shaped)
+   */
+  public search = async (
+    query: string,
+    options: VideoSearchOptions = {}
+  ): Promise<SearchResponse | SearchResult> => {
+    const oldParams: (keyof VideoSearchOptions)[] = [
+      'searchType',
+      'indexType',
+      'resultThreshold',
+      'dynamicScorePercentage',
+      'sceneIndexId',
+      'indexId',
+      'algorithm',
+      'sortDocsOn',
+      'namespace',
+    ];
+    const newParams: (keyof VideoSearchOptions)[] = [
+      'topK',
+      'mode',
+      'returnFields',
+      'includeClip',
+      'sessionId',
+      'config',
+    ];
+    const unsupported: (keyof VideoSearchOptions)[] = [
+      'indexName',
+      'indexNames',
+      'indexId',
+      'indexIds',
+    ];
+
+    const hasOld = oldParams.some(
+      k => options[k] !== undefined && options[k] !== null
+    );
+    const hasNew = newParams.some(
+      k => options[k] !== undefined && options[k] !== null
+    );
+    const hasUnsupported = unsupported.some(
+      k => options[k] !== undefined && options[k] !== null
+    );
+
+    if (options.deepsearchConfig != null) {
+      throw new VideodbError(
+        'deepsearchConfig is internal and cannot be passed to search().'
+      );
+    }
+    if (hasOld && (hasNew || hasUnsupported)) {
+      throw new VideodbError(
+        'Cannot mix legacy search params with new search params. ' +
+          'Use search(...) for new search or legacySearch(...) for legacy search.'
+      );
+    }
+    if (hasUnsupported) {
+      throw new VideodbError(
+        'indexName/indexNames/indexId/indexIds are not supported in search(). ' +
+          'Use semanticSearch(), query(), or aggregate() for index-specific calls.'
+      );
+    }
+
+    if (hasOld) {
+      warnLegacySearchOnce();
+      return this.legacySearch(
+        query,
+        options.searchType,
+        options.indexType,
+        options.resultThreshold,
+        options.scoreThreshold,
+        options.dynamicScorePercentage,
+        options.filter,
+        options.sortDocsOn
+      );
+    }
+
+    return this.#newSearch(query, options);
+  };
+
+  #newSearch = async (
+    query: string,
+    options: VideoSearchOptions
+  ): Promise<SearchResponse> => {
+    const payload: Record<string, unknown> = { query };
+    if (options.topK != null) payload.top_k = options.topK;
+    if (options.mode != null) payload.mode = options.mode;
+    if (options.returnFields != null)
+      payload.return_fields = options.returnFields;
+    if (options.includeClip != null) payload.include_clip = options.includeClip;
+    if (options.sessionId != null) payload.session_id = options.sessionId;
+    if (options.config != null) payload.config = options.config;
+    const res = await this.#vhttp.post<Record<string, unknown>, typeof payload>(
+      [video, this.id, searchPath, 'v2'],
+      payload
+    );
+    return new SearchResponse(this.#vhttp, res.data as SearchResponseData);
+  };
+
+  /**
+   * Ask a question and get an answer generated from retrieved video context.
+   * @param question - The question to answer
+   * @param topK - Number of context chunks to retrieve (default 15)
+   * @param mode - Retrieval/answer mode (default `"default"`)
+   * @param includeSources - Whether to include source shots (default false)
+   */
+  public ask = async (
+    question: string,
+    topK: number = 15,
+    mode: string = 'default',
+    includeSources: boolean = false
+  ): Promise<AskResponse> => {
+    const res = await this.#vhttp.post<Record<string, unknown>, object>(
+      [video, this.id, ask],
+      { question, top_k: topK, mode, include_sources: includeSources }
+    );
+    return new AskResponse(this.#vhttp, res.data as AskResponseData);
+  };
+
+  /**
+   * Semantic search across one or more indexes on this video.
+   */
+  public semanticSearch = async (
+    query: string,
+    options: {
+      indexNames?: string[] | string;
+      topK?: number;
+      scoreThreshold?: number;
+      filter?: unknown[] | Record<string, unknown>;
+      returnFields?: unknown[] | Record<string, unknown> | string;
+      indexIds?: string[] | string;
+    } = {}
+  ): Promise<SearchResult> => {
+    const res = await this.#vhttp.post<SearchApiResponse, object>(
+      [video, this.id, semantic_search],
+      {
+        query,
+        index_names: options.indexNames,
+        index_ids: options.indexIds,
+        top_k: options.topK ?? 10,
+        score_threshold: options.scoreThreshold,
+        filter: options.filter,
+        return_fields: options.returnFields,
+      }
+    );
+    return new SearchResult(this.#vhttp, res.data);
+  };
+
+  /**
+   * Structured query against an index on this video.
+   */
+  public query = async (
+    options: {
+      indexName?: string;
+      filter?: unknown[] | Record<string, unknown>;
+      limit?: number;
+      returnFields?: unknown[] | Record<string, unknown> | string;
+      sort?: string | [string, string][];
+      indexId?: string;
+    } = {}
+  ): Promise<SearchResult> => {
+    const res = await this.#vhttp.post<SearchApiResponse, object>(
+      [video, this.id, queryPath],
+      {
+        index_name: options.indexName,
+        index_id: options.indexId,
+        filter: options.filter,
+        limit: options.limit ?? 100,
+        return_fields: options.returnFields,
+        sort: options.sort,
+      }
+    );
+    return new SearchResult(this.#vhttp, res.data);
+  };
+
+  /**
+   * Aggregate over an index on this video.
+   */
+  public aggregate = async (
+    options: {
+      indexName?: string;
+      filter?: unknown[] | Record<string, unknown>;
+      groupBy?: string;
+      metric?: string;
+      limit?: number;
+      sort?: string | [string, string][];
+      indexId?: string;
+    } = {}
+  ): Promise<Record<string, unknown> | Record<string, unknown>[]> => {
+    // convert:false — aggregate buckets are keyed by user field names/values.
+    const res = await this.#vhttp.post<
+      Record<string, unknown> | Record<string, unknown>[],
+      object
+    >(
+      [video, this.id, aggregate],
+      {
+        index_name: options.indexName,
+        index_id: options.indexId,
+        filter: options.filter,
+        group_by: options.groupBy,
+        metric: options.metric ?? 'count',
+        limit: options.limit ?? 100,
+        sort: options.sort,
+      },
+      undefined,
+      { convert: false }
+    );
+    return res.data;
+  };
+
+  /**
+   * Legacy search (pre-v2). Delegates to the {@link SearchFactory}.
    * @param query - Search query
    * @param searchType - [optional] Type of search to be performed
    * @param indexType - [optional] Index Type
@@ -117,7 +400,7 @@ export class Video implements IVideo {
    * @param filter - [optional] Additional metadata filters
    * @param sortDocsOn - [optional] Sort docs within each video by "score" or "start"
    */
-  public search = async (
+  public legacySearch = async (
     query: string,
     searchType?: SearchType,
     indexType?: IndexType,
@@ -126,7 +409,7 @@ export class Video implements IVideo {
     dynamicScorePercentage?: number,
     filter?: Array<Record<string, unknown>>,
     sortDocsOn?: string
-  ) => {
+  ): Promise<SearchResult> => {
     const s = new SearchFactory(this.#vhttp);
     const searchFunc = s.getSearch(searchType ?? DefaultSearchType);
     const results = await searchFunc.searchInsideVideo({
@@ -151,10 +434,10 @@ export class Video implements IVideo {
   public update = async (options: { name?: string }) => {
     const data: Record<string, unknown> = {};
     if (options.name !== undefined) data.name = options.name;
-    const res = await this.#vhttp.patch<{ id: string; name: string }, typeof data>(
-      [video, this.id],
-      data
-    );
+    const res = await this.#vhttp.patch<
+      { id: string; name: string },
+      typeof data
+    >([video, this.id], data);
     if (options.name !== undefined) this.name = res.data.name ?? options.name;
   };
 
@@ -187,6 +470,8 @@ export class Video implements IVideo {
       body
     );
 
+    this.streamUrl = res.data.streamUrl;
+    if (res.data.playerUrl) this.playerUrl = res.data.playerUrl;
     return res.data.streamUrl;
   };
 
@@ -385,14 +670,16 @@ export class Video implements IVideo {
     };
 
     const payload: Record<string, unknown> = { ...defaultConfig };
-    if (config.extractionType !== undefined) payload.extraction_type = config.extractionType;
-    if (config.extractionConfig !== undefined) payload.extraction_config = config.extractionConfig;
+    if (config.extractionType !== undefined)
+      payload.extraction_type = config.extractionType;
+    if (config.extractionConfig !== undefined)
+      payload.extraction_config = config.extractionConfig;
     if (config.force !== undefined) payload.force = config.force;
 
-    const res = await this.#vhttp.post<
-      SceneCollectionResponse,
-      typeof payload
-    >([video, this.id, scenes], payload);
+    const res = await this.#vhttp.post<SceneCollectionResponse, typeof payload>(
+      [video, this.id, scenes],
+      payload
+    );
 
     return this._formatSceneCollectionData(res.data.sceneCollection);
   };
@@ -447,9 +734,12 @@ export class Video implements IVideo {
     if (config.prompt !== undefined) payload.prompt = config.prompt;
     if (config.metadata !== undefined) payload.metadata = config.metadata;
     if (config.modelName !== undefined) payload.model_name = config.modelName;
-    if (config.modelConfig !== undefined) payload.model_config = config.modelConfig;
+    if (config.modelConfig !== undefined)
+      payload.model_config = config.modelConfig;
     if (config.name !== undefined) payload.name = config.name;
-    if (config.callbackUrl !== undefined) payload.callback_url = config.callbackUrl;
+    if (config.callbackUrl !== undefined)
+      payload.callback_url = config.callbackUrl;
+    if (config.sandboxId !== undefined) payload.sandbox_id = config.sandboxId;
     if (config.scenes) {
       payload.scenes = config.scenes.map((s: Scene) => s.getRequestData());
     }
@@ -522,6 +812,7 @@ export class Video implements IVideo {
     modelConfig?: Record<string, unknown>;
     name?: string;
     callbackUrl?: string;
+    sandboxId?: string;
   }): Promise<string | undefined> => {
     const {
       prompt,
@@ -530,6 +821,7 @@ export class Video implements IVideo {
       modelConfig = {},
       name,
       callbackUrl,
+      sandboxId,
     } = config ?? {};
 
     const extractionType = batchConfig.type ?? 'time';
@@ -561,6 +853,7 @@ export class Video implements IVideo {
         model_config: modelConfig,
         name,
         callback_url: callbackUrl,
+        sandbox_id: sandboxId,
       }
     );
 
@@ -630,13 +923,249 @@ export class Video implements IVideo {
     return res.data?.sceneIndexId;
   };
 
+  /**
+   * Create an understanding run for this video.
+   * @param analyzers - Analyzer definitions. The SDK accepts the friendly
+   *   analyzer type `spoken_words` and maps it to the server analyzer.
+   * @param options - Optional run-level config (segmentation/sampling/transform/
+   *   audioChunking/callbackUrl) plus any extra fields.
+   */
+  public understand = async (
+    analyzers: AnalyzerSpec[],
+    options: {
+      segmentation?: Record<string, unknown>;
+      sampling?: Record<string, unknown>;
+      transform?: Record<string, unknown>;
+      audioChunking?: Record<string, unknown>;
+      callbackUrl?: string;
+      [key: string]: unknown;
+    } = {}
+  ): Promise<Understanding> => {
+    const normalized = normalizeUnderstandingAnalyzers(analyzers);
+    const payload: Record<string, unknown> = { analyzers: normalized };
+    if (options.segmentation != null)
+      payload.segmentation = options.segmentation;
+    if (options.sampling != null) payload.sampling = options.sampling;
+    if (options.transform != null) payload.transform = options.transform;
+    if (options.audioChunking != null)
+      payload.audio_chunking = options.audioChunking;
+    if (options.callbackUrl != null) payload.callback_url = options.callbackUrl;
+    for (const [key, value] of Object.entries(options)) {
+      if (
+        ![
+          'segmentation',
+          'sampling',
+          'transform',
+          'audioChunking',
+          'callbackUrl',
+        ].includes(key) &&
+        value != null
+      ) {
+        payload[key] = value;
+      }
+    }
+
+    const res = await this.#vhttp.post<UnderstandingData, typeof payload>(
+      [video, this.id, understand],
+      payload
+    );
+    const data: UnderstandingData = res.data ?? {};
+    if (!data.analyzers) {
+      data.analyzers = normalized.map(a => ({
+        name: a.name,
+        type: a.type,
+        status: 'pending',
+      }));
+    }
+    return new Understanding(this.#vhttp, this.id, {
+      collectionId: this.collectionId,
+      ...data,
+    });
+  };
+
+  /**
+   * Get an understanding run by id.
+   * @param understandingId - Understanding run id
+   */
+  public getUnderstanding = async (
+    understandingId: string
+  ): Promise<Understanding> => {
+    if (!understandingId) throw new VideodbError('understandingId is required');
+    const res = await this.#vhttp.get<UnderstandingData>([
+      video,
+      this.id,
+      understand,
+      understandingId,
+    ]);
+    return new Understanding(this.#vhttp, this.id, {
+      understandingId,
+      collectionId: this.collectionId,
+      ...(res.data ?? {}),
+    });
+  };
+
+  /** List understanding runs for this video. */
+  public listUnderstandings = async (): Promise<Understanding[]> => {
+    const res = await this.#vhttp.get<{
+      understandingResults?: UnderstandingData[];
+    }>([video, this.id, understand]);
+    const results = res.data?.understandingResults ?? [];
+    return results.map(
+      item =>
+        new Understanding(this.#vhttp, this.id, {
+          collectionId: this.collectionId,
+          ...item,
+        })
+    );
+  };
+
+  /** Delete an understanding run. */
+  public deleteUnderstanding = async (
+    understandingId: string
+  ): Promise<void> => {
+    if (!understandingId) throw new VideodbError('understandingId is required');
+    await this.#vhttp.delete([video, this.id, understand, understandingId]);
+  };
+
+  static #formatIndexSource(source: IndexSource): Record<string, unknown> {
+    if (source === null || source === undefined) {
+      throw new VideodbError('source is required');
+    }
+    if (
+      typeof source === 'object' &&
+      'toIndexSource' in source &&
+      typeof (source as { toIndexSource?: unknown }).toIndexSource ===
+        'function'
+    ) {
+      return (
+        source as { toIndexSource: () => Record<string, unknown> }
+      ).toIndexSource();
+    }
+    if (Array.isArray(source)) {
+      return { scenes: source };
+    }
+    if (typeof source === 'object') {
+      const s = source as Record<string, unknown>;
+      if (Array.isArray(s.scenes) || s.understanding_id) {
+        return s;
+      }
+      throw new VideodbError(
+        "source dict must carry 'scenes' (temporal records) or an 'understanding_id' reference"
+      );
+    }
+    throw new VideodbError(
+      "source must be an analyzer object, a dict with 'scenes' or 'understanding_id', or a list of temporal records"
+    );
+  }
+
+  #formatIndex = (indexData: RawIndexManifest): Index => {
+    const { video_id, collection_id, ...rest } = indexData;
+    return new Index(
+      this.#vhttp,
+      video_id || this.id,
+      collection_id || this.collectionId,
+      rest
+    );
+  };
+
+  /**
+   * Create a retrieval-ready index from an understanding artifact.
+   * @param source - An {@link UnderstandingAnalyzer} (indexed by reference), a
+   *   dict carrying `scenes` or an `understanding_id`, or a list of records.
+   * @param options - name / useFor / fields / callbackUrl
+   */
+  public index = async (
+    source: IndexSource,
+    options: {
+      name?: string;
+      useFor?: string[];
+      fields?: Record<string, string[]>;
+      callbackUrl?: string;
+    } = {}
+  ): Promise<Index | undefined> => {
+    const res = await this.#vhttp.post<RawIndexManifest, object>(
+      [video, this.id, indexes],
+      {
+        source: Video.#formatIndexSource(source),
+        name: options.name,
+        use_for: options.useFor,
+        fields: options.fields,
+        callback_url: options.callbackUrl,
+      },
+      undefined,
+      { convert: false }
+    );
+    if (!res.data) return undefined;
+    return this.#formatIndex(res.data as unknown as RawIndexManifest);
+  };
+
+  /**
+   * Get an index manifest by its ID or name.
+   * @param options - Either `indexId` or `name` must be provided.
+   */
+  public getIndex = async (options: {
+    indexId?: string;
+    name?: string;
+  }): Promise<Index | undefined> => {
+    if (!options.indexId && !options.name) {
+      throw new VideodbError('Either indexId or name is required');
+    }
+    const params: Record<string, unknown> = {
+      collection_id: this.collectionId,
+    };
+    let path: string[];
+    if (options.indexId) {
+      path = [video, this.id, indexes, options.indexId];
+    } else {
+      path = [video, this.id, indexes];
+      params.name = options.name;
+    }
+    const res = await this.#vhttp.get<RawIndexManifest>(path, { params }, {
+      convert: false,
+    });
+    if (!res.data) return undefined;
+    return this.#formatIndex(res.data as unknown as RawIndexManifest);
+  };
+
+  /**
+   * List all the indexes of the video.
+   * @param useFor - (optional) Filter by retrieval capability.
+   */
+  public listIndexes = async (useFor?: string): Promise<Index[]> => {
+    const params: Record<string, unknown> = {
+      collection_id: this.collectionId,
+    };
+    if (useFor != null) params.use_for = useFor;
+    const res = await this.#vhttp.get<{ indexes?: RawIndexManifest[] }>(
+      [video, this.id, indexes],
+      { params },
+      { convert: false }
+    );
+    const data = res.data as unknown as { indexes?: RawIndexManifest[] };
+    return (data?.indexes ?? []).map(i => this.#formatIndex(i));
+  };
+
+  /**
+   * Delete an index. Removes the index's retrieval structures only.
+   * @param indexId - The id of the index to be deleted
+   */
+  public deleteIndex = async (indexId: string): Promise<void> => {
+    if (!indexId) throw new VideodbError('indexId is required');
+    await this.#vhttp.delete([video, this.id, indexes, indexId], {
+      params: { collection_id: this.collectionId },
+    });
+  };
+
   /**
    * Overlays subtitles on top of a video
    * @returns an awaited stream url for subtitled overlayed video
    *
    */
   public addSubtitle = async (config?: Partial<SubtitleStyleProps>) => {
-    const merged: SubtitleStyleProps = { ...SubtitleStyleDefaultValues, ...config };
+    const merged: SubtitleStyleProps = {
+      ...SubtitleStyleDefaultValues,
+      ...config,
+    };
     const res = await this.#vhttp.post<
       GenerateStreamResponse,
       { type: string; subtitle_style: Record<string, unknown> }
@@ -655,6 +1184,39 @@ export class Video implements IVideo {
     return playStream(this.streamUrl);
   };
 
+  /**
+   * Generate an HTML iframe embed code for the video.
+   * @param width - Width of the iframe (default `"100%"`)
+   * @param height - Height of the iframe in pixels (default `405`)
+   * @param title - Title attribute (default `"VideoDB Player"`)
+   * @param allowFullscreen - Whether to allow fullscreen (default `true`)
+   * @param autoGenerate - If true and playerUrl is missing, auto-generate it (default `true`)
+   * @throws {VideodbError} If the player URL is not available.
+   */
+  public getEmbedCode = async (
+    width: string = '100%',
+    height: number = 405,
+    title: string = 'VideoDB Player',
+    allowFullscreen: boolean = true,
+    autoGenerate: boolean = true
+  ): Promise<string> => {
+    if (!this.playerUrl && autoGenerate) {
+      await this.generateStream();
+    }
+    if (!this.playerUrl) {
+      throw new VideodbError(
+        'player_url not available. Call generateStream() first or set autoGenerate=true.'
+      );
+    }
+    return buildIframeEmbedCode(
+      this.playerUrl,
+      width,
+      height,
+      title,
+      allowFullscreen
+    );
+  };
+
   /**
    * Remove the video storage
    * @returns A promise that resolves when the removal is successful
diff --git a/src/core/voiceClone.ts b/src/core/voiceClone.ts
new file mode 100644
index 0000000..75720e1
--- /dev/null
+++ b/src/core/voiceClone.ts
@@ -0,0 +1,93 @@
+import { ApiPath } from '@/constants';
+import { HttpClient } from '@/utils/httpClient';
+
+const { voice_clone } = ApiPath;
+
+/**
+ * Plain-data shape a {@link VoiceClone} is constructed from.
+ * Keys are camelCase (responses are auto-converted from snake_case).
+ */
+export interface VoiceCloneBase {
+  id?: string;
+  voiceCloneId?: string;
+  refAudioId?: string;
+  refText?: string;
+  name?: string;
+  description?: string;
+  language?: string;
+  collectionId?: string;
+  status?: string;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/**
+ * A reusable cloned voice reference backed by a VideoDB audio asset.
+ * Mirrors `videodb.voice_clone.VoiceClone`.
+ *
+ * Create/list/get via {@link Connection} or {@link Collection}.
+ */
+export class VoiceClone {
+  public id?: string;
+  public refAudioId?: string;
+  public refText?: string;
+  public name?: string;
+  public description?: string;
+  public language?: string;
+  public collectionId?: string;
+  public status?: string;
+  public createdAt?: string;
+  public updatedAt?: string;
+  #vhttp: HttpClient;
+
+  constructor(http: HttpClient, data: VoiceCloneBase = {}) {
+    this.#vhttp = http;
+    this.id = data.voiceCloneId ?? data.id;
+    this.refAudioId = data.refAudioId;
+    this.refText = data.refText;
+    this.name = data.name;
+    this.description = data.description;
+    this.language = data.language;
+    this.collectionId = data.collectionId;
+    this.status = data.status;
+    this.createdAt = data.createdAt;
+    this.updatedAt = data.updatedAt;
+  }
+
+  #update = (data?: VoiceCloneBase): void => {
+    if (!data) return;
+    this.id = data.voiceCloneId ?? data.id ?? this.id;
+    this.refAudioId = data.refAudioId ?? this.refAudioId;
+    this.refText = data.refText ?? this.refText;
+    this.name = data.name ?? this.name;
+    this.description = data.description ?? this.description;
+    this.language = data.language ?? this.language;
+    this.collectionId = data.collectionId ?? this.collectionId;
+    this.status = data.status ?? this.status;
+    this.createdAt = data.createdAt ?? this.createdAt;
+    this.updatedAt = data.updatedAt ?? this.updatedAt;
+  };
+
+  /**
+   * Fetch latest voice clone state from the server.
+   */
+  public refresh = async (): Promise<VoiceClone> => {
+    const res = await this.#vhttp.get<VoiceCloneBase>([
+      voice_clone,
+      this.id ?? '',
+    ]);
+    this.#update(res.data);
+    return this;
+  };
+
+  /**
+   * Delete this voice clone.
+   */
+  public delete = async (): Promise<void> => {
+    await this.#vhttp.delete([voice_clone, this.id ?? '']);
+  };
+
+  public toString(): string {
+    return `VoiceClone(id=${this.id}, name=${this.name}, refAudioId=${this.refAudioId}, status=${this.status})`;
+  }
+}
diff --git a/src/index.ts b/src/index.ts
index e358c35..32c7ab1 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -101,7 +101,9 @@ export {
   RTStreamSceneIndex,
   RTStreamSearchResult,
   RTStreamShot,
-  type RTStreamExportResult,
+  RTStreamExportResult,
+  RTStreamUnderstanding,
+  RTStreamIndex,
 } from './core/rtstream';
 export {
   WebSocketConnection,
@@ -112,6 +114,51 @@ export { CaptureSession, type CaptureSessionBase } from './core/captureSession';
 export { SceneIndex, type SceneData, type AlertData } from './core/sceneIndex';
 export { SpokenIndex } from './core/spokenIndex';
 
+// Indexing v2 — retrieval, understanding, generation, compute
+export {
+  Understanding,
+  UnderstandingAnalyzer,
+  normalizeUnderstandingAnalyzers,
+  normalizeAnalyzerType,
+  defaultAnalyzerName,
+  type AnalyzerSpec,
+  type AnalyzerData,
+  type UnderstandingData,
+} from './core/understanding';
+export {
+  Index,
+  IndexRecord,
+  FieldSchema,
+  RecordPage,
+  type IndexData,
+  type IndexRecordData,
+  type FieldSchemaData,
+} from './core/indexManifest';
+export { GenerationJob, type JobStatus, type JobData } from './core/job';
+export { Sandbox, type SandboxBase } from './core/sandbox';
+export { SandboxModel, type SandboxModelValue } from './core/sandboxModels';
+export { VoiceClone, type VoiceCloneBase } from './core/voiceClone';
+export {
+  AskResponse,
+  SearchResponse,
+  warnLegacySearchOnce,
+  type AskResponseData,
+  type SearchResponseData,
+} from './core/search/responses';
+export type { VideoSearchOptions, IndexSource } from './core/video';
+export type { CollectionSearchOptions } from './core/collection';
+export {
+  IndexCapability,
+  FieldGroup,
+  SandboxTier,
+  SandboxStatus,
+} from './constants';
+export {
+  buildIframeEmbedCode,
+  playerUrlToEmbedUrl,
+} from './utils';
+export { RequestTimeoutError } from './utils/error';
+
 // Capture session types
 export {
   type ConnectionConfig,
diff --git a/src/interfaces/core.ts b/src/interfaces/core.ts
index fbf4c5d..802107e 100644
--- a/src/interfaces/core.ts
+++ b/src/interfaces/core.ts
@@ -1,4 +1,6 @@
 import { SearchResult } from '@/core/search/searchResult';
+import type { VideoSearchOptions } from '@/core/video';
+import type { CollectionSearchOptions } from '@/core/collection';
 import { Video } from '@/core/video';
 import { Audio } from '@/core/audio';
 import { Image } from '@/core/image';
@@ -32,7 +34,7 @@ export interface ICollection extends CollectionBase {
     data: URLUploadConfig
   ) => Promise<Video | Audio | Image | undefined>;
   // Note: search method signature is more complex in implementation to support RTStream namespace
-  search: (query: string, searchType?: SearchType) => Promise<unknown>;
+  search: (query: string, options?: CollectionSearchOptions) => Promise<unknown>;
 }
 
 /**
@@ -73,7 +75,7 @@ export interface IVideo extends Omit<VideoBase, 'thumbnail'> {
     callbackUrl?: string
   ) => Promise<{ success: boolean; message?: string }>;
   indexScenes: (config: IndexSceneConfig) => Promise<string | undefined>;
-  search: (query: string, searchType?: SearchType) => Promise<SearchResult>;
+  search: (query: string, options?: VideoSearchOptions) => Promise<unknown>;
   generateThumbnail: (time?: number) => Promise<string | Image>;
   addSubtitle: (config: SubtitleStyleProps) => Promise<string>;
 }
diff --git a/src/types/config.ts b/src/types/config.ts
index f1b68cf..1c9cbb7 100644
--- a/src/types/config.ts
+++ b/src/types/config.ts
@@ -98,6 +98,7 @@ export type IndexSceneConfig = {
   name?: string | null;
   callbackUrl?: string | null;
   scenes?: Scene[];
+  sandboxId?: string;
 };
 
 export type IndexConfig = {
diff --git a/src/types/response.ts b/src/types/response.ts
index 3a11eb1..f3a3f8a 100644
--- a/src/types/response.ts
+++ b/src/types/response.ts
@@ -144,6 +144,7 @@ export type SearchResponse = {
       score: number;
       start: number;
       stream_link?: string;
+      stream_url?: string;
       player_url?: string;
       text: string;
       scene_index_id?: string;
diff --git a/src/utils/error.ts b/src/utils/error.ts
index 947e61b..201e4e4 100644
--- a/src/utils/error.ts
+++ b/src/utils/error.ts
@@ -15,10 +15,29 @@ export class AuthenticationError<T = unknown> extends VdbBaseError {
 }
 
 export class InvalidRequestError<C = unknown> extends VdbBaseError {
-  public response: AxiosResponse;
-  constructor(response: AxiosResponse, cause?: C) {
-    super(`Error ${response.status}: ${response.statusText}`, { cause });
-    this.response = response;
+  public response?: AxiosResponse;
+  constructor(responseOrMessage: AxiosResponse | string, cause?: C) {
+    if (typeof responseOrMessage === 'string') {
+      super(`Invalid Request Error: ${responseOrMessage}`, { cause });
+    } else {
+      super(
+        `Error ${responseOrMessage.status}: ${responseOrMessage.statusText}`,
+        { cause }
+      );
+      this.response = responseOrMessage;
+    }
+    this.name = 'InvalidRequestError';
+  }
+}
+
+/**
+ * Raised when a request or a client-side poll loop times out.
+ * Mirrors `videodb.exceptions.RequestTimeoutError`.
+ */
+export class RequestTimeoutError<T = undefined> extends VdbBaseError {
+  constructor(message?: string, cause?: T) {
+    super(`Request Timeout Error: ${message}`, { cause });
+    this.name = 'RequestTimeoutError';
   }
 }
 
diff --git a/src/utils/httpClient.ts b/src/utils/httpClient.ts
index 6724dc7..ebd92a7 100644
--- a/src/utils/httpClient.ts
+++ b/src/utils/httpClient.ts
@@ -7,6 +7,7 @@ import type {
 import {
   AuthenticationError,
   InvalidRequestError,
+  RequestTimeoutError,
   VideodbError,
 } from '@/utils/error';
 import { fromSnakeToCamel } from '@/utils';
@@ -21,8 +22,28 @@ import axios, {
 } from 'axios';
 import FormData from 'form-data';
 
-const POLLING_INTERVAL = 5000;
-const MAX_POLLING_TIME = 500000;
+const POLLING_INTERVAL = HttpClientDefaultValues.pollInterval;
+const MAX_POLLING_TIME = HttpClientDefaultValues.maxPollTime;
+
+/**
+ * Per-call polling controls, mirroring the Python client's
+ * `wait` / `max_poll_time` / `poll_interval` kwargs.
+ */
+export interface RequestPollOptions {
+  /** When false, skip polling the async output URL and return immediately. */
+  wait?: boolean;
+  /** Override the max poll time (ms) for this call. */
+  maxPollTime?: number;
+  /** Override the poll interval (ms) for this call. */
+  pollInterval?: number;
+  /**
+   * When false, do NOT snake→camel convert the response body. Use for endpoints
+   * whose payload contains user-defined opaque key maps (e.g. index `data`,
+   * `field_schema`, aggregate buckets) that must be preserved verbatim to match
+   * the server/Python SDK. Defaults to true.
+   */
+  convert?: boolean;
+}
 
 /**
  * Authentication configuration for HttpClient
@@ -147,10 +168,14 @@ export class HttpClient {
    * @param url - The output URL to poll
    * @returns The final response data (already converted to camelCase)
    */
-  #getOutput = async <R>(url: string): Promise<R> => {
+  #getOutput = async <R>(
+    url: string,
+    maxPollTime: number = MAX_POLLING_TIME,
+    pollInterval: number = POLLING_INTERVAL
+  ): Promise<R> => {
     const startTime = Date.now();
 
-    while (Date.now() - startTime < MAX_POLLING_TIME) {
+    while (Date.now() - startTime < maxPollTime) {
       const response = await this.#db.get<ApiResponseOf<R>>(url);
       const data = response.data;
 
@@ -158,7 +183,7 @@ export class HttpClient {
         data.status === ResponseStatus.in_progress ||
         data.status === ResponseStatus.processing
       ) {
-        await this.#sleep(POLLING_INTERVAL);
+        await this.#sleep(pollInterval);
         continue;
       }
 
@@ -175,8 +200,8 @@ export class HttpClient {
       return this.#convertResponseData(data.data);
     }
 
-    throw new VideodbError(
-      'Job timed out after ' + MAX_POLLING_TIME / 1000 + ' seconds'
+    throw new RequestTimeoutError(
+      'Polling timed out after ' + Math.round(maxPollTime / 1000) + 's'
     );
   };
 
@@ -186,7 +211,8 @@ export class HttpClient {
    * @typeParam D - The request data type (must be provided in snake_case)
    */
   #makeRequest = async <R, D = undefined>(
-    options: AxiosRequestConfig<D>
+    options: AxiosRequestConfig<D>,
+    poll?: RequestPollOptions
   ): Promise<ResponseOf<R>> => {
     try {
       const response = await this.#db.request<
@@ -195,23 +221,36 @@ export class HttpClient {
         D
       >(options);
       const data = response.data;
+      const convert = poll?.convert !== false;
+
+      // wait=false: do not poll the async output URL; return data as-is.
+      if (poll?.wait === false) {
+        return {
+          ...data,
+          data: convert ? this.#convertResponseData(data.data) : data.data,
+        } as ResponseOf<R>;
+      }
 
       if (data.status === ResponseStatus.processing) {
         if (data.request_type === 'async') {
           return {
             ...data,
-            data: this.#convertResponseData(data.data),
+            data: convert ? this.#convertResponseData(data.data) : data.data,
           } as ResponseOf<R>;
         }
 
         const outputUrl = (data.data as { output_url?: string })?.output_url;
         if (outputUrl) {
-          const result = await this.#getOutput<R>(outputUrl);
+          const result = await this.#getOutput<R>(
+            outputUrl,
+            poll?.maxPollTime,
+            poll?.pollInterval
+          );
           return { data: result, success: true } as ResponseOf<R>;
         }
       }
 
-      return this.#parseResponse(data);
+      return this.#parseResponse(data, convert);
     } catch (error) {
       if (error instanceof VideodbError) {
         throw error;
@@ -225,13 +264,16 @@ export class HttpClient {
   /**
    * Parses API response and converts data to camelCase
    */
-  #parseResponse = <R>(data: ApiResponseOf<R>): ResponseOf<R> => {
+  #parseResponse = <R>(
+    data: ApiResponseOf<R>,
+    convert: boolean = true
+  ): ResponseOf<R> => {
     if (data.success === false) {
       throw new VideodbError(data.message);
     }
     return {
       ...data,
-      data: this.#convertResponseData(data.data),
+      data: convert ? this.#convertResponseData(data.data) : data.data,
     } as ResponseOf<R>;
   };
 
@@ -265,13 +307,17 @@ export class HttpClient {
 
   public get = async <R>(
     urlSeries: string[],
-    options?: AxiosRequestConfig<undefined>
+    options?: AxiosRequestConfig<undefined>,
+    poll?: RequestPollOptions
   ) => {
-    return await this.#makeRequest<R>({
-      method: 'GET',
-      url: urlSeries.join('/'),
-      ...options,
-    });
+    return await this.#makeRequest<R>(
+      {
+        method: 'GET',
+        url: urlSeries.join('/'),
+        ...options,
+      },
+      poll
+    );
   };
 
   public delete = async <R>(
@@ -288,18 +334,22 @@ export class HttpClient {
   public post = async <R, D = undefined>(
     urlSeries: string[],
     data?: D,
-    options?: AxiosRequestConfig<D>
+    options?: AxiosRequestConfig<D>,
+    poll?: RequestPollOptions
   ) => {
-    return await this.#makeRequest<R, D>({
-      method: 'POST',
-      url: urlSeries.join('/'),
-      data,
-      headers: new AxiosHeaders({
-        'Content-Type': 'application/json',
-        ...options?.headers,
-      }),
-      ...options,
-    });
+    return await this.#makeRequest<R, D>(
+      {
+        method: 'POST',
+        url: urlSeries.join('/'),
+        data,
+        headers: new AxiosHeaders({
+          'Content-Type': 'application/json',
+          ...options?.headers,
+        }),
+        ...options,
+      },
+      poll
+    );
   };
 
   public put = async <R, D = undefined>(
diff --git a/src/utils/index.ts b/src/utils/index.ts
index 3141827..4be3fa5 100644
--- a/src/utils/index.ts
+++ b/src/utils/index.ts
@@ -23,32 +23,34 @@ export type CamelToSnakeCase<S extends string> =
 /**
  * Recursively converts all keys in an object type from snake_case to camelCase
  */
-export type SnakeKeysToCamelCase<T> = T extends Array<infer U>
-  ? U extends object
-    ? SnakeKeysToCamelCase<U>[]
-    : U[]
-  : T extends object
-    ? {
-        [K in keyof T as SnakeToCamelCase<K & string>]: SnakeKeysToCamelCase<
-          T[K]
-        >;
-      }
-    : T;
+export type SnakeKeysToCamelCase<T> =
+  T extends Array<infer U>
+    ? U extends object
+      ? SnakeKeysToCamelCase<U>[]
+      : U[]
+    : T extends object
+      ? {
+          [K in keyof T as SnakeToCamelCase<K & string>]: SnakeKeysToCamelCase<
+            T[K]
+          >;
+        }
+      : T;
 
 /**
  * Recursively converts all keys in an object type from camelCase to snake_case
  */
-export type CamelKeysToSnakeCase<T> = T extends Array<infer U>
-  ? U extends object
-    ? CamelKeysToSnakeCase<U>[]
-    : U[]
-  : T extends object
-    ? {
-        [K in keyof T as CamelToSnakeCase<K & string>]: CamelKeysToSnakeCase<
-          T[K]
-        >;
-      }
-    : T;
+export type CamelKeysToSnakeCase<T> =
+  T extends Array<infer U>
+    ? U extends object
+      ? CamelKeysToSnakeCase<U>[]
+      : U[]
+    : T extends object
+      ? {
+          [K in keyof T as CamelToSnakeCase<K & string>]: CamelKeysToSnakeCase<
+            T[K]
+          >;
+        }
+      : T;
 
 /**
  * Recursively converts a value from snake_case to camelCase
@@ -84,7 +86,7 @@ const convertValueCamelToSnake = (v: unknown): unknown => {
   if (_.isArray(v)) {
     return v.map((item: unknown) =>
       _.isObject(item) && item !== null && !_.isArray(item)
-        ? fromCamelToSnake(item as object)
+        ? fromCamelToSnake(item)
         : _.isArray(item)
           ? convertValueCamelToSnake(item)
           : item
@@ -105,7 +107,7 @@ export const fromCamelToSnake = <T extends object>(
   if (_.isArray(data)) {
     return data.map((item: unknown) =>
       _.isObject(item) && item !== null && !_.isArray(item)
-        ? fromCamelToSnake(item as object)
+        ? fromCamelToSnake(item)
         : item
     ) as CamelKeysToSnakeCase<T>;
   }
@@ -118,6 +120,67 @@ export const fromCamelToSnake = <T extends object>(
 
 export const playStream = (url: string) => `${PLAYER_URL}?url=${url}`;
 
+/**
+ * Sleep for the given number of milliseconds. Used by the client-side
+ * poll loops (`waitUntilComplete`, `GenerationJob.wait`, `Sandbox.waitForReady`).
+ */
+export const sleep = (ms: number): Promise<void> =>
+  new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Convert a `/watch` player URL into an `/embed` URL.
+ * Mirrors `videodb._utils._video.player_url_to_embed_url`.
+ *
+ * @param playerUrl - e.g. `https://player.videodb.io/watch?v=slug`
+ * @returns e.g. `https://player.videodb.io/embed?v=slug`
+ * @throws {Error} If the URL is empty, missing `/watch?`, or missing the `v` param.
+ */
+export const playerUrlToEmbedUrl = (playerUrl: string): string => {
+  if (!playerUrl) {
+    throw new Error('player_url is required to generate embed URL');
+  }
+  if (!playerUrl.includes('/watch?')) {
+    throw new Error("player_url must contain '/watch?' path");
+  }
+  if (!playerUrl.split('/watch?')[1].includes('v=')) {
+    throw new Error("player_url must contain a 'v' query parameter");
+  }
+  return playerUrl.replace('/watch?', '/embed?');
+};
+
+/**
+ * Build an iframe embed HTML string from a player URL.
+ * Mirrors `videodb._utils._video.build_iframe_embed_code`.
+ *
+ * @param playerUrl - The player URL to embed
+ * @param width - Width of the iframe (default `"100%"`)
+ * @param height - Height of the iframe in pixels (default `405`)
+ * @param title - Title attribute for the iframe (default `"VideoDB Player"`)
+ * @param allowFullscreen - Whether to allow fullscreen (default `true`)
+ * @throws {Error} If `playerUrl` is empty or `height` is not positive.
+ */
+export const buildIframeEmbedCode = (
+  playerUrl: string,
+  width: string = '100%',
+  height: number = 405,
+  title: string = 'VideoDB Player',
+  allowFullscreen: boolean = true
+): string => {
+  if (!playerUrl) {
+    throw new Error('player_url is required to generate embed code');
+  }
+  if (height <= 0) {
+    throw new Error('height must be a positive integer');
+  }
+  const embedUrl = playerUrlToEmbedUrl(playerUrl);
+  const fullscreenAttr = allowFullscreen ? ' allowfullscreen' : '';
+  return (
+    `<iframe src="${embedUrl}" ` +
+    `width="${width}" height="${height}" ` +
+    `title="${title}" frameborder="0"${fullscreenAttr}></iframe>`
+  );
+};
+
 export const isMediaAudio = (
   media: AudioBase | VideoBase
 ): media is AudioBase => {
diff --git a/src/utils/upload.ts b/src/utils/upload.ts
index cb2a726..c80e011 100644
--- a/src/utils/upload.ts
+++ b/src/utils/upload.ts
@@ -31,6 +31,43 @@ export const getUploadUrl = async (http: HttpClient, collectionId: string) => {
   return res.data.uploadUrl;
 };
 
+/**
+ * Upload in-memory content via a presigned upload URL and return the object URL.
+ * Mirrors `videodb._upload.upload_bytes`.
+ *
+ * @param http - The HttpClient instance
+ * @param content - The content to upload (string or Buffer)
+ * @param name - Name of the object (used as the `name` query param and filename)
+ * @param contentType - MIME type of the content (default `application/octet-stream`)
+ * @param collectionId - Collection to presign against
+ * @returns The presigned object URL (the content is now reachable at this URL)
+ */
+export const uploadBytes = async (
+  http: HttpClient,
+  content: string | Buffer,
+  name: string,
+  contentType: string = 'application/octet-stream',
+  collectionId?: string
+): Promise<string> => {
+  const res = await http.get<GetUploadUrl>(
+    [collection, collectionId ?? '', upload_url],
+    { params: { name } }
+  );
+  const uploadUrl = res.data.uploadUrl;
+
+  try {
+    const formData = new FormData();
+    formData.append('file', content, { filename: name, contentType });
+    await http.post<unknown, FormData>([uploadUrl], formData, {
+      headers: formData.getHeaders(),
+    });
+  } catch (err) {
+    throw new VideodbError('Error while uploading content', err);
+  }
+
+  return uploadUrl;
+};
+
 /**
  * @param filePath - absolute path to a file
  * @param url - a url to a pre-uploaded file

From 8068e15db17836161adb0bc44aab1c949585197a Mon Sep 17 00:00:00 2001
From: Om Gate <om@videodb.io>
Date: Sat, 25 Jul 2026 10:49:42 +0530
Subject: [PATCH 2/5] feat: sandbox endpoints

---
 src/core/connection.ts | 25 +++++++++++++++++++------
 src/core/sandbox.ts    | 25 ++++++++++++++++++++-----
 2 files changed, 39 insertions(+), 11 deletions(-)

diff --git a/src/core/connection.ts b/src/core/connection.ts
index 6d6883d..b746791 100644
--- a/src/core/connection.ts
+++ b/src/core/connection.ts
@@ -613,16 +613,22 @@ export class Connection {
    * @param tier - Compute tier (see {@link SandboxTier})
    * @param name - Human-readable name
    * @param callbackUrl - URL to notify on provisioning events
+   * @param modelCategories - Model categories to prepare for this sandbox, e.g. `["vlm", "image_generation"]`
+   * @param models - Specific model names to prepare for this sandbox
    */
   public createSandbox = async (
     tier?: string,
     name?: string,
-    callbackUrl?: string
+    callbackUrl?: string,
+    modelCategories?: string[],
+    models?: string[]
   ): Promise<Sandbox> => {
     const res = await this.vhttp.post<SandboxBase, object>([sandbox], {
       tier,
       name,
       callback_url: callbackUrl,
+      model_categories: modelCategories,
+      models,
     });
     return new Sandbox(this.vhttp, res.data);
   };
@@ -639,12 +645,19 @@ export class Connection {
   /**
    * List sandboxes, optionally filtered by status.
    * @param status - Filter by sandbox status (see {@link SandboxStatus})
+   * @param page - Page number (default 1)
+   * @param pageSize - Sandboxes per page (default 20, maximum 100)
    */
-  public listSandboxes = async (status?: string): Promise<Sandbox[]> => {
-    const res = await this.vhttp.get<{ sandboxes?: SandboxBase[] }>(
-      [sandbox],
-      status ? { params: { status } } : undefined
-    );
+  public listSandboxes = async (
+    status?: string,
+    page: number = 1,
+    pageSize: number = 20
+  ): Promise<Sandbox[]> => {
+    const params: Record<string, unknown> = { page, page_size: pageSize };
+    if (status) params.status = status;
+    const res = await this.vhttp.get<{ sandboxes?: SandboxBase[] }>([sandbox], {
+      params,
+    });
     return (res.data?.sandboxes || []).map(s => new Sandbox(this.vhttp, s));
   };
 
diff --git a/src/core/sandbox.ts b/src/core/sandbox.ts
index fb9dda6..735991e 100644
--- a/src/core/sandbox.ts
+++ b/src/core/sandbox.ts
@@ -10,6 +10,8 @@ const TERMINAL_STATUSES: string[] = [
   SandboxStatus.failed,
 ];
 
+const READY_STATUSES: string[] = [SandboxStatus.active, SandboxStatus.alert];
+
 /**
  * Plain-data shape a {@link Sandbox} is constructed from (camelCase).
  */
@@ -22,6 +24,10 @@ export interface SandboxBase {
   createdAt?: string;
   startedAt?: string;
   stoppedAt?: string;
+  modelCategories?: string[];
+  models?: string[];
+  region?: string;
+  expiresAt?: string;
 }
 
 /**
@@ -38,6 +44,10 @@ export class Sandbox {
   public createdAt?: string;
   public startedAt?: string;
   public stoppedAt?: string;
+  public modelCategories: string[];
+  public models: string[];
+  public region?: string;
+  public expiresAt?: string;
   #vhttp: HttpClient;
 
   constructor(http: HttpClient, data: SandboxBase = {}) {
@@ -49,6 +59,10 @@ export class Sandbox {
     this.createdAt = data.createdAt;
     this.startedAt = data.startedAt;
     this.stoppedAt = data.stoppedAt;
+    this.modelCategories = data.modelCategories ?? [];
+    this.models = data.models ?? [];
+    this.region = data.region;
+    this.expiresAt = data.expiresAt;
   }
 
   #update = (data?: SandboxBase): void => {
@@ -60,6 +74,10 @@ export class Sandbox {
     this.createdAt = data.createdAt ?? this.createdAt;
     this.startedAt = data.startedAt ?? this.startedAt;
     this.stoppedAt = data.stoppedAt ?? this.stoppedAt;
+    this.modelCategories = data.modelCategories ?? this.modelCategories;
+    this.models = data.models ?? this.models;
+    this.region = data.region ?? this.region;
+    this.expiresAt = data.expiresAt ?? this.expiresAt;
   };
 
   /**
@@ -86,7 +104,7 @@ export class Sandbox {
     const deadline = Date.now() + timeout * 1000;
     for (;;) {
       await this.refresh();
-      if (this.status === SandboxStatus.active) return this;
+      if (this.status && READY_STATUSES.includes(this.status)) return this;
       if (this.status && TERMINAL_STATUSES.includes(this.status)) {
         throw new VideodbError(
           `Sandbox ${this.id} entered terminal state: ${this.status}`
@@ -144,10 +162,7 @@ export class Sandbox {
   }
 
   public get isReady(): boolean {
-    return (
-      this.status === SandboxStatus.provisioning ||
-      this.status === SandboxStatus.active
-    );
+    return this.status ? READY_STATUSES.includes(this.status) : false;
   }
 
   public toString(): string {

From 59c760ac6ed8e5d8a71c780bceb4ced6fb9021da Mon Sep 17 00:00:00 2001
From: Om Gate <om@videodb.io>
Date: Sat, 25 Jul 2026 10:58:24 +0530
Subject: [PATCH 3/5] feat: version bump

---
 CHANGELOG.md      | 29 +++++++++++++++++++++++++++++
 package-lock.json |  4 ++--
 package.json      |  2 +-
 3 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c29c650..ab176c3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,34 @@
 # Changelog
 
+## [0.3.0] (2026-07-25)
+
+Indexing v2 — a new retrieval architecture plus a generation/compute stack, ported from `videodb-python`'s `feat/add-indexing-v2`.
+
+### Added
+
+- **Search v2 on `Video` and `Collection`** — new `search()` dispatcher with dedicated `ask()`, `semanticSearch()`, `query()`, and `aggregate()` methods, returning the v2 `SearchResponse` / `AskResponse` envelopes (iterable `SearchResult`). `legacySearch()` preserves the old behavior behind a one-time deprecation warning
+- **Understanding runs** — `Video.understand()` / `getUnderstanding()` / `listUnderstandings()` / `deleteUnderstanding()`, backed by new `Understanding` and `UnderstandingAnalyzer` classes and analyzer-normalization helpers (`normalizeUnderstandingAnalyzers`, `normalizeAnalyzerType`, `defaultAnalyzerName`)
+- **Index manifest** — `Video.index()` / `getIndex()` / `listIndexes()` / `deleteIndex()`, backed by new `Index`, `IndexRecord`, `FieldSchema`, and `RecordPage` classes with `IndexCapability` and `FieldGroup` constants
+- **Sandboxes (persistent GPU compute pools)** — `Connection.createSandbox()` / `getSandbox()` / `listSandboxes()`, a `Sandbox` class with `waitForReady()` / `stop()` / `waitForStop()` lifecycle polling, and `SandboxTier` / `SandboxStatus` constants
+- **Async generation jobs** — `GenerationJob` with `wait()` polling, plus `Connection.getJobStatus()` and `waitForJob()`. `Collection.generateImage()` / `generateVoice()` / `generateText()` gain self-inference model routing (`SandboxModel`), `sandboxId`, and `wait` options, returning a `GenerationJob` when the server dispatches async work
+- **Voice clones** — `VoiceClone` class and CRUD on both `Connection` and `Collection` (`createVoiceClone` / `getVoiceClone` / `listVoiceClones` / `deleteVoiceClone`), plus `voiceCloneId` support in `generateVoice()`
+- **Real-time stream understanding & indexing** — new `RTStreamUnderstanding` and `RTStreamIndex` classes with `understand()` / `index()` on `RTStream`, alert management (`createAlert` / `listAlerts` / `enableAlert` / `disableAlert`), and record retrieval
+- **Embed-code helpers** — `getEmbedCode()` on `Video`, `Shot`, `Timeline`, and RTStream types, plus `buildIframeEmbedCode()` / `playerUrlToEmbedUrl()` utilities. `Video`, `Shot`, and RTStream types now carry `playerUrl`
+- **`sandboxId` threading** into `Video.indexScenes()` / `indexVisuals()`, `Scene.describe()` (also gains `modelConfig`), and all `RTStream` indexing methods, to route inference to a specific sandbox
+- **`Connection.getAsyncResponse()`** to fetch a stored async response without polling
+
+### Changed
+
+- `HttpClient` `get`/`post` accept a `wait` flag and per-call poll overrides (`maxPollTime` / `pollInterval`); the async-output poll loop was rewritten from `backoff` to a monotonic-clock loop that throws `RequestTimeoutError` on timeout
+- `uploadBytes()` helper added for in-memory uploads; `upload()` refactored to reuse it, and large `generateText()` prompts are now offloaded to a presigned URL (`prompt_url`) above ~250 KB to avoid gateway payload limits
+- `ResponseStatus` gains `complete`; new `ApiPath` segments and polling defaults added
+
+### Fixed
+
+- `Sandbox.isReady` and `waitForReady()` now treat `alert` as a ready state (matching `videodb-python`'s `READY_STATUSES`) and no longer report `provisioning` as ready
+
+---
+
 ## [0.2.7] (2026-06-03)
 
 ### Added
diff --git a/package-lock.json b/package-lock.json
index 9e47052..eead51a 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "videodb",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "videodb",
-      "version": "0.2.7",
+      "version": "0.3.0",
       "hasInstallScript": true,
       "license": "Apache-2.0",
       "dependencies": {
diff --git a/package.json b/package.json
index 0e07e6e..e1ea320 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "videodb",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "A NodeJS wrapper for VideoDB's API written in TypeScript",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

From 4f780eef503a14c2f2f2c97b65657a9e0e1d642a Mon Sep 17 00:00:00 2001
From: Om Gate <om@videodb.io>
Date: Sat, 25 Jul 2026 17:42:30 +0530
Subject: [PATCH 4/5] fix: convert arg honouring

---
 src/utils/httpClient.ts | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/src/utils/httpClient.ts b/src/utils/httpClient.ts
index ebd92a7..bc4b868 100644
--- a/src/utils/httpClient.ts
+++ b/src/utils/httpClient.ts
@@ -171,7 +171,8 @@ export class HttpClient {
   #getOutput = async <R>(
     url: string,
     maxPollTime: number = MAX_POLLING_TIME,
-    pollInterval: number = POLLING_INTERVAL
+    pollInterval: number = POLLING_INTERVAL,
+    convert: boolean = true
   ): Promise<R> => {
     const startTime = Date.now();
 
@@ -195,9 +196,11 @@ export class HttpClient {
         if (data.response.success === false) {
           throw new VideodbError(data.response.message);
         }
-        return this.#convertResponseData(data.response.data);
+        return convert
+          ? this.#convertResponseData(data.response.data)
+          : data.response.data;
       }
-      return this.#convertResponseData(data.data);
+      return convert ? this.#convertResponseData(data.data) : data.data;
     }
 
     throw new RequestTimeoutError(
@@ -244,7 +247,8 @@ export class HttpClient {
           const result = await this.#getOutput<R>(
             outputUrl,
             poll?.maxPollTime,
-            poll?.pollInterval
+            poll?.pollInterval,
+            convert
           );
           return { data: result, success: true } as ResponseOf<R>;
         }

From 16b36b48350ddc74bd0445ebdb6e4c9f52d0cbdc Mon Sep 17 00:00:00 2001
From: Om Gate <om@videodb.io>
Date: Sat, 25 Jul 2026 17:42:50 +0530
Subject: [PATCH 5/5] feat: preserve the pre-v2 positional signature

---
 docs/PR-feat-indexing-v2.md | 45 ++++++++++++++++++++++++++++++++
 src/core/collection.ts      | 51 ++++++++++++++++++++++++++++++++++---
 2 files changed, 92 insertions(+), 4 deletions(-)
 create mode 100644 docs/PR-feat-indexing-v2.md

diff --git a/docs/PR-feat-indexing-v2.md b/docs/PR-feat-indexing-v2.md
new file mode 100644
index 0000000..c3c95da
--- /dev/null
+++ b/docs/PR-feat-indexing-v2.md
@@ -0,0 +1,45 @@
+## Pull Request
+
+**Description:**
+
+Ports `videodb-python`'s `feat/add-indexing-v2` drop to the NodeJS SDK (`feat/indexing-v2` → `main`), bringing the SDK to parity across two related workstreams:
+
+1. **Indexing v2** — a new retrieval architecture (Search v2 dispatcher, Understanding runs, and an Index manifest) that supersedes the legacy single-shot search.
+2. **Generation / compute stack** — persistent GPU **sandboxes**, async **generation jobs** for self-inference TTS/image models, and reusable **voice clones**, wired into the `generate*` methods.
+
+Also adds embed-code helpers and threads `sandboxId` through the inference-bearing methods. Bodies are authored in snake_case at the call site and responses are auto-camelCased by `HttpClient`, per existing SDK conventions; every new public symbol is re-exported from the `src/index.ts` barrel. Bumps the package `0.2.7` → `0.3.0` (minor) and updates the changelog.
+
+Scope: 25 files changed, ~+3,700 / −133. New source modules: `understanding.ts`, `indexManifest.ts`, `job.ts`, `sandbox.ts`, `sandboxModels.ts`, `voiceClone.ts`, `search/responses.ts`.
+
+**Changes:**
+- [x] Search v2 on `Video` & `Collection` — `search()` dispatcher + `ask()` / `semanticSearch()` / `query()` / `aggregate()`, v2 `SearchResponse` / `AskResponse` envelopes, iterable `SearchResult`; `legacySearch()` behind a one-time deprecation warning
+- [x] Understanding runs — `Understanding` + `UnderstandingAnalyzer` classes and `Video.understand()` / `getUnderstanding()` / `listUnderstandings()` / `deleteUnderstanding()`
+- [x] Index manifest — `Index` / `IndexRecord` / `FieldSchema` / `RecordPage` and `Video.index()` / `getIndex()` / `listIndexes()` / `deleteIndex()`, with `IndexCapability` / `FieldGroup` constants
+- [x] Sandboxes — `Sandbox` (lifecycle polling) + `Connection.createSandbox()` / `getSandbox()` / `listSandboxes()`, `SandboxTier` / `SandboxStatus` / `SandboxModel`
+- [x] Generation jobs — `GenerationJob` + `Connection.getJobStatus()` / `waitForJob()`; `generateImage()` / `generateVoice()` / `generateText()` gain self-inference routing, `sandboxId`, and `wait`
+- [x] Voice clones — `VoiceClone` CRUD on `Connection` and `Collection`; `voiceCloneId` in `generateVoice()`
+- [x] RTStream understanding & indexing — `RTStreamUnderstanding` / `RTStreamIndex`, `understand()` / `index()`, alert management, record retrieval
+- [x] Embed-code helpers — `getEmbedCode()` on `Video` / `Shot` / `Timeline` / RTStream, `buildIframeEmbedCode()` / `playerUrlToEmbedUrl()`, `playerUrl` fields
+- [x] `sandboxId` threading into `Video.indexScenes()` / `indexVisuals()`, `Scene.describe()` (+ `modelConfig`), and RTStream indexing; `Connection.getAsyncResponse()`
+- [x] Infra — `wait` flag + per-call poll overrides on `HttpClient`, monotonic-clock poll loop w/ `RequestTimeoutError`, `uploadBytes()` helper, `prompt_url` offload for large `generateText()` prompts
+- [x] Bugfix: `Sandbox.isReady` / `waitForReady()` treat `alert` as ready (matching Python `READY_STATUSES`) and no longer report `provisioning` as ready
+- [x] Version bump `0.2.7` → `0.3.0` + `CHANGELOG.md`
+
+**Related Issues:**
+- N/A
+
+**Testing:**
+
+Validated against the companion **`nodejs-test-suite`** (symlinked to this package's built `dist/`), across pure, mocked, and live-API layers:
+
+- **Offline (pure + mock):** full suite green — sandbox constant/getter behavior, poll-loop branches (terminal-state, timeout, `alert`-resolves-ready), and `createSandbox` / `listSandboxes` wire payloads. `npm run typecheck` passes.
+- **Live API:** `Sandbox` provision → wait-ready → stop lifecycle; `VoiceClone` CRUD (via `Connection` and `Collection`); `GenerationJob` polling; and all `generate*` methods (text, image, music, sound-effect, voice, video). The only live failures observed were pre-existing backend/account flakiness (semantic/title search, one upload stream-link generation, billing `getInvoices`) — unrelated to this change.
+
+Re-test after merge: because this rebuilds the SDK `dist/`, downstream consumers of `search()` should confirm the v2 dispatcher / legacy fallback behaves as expected, and the sandbox-routed `generate*` paths should be smoke-tested once a sandbox is provisioned.
+
+**Checklist:**
+- [x] Code follows project coding standards
+- [x] Tests have been added or updated
+- [ ] Code Review
+- [ ] Manual test after merge
+- [ ] All checks passed
diff --git a/src/core/collection.ts b/src/core/collection.ts
index b154e9e..2c28db1 100644
--- a/src/core/collection.ts
+++ b/src/core/collection.ts
@@ -304,12 +304,55 @@ export class Collection implements ICollection {
    */
   public search = async (
     query: string,
-    options: CollectionSearchOptions = {}
+    optionsOrSearchType: CollectionSearchOptions | SearchType = {},
+    indexType?: IndexType,
+    resultThreshold?: number,
+    scoreThreshold?: number,
+    dynamicScorePercentage?: number,
+    filter?: Array<Record<string, unknown>>,
+    sortDocsOn?: string,
+    namespace?: string,
+    sceneIndexId?: string
   ): Promise<SearchResponse | SearchResult | RTStreamSearchResult> => {
+    // Back-compat: the pre-v2 signature was fully positional —
+    //   search(query, searchType, indexType, resultThreshold, scoreThreshold,
+    //          dynamicScorePercentage, filter, sortDocsOn, namespace, sceneIndexId)
+    // Detect it (2nd arg is a SearchType string, or any trailing positional arg
+    // is present) and fold it into an options object, forcing legacy routing —
+    // mirroring videodb-python's `has_old = bool(args)`.
+    const positionalLegacy =
+      typeof optionsOrSearchType === 'string' ||
+      indexType !== undefined ||
+      resultThreshold !== undefined ||
+      scoreThreshold !== undefined ||
+      dynamicScorePercentage !== undefined ||
+      filter !== undefined ||
+      sortDocsOn !== undefined ||
+      namespace !== undefined ||
+      sceneIndexId !== undefined;
+
+    const options: CollectionSearchOptions = positionalLegacy
+      ? {
+          searchType:
+            typeof optionsOrSearchType === 'string'
+              ? (optionsOrSearchType as SearchType)
+              : undefined,
+          indexType,
+          resultThreshold,
+          scoreThreshold,
+          dynamicScorePercentage,
+          filter,
+          sortDocsOn,
+          namespace,
+          sceneIndexId,
+        }
+      : (optionsOrSearchType as CollectionSearchOptions);
+
     const oldParams: (keyof CollectionSearchOptions)[] = [
       'searchType',
       'indexType',
       'resultThreshold',
+      'scoreThreshold',
       'dynamicScorePercentage',
       'sceneIndexId',
       'indexId',
@@ -332,9 +375,9 @@ export class Collection implements ICollection {
       'indexIds',
     ];
 
-    const hasOld = oldParams.some(
-      k => options[k] !== undefined && options[k] !== null
-    );
+    const hasOld =
+      positionalLegacy ||
+      oldParams.some(k => options[k] !== undefined && options[k] !== null);
     const hasNew = newParams.some(
       k => options[k] !== undefined && options[k] !== null
     );