Status API

The Status API provides simple health check endpoints to verify API availability and system status.

Base URLs

• GET /api/status - Basic API health check
• GET /api/example - Example endpoint for testing
• GET /api/status/external - External service status checks

Authentication

Status endpoints do not require authentication and can be used for monitoring and health checks.

Basic Health Check

Simple endpoint to verify that the API is operational.

Request

GET /api/status

Response

{
  "status": "ok",
  "message": "API is operational"
}

Response Codes

• 200 OK - API is healthy and operational
• 503 Service Unavailable - API is experiencing issues

Example Endpoint

Test endpoint that mirrors the status check functionality.

Request

GET /api/example
POST /api/example

Both GET and POST methods are supported and return the same response.

Response

{
  "status": "ok", 
  "message": "API is operational"
}

External Service Status

Check the status of external services that the API depends on.

Request

GET /api/status/external

Response

{
  "status": "ok",
  "services": {
    "database": {
      "status": "healthy",
      "response_time": 12,
      "last_check": "2024-01-16T15:30:00Z"
    },
    "openai": {
      "status": "healthy", 
      "response_time": 145,
      "last_check": "2024-01-16T15:30:00Z"
    },
    "elevenlabs": {
      "status": "healthy",
      "response_time": 89,
      "last_check": "2024-01-16T15:30:00Z"
    },
    "stripe": {
      "status": "healthy",
      "response_time": 234,
      "last_check": "2024-01-16T15:30:00Z"
    }
  },
  "overall_status": "healthy",
  "timestamp": "2024-01-16T15:30:15Z"
}

Service Status Values

• healthy - Service is fully operational
• degraded - Service is operational but slower than normal
• unhealthy - Service is experiencing issues
• unknown - Unable to determine service status

Usage Examples

Basic Health Check (JavaScript)

const response = await fetch('/api/status');
const data = await response.json();

if (data.status === 'ok') {
  console.log('API is operational');
} else {
  console.log('API is experiencing issues');
}

Monitor External Services (JavaScript)

const response = await fetch('/api/status/external');
const data = await response.json();

console.log('Overall status:', data.overall_status);

// Check individual services
Object.entries(data.services).forEach(([service, info]) => {
  console.log(`${service}: ${info.status} (${info.response_time}ms)`);
});

Using cURL

Basic Status Check

curl -X GET https://your-domain.com/api/status

External Services Status

curl -X GET https://your-domain.com/api/status/external

Health Check Script (Bash)

#!/bin/bash
API_URL="https://your-domain.com/api/status"

response=$(curl -s -o /dev/null -w "%{http_code}" "$API_URL")

if [ "$response" = "200" ]; then
    echo "✅ API is healthy"
    exit 0
else
    echo "❌ API is unhealthy (HTTP $response)"
    exit 1
fi

Monitoring Integration

Uptime Monitoring

Status endpoints are designed for integration with uptime monitoring services:

• Pingdom: Monitor /api/status endpoint
• UptimeRobot: Check response contains "status": "ok"
• DataDog: Set up synthetic tests for health checks
• Custom monitoring: Use response time and status checks

Example Monitoring Configuration

Pingdom

• URL: https://your-domain.com/api/status
• Check for: "status": "ok"
• Interval: 1 minute

Prometheus/Grafana

# prometheus.yml
- job_name: 'api-health'
  metrics_path: '/api/status'
  static_configs:
    - targets: ['your-domain.com']

Response Time Benchmarks

Expected response times for status endpoints:

• Basic status: < 100ms
• External services: < 500ms (depends on external service latency)

Error Responses

Service Unavailable

{
  "status": "error",
  "message": "Service temporarily unavailable",
  "error_code": "service_unavailable"
}

Partial Service Degradation

{
  "status": "degraded",
  "message": "Some services are experiencing issues", 
  "services": {
    "database": {
      "status": "healthy"
    },
    "openai": {
      "status": "degraded",
      "issue": "High response times detected"
    }
  }
}

Best Practices

For API Consumers

1. Regular Health Checks: Implement regular status checks before making API calls
2. Timeout Handling: Set appropriate timeouts for status checks (5-10 seconds)
3. Graceful Degradation: Handle API unavailability gracefully in your application
4. Retry Logic: Implement exponential backoff for failed health checks

For Monitoring

1. Multiple Endpoints: Monitor both basic and external service status
2. Alert Thresholds: Set up alerts when services are degraded or unhealthy
3. Geographic Monitoring: Check status from multiple geographic locations
4. Response Time Alerts: Alert when response times exceed normal thresholds

Status Page Integration

The status API can be integrated with status page services:

• Atlassian Statuspage
• StatusPage.io
• Custom status pages

Example integration with a custom status page:

// Update status page based on API health
async function updateStatusPage() {
  try {
    const response = await fetch('/api/status/external');
    const data = await response.json();
    
    // Update status page components based on service health
    updateComponent('api', data.overall_status);
    updateComponent('database', data.services.database.status);
    updateComponent('ai-services', data.services.openai.status);
    
  } catch (error) {
    updateComponent('api', 'unhealthy');
  }
}

Rate Limits

Status endpoints have generous rate limits:

• Basic status: 300 requests per minute
• External status: 60 requests per minute (to avoid overwhelming external services)

Caching

Status responses include appropriate cache headers:

• Basic status: No caching (always fresh)
• External status: 30-second cache to reduce external service load