System and Monitoring

OpenViking provides system health, observability, and debug APIs for monitoring component status.

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}")

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)

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"])

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}")

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
}

---

reindex()

Reindex semantic and/or vector artifacts for existing content already stored in OpenViking. This is an operational maintenance API intended for scenarios such as embedding model changes, VLM changes, vector store rebuild, or post-upgrade repair of existing indexes.

This API operates on existing viking://... content. It does not import new files. For normal ingestion, use Resources.

Authentication

• HTTP endpoint: requires admin/root role when authentication is enabled. In api_key mode, use an admin key for tenant content; a raw root key cannot access tenant-scoped data.
• Python embedded mode: uses the current service context
• Python HTTP client / CLI: sends the current authenticated identity

Parameters

Parameter	Type	Required	Default	Description
uri	str	Yes	-	Viking URI to reindex
mode	str	No	vectors_only	Reindex mode: vectors_only or semantic_and_vectors
wait	bool	No	true	Whether to wait for completion

The HTTP request body rejects unknown fields. uri may use OpenViking path variables accepted by other content APIs; it is resolved before validation.

Supported URI scopes

• viking://
• viking://user
• viking://user/<user_id>
• viking://resources
• viking://resources/...
• viking://user/<user_id>/memories/...
• viking://user/<user_id>/skills
• viking://user/<user_id>/skills/<skill_name>

Session namespaces are not supported by reindex(). Requests for viking://session/... or viking://user/<user_id>/sessions/... are rejected; when reindexing a broader user namespace, session subtrees are skipped.

Modes

• vectors_only: rebuilds vector-store records from currently recoverable source data without rewriting .abstract.md or .overview.md
• semantic_and_vectors: regenerates semantic artifacts first, then rebuilds vectors from the refreshed semantic outputs

For resource and skill, semantic_and_vectors refreshes directory/file semantic artifacts, including .abstract.md and .overview.md. For memory, it rebuilds the current persisted memory subtree semantics and vectors, but it does not replay historical extraction order.

For semantic_and_vectors, semantic generation and vector rebuilding are sequenced by the reindex executor. The semantic refresh step does not enqueue its own background vectorization work; vectors are rebuilt by the reindex step so wait=true reflects the reindex operation itself.

Python SDK (Embedded / HTTP)

result = client.reindex(
    uri="viking://resources",
    mode="vectors_only",
    wait=True,
)
print(result)

result = client.reindex(
    uri="viking://user/default/skills",
    mode="semantic_and_vectors",
    wait=False,
)
print(result["status"])

HTTP API

POST /api/v1/content/reindex

There is no /api/v1/maintenance/reindex endpoint. Use /api/v1/content/reindex.

curl -X POST http://localhost:1933/api/v1/content/reindex \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -H "X-OpenViking-Account: default" \
  -d '{
    "uri": "viking://resources",
    "mode": "vectors_only",
    "wait": true
  }'

CLI

openviking reindex viking://resources --mode vectors_only

openviking reindex viking://user/default/skills --mode semantic_and_vectors --wait false

Synchronous response (wait=true)

{
  "status": "ok",
  "result": {
    "uri": "viking://resources",
    "mode": "vectors_only",
    "status": "completed",
    "object_type": "resource",
    "scanned_records": 120,
    "rebuilt_records": 118,
    "unsupported_records": 2,
    "failed_records": 0,
    "duration_ms": 1284,
    "warnings": []
  },
  "time": 0.1
}

Asynchronous response (wait=false)

{
  "status": "ok",
  "result": {
    "uri": "viking://resources",
    "mode": "vectors_only",
    "object_type": "resource",
    "status": "accepted",
    "task_id": "task_xxx"
  },
  "time": 0.1
}

Poll the returned task through the task API:

curl -X GET http://localhost:1933/api/v1/tasks/task_xxx \
  -H "X-API-Key: your-key" \
  -H "X-OpenViking-Account: default"

Reindex background tasks use task_type="admin_reindex" and resource_id equal to the requested uri, so they can also be listed with:

GET /api/v1/tasks?task_type=admin_reindex&resource_id=viking://resources

Task records are persisted under /local/{account_id}/_system/tasks/{user_id}/{task_id}.json and can be queried after restart.

Result fields

