Skip to content

Health Check

Check the API health status and version information.

Endpoint

GET /api/health

Authentication

❌ No authentication required - This is the only public endpoint that doesn't require an API key.

Description

The health endpoint provides information about the API's current status, version, and build information. It's useful for:

  • Monitoring API availability
  • Checking the deployed version
  • Verifying connectivity before making authenticated requests
  • Health checks in containerized environments

Request

No parameters required.

Example Request

=== "cURL"

curl https://subx-api.duckdns.org/api/health

import requests

response = requests.get("https://subx-api.duckdns.org/api/health")
data = response.json()

print(f"Status: {data['status']}")
print(f"Version: {data.get('version', 'unknown')}")

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    resp, err := http.Get("https://subx-api.duckdns.org/api/health")
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    fmt.Printf("Status: %v\n", result["status"])
    fmt.Printf("Version: %v\n", result["version"])
}

using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        var response = await client.GetAsync("https://subx-api.duckdns.org/api/health");
        var json = await response.Content.ReadAsStringAsync();
        var data = JsonSerializer.Deserialize<JsonElement>(json);

        Console.WriteLine($"Status: {data.GetProperty("status")}");
        Console.WriteLine($"Version: {data.GetProperty("version")}");
    }
}

const response = await fetch('https://subx-api.duckdns.org/api/health');
const data = await response.json();

console.log(`Status: ${data.status}`);
console.log(`Version: ${data.version}`);

Response

Success Response (200 OK)

{
  "status": "ok",
  "version": "1.0.0",
  "built_at": "2024-01-15T10:30:00Z"
}

Response Fields

Field Type Description
status string Always "ok" when API is healthy
version string API version number (semantic versioning)
built_at string ISO 8601 timestamp of when the API was built

Status Codes

Code Description
200 API is healthy and operational
503 API is temporarily unavailable (rare)

Use Cases

1. Monitoring & Alerting

Use this endpoint in your monitoring system to verify API availability:

import requests
import time

def check_api_health():
    try:
        response = requests.get("https://subx-api.duckdns.org/api/health", timeout=5)
        if response.status_code == 200:
            data = response.json()
            if data.get("status") == "ok":
                return True, f"API healthy (version {data.get('version')})"
        return False, f"API unhealthy (status code: {response.status_code})"
    except requests.exceptions.RequestException as e:
        return False, f"API unreachable: {e}"

# Check every 60 seconds
while True:
    is_healthy, message = check_api_health()
    print(f"[{time.strftime('%Y-%m-%d %H:%M:%S')}] {message}")
    time.sleep(60)

2. Version Verification

Check if you're using the latest API version:

import requests

response = requests.get("https://subx-api.duckdns.org/api/health")
data = response.json()

current_version = data.get("version")
print(f"Current API version: {current_version}")

# Compare with expected version
EXPECTED_VERSION = "1.0.0"
if current_version != EXPECTED_VERSION:
    print(f"⚠️ Warning: API version mismatch. Expected {EXPECTED_VERSION}, got {current_version}")

3. Docker Health Check

Use in Docker Compose or Kubernetes health checks:

# docker-compose.yml
services:
  my-app:
    image: my-app:latest
    depends_on:
      - subx-api
    healthcheck:
      test: ["CMD", "curl", "-f", "http://subx-api:8000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3

4. Pre-flight Check

Verify connectivity before making authenticated requests:

import requests

def verify_api_connectivity():
    """Verify API is accessible before proceeding."""
    try:
        response = requests.get("https://subx-api.duckdns.org/api/health", timeout=5)
        return response.status_code == 200
    except:
        return False

if __name__ == "__main__":
    if not verify_api_connectivity():
        print("❌ Cannot reach SubX API. Check your internet connection.")
        exit(1)

    print("✓ API is accessible. Proceeding with requests...")
    # Your API calls here

Notes

  • This endpoint has no rate limiting - you can call it as often as needed
  • Response time is typically < 100ms
  • Does not count toward your API usage quota
  • Cached by CDN for improved performance

Next Steps