Implementation guides

Use a Firebase browser-session bearer token to manage API keys. Use the created API keys for scoped API, SDK, and MCP integrations. Hosted MCP also supports browser OAuth; an MCP OAuth access token cannot manage API keys.

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://api.vectormethods.com/api/v2/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Idempotency-Key: api-key-create-<unique-attempt-id>" \
  -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: full access within your account, including destructive tenant-resource operations; never platform administration

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://api.vectormethods.com/api/v2/api-keys/key_123/rotate \
  -H "Authorization: Bearer <jwt>" \
  -H "Idempotency-Key: api-key-rotate-key_123-<unique-attempt-id>"

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:

VIDEOVECTOR_API_KEY=sk_live_... videovector-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://api.vectormethods.com/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://api.vectormethods.com/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="content_aware",
        audio_segmentation_type="content_aware",
        processing_model="gemini-3.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://api.vectormethods.com/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://api.vectormethods.com/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://api.vectormethods.com/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://api.vectormethods.com/api/v2/chat/sessions/session_123/turns/stream \
  -H "X-API-Key: ${VIDEOVECTOR_API_KEY}" \
  -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://api.vectormethods.com/api/v2/connectors/gcs \
  -H "Authorization: Bearer <token-or-api-key>" \
  -H "Idempotency-Key: connector-gcs-create-<unique-attempt-id>" \
  -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://api.vectormethods.com/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://api.vectormethods.com/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

Connect with browser OAuth

Add https://api.vectormethods.com/mcp as a remote Streamable HTTP server in your MCP client and choose OAuth. Sign in to your VideoVector account in the browser, verify your email if requested, and return to the client. The client discovers the authorization server and refreshes its tokens; you do not need a local npm package or an API key for this path.

Use Claude's connector setup, Cursor's URL configuration, or the custom-client OAuth contract. Ask the connected client to list your indexes to verify authenticated access.

Choose an authentication boundary

OAuth connects the signed-in account with its permitted tenant operations. Ownership, plan, and credits still apply. Use a scoped API key when you need a restricted automated integration. Hosted HTTP clients can send X-API-Key to the same MCP URL; local stdio uses VIDEOVECTOR_API_KEY.

Run a local stdio server

npm install -g @vectormethods/videovector-mcp-server
VIDEOVECTOR_API_KEY=sk_live_... videovector-mcp

The package is @vectormethods/videovector-mcp-server, the command is videovector-mcp, and the server name is videovector. Local stdio supports authorized file-path uploads in addition to native attachments.

REST helper endpoints

• GET /api/v2/mcp/status: package and capability information
• GET /api/v2/mcp/config: generate local API-key configuration using a verified VideoVector browser session
• GET /api/v2/mcp/tools: inspect the REST helper tool contract
• POST /api/v2/mcp/playground: test a tool through the API

These helpers do not register OAuth clients or issue tokens. Remote clients use OAuth discovery and their own connection's tools/list result.

Self-hosted HTTP

Use MCP_TRANSPORT_MODE=http when operating your own server. The transport is stateless and does not use MCP session IDs. See custom clients and self-hosted HTTP for configuration.

Connect n8n

Use the community package @vectormethods/n8n-nodes-videovector on self-hosted n8n. Install it from Settings → Community nodes, then add a VideoVector API credential. Use the default API URL https://api.vectormethods.com/api/v2 and a key from your VideoVector account. The connection test validates the key without creating or reading resources.

On n8n Cloud, native installation requires the package to be available in the verified community catalog. Built-in HTTP Request and MCP Client Tool nodes also work without installing the community package.

Use a write-scoped key for normal ingestion, extraction, and search workflows. The VideoVector Trigger requires an admin-scoped key to register and remove its webhook subscription. Keep keys in n8n credentials, never workflow JSON.

Upload, run, and retrieve results

1. Fetch media with a source node such as Google Drive, S3, or HTTP Request.
2. Use VideoVector → Media → Upload with the binary property, usually data.
3. Use Run → Start with a saved prompt or new instructions. For Specific Media, set Media Location to Playground or to the containing Index; selected media IDs must belong to that location.
4. Save the returned run_id and use a native Wait node between status checks.
5. Retrieve segment or video-level results with Run → Results.

Public or signed media URLs can use Media → Import URLs. That operation returns an import job. Poll the import job until completion before starting a run with its video_ids. Failed-file details remain available in the response.

The public integration repository contains importable binary-upload, URL-import, HTTP, standalone MCP, and MCP agent templates. The job templates wait 65 seconds between status requests and stop after a 24-hour deadline, retaining resource IDs in timeout errors. Partial run completion follows a separate branch and still retrieves available results.

Choose result output

List and result operations return separate n8n items for downstream mapping. Return All follows supported pagination cursors within the server's result snapshot; a search's result window still applies. Full Response returns each API response page, including pagination, coverage, and warnings. Run results can select filtered, unfiltered, or both views at segment or video level.

Saved prompts keep their execution defaults unless you add an override. Native submissions retain their per-item idempotency keys across Retry On Fail and Retry Execution. Fresh executions and loop iterations get new keys. The HTTP template saves its key in Configure so Retry Execution uses the original submission identity. To deduplicate source events across separate workflow executions, supply the source event ID as an explicit Idempotency Key; use a new key for a new business operation.

Start a workflow from events

The VideoVector Trigger registers a webhook for selected events and indexes, verifies incoming signatures, and removes its subscription when deactivated. Your n8n webhook endpoint must be publicly reachable over HTTPS. Use completion, partial-completion, failure, cancellation, and export-ready events to continue workflows. Fetch the associated resource when you need the latest full status. For self-hosted n8n 2.42.4, configure N8N_WEBHOOK_URL with the public HTTPS base URL; this applies to both test and production webhook URLs.

Events can be delivered more than once. Use $json._delivery.delivery_id or the source resource ID when deduplicating writes into another system.

Use built-in HTTP or an AI agent

For HTTP Request, select Header Auth with header name X-API-Key. Calls use the same /api/v2 API as the native nodes. Send Idempotency-Key when creating work and use native Wait nodes for long jobs.

For a direct tool call, use the built-in MCP Client with streamable HTTP at https://api.vectormethods.com/mcp and Header Auth using X-API-Key. Select list_indexes and use JSON input {"include_defaults":true} to discover available indexes. This needs only your VideoVector credential; the response includes structuredContent.user_indexes and structuredContent.default_indexes.

The hosted MCP endpoint also supports browser OAuth account linking for compatible remote clients. The shipped n8n HTTP/MCP templates intentionally use scoped API keys and remain supported. Native VideoVector nodes call the REST API with X-API-Key; they do not require MCP OAuth.

For an AI Agent, attach MCP Client Tool and a supported chat model instead. The agent template includes an OpenAI Chat Model node that requires its own model-provider credential. Use explicit action nodes or MCP Client for deterministic scheduled automation.