Field	Description
status	completed for synchronous completion, accepted for background execution
uri	Requested URI after path-variable resolution
object_type	Inferred target type, such as resource, skill, memory, user_namespace, skill_namespace, or global_namespace
mode	Effective reindex mode
scanned_records	Number of records or semantic sources considered
rebuilt_records	Number of vector records successfully rebuilt
unsupported_records	Number of records skipped because no usable vector source was available
failed_records	Number of records that failed while rebuilding
duration_ms	Synchronous run duration in milliseconds
warnings	Recoverable per-record warnings
task_id	Background task ID, present only when wait=false

Behavior notes

• Reindex is non-destructive. It uses rebuild/upsert behavior and does not require dropping the vector collection first.
• viking:// reindex fans out to supported top-level namespaces and excludes session.
• Namespace reindex operations such as viking://user propagate to supported child content types.
• vectors_only is the right mode when only the embedding model or vector index needs to be refreshed.
• semantic_and_vectors is the right mode when semantic artifacts themselves must be regenerated before re-vectorization.
• Only one reindex task can run for the same URI and owner at a time. A concurrent request for the same target returns a conflict.
• For resource files, text files can use file content when no summary is available. Non-text files require a generated summary or existing vector record fallback; otherwise they are counted as unsupported.

Current limitations

• Reindex uses the best currently recoverable source inputs. It is not guaranteed to replay the exact historical embedding input byte-for-byte in every case.
• Memory semantic reindex is based on the currently persisted memory tree. It does not reconstruct the original chronological memory-extraction pipeline.

---

Observer API

The observer API provides detailed component-level monitoring.

observer.queue

1. API Implementation Overview

Get queue system status (embedding and semantic processing queues). Shows pending, in-progress, completed, and error counts for each queue.

Code Entry Points:

• openviking/server/routers/observer.py:observer_queue - HTTP route
• openviking/service/debug_service.py:ObserverService.queue - Core implementation
• openviking/storage/observers/queue_observer.py - Queue observer
• crates/ov_cli/src/commands/observer.rs - CLI command

2. Interface and Parameters

No parameters.

3. Usage Examples

HTTP API

GET /api/v1/observer/queue

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

Python SDK

print(client.observer.queue)
# Output:
# [queue] (healthy)
# Queue                 Pending  In Progress  Processed  Errors  Total
# Embedding             0        0            10         0       10
# Semantic              0        0            10         0       10
# TOTAL                 0        0            20         0       20

CLI

ov observer queue

Response Example

{
  "status": "ok",
  "result": {
    "name": "queue",
    "is_healthy": true,
    "has_errors": false,
    "status": "Queue                 Pending  In Progress  Processed  Errors  Total\nEmbedding             0        0            10         0       10\nSemantic              0        0            10         0       10\nTOTAL                 0        0            20         0       20"
  },
  "time": 0.1
}

---

observer.vikingdb

1. API Implementation Overview

Get VikingDB status (collections, indexes, vector counts).

Code Entry Points:

• openviking/server/routers/observer.py:observer_vikingdb - HTTP route
• openviking/service/debug_service.py:ObserverService.vikingdb - Core implementation
• openviking/storage/observers/vikingdb_observer.py - VikingDB observer
• crates/ov_cli/src/commands/observer.rs - CLI command

2. Interface and Parameters

No parameters.

3. Usage Examples

HTTP API

GET /api/v1/observer/vikingdb

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

Python SDK

print(client.observer.vikingdb())
# Output:
# [vikingdb] (healthy)
# Collection  Index Count  Vector Count  Status
# context     1            55            OK
# TOTAL       1            55

# Access specific attributes
print(client.observer.vikingdb().is_healthy)  # True
print(client.observer.vikingdb().status)      # Status table string

CLI

ov observer vikingdb

Response Example

{
  "status": "ok",
  "result": {
    "name": "vikingdb",
    "is_healthy": true,
    "has_errors": false,
    "status": "Collection  Index Count  Vector Count  Status\ncontext     1            55            OK\nTOTAL       1            55"
  },
  "time": 0.1
}

---

observer.models

1. API Implementation Overview

Get aggregated model subsystem status (VLM, embedding, rerank). Checks if each model provider is healthy and available.

Code Entry Points:

• openviking/server/routers/observer.py:observer_models - HTTP route
• openviking/service/debug_service.py:ObserverService.models - Core implementation
• openviking/storage/observers/models_observer.py - Models observer
• crates/ov_cli/src/commands/observer.rs - CLI command

2. Interface and Parameters

No parameters.

3. Usage Examples

HTTP API

GET /api/v1/observer/models

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

Python SDK

print(client.observer.models)
# Output:
# [models] (healthy)
# provider_model         healthy  detail
# dense_embedding        yes      ...
# rerank                 yes      ...
# vlm                    yes      ...

CLI

ov observer models

Response Example

{
  "status": "ok",
  "result": {
    "name": "models",
    "is_healthy": true,
    "has_errors": false,
    "status": "provider_model         healthy  detail\ndense_embedding        yes      ...\nrerank                 yes      ...\nvlm                    yes      ..."
  },
  "time": 0.1
}

---

observer.lock

1. API Implementation Overview

Get distributed lock system status.

Code Entry Points:

• openviking/server/routers/observer.py:observer_lock - HTTP route
• openviking/service/debug_service.py:ObserverService.lock - Core implementation
• openviking/storage/observers/lock_observer.py - Lock observer
• crates/ov_cli/src/commands/observer.rs - CLI command

2. Interface and Parameters

No parameters.

3. Usage Examples

HTTP API

GET /api/v1/observer/lock

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

Python SDK

print(client.observer.lock)

CLI

ov observer transaction

Response Example

{
  "status": "ok",
  "result": {
    "name": "lock",
    "is_healthy": true,
    "has_errors": false,
    "status": "..."
  },
  "time": 0.1
}

---

observer.retrieval

1. API Implementation Overview

Get retrieval quality metrics.

Code Entry Points:

• openviking/server/routers/observer.py:observer_retrieval - HTTP route
• openviking/service/debug_service.py:ObserverService.retrieval - Core implementation
• openviking/storage/observers/retrieval_observer.py - Retrieval observer
• crates/ov_cli/src/commands/observer.rs - CLI command

2. Interface and Parameters

No parameters.

3. Usage Examples

HTTP API

GET /api/v1/observer/retrieval

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

Python SDK

print(client.observer.retrieval)

CLI

ov observer retrieval

Response Example

{
  "status": "ok",
  "result": {
    "name": "retrieval",
    "is_healthy": true,
    "has_errors": false,
    "status": "..."
  },
  "time": 0.1
}

---

observer.filesystem

1. API Implementation Overview

Get filesystem operation metrics.

Code Entry Points:

• openviking/server/routers/observer.py:observer_filesystem - HTTP route
• openviking/service/debug_service.py:ObserverService.filesystem - Core implementation
• openviking/storage/observers/filesystem_observer.py - Filesystem observer
• crates/ov_cli/src/commands/observer.rs - CLI command

2. Interface and Parameters

No parameters.

3. Usage Examples

HTTP API

GET /api/v1/observer/filesystem

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

Python SDK

print(client.observer.filesystem)

CLI

ov observer filesystem

Response Example

{
  "status": "ok",
  "result": {
    "name": "filesystem",
    "is_healthy": true,
    "has_errors": false,
    "status": "..."
  },
  "time": 0.1
}

---

observer.system

1. API Implementation Overview

Get overall system status, including all components (queue, vikingdb, models, lock, retrieval).

Code Entry Points:

• openviking/server/routers/observer.py:observer_system - HTTP route
• openviking/service/debug_service.py:ObserverService.system - Core implementation
• crates/ov_cli/src/commands/observer.rs - CLI command

2. Interface and Parameters

No parameters.

3. Usage Examples

HTTP API

GET /api/v1/observer/system

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

Python SDK

print(client.observer.system())
# Output:
# [queue] (healthy)
# ...
#
# [vikingdb] (healthy)
# ...
#
# [models] (healthy)
# ...
#
# [system] (healthy)

CLI

ov observer system

Response Example

{
  "status": "ok",
  "result": {
    "is_healthy": true,
    "errors": [],
    "components": {
      "queue": {
        "name": "queue",
        "is_healthy": true,
        "has_errors": false,
        "status": "..."
      },
      "vikingdb": {
        "name": "vikingdb",
        "is_healthy": true,
        "has_errors": false,
        "status": "..."
      },
      "models": {
        "name": "models",
        "is_healthy": true,
        "has_errors": false,
        "status": "..."
      },
      "lock": {
        "name": "lock",
        "is_healthy": true,
        "has_errors": false,
        "status": "..."
      },
      "retrieval": {
        "name": "retrieval",
        "is_healthy": true,
        "has_errors": false,
        "status": "..."
      }
    }
  },
  "time": 0.1
}

---

Related Documentation

• Resources - Resource management
• Retrieval - Search and retrieval
• Sessions - Session management