Health API

Check the overall health of the InfoConnect Hybrid Search Engine.

Endpoint

GET /health

Request

No authentication required for health checks.

Response

Healthy

{
  "status": "healthy",
  "version": "0.2.0",
  "components": {
    "api": "ok",
    "redis": "ok",
    "qdrant": "ok",
    "celery": "ok",
    "modernbert-onnx": "ok"
  }
}

Degraded

{
  "status": "degraded",
  "version": "0.2.0",
  "components": {
    "api": "ok",
    "redis": "error",
    "qdrant": "ok",
    "celery": "ok",
    "modernbert-onnx": "ok"
  }
}

Version Field

The top-level version field is the Product Version of the running service. It is derived from the package version in pyproject.toml, not from a separately edited health-check constant. Use it to confirm which release is actually serving traffic after a deploy, rollback, or local rebuild.

The same Product Version also appears as info.version in /openapi.json. Run just version-check before release work to verify that pyproject.toml, runtime metadata, app.version, /health, and the committed OpenAPI document agree.

Component Status

Component	Description
api	FastAPI application status
redis	Redis connection (broker + backend)
qdrant	Qdrant vector database connection
celery	Celery worker availability
modernbert-onnx	ModernBERT ONNX classification model health (when CLASSIFICATION_ENABLED=true)

Examples

Basic Health Check

curl http://localhost:8000/health

Monitoring Script

#!/bin/bash

response=$(curl -s http://localhost:8000/health)
status=$(echo "$response" | jq -r '.status')
version=$(echo "$response" | jq -r '.version')

if [ "$status" = "healthy" ]; then
  echo "✅ System is healthy (version $version)"
  exit 0
else
  echo "❌ System is degraded (version $version)"
  echo "$response" | jq '.'
  exit 1
fi

Docker Health Check

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

Kubernetes Liveness Probe

livenessProbe:
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 60
  periodSeconds: 30

readinessProbe:
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 30
  periodSeconds: 10

Load Balancer Health Check

Configure your load balancer to ping /health every 30 seconds. Remove degraded instances from rotation.

Response Codes

Code	Status	Description
200	Healthy	All components operational

The /health endpoint always returns HTTP 200. Use the status field (healthy or degraded) to determine system health.

Troubleshooting

Redis Error

{
  "status": "degraded",
  "components": {
    "redis": "error"
  }
}

Check: Redis container is running

docker compose ps redis
docker compose logs redis

Qdrant Error

{
  "status": "degraded",
  "components": {
    "qdrant": "error"
  }
}

Check: Qdrant container is running

docker compose ps qdrant
curl http://localhost:6333/healthz

Celery Error

{
  "status": "degraded",
  "components": {
    "celery": "error"
  }
}

Check: Workers are running

just status
# or
docker compose ps

Best Practices

1. Monitor continuously - Use /health for uptime monitoring
2. Alert on degraded - Set up alerts when status != healthy
3. Check components - Inspect individual component status for debugging
4. Log responses - Log health check results for troubleshooting