REST API Reference

Supported auth modes

Most workflow endpoints support either:

• X-API-Key: sk_...
• Authorization: Bearer <jwt>

Use API keys for server-to-server integrations. Use JWT bearer tokens for browser-backed or operator-driven workflows.

Scope model

The platform enforces four public scopes:

The hierarchy is documented in the API key controller as admin > write > read > search.

Scope requirements by workflow

Request headers

Example: call a search-scoped endpoint

curl /api/v2/indexes/idx_archive/search \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "reporter at station entrance",
    "top_k": 10
  }'

Example: create an API key

curl -X POST /api/v2/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production search key",
    "scopes": ["read", "search"],
    "expires_in_days": 90
  }'

API key lifecycle endpoints

Related surfaces

• Use Create and rotate API keys for an operator workflow.
• Use SDK setup for media workflows when connecting Python services.
• Use MCP setup when the credential will be embedded in MCP client configuration.

Index endpoints

Indexes are the collection boundary for video-to-vector embeddings and multimodal media search. Prompt runs can add transcription, image embeddings, and metadata_text so later search requests can use both semantic vectors and exact structured metadata.

Media endpoints

Playground media

Playground media is index-less media owned by the current user.

Example: create an index

curl -X POST /api/v2/indexes \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: index-create-archive-2026-04-20" \
  -d '{"name":"Broadcast archive"}'

Example: upload media into an index

curl -X POST /api/v2/videos/upload \
  -H "X-API-Key: sk_live_..." \
  -F "file=@episode-001.mp4" \
  -F "title=Episode 001" \
  -F "index_id=idx_archive"

Segment retrieval

GET /api/v2/videos/{video_id}/segments supports:

• run_id to pin results to one prompt run
• latest_run=true to retrieve the most recent run-backed segments
• cursor pagination

Use this endpoint when you need the canonical segment records rather than ranked search results.

SDK equivalents

• client.indexes.create, client.indexes.list, client.indexes.list_videos
• client.videos.upload, client.videos.retrieve, client.videos.list_segments
• client.videos.batch_retrieve, client.videos.batch_status, client.videos.batch_segments
• client.videos.list_playground

Prompt endpoints

Request shape

Public prompt creation supports these top-level fields:

Example: create a prompt

curl -X POST /api/v2/prompts \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: prompt-create-scene-v1" \
  -d '{
    "name": "Scene extractor",
    "description": "Extract structured scene evidence per segment.",
    "prompt_text": "Extract the requested fields from this media segment.",
    "json_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" }
                }
              }
            }
          }
        }
      }
    },
    "video_level": {
      "instructions_text": "Summarize the entire asset from the extracted segment evidence.",
      "included_segment_fields": ["headline", "scene.location", "transcription"],
      "json_schema": {
        "type": "object",
        "properties": {
          "program_summary": { "type": "string" }
        }
      }
    },
    "semantic_indexing": {
      "disabled_segment_fields": [],
      "disabled_video_level_fields": []
    }
  }'

Schema validation

Use /api/v2/prompts/test-schema before saving a production contract.

curl -X POST /api/v2/prompts/test-schema \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "json_schema": {
      "type": "object",
      "properties": {
        "headline": { "type": "string" }
      }
    },
    "sample_data": {
      "headline": "Reporter outside station"
    }
  }'

Update semantics

PUT /api/v2/prompts/{prompt_id} supports partial replacement of documented prompt fields. Public update behavior includes:

• replacing prompt_text
• replacing json_schema
• replacing video_level
• replacing semantic_indexing
• clearing video_level with clear_video_level: true

Legacy index prompt attachment

The route /api/v2/indexes/{index_id}/prompt still exists, but the route implementation explicitly warns that index-level prompt attachment is deprecated. New integrations should execute prompts through prompt runs.

SDK equivalents

• client.prompts.create
• client.prompts.update
• client.prompts.test_schema
• client.prompts.get_usage

Prompt run endpoints

Execute request

The public execute request uses:

Example: execute against an index

curl -X POST /api/v2/prompt-runs/execute \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: run-archive-2026-04-20" \
  -d '{
    "prompt_id": "prompt_scene_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
  }'

Result retrieval

GET /api/v2/prompt-runs/{run_id}/results requires video_id as a query parameter so the response can paginate one media item's segment-level records at a time.

curl "/api/v2/prompt-runs/run_123/results?video_id=vid_456&limit=50" \
  -H "X-API-Key: sk_live_..."

Failure handling

Use the failed-segment manifest before retrying:

1. Retrieve /failed-segments.
2. Inspect the failed operation counts and retryability.
3. Retry only the affected segment.
4. Poll the retry status endpoint until terminal.

Cancellation

Cancellation is cooperative. The stop request is stored on the run, and work already in progress may still finish before the run reaches a terminal state.

Estimate endpoint

The platform also exposes POST /api/v2/prompt-runs/estimate with the same request shape as execution. It is useful for dry-run validation before execution, but billing interpretation is intentionally out of scope for this documentation set.

