API Overview

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

Connection Modes

OpenViking supports two usage modes: Embedded Mode (direct Python API calls) and Client-Server Mode (via HTTP API).

This API documentation primarily focuses on the HTTP API usage in Client-Server Mode. Embedded mode is available but will not be covered separately in subsequent documentation.

Embedded Mode (Brief Overview)

Embedded mode allows direct OpenViking API calls within a Python process without starting a separate server process.

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 configuration 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.

Client-Server Mode (Main Focus)

Client-Server mode connects to an OpenViking server via HTTP API, supporting multi-tenancy, remote access, and other features. See the deployment documentation for how to start the OpenViking server.

Python SDK Client

import openviking as ov

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 reads connection information from ovcli.conf. ovcli.conf is a configuration file 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

Configuration file example:

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

Configuration field description:

See the Configuration Guide for details.

Using Python SDK Client Without Configuration File

SyncHTTPClient and AsyncHTTPClient support operating completely without relying on the ovcli.conf configuration file, by explicitly passing all parameters during initialization:

import openviking as ov

client = ov.SyncHTTPClient(
    url="http://localhost:1933",          # Explicitly provided
    api_key="your-key",                    # Explicitly provided (api_key usually identifies user identity)
    timeout=30.0,                          # Don't use default 60.0
    extra_headers={}                       # Pass empty dict instead of None, useful for gateway auth in some scenarios
)
client.initialize()

⚠️ Note: The client will attempt to load the configuration file if any of the following conditions are met:

• url is None
• api_key is None
• timeout equals 60.0 (default value)
• extra_headers is None

HTTP Call Examples

• CLI, SyncHTTPClient, and AsyncHTTPClient automatically upload local files or directories before calling the server API.
• Raw HTTP calls don't get this convenience layer. When using curl or other HTTP clients, you need to first call POST /api/v1/resources/temp_upload, then pass the returned temp_file_id to the target API.
• For raw HTTP imports of local directories, you need to first zip them into a .zip file and upload using the above method; the server does not accept direct host directory paths.
• POST /api/v1/resources can directly accept remote URLs, but does not accept host local paths like ./doc.md or /tmp/doc.md.

Direct HTTP (curl) call example:

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

CLI Mode

The OpenViking CLI (can be abbreviated as ov command) connects to an OpenViking server and exposes all operations as shell commands. The CLI also reads connection information 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):

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()

Client-Server Mode

import openviking as ov

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

# ... use client ...

client.close()

The CLI is called directly via the command line, requiring the ovcli.conf file to be configured first, with no additional client initialization needed:

openviking -o json ls viking://resources/

Authentication

See the Authentication Guide for full details.

• Authorization Bearer header: Authorization: Bearer your-key (recommended)
• X-API-Key header: X-API-Key: your-key
• If the server doesn't have an API Key configured, authentication is skipped.
• The /health and /ready endpoints never require authentication.

Response Format

All HTTP API responses follow a unified format:

Success Response

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

{
  "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 result structure of API responses:

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

Compact Mode (--compact, -c)

• When --output=json: Compact JSON format + {ok, result} wrapper, suitable for scripts
• When --output=table: Simplified representation for table output (e.g., removing empty columns)

JSON output - success:

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

JSON output - 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

Note: Exit codes are return codes from the CLI (command line tool), not HTTP API status codes.

Error Codes

API Endpoints

Below are all HTTP API endpoints provided by OpenViking, grouped by functional module:

System

Resources

Pack

File System

Content

Search

Relations (Experimental, may change in future versions)

Sessions

Privacy Configs

Tasks

Observer

Debug

Maintenance

Statistics

Admin (Multi-tenant)

VikingBot Interaction Endpoints (Optional)

VikingBot API requires the server to be started with the --with-bot option:

WebDAV Endpoints

Documentation Reading Plan

Subsequent API documentation is organized by functional module as follows: