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

HTTP Mode

client = ov.OpenViking(
    url="http://localhost:1933",
    api_key="your-key",
)
client.initialize()

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.

Configuration

Create ~/.openviking/ovcli.conf (or set OPENVIKING_CLI_CONFIG_FILE environment variable):

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

Basic Usage

openviking [global options] <command> [arguments] [command options]

Global Options (must be placed before the command name)

Example:

openviking --json ls viking://resources/
openviking -o json ls viking://resources/

Client Lifecycle

client = ov.OpenViking(path="./data")  # or url="http://..."
client.initialize()  # Required before any operations

# ... use client ...

client.close()  # Release resources

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

Compact JSON with status wrapper, suitable for scripting. Overrides --output:

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

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