SDK equivalents

• client.prompt_runs.execute
• client.prompt_runs.retrieve
• client.prompt_runs.list_results
• client.prompt_runs.get_video_result
• client.prompt_runs.get_failed_segments
• client.prompt_runs.retry_segment
• client.prompt_runs.get_segment_retry_status

Semantic search endpoints

VideoVector search combines vector-style semantic retrieval with structured metadata filters. Use the same index and prompt-run outputs for video vector embedding search, hybrid vector and metadata search, SQL media search, and agentic media search through agentic chat sessions.

Filter search endpoints

SQL search endpoints

Example: multimodal search

curl -X POST /api/v2/indexes/idx_archive/multimodal-search \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text_query": "red emergency vehicle",
    "image_data": "<base64-image>",
    "text_weight": 0.7,
    "image_weight": 0.3,
    "top_k": 20,
    "run_ids": ["run_123"]
  }'

Filter condition contract

Filter requests use a list of conditions. Each condition includes:

The API combines conditions with AND semantics.

Example: filter by nested fields

curl -X POST /api/v2/search/filter/idx_archive \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "run_ids": ["run_123"],
    "conditions": [
      {
        "field": "scene.people[].emotion",
        "operator": "equals",
        "value": "happy",
        "type": "string"
      }
    ],
    "page_size": 50
  }'

SQL search behavior

The SQL catalog response documents:

• queryable tables
• table-to-index and table-to-run mapping
• field-path columns
• default query scaffolding
• public query limits

POST /api/v2/search/sql/{index_id} accepts:

• query
• optional run_ids
• optional index_ids
• optional result_limit

POST /api/v2/search/sql/{index_id}/generate accepts:

• instruction
• optional existing_query
• optional run_ids
• optional index_ids

Example: SQL query generation

curl -X POST /api/v2/search/sql/idx_archive/generate \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "Show the top 20 scenes where scene.people[].emotion is happy.",
    "run_ids": ["run_123"]
  }'

SDK equivalents

• client.search.text
• client.search.image
• client.search.multimodal
• client.search.filter
• client.search.filter_playground
• client.search.multi_run
• client.search.playground

Connector endpoints

Common connector fields

Provider-specific creation

• GCS creation uses multipart form data with credentials_file.
• S3 creation uses JSON with bucket, region, aws_access_key_id, and aws_secret_access_key.
• Azure creation uses JSON with storage_account, container, tenant_id, client_id, and client_secret.

Example: create an S3 connector

curl -X POST /api/v2/connectors/s3 \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: connector-s3-archive" \
  -d '{
    "name": "Archive S3",
    "bucket": "media-archive",
    "region": "us-east-1",
    "aws_access_key_id": "AKIA...",
    "aws_secret_access_key": "<secret>",
    "scopes": ["import", "export"],
    "export_base_path": "exports/review",
    "import_mode": "new_only"
  }'

Example: browse files

curl -X POST /api/v2/connectors/conn_123/browse \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prefix": "incoming/2026/04/",
    "pattern": "*.mp4"
  }'

SDK equivalents

• client.connectors.create_gcs
• client.connectors.create_s3
• client.connectors.create_azure
• client.connectors.test
• client.connectors.browse

Import job endpoints

Request fields

Example: create an import job

curl -X POST /api/v2/import-jobs \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-job-archive-2026-04-20" \
  -d '{
    "connector_id": "conn_archive",
    "index_id": "idx_archive",
    "source_prefix": "incoming/2026/04/",
    "file_pattern": "*.mp4",
    "recursive": true
  }'

Lifecycle

The SDK type model exposes these public statuses:

• pending
• scanning
• importing
• completed
• failed
• cancelled

Use GET /api/v2/import-jobs/{job_id} to inspect job progress, imported media IDs, failed files, skipped files, and terminal error details.

SDK equivalents

• client.import_jobs.create
• client.import_jobs.retrieve
• client.import_jobs.list
• client.import_jobs.cancel

Export endpoints

Export request fields

Index exports support:

• optional prompt_run_ids
• optional destination_connector_id
• optional destination_subpath

Prompt-run exports support:

• optional destination_connector_id
• optional destination_subpath

Example: export selected runs from an index

curl -X POST /api/v2/exports/index/idx_archive \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: export-archive-review" \
  -d '{
    "prompt_run_ids": ["run_123", "run_124"],
    "destination_connector_id": "conn_export",
    "destination_subpath": "exports/review-team"
  }'

Status model

The SDK exposes these public export statuses:

• pending
• processing
• completed
• failed

Completed exports may provide a download URL, connector-delivery metadata, or both depending on the requested destination mode.

SDK equivalents

• client.exports.create_index_export
• client.exports.create_prompt_run_export
• client.exports.retrieve
• client.exports.list

Import automation endpoints

Export automation endpoints

Import automation request

{
  "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"
  }
}

