Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

11.0 KB
Raw Blame

System Status

The OpenViking System API provides health, readiness, consistency, and background-processing status. Component observers and Prometheus metrics are documented separately.

API Reference

health

1. API Implementation Overview

Basic liveness check; no authentication is required. Returns the service version, health status, and auth mode. Supplied credentials trigger identity resolution; successful resolution adds identity fields, and invalid credentials are rejected with an authentication error.

In trusted mode, a complete X-OpenViking-Account and X-OpenViking-User header pair requests identity resolution and requires the matching root API key, including on localhost. root_api_key_required is always true in trusted mode; the resolved role describes the caller's permissions. Anonymous health probes return basic liveness information without identity fields.

Code Entry Points:

  • openviking/server/routers/system.py:health_check - HTTP route
  • sdk/python/openviking_sdk/client.py:SyncHTTPClient.health - SDK entry
  • crates/ov_cli/src/commands/system.rs - CLI command

2. Interface and Parameters

Parameter Type Required Default Description
profile string No - When set to 1, true, yes, or on, enables request-scoped cProfile and appends a profile field to JSON responses

profile behavior:

  • profile is implemented at the HTTP middleware layer and works for any OpenViking endpoint that returns JSON, not just /health.
  • The request flag only takes effect when the server enables server.profile_enabled = true in ov.conf; otherwise the server ignores profile=1.
  • profile only applies to the current request and is automatically disabled when the request completes, so later requests do not inherit it.
  • The middleware only injects a profile field into JSON responses; plain text, file, and streaming responses are left unchanged.
  • The returned value is list[string], where each element is one formatted pstats line. This makes browser JSON viewers and line-by-line UI rendering easier.
  • The ov CLI displays the returned profile. The Python HTTP client can trigger server-side profiling via ovcli.conf.profile = true, but most SDK methods still return only the business result and do not expose the top-level profile field directly.

profile column meanings:

  • ncalls: Number of calls. When shown as total/primitive, the first value is total calls and the second is primitive calls.
  • tottime: Total time spent in the function body itself, excluding time in subcalls.
  • percall (first): tottime / ncalls, the average self time per call.
  • cumtime: Cumulative time including the current function and all of its subcalls.
  • percall (second): cumtime / primitive calls, the average cumulative time per primitive call.
  • filename:lineno(function): Function location. Regular Python code shows the trimmed module path; entries like ~:0(...) usually represent builtin or native-extension calls.

3. Usage Examples

HTTP API

GET /health
curl -X GET http://localhost:1933/health
curl -G http://localhost:1933/health \
  --data-urlencode "profile=1"

Python SDK

import openviking_sdk as ov

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

healthy = client.health()
print(f"Healthy: {healthy}")

TypeScript SDK

console.log(await client.health());

Go SDK

healthy, err := client.Health(ctx)
if err != nil {
    return err
}
fmt.Println(healthy)

CLI

ov system health
ov --profile health

Response Example

{
  "status": "ok",
  "healthy": true,
  "version": "0.1.x",
  "auth_mode": "api_key"
}

Response Example With profile

{
  "status": "ok",
  "healthy": true,
  "version": "0.1.x",
  "profile": [
    "         325 function calls (310 primitive calls) in 0.004 seconds",
    "",
    "   Ordered by: cumulative time",
    "   List reduced from 87 to 87 due to restriction <100>",
    "",
    "   ncalls  tottime  percall  cumtime  percall filename:lineno(function)",
    "        1    0.000    0.000    0.003    0.003 starlette/middleware/base.py:112(call_next)",
    "        1    0.000    0.000    0.001    0.001 openviking/server/routers/system.py:39(health_check)",
    "        3    0.000    0.000    0.000    0.000 ~:0(<method 'read' of 'builtins.RAGFSBindingClient' objects>)"
  ]
}

ready

1. API Implementation Overview

Readiness probe for deployment environments. Checks AGFS, VectorDB, APIKeyManager, embedding, and Ollama (if configured). Returns 200 when all configured subsystems are ready and 503 otherwise. No authentication required (designed for Kubernetes probes).

Code Entry Points:

  • openviking/server/routers/system.py:readiness_check - HTTP route

2. Interface and Parameters

No parameters.

Check Item Descriptions:

  • agfs: Nested filesystem and multi-write sync checks
  • vectordb: Whether vector database is healthy
  • api_key_manager: Whether API key manager is loaded
  • embedding: Whether the embedding provider was initialized at startup; no provider request is sent
  • ollama: Whether Ollama service is reachable (only if configured)

