API Overview

This page covers how to connect to OpenViking and the conventions shared across all API endpoints.

Connecting to OpenViking

OpenViking supports three connection modes:

Mode	Use Case	Description
Embedded	Local development, single process	Runs locally with local data storage
HTTP	Connect to OpenViking Server	Connects to a remote server via HTTP API
CLI	Shell scripting, agent tool-use	Connects to server via CLI commands

Embedded Mode

import openviking as ov

client = ov.OpenViking(path="./data")
client.initialize()

Embedded mode uses ov.conf to configure embedding, vlm, storage, and other modules. Default path: ~/.openviking/ov.conf. You can also specify the path via environment variable:

export OPENVIKING_CONFIG_FILE=/path/to/ov.conf

Minimal configuration example:

{
  "embedding": {
    "dense": {
      "api_base": "<api-endpoint>",
      "api_key": "<your-api-key>",
      "provider": "<volcengine|openai|jina|...>",
      "dimension": 1024,
      "model": "<model-name>"
    }
  },
  "vlm": {
    "api_base": "<api-endpoint>",
    "api_key": "<your-api-key>",
    "provider": "<volcengine|openai|openai-codex|kimi|glm>",
    "model": "<model-name>"
  }
}

For provider: "openai-codex", vlm.api_key is optional once Codex OAuth is available through openviking-server init.

For full configuration options and provider-specific examples, see the Configuration Guide.

HTTP Mode

client = ov.SyncHTTPClient(
    url="http://localhost:1933",
    api_key="your-key",
    agent_id="my-agent",
    timeout=120.0,
)
client.initialize()

When url is not explicitly provided, the HTTP client automatically loads connection info from ovcli.conf. This config file is shared between the HTTP client and CLI. Default path: ~/.openviking/ovcli.conf. You can also specify the path via environment variable:

export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf

{
  "url": "http://localhost:1933",
  "api_key": "your-key",
  "account": "acme",
  "user": "alice",
  "agent_id": "my-agent"
}

Field	Description	Default
url	Server address	(required)
api_key	API key	null (no auth)
account	Default account header for tenant-scoped requests	null
user	Default user header for tenant-scoped requests	null
agent_id	Agent identifier header	null
timeout	HTTP request timeout in seconds	60.0
output	Default output format: "table" or "json"	"table"

See the Configuration Guide for details.

Local files in HTTP mode

• CLI, SyncHTTPClient, and AsyncHTTPClient automatically upload local files and directories before calling the server API.
• Raw HTTP callers do not get this convenience layer. When using curl or another HTTP client, upload the file with POST /api/v1/resources/temp_upload first, then call the target API with the returned temp_file_id.
• For local directories in raw HTTP mode, zip the directory first and upload the .zip file; the server does not accept direct host directory paths.
• POST /api/v1/resources accepts remote URLs directly, but does not accept direct host filesystem paths such as ./doc.md or /tmp/doc.md.

Direct HTTP (curl)

curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \
  -H "X-API-Key: your-key"

CLI Mode

The CLI connects to an OpenViking server and exposes all operations as shell commands. The CLI also loads connection info from ovcli.conf (shared with the HTTP client).

Basic Usage

openviking [global options] <command> [arguments] [command options]

Global Options (must be placed before the command name)

Option	Description
--output, -o	Output format: table (default), json
--version	Show CLI version

Example:

openviking -o json ls viking://resources/

Lifecycle

Embedded Mode

import openviking as ov

client = ov.OpenViking(path="./data")
client.initialize()

# ... use client ...

client.close()

HTTP Mode

import openviking as ov

client = ov.SyncHTTPClient(url="http://localhost:1933")
client.initialize()

# ... use client ...

client.close()

Authentication

See Authentication Guide for full details.

• X-API-Key header: X-API-Key: your-key
• Bearer header: Authorization: Bearer your-key
• If no API key is configured on the server, authentication is skipped.
• The /health endpoint never requires authentication.

Response Format

All HTTP API responses follow a unified format:

Success

{
  "status": "ok",
  "result": { ... },
  "time": 0.123
}

The top-level status describes whether the HTTP API request succeeded. Some successful operations return domain-level status fields inside result, such as "status": "success", "status": "accepted", or task states. Those fields are not API transport errors.

Error

{
  "status": "error",
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found: viking://resources/nonexistent/"
  },
  "time": 0.01
}

HTTP errors always use the top-level error envelope. Synchronous processing failures, such as resource parsing or synchronous reindex failures, are returned as non-2xx responses with status="error" and an error object. Clients should not look for result.status="error" to detect request failure.

Request validation failures, including malformed JSON, missing required fields, and invalid parameter values, return HTTP 400 with error.code="INVALID_ARGUMENT". The response never uses FastAPI's raw {"detail": ...} error format; when field-level validation information is available, it is exposed under error.details.validation_errors.

Python HTTP SDKs (SyncHTTPClient and AsyncHTTPClient) raise the corresponding OpenVikingError subclass for this envelope. For example, PROCESSING_ERROR is raised as ProcessingError.

CLI Output Format

Table Mode (default)

List data is rendered as tables; non-list data falls back to formatted JSON:

openviking ls viking://resources/
# name          size  mode  isDir  uri
# .abstract.md  100   420   False  viking://resources/.abstract.md

JSON Mode (--output json)

All commands output formatted JSON matching the API response result structure:

openviking -o json ls viking://resources/
# [{ "name": "...", "size": 100, ... }, ...]

The default output format can be set in ovcli.conf:

{
  "url": "http://localhost:1933",
  "output": "json"
}

Script Mode (-o json)

Compact JSON with status wrapper (when --compact is true, which is the default), suitable for scripting:

Success

{"ok": true, "result": ...}

Error

{"ok": false, "error": {"code": "NOT_FOUND", "message": "Resource not found", "details": {}}}

Special Cases

• String results (read, abstract, overview): printed directly as plain text
• None results (mkdir, rm, mv): no output

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
3	Connection error

Error Codes

Code	HTTP Status	Description
OK	200	Success
INVALID_ARGUMENT	400	Invalid parameter
INVALID_URI	400	Invalid Viking URI format
NOT_FOUND	404	Resource not found
ALREADY_EXISTS	409	Resource already exists
UNAUTHENTICATED	401	Missing or invalid API key
PERMISSION_DENIED	403	Insufficient permissions
RESOURCE_EXHAUSTED	429	Rate limit exceeded
FAILED_PRECONDITION	412	Precondition failed
CONFLICT	409	Operation conflicts with an in-progress task or existing state
DEADLINE_EXCEEDED	504	Operation timed out
UNAVAILABLE	503	Service unavailable
PROCESSING_ERROR	500	Resource or semantic processing failed
INTERNAL	500	Internal server error
UNIMPLEMENTED	501	Feature not implemented
EMBEDDING_FAILED	500	Embedding generation failed
VLM_FAILED	500	VLM call failed
SESSION_EXPIRED	410	Session no longer exists

API Endpoints

System

Method	Path	Description
GET	/health	Health check (no auth)
GET	/ready	Readiness probe (no auth)
GET	/metrics	Prometheus metrics export
GET	/api/v1/system/status	System status
POST	/api/v1/system/wait	Wait for processing

Resources

Method	Path	Description
POST	/api/v1/resources/temp_upload	Upload local file for raw HTTP resource / pack import
POST	/api/v1/resources	Add resource
POST	/api/v1/skills	Add skill
POST	/api/v1/pack/export	Export .ovpack
POST	/api/v1/pack/import	Import .ovpack

File System

Method	Path	Description
GET	/api/v1/fs/ls	List directory
GET	/api/v1/fs/tree	Directory tree
GET	/api/v1/fs/stat	Resource status
POST	/api/v1/fs/mkdir	Create directory
DELETE	/api/v1/fs	Delete resource
POST	/api/v1/fs/mv	Move resource

Content

Method	Path	Description
GET	/api/v1/content/read	Read full content (L2)
GET	/api/v1/content/abstract	Read abstract (L0)
GET	/api/v1/content/overview	Read overview (L1)
GET	/api/v1/content/download	Download raw file bytes
POST	/api/v1/content/write	Update an existing file and refresh semantics/vectors
POST	/api/v1/content/reindex	Rebuild semantic/vector index for existing content

Search

Method	Path	Description
POST	/api/v1/search/find	Semantic search
POST	/api/v1/search/search	Context-aware search
POST	/api/v1/search/grep	Pattern search
POST	/api/v1/search/glob	File pattern matching

Relations

Method	Path	Description
GET	/api/v1/relations	Get relations
POST	/api/v1/relations/link	Create link
DELETE	/api/v1/relations/link	Remove link

Sessions

Method	Path	Description
POST	/api/v1/sessions	Create session
GET	/api/v1/sessions	List sessions
GET	/api/v1/sessions/{id}	Get session
GET	/api/v1/sessions/{id}/context	Get assembled session context
DELETE	/api/v1/sessions/{id}	Delete session
POST	/api/v1/sessions/{id}/commit	Commit session
POST	/api/v1/sessions/{id}/extract	Extract memories from a session
POST	/api/v1/sessions/{id}/messages	Add message
POST	/api/v1/sessions/{id}/used	Record contexts / skills actually used
GET	/api/v1/sessions/{id}/archives/{archive_id}	Get a specific session archive

Tasks

Method	Path	Description
GET	/api/v1/tasks/{task_id}	Get background task status
GET	/api/v1/tasks	List background tasks

Observer

Method	Path	Description
GET	/api/v1/observer/queue	Queue status
GET	/api/v1/observer/vikingdb	VikingDB status
GET	/api/v1/observer/models	Models status (VLM / embedding / rerank)
GET	/api/v1/observer/lock	Lock subsystem status
GET	/api/v1/observer/retrieval	Retrieval subsystem status
GET	/api/v1/observer/system	System status

Debug

Method	Path	Description
GET	/api/v1/debug/health	Quick health check
GET	/api/v1/debug/vector/scroll	Paginated vector record inspection
GET	/api/v1/debug/vector/count	Count vector records

Admin (Multi-tenant)

Method	Path	Description
POST	/api/v1/admin/accounts	Create workspace + first admin (ROOT)
GET	/api/v1/admin/accounts	List workspaces (ROOT)
DELETE	/api/v1/admin/accounts/{account_id}	Delete workspace (ROOT)
POST	/api/v1/admin/accounts/{account_id}/users	Register user (ROOT, ADMIN)
GET	/api/v1/admin/accounts/{account_id}/users	List users (ROOT, ADMIN)
DELETE	/api/v1/admin/accounts/{account_id}/users/{user_id}	Remove user (ROOT, ADMIN)
PUT	/api/v1/admin/accounts/{account_id}/users/{user_id}/role	Change user role (ROOT)
POST	/api/v1/admin/accounts/{account_id}/users/{user_id}/key	Regenerate user key (ROOT, ADMIN)

Related Documentation

• Resources - Resource management API
• Retrieval - Search API
• File System - File system operations
• Sessions - Session management
• Skills - Skill management
• System - System and monitoring API
• Metrics - Prometheus metrics export and scraping guide
• Admin - Multi-tenant management API