Health Check

Overview

The health check endpoint provides a simple way to verify that the API server is running and responsive. Use this for monitoring, load balancer health checks, and readiness probes.

Endpoint

GET /health

Authentication

No authentication required - This endpoint is publicly accessible.

Request

Simple GET request with no parameters:

curl http://localhost:7100/health

Response

Healthy Response

HTTP Status: 200 OK

{
  "status": "healthy"
}

Unhealthy Response

HTTP Status: 503 Service Unavailable

{
  "status": "unhealthy",
  "reason": "No ASR workers available"
}

Use Cases

Load Balancer Health Checks

Configure your load balancer to use the health endpoint:

AWS ALB/NLB
Kubernetes Service

apiServer:
  service:
    type: LoadBalancer
    healthCheckPath: /health
    healthCheckInterval: 30
    healthCheckTimeout: 5
    healthyThreshold: 2
    unhealthyThreshold: 3

apiVersion: v1
kind: Service
metadata:
  name: api-server
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-healthcheck-path: "/health"
spec:
  type: LoadBalancer

Kubernetes Liveness Probe

Monitor pod health in Kubernetes:

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

Kubernetes Readiness Probe

Determine when pod is ready to receive traffic:

readinessProbe:
  httpGet:
    path: /health
    port: 7100
  initialDelaySeconds: 10
  periodSeconds: 5
  timeoutSeconds: 3
  failureThreshold: 3

Monitoring and Alerting

Monitor service availability:

Prometheus
Python Script
Bash Script

- job_name: 'api-server-health'
  metrics_path: '/health'
  scrape_interval: 30s
  static_configs:
    - targets: ['api-server:7100']

import requests
import time

def check_health():
    try:
        response = requests.get(
            "http://localhost:7100/health",
            timeout=5
        )
        return response.status_code == 200
    except Exception as e:
        print(f"Health check failed: {e}")
        return False

while True:
    if not check_health():
        print("Service unhealthy!")
    time.sleep(30)

#!/bin/bash

while true; do
    STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:7100/health)
    
    if [ "$STATUS" -ne 200 ]; then
        echo "Health check failed: HTTP $STATUS"
    fi
    
    sleep 30
done

Uptime Monitoring

Integration with uptime monitoring services:

UptimeRobot
Pingdom
Datadog

Monitor Type: HTTP(s)
URL: https://api.example.com/health
Keyword: healthy
Interval: 5 minutes

Check Type: HTTP
URL: https://api.example.com/health
Expected Status: 200
Check Interval: 1 minute

init_config:

instances:
  - url: http://api-server:7100/health
    name: smallest-api
    timeout: 5
    http_response_status_code: 200

Advanced Health Checks

Detailed Health Status

For more detailed health information, add query parameter:

curl http://localhost:7100/health?detailed=true

Response:

{
  "status": "healthy",
  "components": {
    "api_server": "healthy",
    "lightning_asr": "healthy",
    "license_proxy": "healthy",
    "redis": "healthy"
  },
  "uptime_seconds": 86400,
  "version": "1.0.0"
}

Component-Specific Checks

Check individual components:

curl http://localhost:7100/health/asr
curl http://localhost:7100/health/license
curl http://localhost:7100/health/redis

Integration Examples

Docker Compose Healthcheck

docker-compose.yml

services:
  api-server:
    image: quay.io/smallestinc/self-hosted-api-server:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7100/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  template:
    spec:
      containers:
      - name: api-server
        image: quay.io/smallestinc/self-hosted-api-server:latest
        livenessProbe:
          httpGet:
            path: /health
            port: 7100
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 7100
          initialDelaySeconds: 10
          periodSeconds: 5

Automated Testing

Include health checks in CI/CD:

.github/workflows/deploy.yml

- name: Wait for deployment
  run: |
    for i in {1..30}; do
      if curl -f http://api.example.com/health; then
        echo "Service is healthy"
        exit 0
      fi
      sleep 10
    done
    echo "Service failed to become healthy"
    exit 1

Best Practices

Set Appropriate Timeouts

Configure reasonable timeouts:

Timeout: 5 seconds max
Interval: 10-30 seconds
Retries: 3-5 attempts

healthcheck:
  timeout: 5s
  interval: 30s
  retries: 3

Use in Load Balancers

Always configure health checks in load balancers:

Prevents traffic to unhealthy instances
Enables automatic failover
Reduces user-facing errors

Monitor Continuously

Set up continuous monitoring:

External uptime monitoring
Internal health checks
Alerting on failures

Test Failure Scenarios

Regularly test health check behavior:

kubectl delete pod api-server-xxx

Verify:

Health check fails
Load balancer stops routing
New pod becomes ready
Health check succeeds

Troubleshooting

Health Check Failing

Check API server logs:

kubectl logs -l app=api-server -n smallest

Common causes:

Lightning ASR not available
License proxy down
Redis connection failed

Solutions:

Verify all components running
Check service connectivity
Review component logs

False Positives

Symptoms: Health returns 200 but requests fail Solutions:

Use detailed health checks
Test actual transcription endpoint
Monitor error rates

Timeout Issues

Symptoms: Health checks timing out Solutions:

Increase timeout values
Check network latency
Verify no network policies blocking

What’s Next?

Transcription API

Learn about the transcription endpoint

Examples

See complete integration examples

Getting Started

Docker Setup

Kubernetes Setup

Troubleshooting

Health Check

Overview

Endpoint

Authentication

Request

Response

Healthy Response

Unhealthy Response

Use Cases

Load Balancer Health Checks

Kubernetes Liveness Probe

Kubernetes Readiness Probe

Monitoring and Alerting

Uptime Monitoring

Advanced Health Checks

Detailed Health Status

Component-Specific Checks

Integration Examples

Docker Compose Healthcheck

Kubernetes Deployment

Automated Testing

Best Practices

Troubleshooting

Health Check Failing

False Positives

Timeout Issues

What’s Next?

Transcription API

Examples

Getting Started

Docker Setup

Kubernetes Setup

Troubleshooting

​Overview

​Endpoint

​Authentication

​Request

​Response

​Healthy Response

​Unhealthy Response

​Use Cases

​Load Balancer Health Checks

​Kubernetes Liveness Probe

​Kubernetes Readiness Probe

​Monitoring and Alerting

​Uptime Monitoring

​Advanced Health Checks

​Detailed Health Status

​Component-Specific Checks

​Integration Examples

​Docker Compose Healthcheck

​Kubernetes Deployment

​Automated Testing

​Best Practices

​Troubleshooting

​Health Check Failing

​False Positives

​Timeout Issues

​What’s Next?

Transcription API

Examples

Overview

Endpoint

Authentication

Request

Response

Healthy Response

Unhealthy Response

Use Cases

Load Balancer Health Checks

Kubernetes Liveness Probe

Kubernetes Readiness Probe

Monitoring and Alerting

Uptime Monitoring

Advanced Health Checks

Detailed Health Status

Component-Specific Checks

Integration Examples

Docker Compose Healthcheck

Kubernetes Deployment

Automated Testing

Best Practices

Troubleshooting

Health Check Failing

False Positives

Timeout Issues

What’s Next?