System Status

The OpenViking System API provides health, readiness, consistency, and multi-write backend synchronization 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, including on localhost deployments with root_api_key omitted. Configured Root keys remain required for authenticated requests. The optional root_api_key_required boolean reports that trusted-server configuration requirement; the resolved role describes the caller's permissions. Older servers may omit this field. Anonymous health probes return basic liveness information.

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

bash

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

bash

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

Python SDK

python

import openviking_sdk as ov

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

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

TypeScript SDK

typescript

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

Go SDK

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

CLI

bash

ov system health

bash

ov --profile health

Response Example

json

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

Response Example With profile

json

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

bash

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

Response Example

json

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

bash

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

bash

ov system status

Response Example

json

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

bash

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

python

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

TypeScript SDK

typescript

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

bash

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

Response Example

json

{
  "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, or until the timeout. 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

Parameter	Type	Required	Default	Description
timeout	float	No	None	Timeout in seconds. None means wait indefinitely

3. Usage Examples

HTTP API

POST /api/v1/system/wait

bash

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

Python SDK

python

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

TypeScript SDK

typescript

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

Go SDK

status, err := client.WaitProcessed(ctx, &openviking.WaitProcessedOptions{
    Timeout: openviking.Float64(60),
})
if err != nil {
    return err
}
fmt.Println(status)

CLI

bash

ov system wait --timeout 60

Response Example

json

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

backend_sync_status()

Return multi-write backend synchronization status for a Viking URI subtree. This endpoint requires ROOT or ADMIN permission.

HTTP API

http

POST /api/v1/system/backend/sync-status
Content-Type: application/json

bash

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

The URI-path form is also available:

http

GET /api/v1/system/sync/{sync_path}

CLI

bash

ov system backend sync-status viking://resources

Response example

json

{
  "status": "ok",
  "result": {
    "path": "viking://resources",
    "entry_count": 12
  }
}

result is supplied by the active filesystem backend. path identifies the queried scope and entry_count is the number of sync records in that scope. A backend may add diagnostics such as pending or failed records.

backend_sync_retry()

Retry incomplete multi-write backend synchronization work for a URI subtree. This endpoint requires ROOT or ADMIN permission.

HTTP API

http

POST /api/v1/system/backend/sync-retry
Content-Type: application/json

bash

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

The URI-path form is:

http

POST /api/v1/system/sync/{sync_path}/retry

CLI

bash

ov system backend sync-retry viking://resources

Response example

json

{
  "status": "ok",
  "result": {
    "path": "viking://resources",
    "retried": 2,
    "failed": 0
  }
}

retried is the number of records rescheduled by this request, and failed is the number that could not be scheduled. A backend may include additional diagnostic fields.

The public Python, TypeScript, and Go SDKs do not currently expose multi-write backend synchronization methods, so the sections above show only HTTP and CLI tabs.

Resources - Resource management
Retrieval - Search and retrieval
Sessions - Session management
Runtime Observability - immediate component status
Metrics - Prometheus metrics

System Status ​

API Reference ​

health ​

1. API Implementation Overview ​

2. Interface and Parameters ​

3. Usage Examples ​

ready ​

1. API Implementation Overview ​

2. Interface and Parameters ​

3. Usage Examples ​

status ​

1. API Implementation Overview ​

2. Interface and Parameters ​

3. Usage Examples ​

consistency ​

1. API Implementation Overview ​

2. Interface and Parameters ​

3. Usage Examples ​

wait_processed ​

1. API Implementation Overview ​

2. Interface and Parameters ​

3. Usage Examples ​

backend_sync_status() ​

backend_sync_retry() ​

Related Documentation ​

System Status

API Reference

health

1. API Implementation Overview

2. Interface and Parameters

3. Usage Examples

ready

1. API Implementation Overview

2. Interface and Parameters

3. Usage Examples

status

1. API Implementation Overview

2. Interface and Parameters

3. Usage Examples

consistency

1. API Implementation Overview

2. Interface and Parameters

3. Usage Examples

wait_processed

1. API Implementation Overview

2. Interface and Parameters

3. Usage Examples

backend_sync_status()

backend_sync_retry()

Related Documentation