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",
    timeout=120.0,
)
client.initialize()

Go SDK Client

The Go SDK is an HTTP-only client for Client-Server mode. It is published from the main repository as the sdk/go module.

go get github.com/volcengine/OpenViking/sdk/go

client, err := openviking.NewClient(openviking.Config{
    BaseURL: "http://localhost:1933",
    APIKey:  "your-key",
})
if err != nil {
    return err
}
defer client.CloseIdleConnections()

The Go SDK sends the same identity headers as the Python HTTP client:

For normal api_key deployments, APIKey is enough because the server derives tenant identity from the key. Set Account and User only for trusted deployments or gateways that explicitly forward tenant identity.

It does not implement Python embedded mode or legacy agent_id compatibility. See sdk/go/README.md for package-level examples.

JavaScript/TypeScript SDK Client

The JavaScript/TypeScript SDK is an HTTP-only client for Node.js 18+. It ships ESM, CommonJS and TypeScript declarations.

npm install @openviking/sdk

import { OpenVikingClient } from "@openviking/sdk";

const client = new OpenVikingClient({
  baseUrl: "http://localhost:1933",
  apiKey: "your-key",
});

const results = await client.search("deployment guide", {
  targetUri: "viking://resources",
});

It uses the same identity headers and response envelope as the Python and Go HTTP clients. See sdk/typescript/README.md for package-level examples.

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

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 600.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 600.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.
• Python HTTP clients can opt into shared temporary uploads through ovcli.conf (upload.mode = "shared"). The Rust ov CLI does not read that field; set OPENVIKING_UPLOAD_MODE=shared for ov instead.
• 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.
• temp_upload defaults to upload_mode=local. Use upload_mode=shared only when you explicitly want distributed shared temporary uploads.
• 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

This catalog follows the routes actually mounted by the server. Each group heading links to its detailed reference. Detail pages show an HTTP, Python SDK, TypeScript SDK, Go SDK, or CLI tab only when that surface is genuinely available; a raw HTTP workaround is not presented as an SDK.

System Status

Resources and Filesystem

Content

Skills

Sessions and Memory

Retrieval and Relations

Watches, Snapshots, and OVPack

Background Tasks, Runtime Observer, and Metrics

Administration and Privacy Configuration

OpenViking Assets, WebDAV, and VikingBot API

Documentation Reading Plan

The sidebar is organized by responsibility rather than historical file size: