Health API

Service health check with queue and Redis status

GET /api/health

Health API

cURL

curl --request GET \
  --url https://api.example.com/api/health

200

{
  "status": "<string>",
  "timestamp": "<string>",
  "jobQueue": {
    "enabled": true,
    "redis": "<string>"
  }
}

Overview

The Health API provides a lightweight endpoint to check the operational status of the BioAgents service, including job queue and Redis connectivity when enabled.

No Authentication Required

This endpoint is publicly accessible for monitoring and health checks.

---

GET /api/health

Check service health status.

Response Fields

status · string

Overall service status:

• ok: All systems operational
• degraded: Some systems unavailable but core functionality works

timestamp · string

ISO 8601 timestamp of health check

jobQueue · object

Job queue status information

Show jobQueue properties

enabled · boolean

Whether job queue is enabled (USE_JOB_QUEUE environment variable)

redis · string

Redis connection status: connected, disconnected, or omitted if queue disabled

---

Examples

Example: Healthy Service (Queue Disabled)

curl https://api.bioagents.xyz/api/health

Response:

{
  "status": "ok",
  "timestamp": "2024-03-15T10:30:45.123Z",
  "jobQueue": {
    "enabled": false
  }
}

Example: Healthy Service (Queue Enabled)

curl https://api.bioagents.xyz/api/health

Response:

{
  "status": "ok",
  "timestamp": "2024-03-15T10:30:45.123Z",
  "jobQueue": {
    "enabled": true,
    "redis": "connected"
  }
}

Example: Degraded Service (Redis Unavailable)

curl https://api.bioagents.xyz/api/health

Response:

{
  "status": "degraded",
  "timestamp": "2024-03-15T10:30:45.123Z",
  "jobQueue": {
    "enabled": true,
    "redis": "disconnected"
  }
}

---

Use Cases

Kubernetes Liveness Probe

livenessProbe:
  httpGet:
    path: /api/health
    port: 3000
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

Docker Compose Health Check

services:
  bioagents:
    image: bioagents:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Monitoring Script

#!/bin/bash
# health-check.sh

RESPONSE=$(curl -s https://api.bioagents.xyz/api/health)
STATUS=$(echo $RESPONSE | jq -r '.status')

if [ "$STATUS" != "ok" ]; then
  echo "Service degraded: $RESPONSE"
  # Send alert to monitoring system
  curl -X POST https://monitoring.example.com/alert \
    -H "Content-Type: application/json" \
    -d "{\"service\": \"bioagents\", \"status\": \"$STATUS\", \"details\": $RESPONSE}"
fi

JavaScript Health Monitor

async function checkHealth() {
  try {
    const response = await fetch('https://api.bioagents.xyz/api/health');
    const health = await response.json();
    
    if (health.status !== 'ok') {
      console.warn('Service health degraded:', health);
      
      // Check specific subsystems
      if (health.jobQueue?.enabled && health.jobQueue?.redis === 'disconnected') {
        console.error('Redis connection lost - queue jobs may fail');
      }
    }
    
    return health;
  } catch (error) {
    console.error('Health check failed:', error);
    return { status: 'unreachable', error: error.message };
  }
}

// Poll every 30 seconds
setInterval(checkHealth, 30000);

---

Status Interpretation

ok Status

• Core API endpoints are operational
• Database connectivity is working
• If queue enabled: Redis is connected
• Ready to accept requests

degraded Status

• Core API may still work
• Redis connection failed (if queue enabled)
• Queue-based endpoints will return 503 errors
• In-process mode endpoints continue working

No Response

• Service is down or unreachable
• Network connectivity issues
• Server crashed or not started

---

Implementation Details

Queue Disabled (USE_JOB_QUEUE=false)

• Health check always returns ok (no external dependencies)
• Response time: ~1-5ms

Queue Enabled (USE_JOB_QUEUE=true)

• Performs Redis PING to verify connectivity
• Response time: ~10-50ms (depends on Redis latency)
• If Redis unavailable, sets status to degraded

Endpoint Location

Defined in src/index.ts:212-251

.get("/api/health", async () => {
  const health = {
    status: "ok",
    timestamp: new Date().toISOString(),
  };

  if (isJobQueueEnabled()) {
    try {
      const redis = getBullMQConnection();
      await redis.ping();
      health.jobQueue = {
        enabled: true,
        redis: "connected",
      };
    } catch (error) {
      health.jobQueue = {
        enabled: true,
        redis: "disconnected",
      };
      health.status = "degraded";
    }
  } else {
    health.jobQueue = {
      enabled: false,
    };
  }

  return health;
})

---

Related Endpoints

• Status API - Check deep research job progress
• Chat API - Submit chat requests
• Deep Research API - Start research investigations

---

Monitoring Best Practices

1. Set up automated health checks every 30-60 seconds
2. Alert on degraded status - indicates Redis issues
3. Alert on consecutive failures (3+ in a row) - service may be down
4. Monitor response times - slow responses indicate resource constraints
5. Check logs when health degrades - look for Redis connection errors

Example Alert Rules

# Prometheus alerting rules
groups:
  - name: bioagents
    rules:
      - alert: BioAgentsServiceDown
        expr: up{job="bioagents"} == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "BioAgents service is down"
          
      - alert: BioAgentsServiceDegraded
        expr: bioagents_health_status{status="degraded"} == 1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "BioAgents service degraded (Redis disconnected)"
          
      - alert: BioAgentsSlowHealthCheck
        expr: bioagents_health_check_duration_seconds > 1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Health check taking longer than 1 second"