API Reference

Health Checks

Liveness and readiness probes for Kubernetes deployments and load balancer health checks.

The API Gateway exposes standard health check endpoints compatible with Kubernetes probes and common load balancers. All health endpoints are public — no authentication required.

Endpoints

Method	Endpoint	Purpose	Latency Target
GET	/health	Basic liveness check	< 5ms
GET	/health/live	Kubernetes liveness probe	< 5ms
GET	/health/ready	Kubernetes readiness probe	< 50ms
GET	/health/detailed	Full dependency status	< 200ms

GET /health — Basic Check

Simplest check — confirms the process is alive and the HTTP server is responding. Use for load balancer health checks.

bash

curl http://localhost:3009/api/v1/health

Response 200

{
  "status": "ok",
  "timestamp": "2024-01-15T10:00:00.000Z"
}

GET /health/ready — Readiness Probe

Checks all critical dependencies before accepting traffic. Returns 503 if any required dependency is unavailable.

bash

curl http://localhost:3009/api/v1/health/ready

Response 200 — all healthy

{
  "status": "ok",
  "checks": {
    "database": { "status": "up", "latency": 2 },
    "redis": { "status": "up", "latency": 1 },
    "kafka": { "status": "up", "latency": 5 }
  }
}

Response 503 — dependency down

{
  "status": "error",
  "checks": {
    "database": { "status": "up", "latency": 2 },
    "redis": { "status": "down", "error": "ECONNREFUSED" },
    "kafka": { "status": "up", "latency": 5 }
  }
}

GET /health/detailed

Full system status including version info, uptime, and all dependency details.

Response 200

{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 86400,
  "environment": "production",
  "checks": {
    "database": {
      "status": "up",
      "latency": 2,
      "details": {
        "host": "localhost:5432",
        "database": "ai_interview",
        "connections": { "active": 3, "idle": 7, "max": 10 }
      }
    },
    "redis": {
      "status": "up",
      "latency": 1,
      "details": { "host": "localhost:6379", "memory": "12MB" }
    },
    "kafka": {
      "status": "up",
      "latency": 5,
      "details": { "broker": "localhost:9092", "topics": 7 }
    },
    "agnoAgent": {
      "status": "up",
      "latency": 15,
      "details": { "url": "http://localhost:8000", "version": "0.4.0" }
    }
  }
}

Kubernetes Configuration

yaml

livenessProbe:
  httpGet:
    path: /api/v1/health/live
    port: 3009
  initialDelaySeconds: 30
  periodSeconds: 10
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /api/v1/health/ready
    port: 3009
  initialDelaySeconds: 10
  periodSeconds: 5
  failureThreshold: 3

Agent Discovery

The agent card endpoint is part of the A2A protocol and is always public. It describes the agent's capabilities and supported methods.

bash

curl http://localhost:3009/.well-known/agent.json

Response 200

{
  "name": "AI Interview Agent",
  "version": "1.0.0",
  "description": "Multi-tenant AI interview platform with HITL workflow",
  "url": "http://localhost:3009",
  "capabilities": {
    "a2a": true,
    "jsonRpc": true,
    "webhooks": true,
    "streaming": false
  },
  "methods": [
    "interview.create",
    "interview.getStatus",
    "interview.approve",
    "interview.reject"
  ]
}

Configure Prometheus to scrape the /api/v1/health/metrics endpoint (Prometheus format) for latency histograms, request counters, and dependency health metrics.

Was this page helpful?

Previous← MCP Skills

NextOverview →