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 health check endpoint. No authentication required. Returns service version and health status. If authentication is provided, also returns auth mode and identity information.

Code Entry Points:

• openviking/server/routers/system.py:health_check - HTTP route
• openviking_cli/client/sync_http.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 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, and Ollama (if configured) status. 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: Whether Viking filesystem is accessible
• vectordb: Whether vector database is healthy
• api_key_manager: Whether API key manager is loaded
• 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": "ok",
    "vectordb": "ok",
    "api_key_manager": "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
• openviking_cli/client/sync_http.py:SyncHTTPClient.get_status - SDK entry
• 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"

Python SDK

status = client.get_status()
print(status)

TypeScript SDK

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

CLI

ov system status

Response Example

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

---

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
• openviking_cli/client/sync_http.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("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 for all asynchronous processing (embedding, semantic generation) to complete. This method blocks until all queued tasks are processed or timeout occurs.

Code Entry Points:

• openviking/server/routers/system.py:wait_processed - HTTP route
• openviking_cli/client/sync_http.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

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

# Add resources
client.add_resource("./docs/")

# Wait for all processing to complete
status = client.wait_processed(timeout=60.0)
print(f"Processing complete: {status}")

TypeScript SDK

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

ov system wait --timeout 60

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": []
    }
  },
  "time": 0.1
}

---

backend_sync_status()

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

HTTP API

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

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:

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

CLI

ov system backend sync-status viking://resources

Response example

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

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

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:

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

CLI

ov system backend sync-retry viking://resources

Response example

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

---

Related Documentation

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