Search documentation
Search pages, API reference sections, and guide headings.
Summary
The public API accepts either API keys or JWT bearer tokens for most workflow endpoints. API key management endpoints require JWT bearer auth, and `/mcp/config` requires a verified JWT session.
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.
API key management endpoints under /api-keys require JWT bearer auth. An API key cannot create, rotate,
revoke, or delete other API keys.
Scope model
The platform enforces four public scopes:
| Scope | Typical capability |
|---|---|
search | Search, retrieval, and chat retrieval workflows |
read | Read workflow resources and inspect results |
write | Create or update prompts, runs, connectors, jobs, and webhooks |
admin | Delete higher-risk resources |
The hierarchy is documented in the API key controller as admin > write > read > search.
Scope requirements by workflow
| Endpoint family | Requirement |
|---|---|
/indexes/*/search, /search/*, /chat/* | search |
Most GET workflow resources | read |
| Most create or update workflow resources | write |
| Destructive deletes | admin |
/api-keys/* | JWT bearer only |
/mcp/config | verified JWT bearer only |
Request headers
| Header | When to use |
|---|---|
X-API-Key | Preferred for programmatic API clients |
Authorization: Bearer ... | JWT sessions and operator workflows |
Idempotency-Key | Safe retry for create, update, execute, cancel, and retry-style writes |
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
| Method | Path | Notes |
|---|---|---|
POST | /api/v2/api-keys | Create a key and return the full secret once |
GET | /api/v2/api-keys | List masked keys |
GET | /api/v2/api-keys/{key_id} | Retrieve one masked key |
POST | /api/v2/api-keys/{key_id}/rotate | Return a new full secret and revoke the old one |
POST | /api/v2/api-keys/{key_id}/revoke | Soft-disable the key |
DELETE | /api/v2/api-keys/{key_id} | Remove the key |
Rotation and creation are the only moments when the full API key secret is returned. Persist it immediately in your own secret store.
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.
Related documentation
API keys are the primary credential for public workflow access. This guide shows how to create them, scope them, and rotate them without breaking integrations.
Use this page to initialize the Python SDK for media ingestion, extraction, search, delivery, and automation flows, then configure credentials and runtime behavior as needed.
The VideoVector MCP docs show how AI clients can browse indexes, run prompts, search media evidence, inspect workflow resources, and validate available tools.