# How the Health Check Endpoint Functions in PrivateGPT for System Monitoring

> Learn how the PrivateGPT health check endpoint at /health monitors your system. This simple GET route confirms API server responsiveness with a quick JSON status check.

- Repository: [Zylon/private-gpt](https://github.com/zylon-ai/private-gpt)
- Tags: how-to-guide
- Published: 2026-03-06

---

**The PrivateGPT health check endpoint exposes a lightweight, unauthenticated GET route at `/health` that returns a static JSON payload `{"status": "ok"}` to confirm the API server is responsive.**

The `zylon-ai/private-gpt` repository implements a dedicated health check endpoint to support external monitoring systems and load balancers. This endpoint provides a zero-dependency mechanism to verify that the FastAPI application is running without performing expensive operations. Understanding how this health check endpoint functions is essential for deploying PrivateGPT in production environments with automated monitoring.


## Router Definition and File Structure

The health check logic resides in [`private_gpt/server/health/health_router.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/health/health_router.py), where a dedicated `APIRouter` instance handles all health-related routes.

### The APIRouter Setup

The router is instantiated without authentication requirements, making it accessible to unauthenticated probes from load balancers and container orchestrators.

```python
health_router = APIRouter()

```

### The HealthResponse Pydantic Model

The endpoint returns a strictly typed `HealthResponse` model that guarantees a consistent JSON structure. This model uses a `Literal` type to constrain the status field to only accept `"ok"` as a valid value.

```python
class HealthResponse(BaseModel):
    status: Literal["ok"] = Field(default="ok")

```


## Endpoint Implementation

The actual handler is registered as a GET operation at the `/health` path with a "Health" tag for OpenAPI documentation organization.

```python
@health_router.get("/health", tags=["Health"])
def health() -> HealthResponse:
    """Return ok if the system is up."""
    return HealthResponse(status="ok")

```

When invoked, the function immediately instantiates and returns a `HealthResponse` object, resulting in an HTTP **200 OK** response with the body `{"status":"ok"}`. The implementation performs no database queries, external API calls, or computational heavy lifting, ensuring sub-millisecond response times.


## Integration with the Main Application

The health router is attached to the central FastAPI application inside [`private_gpt/launcher.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/launcher.py). This file imports the router and includes it in the application stack alongside other feature routers such as chat, completions, and ingest.

```python
from private_gpt.server.health.health_router import health_router

# ...

app.include_router(health_router)

```

Because the router is added last in the initialization sequence, the `/health` endpoint becomes available immediately after the application starts, providing an early signal that the server is ready to accept connections.


## Production Monitoring Examples

The health check endpoint's zero-dependency design makes it ideal for high-frequency polling scenarios. Below are practical implementations for common monitoring tools.

### Command-Line Health Verification

Use `curl` to quickly verify service availability during deployment scripts or local development:

```bash
curl -s http://localhost:8000/health | jq .

# Output: {"status":"ok"}

```

### Automated Python Monitoring

For custom monitoring scripts, use an HTTP client like `httpx` to validate the response payload:

```python
import httpx

def check_health(base_url: str = "http://localhost:8000") -> bool:
    try:
        resp = httpx.get(f"{base_url}/health", timeout=2.0)
        resp.raise_for_status()
        return resp.json().get("status") == "ok"
    except Exception:
        return False

if __name__ == "__main__":
    print("Service healthy:", check_health())

```

### Kubernetes Liveness and Readiness Probes

Configure container orchestration platforms to use the endpoint for automated health management:

```yaml
livenessProbe:
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 5
  periodSeconds: 10

```


## Summary

- The **health check endpoint** is defined in [`private_gpt/server/health/health_router.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/health/health_router.py) and mounted via [`private_gpt/launcher.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/launcher.py).
- It returns a static **JSON payload** `{"status": "ok"}` with HTTP status **200 OK**.
- The endpoint requires **no authentication**, making it safe for external load balancers and monitoring tools.
- **Zero dependencies** ensure the check reflects only the API process liveliness, not external service states.
- Response times are sub-millisecond because the handler performs no I/O or computation.


## Frequently Asked Questions

### Does the health check endpoint require authentication?

No. The router is explicitly configured without authentication requirements, allowing unauthenticated probes from load balancers, Kubernetes, and external uptime monitors to verify system availability without API keys or tokens.

### What HTTP status code does the health endpoint return?

The endpoint returns **HTTP 200 OK** when the PrivateGPT server is running. If the server is down or unreachable, the connection will fail entirely; the endpoint does not return error status codes like 503 because it represents a simple liveness check rather than a deep system health validation.

### Can I use the health check for Kubernetes liveness probes?

Yes. The lightweight, fast-responding endpoint at `/health` is ideal for Kubernetes liveness and readiness probes. Configure your pod spec to poll `http://<pod-ip>:8000/health` with appropriate `initialDelaySeconds` and `periodSeconds` values to automate container restart decisions.

### Does the health check verify that the LLM or vector database is connected?

No. According to the source code in [`private_gpt/server/health/health_router.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/health/health_router.py), the endpoint returns a static response without checking external dependencies such as the LLM backend, vector store, or file ingestion services. It verifies only that the FastAPI process is alive and responsive.