API Reference

Health Check

The health endpoint provides real-time status of the HyperSearchX API server and all connected services. Useful for monitoring, load balancers, and uptime checks.

GET/health

No authentication required. The health endpoint is publicly accessible for use with load balancers and monitoring services.

Example request

bash

curl https://api.hypersearchx.zuhabul.com/health

Response — healthy

healthy.json

{
  "status": "ok",
  "version": "1.0.0",
  "uptime_secs": 86412,
  "timestamp": "2025-11-20T14:30:00Z",
  "services": {
    "database": { "status": "ok", "latency_ms": 1 },
    "cache": { "status": "ok", "entries": 4821, "size_mb": 12.4 },
    "searxng": { "status": "ok", "url": "http://localhost:4040", "latency_ms": 23 },
    "intelligence": { "status": "ok", "sources_tracked": 1247 }
  },
  "backends": {
    "brave": { "status": "ok", "success_rate": 0.98 },
    "stackoverflow": { "status": "ok", "success_rate": 0.99 },
    "github": { "status": "ok", "success_rate": 0.97 },
    "reddit": { "status": "ok", "success_rate": 0.95 },
    "youtube": { "status": "ok", "success_rate": 0.99 }
  }
}

Response — degraded

degraded.json

{
  "status": "degraded",
  "version": "1.0.0",
  "uptime_secs": 3600,
  "timestamp": "2025-11-20T14:30:00Z",
  "services": {
    "database": { "status": "ok", "latency_ms": 1 },
    "cache": { "status": "ok", "entries": 100, "size_mb": 0.2 },
    "searxng": { "status": "unreachable", "url": "http://localhost:4040", "error": "connection refused" },
    "intelligence": { "status": "ok", "sources_tracked": 12 }
  }
}

HTTP status codes

Code	status field	Meaning
`200`	`ok`	All services healthy
`200`	`degraded`	Partially operational (some backends down)
`503`	`unavailable`	Critical service failure (database unreachable)

Monitoring integration

uptime-check.sh

#!/bin/bash
# Simple uptime check — exit 0 if healthy, 1 if not
STATUS=$(curl -sf https://api.hypersearchx.zuhabul.com/health | jq -r .status)
if [ "$STATUS" = "ok" ] || [ "$STATUS" = "degraded" ]; then
  echo "API is UP (status: $STATUS)"
  exit 0
else
  echo "API is DOWN"
  exit 1
fi

docker-healthcheck

services:
  hsx-api:
    image: ghcr.io/zuhabul/hypersearchx:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3050/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Next steps

Usage Stats →

Token and request quotas

Search API →

Core search endpoint

Docker Setup →

Self-hosted deployment

Error Reference →

All error codes