Health Endpoints

This page documents the health and monitoring endpoints available in RAG API Core. These endpoints help you monitor the status of the API and its dependencies, and are useful for both automated systems and manual troubleshooting.

Available Endpoints

/api/health: Basic liveness check. Returns a simple status to confirm the API is running.
/api/health/live: Liveness probe for orchestrators (e.g., Kubernetes). Indicates if the service is up.
/api/health/ready: Readiness probe. Checks if the service is ready to accept requests (all dependencies available).
/api/health/check: Deep health check (v1). Performs comprehensive checks on major dependencies.
/api/v2/health/check: Health dashboard UI (v2). Visual dashboard for real-time status, manual refresh, and diagnostics.
/api/v2/health/service-health: JSON summary used by the dashboard (quick/deep via ?test_services=true|false). Suitable for automation.

Deep Health Check Details

The deep checks validate all critical services. The v2 dashboard (/api/v2/health/check) reads from the JSON endpoint /api/v2/health/service-health and supports two modes: - test_services=false (quick): configuration presence and safe client constructs (no external calls) - test_services=true (deep): performs minimal external calls to validate connectivity/permissions

Detailed Checks by Service

The /api/v2/health/check dashboard and the /api/v2/health/service-health JSON endpoint perform comprehensive, multi-step checks across critical services. For each service, the following steps are taken:

1. LLM Service (Azure OpenAI)

Configuration Check: Validates LLM deployment settings in the config.
Instantiation: Attempts to instantiate the LLM client/model.
Service Test (if enabled): Sends a simple prompt to the model and checks for a valid response.
Tracks: response time, model/deployment name, endpoint URL, test success, error details if any.

2. Azure Search Service

Configuration Check: Validates search endpoint and index settings.
Instantiation: Attempts to instantiate the Azure Search client/fetcher.
Service Test (if enabled): Performs a small/wildcard query to verify connectivity and permissions.
Tracks: response time, index name, endpoint URL, result shape, error details if any.

3. Embedding Service (Azure OpenAI Embeddings)

Configuration Check: Validates embedding model deployment settings.
Instantiation: Attempts to instantiate the embeddings client.
Service Test (if enabled): Requests a minimal embedding to verify access and limits.
Tracks: response time, model/deployment, endpoint URL, success flag, error details if any.

4. Table Storage (Status Tracking)

Configuration Check: Validates table storage account and table name.
Instantiation: Attempts to instantiate the Table Storage client.
Service Test (if enabled): Queries the table; if missing, attempts to create it (best-effort).
Tracks: response time, account name, table name, access success, error details if any.

5. Blob Storage (File Upload)

Configuration Check: Validates blob storage account settings.
Instantiation: Attempts to instantiate the Blob Storage client.
Service Test (if enabled): Lists containers to verify connectivity and permissions.
Tracks: response time, account name, visible containers, error details if any.

6. Form Recognizer / Document Intelligence (optional)

Configuration Check: Validates endpoint and API version.
Instantiation: Attempts to instantiate the Form Recognizer admin/client.
Service Test (if enabled): Fetches resource details (e.g., model counts/limits) to verify access.
Tracks: response time, endpoint URL, model counts, access success, error details if any.

7. Configuration Source

Check: Shows where config is loaded from (blob storage vs local files), relevant paths, and environment.

Services Covered

LLM Service (Azure OpenAI chat)
Azure AI Search
Embedding Service (Azure OpenAI embeddings)
Table Storage (status tracking)
Blob Storage (file upload)
Form Recognizer / Document Intelligence (optional)
Configuration source (where config is loaded from)

Dashboard Features

Manual refresh, auto-refresh toggle (60s)
Toggle to enable/disable external service tests
Real-time status with response times and error details

Usage

Use /api/health or /api/health/live for basic uptime monitoring.
Use /api/health/ready for readiness checks in deployment pipelines or orchestrators.
Use /api/health/check (v1) or the v2 dashboard at /api/v2/health/check for detailed diagnostics.
Use /api/v2/health/service-health for machine-readable JSON (append ?test_services=true for deep mode).

Example Response (/api/v2/health/service-health)

{
  "status": "ok",
  "overall_status": "HEALTHY",
  "services": {
    "azure_openai_chat": {"status": "healthy", "response_time": 0.0, "details": {"endpoint": "...", "deployment": "..."}},
    "azure_ai_search": {"status": "healthy", "response_time": 0.0, "details": {"endpoint": "...", "index": "..."}},
    "azure_openai_embeddings": {"status": "healthy", "response_time": 0.0, "details": {"endpoint": "...", "deployment": "..."}},
    "blob_storage": {"status": "healthy", "response_time": 0.0, "details": {"account_name": "..."}},
    "table_storage": {"status": "degraded", "response_time": null, "details": {"account_name": "..."}},
    "form_recognizer": {"status": "unknown"},
    "rag_pipeline": {"status": "healthy"}
  },
  "service_statuses": {"azure_openai_chat": "configured", "azure_ai_search": "configured"},
  "service_summary": {"healthy": 5, "failed": 0, "degraded": 1, "total": 7},
  "errors": [],
  "latencies": {"azure_openai_chat": 0.03},
  "timestamp": "2025-09-19 10:00:00 UTC",
  "mode": "quick",
  "recommendations": []
}

Value

Quickly see if the API or any dependency is down or misconfigured
Integrate with uptime monitoring and alerting tools
Use the dashboard for real-time troubleshooting and support
Understand which services are healthy, degraded, or failing

Back to Architecture