API Overview

Overview of the OpenViking Python SDK and HTTP API

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:

X-API-Key Header

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

Python SDK

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

Python SDK

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