Supported public debounce intervals are:

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

Export automation request

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

Operational behavior

• enabled controls whether the automation is configured for execution.
• paused is the public temporary stop control.
• Pause and resume preserve the configuration.

Related workflows

• Build the source and destination boundaries with Connectors.
• Use Import jobs and Exports for one-time operations.

Webhook endpoints

Event model

The public SDK lists these supported event names:

• media.created
• media.processing.started
• media.processing.completed
• media.processing.failed
• prompt_run.started
• prompt_run.completed
• prompt_run.failed
• prompt_run.cancelled
• prompt_run.partial_completed
• prompt_run.progress
• export.ready
• export.failed
• import_job.started
• import_job.completed
• import_job.failed
• import_job.partial_completed
• import_job.progress

Example: create a webhook

curl -X POST /api/v2/webhooks \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webhook-review-events" \
  -d '{
    "name": "Review operations",
    "url": "https://example.com/webhooks/videovector",
    "events": ["prompt_run.completed", "export.ready"],
    "index_ids": ["idx_archive"],
    "metadata": {"owner":"review-ops"}
  }'

Delivery headers and signature verification

Webhook deliveries include:

• X-Webhook-Signature
• X-Webhook-ID
• X-Delivery-ID
• X-Event-Type

The delivery worker signs the canonical JSON payload with HMAC-SHA256 and sends the header as sha256=<hex-digest>.

import hashlib
import hmac
import json

payload_json = json.dumps(payload, sort_keys=True)
expected = hmac.new(secret.encode("utf-8"), payload_json.encode("utf-8"), hashlib.sha256).hexdigest()
assert received_signature == f"sha256={expected}"

Delivery status and recovery

The delivery worker treats response classes differently:

• 2xx: success
• 4xx: permanent failure, no automatic retry
• 5xx and network failures: retryable failure

Use POST /api/v2/webhooks/deliveries/{delivery_id}/retry when the downstream issue is resolved.

Secret rotation

POST /api/v2/webhooks/{webhook_id}/rotate-secret returns a new secret. Update the receiving system before you depend on the next production delivery.

SDK equivalents

• client.webhooks.create
• client.webhooks.update
• client.webhooks.rotate_secret
• client.webhooks.test
• client.webhooks.list_deliveries
• client.webhooks.retry_delivery

Agentic chat endpoints

Scope model

Each turn can optionally narrow retrieval scope with:

• index_ids
• prompt_run_ids

That scope is stored on the turn as effective_scope.

Example: create a session

curl -X POST /api/v2/chat/sessions \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Daily review assistant"}'

Example: create a scoped turn

curl -X POST /api/v2/chat/sessions/session_123/turns \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Find scenes where a reporter appears outside a station entrance.",
    "scope": {
      "index_ids": ["idx_archive"],
      "prompt_run_ids": ["run_123"]
    },
    "idempotency_key": "chat-turn-session-123-1"
  }'

Streaming protocol

POST /api/v2/chat/sessions/{session_id}/turns/stream returns text/event-stream.

The DTO layer documents event families such as:

• turn_started
• turn_resumed
• agent_state
• tool_call_started
• tool_call_result
• turn_completed
• error

Use Idempotency-Key, X-Idempotency-Key, or the request-body idempotency_key when you need resumable turn behavior.

Response structure

Completed turns can include:

• user_message
• assistant_message
• effective_scope
• tool_trace
• result_sets
• stats
• terminal error details when the turn fails

Processing event stream

GET /api/v2/processing/events/stream exposes Server-Sent Events for processing lifecycle updates.

Public filters include:

• run_id
• index_id
• video_ids
• event_types
• batch_size
• Last-Event-ID request header

Each SSE event includes:

• event_id
• event_type
• user_id
• run_id
• video_id
• segment_id
• index_id
• created_at
• payload

The server also emits heartbeat comments and a processing.stream_error event if the stream terminates unexpectedly.

Marker endpoints

Markers can be attached to prompts, runs, or extracted fields and are surfaced in SDK response models such as marker and metadata_markers.

Signed URL helper

POST /api/v2/videos/signed-url exchanges a gcs_uri for a signed URL.

curl -X POST /api/v2/videos/signed-url \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"gcs_uri":"gs://bucket/path/to/asset.mp4"}'

Raw media helper endpoints

These endpoints are public but intentionally treated as helper surfaces rather than first-class workflow resources:

Batch media helpers

These endpoints are useful when the client already has a media ID set and wants a compact fetch pattern:

• POST /api/v2/videos/batch
• POST /api/v2/videos/batch/status
• POST /api/v2/videos/batch/segments

The Python SDK exposes these as:

• client.videos.batch_retrieve
• client.videos.batch_status
• client.videos.batch_segments

Playground helpers

Playground-specific retrieval surfaces are public and documented on other pages:

• GET /api/v2/playground/videos
• POST /api/v2/playground/search
• POST /api/v2/search/filter/playground