GET
/
api
/
v1
/
system
/
health
Health Check
curl --request GET \
  --url https://spideriq.di-atomic.com/api/v1/system/health \
  --header 'Authorization: Bearer <token>'
{
  "status": "<string>",
  "timestamp": "<string>",
  "version": "<string>",
  "services": {},
  "services.database": "<string>",
  "services.redis": "<string>",
  "services.rabbitmq": "<string>",
  "services.workers": {}
}

Overview

Health check endpoint to verify the API is operational and all core services are running properly. This endpoint does not require authentication.

Authentication

No authentication required - This endpoint is publicly accessible for health monitoring.

Response

status
string
Overall system statusValues:
  • healthy - All systems operational
  • degraded - Some non-critical issues
  • unhealthy - Critical services down
timestamp
string
ISO 8601 timestamp of the health check
version
string
Current API version
services
object
Status of individual services

Services Object

services.database
string
Database database status (up or down)
services.redis
string
Redis cache status (up or down)
services.rabbitmq
string
RabbitMQ message queue status (up or down)
services.workers
object
Worker availability information

Example Request

curl https://spideriq.di-atomic.com/api/v1/system/health

Example Response

{
  "status": "healthy",
  "timestamp": "2025-10-27T10:30:45Z",
  "version": "1.0.0",
  "services": {
    "database": "up",
    "redis": "up",
    "rabbitmq": "up",
    "workers": {
      "spider_site": 4,
      "spider_maps": 2,
      "total": 6,
      "available": true
    }
  }
}

Status Codes

Status CodeMeaningDescription
200OKSystem is healthy or degraded but operational
503Service UnavailableCritical services are down

Use Cases

Application Health Check

Monitor API availability in your application:
import requests
import time

def wait_for_api_ready(max_wait=60):
    """Wait for API to be healthy before proceeding"""
    url = "https://spideriq.di-atomic.com/api/v1/system/health"
    start_time = time.time()

    while time.time() - start_time < max_wait:
        try:
            response = requests.get(url, timeout=5)
            data = response.json()

            if data["status"] == "healthy":
                print("API is healthy and ready")
                return True

            elif data["status"] == "degraded":
                print("API is degraded but operational")
                return True

            else:
                print(f"API unhealthy: {data.get('issues', [])}")
                time.sleep(5)

        except Exception as e:
            print(f"Health check failed: {e}")
            time.sleep(5)

    raise TimeoutError("API did not become healthy within timeout")

# Usage
wait_for_api_ready()

Monitoring Script

Continuous monitoring for alerting systems:
import requests
import time
import smtplib
from email.message import EmailMessage

def monitor_health(check_interval=60, alert_email="admin@example.com"):
    """Monitor API health and send alerts"""
    url = "https://spideriq.di-atomic.com/api/v1/system/health"
    last_status = None

    while True:
        try:
            response = requests.get(url, timeout=10)
            data = response.json()
            current_status = data["status"]

            # Alert on status change
            if last_status and current_status != last_status:
                send_alert(
                    alert_email,
                    f"SpiderIQ status changed: {last_status}{current_status}",
                    data
                )

            # Alert on unhealthy
            if current_status == "unhealthy":
                send_alert(
                    alert_email,
                    "SpiderIQ is UNHEALTHY",
                    data
                )

            last_status = current_status
            print(f"[{data['timestamp']}] Status: {current_status}")

        except Exception as e:
            print(f"Health check error: {e}")
            send_alert(alert_email, "SpiderIQ health check failed", str(e))

        time.sleep(check_interval)

def send_alert(to_email, subject, body):
    """Send email alert"""
    # Implement your alerting logic
    print(f"ALERT: {subject}")

Docker Healthcheck

Use in Docker Compose healthcheck:
healthcheck:
  test: ["CMD", "curl", "-f", "https://spideriq.di-atomic.com/api/v1/system/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

Kubernetes Liveness Probe

Use as Kubernetes probe:
livenessProbe:
  httpGet:
    path: /api/v1/system/health
    port: 3000
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

Status Page Widget

Display on your status page:
async function updateStatusPage() {
  try {
    const response = await fetch(
      'https://spideriq.di-atomic.com/api/v1/system/health'
    );
    const health = await response.json();

    // Update status indicator
    const statusEl = document.getElementById('api-status');
    statusEl.textContent = health.status.toUpperCase();
    statusEl.className = `status-badge status-${health.status}`;

    // Update service indicators
    document.getElementById('db-status').textContent =
      health.services.database === 'up' ? '✓' : '✗';
    document.getElementById('redis-status').textContent =
      health.services.redis === 'up' ? '✓' : '✗';
    document.getElementById('workers-status').textContent =
      `${health.services.workers.total} available`;

    // Show issues if any
    if (health.issues && health.issues.length > 0) {
      const issuesEl = document.getElementById('issues');
      issuesEl.innerHTML = health.issues.map(i => `<li>${i}</li>`).join('');
    }

  } catch (error) {
    console.error('Failed to fetch health status:', error);
    document.getElementById('api-status').textContent = 'UNKNOWN';
  }
}

// Update every 30 seconds
setInterval(updateStatusPage, 30000);
updateStatusPage();

Understanding Status Levels

Healthy

All core services are operational:
  • Database connected
  • Redis cache working
  • RabbitMQ queue available
  • Workers available to process jobs
Action: Normal operation

Degraded

API is functional but with reduced performance:
  • Redis cache may be down (slower responses)
  • Fewer workers available (slower processing)
Action: Monitor closely, consider reducing load

Unhealthy

Critical services are down:
  • RabbitMQ unavailable (cannot queue jobs)
  • No workers available (cannot process jobs)
  • Database connection lost
Action: Do not submit jobs, contact support

Monitoring Best Practices

Regular checks: Poll this endpoint every 30-60 seconds for production monitoring.
Timeout: Set a reasonable timeout (5-10s) for health checks to avoid hanging monitors.
Rate limits: This endpoint is exempt from rate limiting, but avoid excessive polling (< 10s intervals).