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

Service Mode

client = ov.OpenViking(
    vectordb_url="http://vectordb.example.com:8000",
    agfs_url="http://agfs.example.com:1833",
)
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"

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
}

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