OmniRoute Monitoring and Health Check Endpoints: A Complete Developer Guide

OmniRoute exposes two public HTTP endpoints—/api/health/ping for basic uptime checks and /api/monitoring/health for comprehensive subsystem diagnostics.

Understanding the available monitoring and health check endpoints in OmniRoute is essential for production deployments, load balancer configuration, and operational observability. This guide examines both endpoints as implemented in the diegosouzapw/OmniRoute source code, including their exact routes, response formats, and underlying implementation.

Available OmniRoute Health Check Endpoints

OmniRoute's public API defines two distinct monitoring and health check endpoints in src/shared/constants/publicApiRoutes.ts. Each serves a different operational purpose.

/api/health/ping: Minimal Uptime Verification

The ping endpoint provides a lightweight health check suitable for load balancers and container orchestrators.

Attribute	Value
Route	/api/health/ping
Method	GET
Authentication	None required
Response	HTTP 200 OK (plain text)

Use this endpoint when you need to verify that the OmniRoute server process is reachable without consuming significant resources.

GET /api/health/ping HTTP/1.1
Host: localhost:20128

Orchestration tools like Kubernetes or AWS ALB can poll this endpoint at high frequency without impacting performance.

/api/monitoring/health: Comprehensive Subsystem Diagnostics

The health monitoring endpoint returns detailed JSON reporting on all critical OmniRoute subsystems.

Attribute	Value
Route	/api/monitoring/health
Method	GET
Authentication	None (public endpoint)
Response	JSON object with component statuses

This endpoint aggregates data from multiple internal services to present a holistic view of system health.

GET /api/monitoring/health HTTP/1.1
Host: localhost:20128
Accept: application/json

Typical response structure:

{
  "status": "healthy",
  "components": {
    "providerCircuitBreakers": { "open": 0, "closed": 12 },
    "db": { "connected": true },
    "comboAutopilot": { "state": "healthy" },
    "cloudAgents": { "active": 3 }
  },
  "timestamp": "2026-08-13T13:45:00Z"
}

Health Check Implementation Details

The OmniRoute monitoring and health check endpoints rely on two core implementation files that collect and surface runtime data.

Health Check Service (src/lib/services/healthCheck.ts)

This file implements the primary health-check logic consumed by the monitoring endpoint. It evaluates:

• Database connectivity status
• Provider circuit breaker states
• Connection cooldown timers
• Model lockout conditions

Version Manager Health Monitor (src/lib/versionManager/healthMonitor.ts)

The healthMonitor.ts module centralizes health data collection across the OmniRoute runtime. It aggregates information from:

• Provider subsystems: Tracks which LLM providers are currently operational
• Combo routing engine: Reports on the combo autopilot state
• Cloud agents: Counts active agent connections

Data from both files flows into the JSON response returned by /api/monitoring/health.

Production Monitoring Strategies

Choosing the right OmniRoute monitoring and health check endpoint depends on your operational requirements.

Use Case	Recommended Endpoint	Polling Frequency
Load balancer health checks	/api/health/ping	5-10 seconds
Kubernetes liveness probes	/api/health/ping	10 seconds
Kubernetes readiness probes	/api/monitoring/health	30 seconds
Dashboard/alerting systems	/api/monitoring/health	60 seconds
Incident investigation	/api/monitoring/health	On-demand

CORS and Security Considerations

Both monitoring and health check endpoints are part of OmniRoute's public API with default CORS configuration:

• No authentication required for /api/health/ping
• The comprehensive health report at /api/monitoring/health is similarly accessible to any reachable client
• Restrict network access through firewall rules or reverse proxy configuration in production environments

Source File Reference

File Path	Purpose
src/shared/constants/publicApiRoutes.ts	Declares public health routes
src/lib/services/healthCheck.ts	Core health-check implementation
src/lib/versionManager/healthMonitor.ts	Runtime health data aggregation
tests/unit/healthz-route.test.ts	Unit tests for monitoring endpoint
tests/unit/health-ping-route.test.ts	Unit tests for ping endpoint

Summary

• Two endpoints provide complete OmniRoute monitoring and health check coverage: lightweight /api/health/ping and comprehensive /api/monitoring/health
• The ping endpoint returns HTTP 200 for uptime verification without authentication overhead
• The health endpoint surfaces JSON diagnostics for provider circuit breakers, database connections, combo routing, and cloud agents
• Implementation spans src/lib/services/healthCheck.ts and src/lib/versionManager/healthMonitor.ts with route definitions in src/shared/constants/publicApiRoutes.ts
• Both endpoints are public and unauthenticated by default—secure them at the network layer for production deployments

Frequently Asked Questions

What is the difference between the ping and health endpoints in OmniRoute?

The /api/health/ping endpoint performs a minimal reachability check returning HTTP 200, ideal for load balancers that need fast, lightweight verification. The /api/monitoring/health endpoint executes deep subsystem diagnostics and returns structured JSON detailing component states including provider circuit breakers, database connectivity, and cloud agent status.

Does OmniRoute require authentication for health check endpoints?

No authentication is required for either monitoring and health check endpoint according to the source implementation in src/shared/constants/publicApiRoutes.ts. Both endpoints use default CORS configuration only. Production deployments should implement network-level access controls or reverse proxy rules to restrict health endpoint exposure.

How can I parse the health endpoint response for alerting?

The /api/monitoring/health response contains a top-level "status" field with values like "healthy" or "degraded", plus a "components" object with granular details. Monitor the "status" field for simple alerting, or drill into specific components—such as "providerCircuitBreakers" or "db"—for targeted operational intelligence. The "timestamp" field enables staleness detection.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}