Platform

Health & Liveness Endpoints

KhaleejiAPI exposes two monitoring endpoints with different authentication and granularity trade-offs. Use /api/v1/ping for basic uptime monitors and load-balancer probes; use /api/v1/health for authenticated, subsystem-level diagnostics from your own backend.

Endpoint overview

EndpointAuth requiredPurposeResponse
GET /api/v1/pingNoneUptime monitors, AWS ALB health checks, CDN probes{ ok: true } — always HTTP 200
GET /api/v1/healthAPI keyAuthenticated subsystem diagnostics from your own backendDetailed status object — HTTP 200 or 503

GET /api/v1/ping

Unauthenticated

A lightweight liveness probe. No API key is required. The endpoint returns HTTP 200 with { ok: true } as long as the Node.js process is alive. It performs no database or cache I/O, so it responds in under 5 ms even under heavy load.

This is the correct endpoint to configure in external uptime monitors (UptimeRobot, Freshping, Better Uptime) and for the AWS ALB health check — which cannot inject API credentials into its probes.

Endpoint:/api/v1/ping
Method:GET
Auth:None
Latency:<5ms

cURL

bash
curl -X GET "https://khaleejiapi.dev/api/v1/ping"

Response (HTTP 200)

json
{ "ok": true }

External uptime monitor config

bash
# UptimeRobot / Freshping / Better Uptime
# URL: https://khaleejiapi.dev/api/v1/ping
# Method: GET
# Expected status: 200
# No authentication required

Shell script example

bash
#!/bin/bash
# Lightweight uptime check — no API key needed
STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://khaleejiapi.dev/api/v1/ping)
if [ "$STATUS" -ne 200 ]; then
  echo "KhaleejiAPI is unreachable (HTTP $STATUS)"
  exit 1
fi
echo "Platform is up"

GET /api/v1/health

Requires API key

Returns a detailed health snapshot including platform version, AWS region, process uptime, and the status of internal subsystems. The response is HTTP 200 when all checks pass or HTTP 503 when any subsystem is degraded — making it machine-parseable for automated on-call alerts.

Because this endpoint requires a valid Authorization: Bearer header it is not suitable for unauthenticated probes (ALB, UptimeRobot, etc.). Use it from your own server-side monitoring code or dashboards.

Endpoint:/api/v1/health
Method:GET
Auth:******
Latency:<50ms

cURL

bash
curl -X GET "https://khaleejiapi.dev/api/v1/health" \
  -H "Authorization: Bearer ******"

Response — healthy (HTTP 200)

json
{
  "data": {
    "status": "healthy",
    "version": "1.3.0",
    "region": "ap-south-1",
    "uptime": 86400,
    "timestamp": "2025-07-01T12:00:00.000Z",
    "checks": {
      "validation": "healthy"
    }
  },
  "meta": { "timestamp": "2025-07-01T12:00:00.000Z" }
}

Response — degraded (HTTP 503)

When one or more subsystems are unavailable the top-level status is “degraded” and the HTTP status code changes to 503. Individual checks fields indicate which subsystem is affected.

json
{
  "data": {
    "status": "degraded",
    "version": "1.3.0",
    "region": "ap-south-1",
    "uptime": 3600,
    "timestamp": "2025-07-01T12:00:00.000Z",
    "checks": {
      "validation": "unavailable"
    }
  },
  "meta": { "timestamp": "2025-07-01T12:00:00.000Z" }
}

Authenticated monitoring example (JavaScript)

javascript
// Detailed health check with API key (e.g., from your backend)
const response = await fetch("https://khaleejiapi.dev/api/v1/health", {
  headers: { Authorization: 'Bearer ******' },
});
 
const { data } = await response.json();
 
if (data.status === "degraded") {
  // data.checks.validation === "unavailable"
  alertOncall(`KhaleejiAPI subsystem degraded: ${JSON.stringify(data.checks)}`);
}

/api/v1/health — response fields

FieldTypeDescription
statusstring"healthy" or "degraded"
versionstringPlatform version
regionstringAWS region (e.g. ap-south-1)
uptimenumberProcess uptime in seconds
timestampstringISO 8601 timestamp of this response
checks.validationstring"healthy" or "unavailable" — validation subsystem probe

When to use which endpoint

Use /api/v1/ping when…

  • Configuring an AWS ALB target group health check
  • Setting up an external uptime monitor (UptimeRobot, Freshping, etc.)
  • Running a Cloudflare health check or CDN probe
  • Checking liveness from a shell script or CI pipeline
  • Any context where you cannot supply API credentials

Use /api/v1/health when…

  • Building an internal status dashboard
  • Setting up PagerDuty / Opsgenie alerts on subsystem degradation
  • Monitoring platform version and region from your backend
  • Verifying a deployment rolled out cleanly
  • Any context where you control the request and can inject an API key

Related

Service Status

How to read the public status page during incidents.

Diagnostics

Run a latency and connectivity diagnostic against the platform.