API Overview - OpenViking

OpenViking provides three ways to interact with the context database: Embedded mode for local development, HTTP API for remote server access, and CLI for shell scripting and agent tool-use.

Connection Modes

Embedded

Run locally with local data storage for development and testing

HTTP API

Connect to a remote OpenViking server via REST API

CLI

Command-line interface for scripting and automation

Quick Start

Embedded Mode (Python SDK)

Use the embedded client for local development with direct database access:

import openviking as ov

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

# Use the client
# ...

client.close()

Embedded mode requires ov.conf to configure embedding, VLM, and storage modules. Default location: ~/.openviking/ov.conf

export OPENVIKING_CONFIG_FILE=/path/to/ov.conf

HTTP Mode (Python SDK)

Connect to a remote OpenViking server:

import openviking as ov

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

# Use the client
# ...

client.close()

When url is not provided, connection info is loaded from ovcli.conf (default: ~/.openviking/ovcli.conf):

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

Direct HTTP API (curl)

Access endpoints directly using HTTP:

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

CLI Mode

The CLI provides shell commands for all operations:

# List resources
openviking ls viking://resources/

# JSON output for scripting
openviking -o json ls viking://resources/

# Search for content
openviking find "authentication flow" --limit 5

Authentication

OpenViking supports two authentication methods via HTTP headers:

curl http://localhost:1933/api/v1/system/status \
  -H "X-API-Key: your-key"

The /health and /ready endpoints never require authentication. If no API key is configured on the server, all authentication is skipped.

Base URL and Endpoints

All API endpoints are prefixed with /api/v1/ and follow RESTful conventions: Base URL: http://localhost:1933 (default) API Version: v1

Response Format

All HTTP API responses follow a unified structure for consistency:

Success Response

{
  "status": "ok",
  "result": {
    // Response data varies by endpoint
  },
  "time": 0.123
}

Error Response

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

Error Codes

OpenViking uses semantic error codes mapped to standard HTTP status 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
`DEADLINE_EXCEEDED`	504	Operation timed out
`UNAVAILABLE`	503	Service unavailable
`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 Endpoint Categories

System

Health checks, system status, and operational endpoints

Resources

Add and manage resources, skills, and import/export packs

File System

List, read, create, move, and delete resources in Viking URIs

Content

Read full content (L2), abstracts (L0), and overviews (L1)

Search

Semantic search, pattern matching, and context-aware retrieval

Skills

List and call agent skills and capabilities

Sessions

Create and manage conversation sessions with message history

Admin

Multi-tenant workspace and user management (ROOT/ADMIN only)

Quick Reference

System Endpoints

GET  /health                      # Health check (no auth)
GET  /ready                       # Readiness probe
GET  /api/v1/system/status       # System status
POST /api/v1/system/wait         # Wait for processing

Resource Management

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
POST /api/v1/resources/temp_upload  # Upload temp file

File System Operations

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 Access

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)

Search Operations

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

GET    /api/v1/relations         # Get relations
POST   /api/v1/relations/link    # Create link
DELETE /api/v1/relations/link    # Remove link

Sessions

POST   /api/v1/sessions          # Create session
GET    /api/v1/sessions          # List sessions
GET    /api/v1/sessions/{id}     # Get session
DELETE /api/v1/sessions/{id}     # Delete session
POST   /api/v1/sessions/{id}/commit    # Commit session
POST   /api/v1/sessions/{id}/messages  # Add message

Example: Adding a Resource

import openviking as ov

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

# Add a local directory as a resource
result = client.add_resource(
    path="./docs",
    target="viking://resources/docs/",
    reason="Project documentation",
    wait=True
)

print(f"Added: {result}")
client.close()

Example: Semantic Search

import openviking as ov

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

# Search for authentication-related content
results = client.find(
    query="How does authentication work?",
    target_uri="viking://resources/",
    limit=5
)

for result in results:
    print(f"{result.uri}: {result.score}")

client.close()

Rate Limiting

OpenViking currently does not enforce rate limiting by default. The RESOURCE_EXHAUSTED error code (HTTP 429) is reserved for future rate limiting implementations.

CLI Output Formats

The CLI supports multiple output formats via the --output or -o flag:

Table Mode (default)

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

JSON Mode

openviking -o json ls viking://resources/
# [{"name": "docs/", "size": 0, "isDir": true, ...}, ...]

Set the default output format in ovcli.conf:

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

Configuration Files

ov.conf (Embedded Mode)

Default location: ~/.openviking/ov.conf

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

ovcli.conf (HTTP/CLI Mode)

Default location: ~/.openviking/ovcli.conf

{
  "url": "http://localhost:1933",
  "api_key": "your-key",
  "agent_id": "my-agent",
  "timeout": 60.0,
  "output": "table"
}

Next Steps

Resources API

Learn how to add and manage resources

Search API

Explore semantic search and retrieval

Sessions API

Build conversation-aware applications

Configuration Guide

Complete configuration reference

Overview

Resources

Filesystem

Search & Retrieval

Sessions

Skills

System

Admin

​Connection Modes

Embedded

HTTP API

CLI

​Quick Start

​Embedded Mode (Python SDK)

​HTTP Mode (Python SDK)

​Direct HTTP API (curl)

​CLI Mode

​Authentication

​Base URL and Endpoints

​Response Format

​Success Response

​Error Response

​Error Codes

​API Endpoint Categories

System

Resources

File System

Content

Search

Skills

Sessions

Admin

​Quick Reference

​System Endpoints

​Resource Management

​File System Operations

​Content Access

​Search Operations

​Relations

​Sessions

​Example: Adding a Resource

​Example: Semantic Search

​Rate Limiting

​CLI Output Formats

​Table Mode (default)

​JSON Mode

​Configuration Files

​ov.conf (Embedded Mode)

​ovcli.conf (HTTP/CLI Mode)

​Next Steps

Resources API

Search API

Sessions API

Configuration Guide

Connection Modes

Quick Start

Embedded Mode (Python SDK)

HTTP Mode (Python SDK)

Direct HTTP API (curl)

CLI Mode

Authentication

Base URL and Endpoints

Response Format

Success Response

Error Response

Error Codes

API Endpoint Categories

Quick Reference

System Endpoints

Resource Management

File System Operations

Content Access

Search Operations

Relations

Sessions

Example: Adding a Resource

Example: Semantic Search

Rate Limiting

CLI Output Formats

Table Mode (default)

JSON Mode

Configuration Files

ov.conf (Embedded Mode)

ovcli.conf (HTTP/CLI Mode)

Next Steps