Health & Readiness

Health Endpoints

Liveness Probe

Check if the API is running. Use for Kubernetes liveness probes:

GET https://api.truthlocks.com/health/live

# Response (200 OK)
{
  "status": "ok",
  "timestamp": "2026-01-13T12:00:00Z"
}

Readiness Probe

Check if the API is ready to serve traffic (all dependencies healthy):

GET https://api.truthlocks.com/health/ready

# Response (200 OK - All systems operational)
{
  "status": "ok",
  "timestamp": "2026-01-13T12:00:00Z",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "signing_service": "ok",
    "transparency_log": "ok"
  }
}

# Response (503 Service Unavailable - Degraded)
{
  "status": "degraded",
  "timestamp": "2026-01-13T12:00:00Z",
  "checks": {
    "database": "ok",
    "redis": "timeout",
    "signing_service": "ok",
    "transparency_log": "ok"
  }
}

Kubernetes Configuration

If you're building applications that depend on Truthlock, configure your probes to check both your app and the Truthlock API:

apiVersion: v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      containers:
        - name: app
          livenessProbe:
            httpGet:
              path: /health/live
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 8080
            initialDelaySeconds: 10
            periodSeconds: 5
            failureThreshold: 3

Example Readiness Check (App)

// Include Truthlock health in your app's readiness
app.get('/health/ready', async (req, res) => {
  const checks = {
    database: await checkDatabase(),
    truthlock: await checkTruthlock(),
  };
  
  const allHealthy = Object.values(checks).every(c => c === 'ok');
  
  res.status(allHealthy ? 200 : 503).json({
    status: allHealthy ? 'ok' : 'degraded',
    checks,
  });
});

async function checkTruthlock(): Promise<string> {
  try {
    const res = await fetch('https://api.truthlocks.com/health/ready', {
      timeout: 5000,
    });
    return res.ok ? 'ok' : 'degraded';
  } catch {
    return 'unreachable';
  }
}

Status Page

For real-time status updates, subscribe to our status page:

Service Level Agreement

Monitoring Integration

Integrate Truthlock health checks with your observability tools:

Prometheus

# prometheus.yml
scrape_configs:
  - job_name: 'truthlock-health'
    scrape_interval: 30s
    metrics_path: /metrics
    static_configs:
      - targets: ['api.truthlocks.com']

Datadog

# datadog.yaml
init_config:

instances:
  - name: truthlock_api
    url: https://api.truthlocks.com/health/ready
    timeout: 5
    content_match: '"status":"ok"'
    http_response_status_code: 200
    tags:
      - service:truthlock
      - env:production

Custom Dashboard Metrics

// Export key metrics for dashboards
const metrics = {
  'truthlock.availability': isHealthy ? 1 : 0,
  'truthlock.latency_ms': responseTime,
  'truthlock.ratelimit_remaining': rateLimitRemaining,
  'truthlock.attestations_today': dailyCount,
};

Incident Response

If Truthlock is experiencing issues:

1. Check status page: status.truthlocks.com
2. Enable circuit breaker: Fail gracefully in your app
3. Queue operations: Retry attestation minting later
4. Contact support: For Enterprise SLA escalation

Circuit Breaker Pattern

import CircuitBreaker from 'opossum';

const breaker = new CircuitBreaker(
  async (attestation) => client.attestations.mint(attestation),
  {
    timeout: 5000,         // Fail if no response in 5s
    errorThresholdPercentage: 50,  // Open if 50% fail
    resetTimeout: 30000,   // Try again after 30s
  }
);

breaker.fallback(() => {
  // Queue for retry later
  queue.add('retry-attestation', attestation);
  return { queued: true };
});

Next Steps