3. Usage Examples

HTTP API

GET /ready
curl -X GET http://localhost:1933/ready

Response Example

{
  "status": "ready",
  "checks": {
    "agfs": {"status": "ok", "checks": {"filesystem": "ok", "multiwrite_sync": "not_supported"}},
    "vectordb": "ok",
    "api_key_manager": "ok",
    "embedding": "ok",
    "ollama": "not_configured"
  }
}

status

1. API Implementation Overview

Get system status including initialization state and authenticated user info. result.user is the authenticated request's user_id (from API key or headers), not the process-level service default - clients can use this to resolve multi-tenant paths.

Code Entry Points:

  • openviking/server/routers/system.py:system_status - HTTP route
  • crates/ov_cli/src/commands/system.rs - CLI command

2. Interface and Parameters

No parameters.

3. Usage Examples

HTTP API

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

The public SDK get_status() / getStatus() / GetStatus() methods return aggregate Observer status, not this endpoint’s identity payload. Use HTTP for this endpoint; see Observer for those SDK methods.

CLI

ov system status

Response Example

{
  "status": "ok",
  "result": {
    "initialized": true,
    "user": "alice"
  }
}

consistency

1. API Implementation Overview

Check filesystem/vector-index consistency for a URI subtree. This is a general data consistency API for debugging missing index records, failed vector snapshot exports, and related issues. It is not an OVPack-private API; ov export --include-vectors and ov backup --include-vectors reuse the same check.

The response returns only a summary and missing records. It does not return the full expected-record list. missing_records includes at most the first 20 records; missing_records_truncated is true when more missing records exist.

Code Entry Points:

  • openviking/server/routers/system.py:check_consistency - HTTP route
  • sdk/python/openviking_sdk/client.py:SyncHTTPClient.check_consistency - SDK entry
  • crates/ov_cli/src/commands/system.rs:consistency - CLI command

2. Interface and Parameters

Parameter Type Required Default Description
uri string Yes - Viking URI subtree to check

3. Usage Examples

HTTP API

POST /api/v1/system/consistency
Content-Type: application/json
curl -X POST http://localhost:1933/api/v1/system/consistency \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"uri":"viking://resources/my-project"}'

Python SDK

report = client.check_consistency(uri="viking://resources/my-project")
print(report["ok"])
print(report["missing_records"])

TypeScript SDK

console.log(await client.checkConsistency("viking://resources/"));

Go SDK

report, err := client.CheckConsistency(ctx, "viking://resources/my-project")
if err != nil {
    return err
}
fmt.Println(report["ok"])

CLI

ov system consistency viking://resources/my-project

Response Example

{
  "status": "ok",
  "result": {
    "ok": false,
    "expected_count": 3,
    "missing_record_count": 1,
    "missing_records_truncated": false,
    "missing_records": [
      {
        "uri": "viking://resources/my-project/README.md",
        "path": "README.md",
        "level": 2,
        "key": "README.md#level=2"
      }
    ]
  }
}

wait_processed

1. API Implementation Overview

Wait until the processing queues are drained. This check is not scoped to the caller’s last request and does not cover every asynchronous API. Check the returned error_count and errors; empty queues do not prove that every operation succeeded. To confirm one import or commit, poll its task ID instead.

Code Entry Points:

  • openviking/server/routers/system.py:wait_processed - HTTP route
  • sdk/python/openviking_sdk/client.py:SyncHTTPClient.wait_processed - SDK entry
  • crates/ov_cli/src/commands/system.rs - CLI command

2. Interface and Parameters

Parameters

No parameters are required. The optional JSON body accepts legacy timeout, which is deprecated and ignored. Empty-body calls continue to work. Configure HTTP timeouts on the client.

3. Usage Examples

HTTP API

POST /api/v1/system/wait
curl -X POST http://localhost:1933/api/v1/system/wait \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key"

Python SDK

# Wait for the current processing queues to drain
status = client.wait_processed()
print(status)  # Inspect each queue’s error_count and errors

TypeScript SDK

console.log(await client.waitProcessed());

Go SDK

status, err := client.WaitProcessed(ctx)
if err != nil {
    return err
}
fmt.Println(status)

CLI

ov system wait

Response Example

{
  "status": "ok",
  "result": {
    "Embedding": {
      "processed": 10,
      "requeue_count": 0,
      "error_count": 0,
      "errors": []
    },
    "Semantic": {
      "processed": 10,
      "requeue_count": 0,
      "error_count": 0,
      "errors": []
    }
  }
}

Related Documentation