# OmniRoute Monitoring and Health Check Endpoints: A Complete Developer Guide

> Discover OmniRoute monitoring and health check endpoints. Use /api/health/ping for uptime and /api/monitoring/health for subsystem diagnostics. Empower your development with these essential tools.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-13

---

**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](https://github.com/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.

```http
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.

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

```

Typical response structure:

```json
{
  "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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/publicApiRoutes.ts) | Declares public health routes |
| [`src/lib/services/healthCheck.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/healthCheck.ts) | Core health-check implementation |
| [`src/lib/versionManager/healthMonitor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/versionManager/healthMonitor.ts) | Runtime health data aggregation |
| [`tests/unit/healthz-route.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/healthz-route.test.ts) | Unit tests for monitoring endpoint |
| [`tests/unit/health-ping-route.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/services/healthCheck.ts) and [`src/lib/versionManager/healthMonitor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/versionManager/healthMonitor.ts) with route definitions in [`src/shared/constants/publicApiRoutes.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.