API Overview

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:

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|jina>",
    "model": "<model-name>"
  }
}

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",
)
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",
  "agent_id": "my-agent"
}

See the Configuration Guide for details.

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)

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
}

Error

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

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

Error Codes

API Endpoints

System

Resources

File System

Content

Search

Relations

Sessions

Observer

Admin (Multi-tenant)

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
• Admin - Multi-tenant management API