Implementation guides

Use JWT bearer auth to manage API keys. Use the created API keys for most API, SDK, and MCP workflow calls.

Prerequisites

• A user session that can call the JWT-only API key endpoints.
• A clear scope plan for the integration, such as read, write, search, or admin.

Create a key

curl -X POST https://playground-api-stg-udk7d32fva-uc.a.run.app/api/v2/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Search integration",
    "scopes": ["read", "search"],
    "expires_in_days": 90
  }'

Choose scopes deliberately

• search: search and retrieval workflows
• read: list and inspect public resources
• write: create and update workflow resources
• admin: destructive or higher-privilege operations

For MCP configuration generated from the public /mcp/config flow, the platform prefers an active key with at least read-level capability and will create one when needed.

Rotate a key

Rotate a key when:

• the secret may be exposed
• the integration owner changes
• you are following a regular credential rotation policy

Rotation returns a new full secret and revokes the old one.

curl -X POST https://playground-api-stg-udk7d32fva-uc.a.run.app/api/v2/api-keys/key_123/rotate \
  -H "Authorization: Bearer <jwt>"

Revoke or delete

• Revoke when you want the key to remain visible but inactive.
• Delete when the key should be removed entirely.

Use the key in clients

Python SDK:

from videovector import VideoVector

with VideoVector(api_key="sk_live_...") as client:
    runs = client.prompt_runs.list(limit=20)

MCP server:

VIDEOSEARCH_API_KEY=sk_live_... videosearch-mcp

Build the segment-level schema first

Start with the evidence-level fields you need per segment.

For schema-aware video metadata extraction, treat the schema as the public contract that operators, search filters, exports, and downstream applications will reuse. Stable nested field names make JSON schema media extraction easier to query after extraction executions complete.

{
  "type": "object",
  "properties": {
    "headline": { "type": "string" },
    "scene": {
      "type": "object",
      "properties": {
        "location": { "type": "string" },
        "people": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "emotion": { "type": "string" }
            }
          }
        }
      }
    }
  }
}

Create the extraction engine

from videovector import VideoVector

schema = {
    "type": "object",
    "properties": {
        "headline": {"type": "string"},
        "scene": {
            "type": "object",
            "properties": {
                "location": {"type": "string"},
                "people": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "name": {"type": "string"},
                            "emotion": {"type": "string"},
                        },
                    },
                },
            },
        },
    },
}

with VideoVector(api_key="sk_live_...") as client:
    extraction_engine = client.prompts.create(
        name="Segment scene extractor",
        description="Extract scene-level metadata.",
        prompt_text="Extract the requested fields from this media segment.",
        json_schema=schema,
        semantic_indexing={
            "disabled_segment_fields": [],
            "disabled_video_level_fields": [],
        },
    )

Validate the schema against sample data

Use the public schema test surface before you save or publish a contract that downstream systems rely on.

curl -X POST https://playground-api-stg-udk7d32fva-uc.a.run.app/api/v2/prompts/test-schema \
  -H "Authorization: Bearer <token-or-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "json_schema": {
      "type": "object",
      "properties": {
        "headline": { "type": "string" }
      }
    },
    "sample_data": {
      "headline": "Crowd gathers near station entrance"
    }
  }'

Keep the schema query-friendly

• Use stable field names.
• Avoid ., [ and ] in field names.
• Treat repeated object fields as future filter paths such as scene.people[].emotion.
• Disable semantic indexing only when a field should stay in structured output but not in embeddings.

When to add video-level synthesis

If the workflow also needs one result per media item, add video_level after the segment-level schema is stable. That keeps evidence extraction and media-wide synthesis as separate contracts.

Video-level synthesis is configured on the extraction engine, not on the run request.

Use video-level synthesis as the rollup layer for segment-driven video analysis. The media-wide result can summarize timestamped segment evidence while the original segment-level outputs remain available for search, filters, exports, and validation.

Choose the fields to carry forward

included_segment_fields should contain the segment fields that matter to the media-wide summary. That list can also include public system fields such as transcription and metadata_text.

Example extraction engine definition

from videovector import VideoVector

with VideoVector(api_key="sk_live_...") as client:
    extraction_engine = client.prompts.create(
        name="Episode extraction engine",
        prompt_text="Extract the requested evidence per segment.",
        json_schema={
            "type": "object",
            "properties": {
                "summary": {"type": "string"},
                "risk_level": {"type": "string"},
            },
        },
        video_level={
            "instructions_text": "Summarize the full asset and identify the dominant risk pattern.",
            "included_segment_fields": ["summary", "risk_level", "transcription"],
            "json_schema": {
                "type": "object",
                "properties": {
                    "program_summary": {"type": "string"},
                    "dominant_risk_level": {"type": "string"},
                },
            },
        },
    )

Retrieve the result

After an extraction execution completes, retrieve the media-wide result from the run rather than searching for it as if it were a segment result.

curl https://playground-api-stg-udk7d32fva-uc.a.run.app/api/v2/prompt-runs/run_123/videos/vid_456/video-result \
  -H "Authorization: Bearer <token-or-api-key>"

Design recommendations

• Keep the video-level schema smaller than the segment-level schema.
• Include only the fields that are actually needed for synthesis.
• Use video-level output for rollups and editorial summaries, not for evidence that should remain searchable per segment.

Common mistake

Do not move evidence-level fields out of the segment schema just because a media-wide summary also needs them. Segment search, filters, and exports still depend on the segment-level contract.

Pick the right target type

• Use index for whole-collection processing.
• Use videos for selected media IDs.
• Use playground when the workflow is isolated to playground content.

Execute a run

from videovector import VideoVector

with VideoVector(api_key="sk_live_...") as client:
    run = client.prompt_runs.execute(
        prompt_id="prompt_episode_extract",
        target={"type": "index", "index_id": "idx_archive"},
        video_segmentation_type="smart",
        audio_segmentation_type="content_aware",
        processing_model="gemini-2.5-flash",
        enable_transcription=True,
        enable_image_embedding=True,
        idempotency_key="extraction-execution-archive-2026-04-20",
    )

Use fixed segmentation only when you need it

If you choose fixed segmentation, include the matching duration field.

{
  "video_segmentation_type": "fixed",
  "video_segment_duration": 15,
  "audio_segmentation_type": "fixed",
  "audio_segment_duration": 30
}

Inspect status and results

After execution:

1. Poll the run status or subscribe to the processing event stream.
2. Inspect terminal state and failure counts.
3. Retrieve segment results for a media item.
4. Retrieve the media-wide result if video_level is enabled.

curl https://playground-api-stg-udk7d32fva-uc.a.run.app/api/v2/prompt-runs/run_123 \
  -H "Authorization: Bearer <token-or-api-key>"

Retry failed segments

If the run ends with failures, inspect the failed segment manifest and retry only the affected segments instead of rerunning the entire workflow.

curl -X POST https://playground-api-stg-udk7d32fva-uc.a.run.app/api/v2/prompt-runs/run_123/videos/vid_456/segments/seg_789/retry \
  -H "Authorization: Bearer <token-or-api-key>"

Cancel safely

Use cancellation when the operator's intent changed. Already-started work may finish, but no new media items should start after the stop is observed.

Text search

Use this guide when implementing video vector embedding search, hybrid vector and metadata search, SQL media search, or agentic media search on top of the same indexed media and extraction execution outputs.

Use text search first when the user can describe the desired content in natural language.

results = client.search.text(
    index_id="idx_archive",
    query="reporter speaking outside a station entrance",
    top_k=10,
    search_fields=["summary", "scene.location"],
)

Image and multimodal search

Use image or multimodal search when the user has a visual reference.

results = client.search.multimodal(
    index_id="idx_archive",
    text_query="red emergency vehicle",
    image_data=encoded_image,
    text_weight=0.7,
    image_weight=0.3,
    top_k=20,
)

Filter search with nested fields

Use filter search when the workflow needs exact or constrained matching.

{
  "conditions": [
    { "field": "scene.people[].emotion", "operator": "equals", "value": "happy", "type": "string" },
    { "field": "scene.people[].confidence", "operator": "greater_equal", "value": 0.8, "type": "number" }
  ],
  "page_size": 50
}

That pattern relies on canonical dotted field paths and [] for repeated objects.

Search by selected runs

When an index contains several extraction executions, pass run_ids deliberately instead of assuming the default search scope matches the workflow you need.

Use SQL search for analyst workflows

Use SQL search when the operator needs:

• selected columns
• aggregations
• analyst-style filtering
• saved-query behavior

Typical flow:

1. Get the SQL catalog for an index.
2. Inspect the available run-backed tables and columns.
3. Execute SQL or generate a draft query from natural language.

curl -X POST https://playground-api-stg-udk7d32fva-uc.a.run.app/api/v2/search/sql/idx_archive/catalog \
  -H "Authorization: Bearer <token-or-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"run_ids":["run_123"]}'

Use agentic chat sessions for agentic search

Use agentic chat sessions when the operator needs a search assistant rather than one fixed retrieval request.

Typical fit:

• an analyst wants to ask follow-up questions over the same search scope
• the client needs scoped conversational retrieval across specific indexes or extraction executions
• the product needs streaming assistant responses and tool-trace visibility

curl -X POST https://playground-api-stg-udk7d32fva-uc.a.run.app/api/v2/chat/sessions/session_123/turns/stream \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Find scenes where the same reporter appears outside multiple station entrances and summarize the differences.",
    "scope": {
      "index_ids": ["idx_archive"],
      "prompt_run_ids": ["run_people_v2", "run_locations_v1"]
    },
    "idempotency_key": "agent-search-session-123-turn-4"
  }'

Choose connector scopes first

A connector can support:

• import
• export
• both

If the connector should only receive exports, do not give it import scope.

Create a GCS connector

GCS connector creation uses multipart form data because the public surface accepts a service account JSON file.

curl -X POST https://playground-api-stg-udk7d32fva-uc.a.run.app/api/v2/connectors/gcs \
  -H "Authorization: Bearer <token-or-api-key>" \
  -F "name=Broadcast storage" \
  -F "bucket=archive-bucket" \
  -F "gcp_project_id=media-project-123" \
  -F "scopes=import" \
  -F "credentials_file=@service-account.json"

Create S3 or Azure connectors

S3 and Azure connector creation uses JSON payloads with provider-specific credentials and optional export_base_path.

Test and browse the connector

After creation:

1. Call the test endpoint to validate credentials and access.
2. Browse the connector with a prefix and pattern before you start an import job.

connector = client.connectors.create_s3(
    name="Archive S3",
    bucket="media-archive",
    region="us-east-1",
    aws_access_key_id="AKIA...",
    aws_secret_access_key="...",
    scopes=["import", "export"],
    export_base_path="exports/team-a",
)

client.connectors.test(connector.connector_id)
files = client.connectors.browse(connector.connector_id, prefix="incoming/", pattern="*.mp4")

Import mode

Connectors expose import_mode such as:

• all
• new_only

Use new_only when the connector should behave as a dedupe-oriented ingestion source across recurring intake flows.

Start with a one-time import job

job = client.import_jobs.create(
    connector_id="conn_archive",
    index_id="idx_archive",
    source_prefix="incoming/2026/04/",
    file_pattern="*.mp4",
    recursive=True,
)

Poll or retrieve the job to inspect:

• progress
• imported video_ids
• failed files
• skipped files

Add connector intake settings

Connector intake settings are index-level saved configurations. They require:

• connector_id
• source prefix and file pattern
• debounce_interval
• an extraction preset with at least prompt_id

{
  "enabled": true,
  "paused": false,
  "connector_id": "conn_archive",
  "source_prefix": "incoming/daily/",
  "file_pattern": "*.mp4",
  "recursive": true,
  "debounce_interval": "10m",
  "prompt_preset": {
    "prompt_id": "prompt_episode_extract"
  }
}

Debounce intervals

Supported public debounce intervals are:

• 5m
• 10m
• 1h
• 1d

Use the shortest interval that matches the business process rather than trying to simulate near-real-time internal polling behavior.

Pause and resume

Connector intake can be paused and resumed without deleting the saved configuration. That is the preferred control for temporary operational freezes.

Export by index or by extraction execution

Export by index when the consumer wants the collection view. Export by extraction execution when the consumer wants one execution boundary.

export = client.exports.create_index_export(
    index_id="idx_archive",
    prompt_run_ids=["run_123", "run_124"],
    destination_connector_id="conn_export",
    destination_subpath="exports/editorial",
)

Download versus connector delivery

Public exports can target:

• a downloadable artifact
• a connector destination

When using a connector destination, keep the export path within the connector's configured export_base_path.

Configure export automation settings

Export automation settings are saved per index and define:

• destination_connector_id
• optional destination_subpath
• enabled and paused state

{
  "enabled": true,
  "paused": false,
  "destination_connector_id": "conn_export",
  "destination_subpath": "exports/review-team"
}

Operational recommendation

Use explicit subpaths when several downstream systems share the same destination connector. That keeps ownership boundaries obvious and avoids ambiguous output placement.

Route platform events

curl -X POST https://playground-api-stg-udk7d32fva-uc.a.run.app/api/v2/webhooks \
  -H "Authorization: Bearer <token-or-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Extraction terminal notifications",
    "url": "https://example.com/webhooks/videovector",
    "events": ["prompt_run.completed", "prompt_run.failed"],
    "index_ids": ["idx_archive"],
    "metadata": {"owner":"media-intelligence"}
  }'

Save the returned secret immediately. It is shown at creation time and after secret rotation.

Validate event delivery

Use the test endpoint after creation and after any destination change.

webhook = client.webhooks.create(
    name="Extraction events",
    url="https://example.com/webhooks/videovector",
    events=["prompt_run.completed", "export.ready"],
)

client.webhooks.test(webhook.webhook_id)

Control downstream delivery

Pause a webhook when the downstream system is temporarily unavailable. Delete only when the integration should no longer exist.

Monitor delivery history

The public delivery surface includes:

• delivery status
• attempt counts
• response status codes
• response bodies
• retry scheduling fields
• payload inspection

Retry a failed delivery when the downstream issue is resolved.

curl -X POST https://playground-api-stg-udk7d32fva-uc.a.run.app/api/v2/webhooks/deliveries/del_123/retry \
  -H "Authorization: Bearer <token-or-api-key>"

Maintain signing trust

Rotate the webhook secret when:

• the destination owner changes
• the secret may have been exposed
• your security policy requires scheduled rotation

Use the published package names

Use these package and environment identifiers when installing or configuring the MCP server:

• package: @videosearch/mcp-server
• command: videosearch-mcp
• environment variables: VIDEOSEARCH_*

Install and run in stdio mode

npm install -g @videosearch/mcp-server
VIDEOSEARCH_API_KEY=sk_live_... videosearch-mcp

Use generated config when available

If your application uses the public MCP helper endpoints, use:

• GET /api/v2/mcp/status
• GET /api/v2/mcp/config
• GET /api/v2/mcp/tools
• POST /api/v2/mcp/playground

Those helpers are useful for setup, inspection, and client testing before a full deployment.

Choose the correct transport

• Use stdio for local agent environments such as Claude Desktop or Cursor.
• Use HTTP when the MCP server needs a network addressable endpoint, readiness probes, host/origin controls, or session controls.

For platform-specific configuration details, continue to the dedicated Claude Desktop, Cursor, or Custom / HTTP transport pages.