Health and Management Endpoints

The gateway provides health check, monitoring, and administrative endpoints for infrastructure management and observability.

Liveness probe


GET /health

Minimal liveness probe for container orchestration (Docker, Kubernetes). Returns 200 unconditionally as long as the gateway process is running. No authentication required.

Response


{
  "status": "ok"
}

Use this endpoint for Docker HEALTHCHECK directives and Kubernetes liveness probes.

Gateway health check


GET /v1/health

Standard health check that reports the gateway’s status along with Redis and MongoDB connectivity. No authentication required.

Response


HTTP/1.1 200 OK


{
  "status": "ok",
  "service": "curate-me-gateway",
  "version": "0.1.0",
  "timestamp": "2026-02-27T12:00:00+00:00",
  "redis": "connected",
  "mongodb": "connected",
  "degraded": false
}

Response fields

Field	Type	Description
`status`	string	Always `"ok"` if the process is running
`service`	string	Service identifier (`"curate-me-gateway"`)
`version`	string	Gateway version
`timestamp`	string	ISO 8601 timestamp (UTC)
`redis`	string	`"connected"`, `"disconnected"`, or `"not_configured"`
`mongodb`	string	`"connected"`, `"disconnected"`, or `"not_configured"`
`degraded`	boolean	`true` when a backing service is unreachable

Degraded state

The endpoint always returns 200 even when backing services are down — the degraded field indicates reduced functionality:

Redis disconnected: Rate limiting falls back to in-memory counters, cost tracking may be delayed
MongoDB disconnected: Audit logging and policy lookups may fail

This design ensures load balancers keep routing traffic to the gateway even when backing services have transient issues.

Provider health


GET /v1/providers/health

Returns the circuit breaker state for each upstream LLM provider. No authentication required. Designed for monitoring dashboards and uptime checks.

Response


{
  "status": "healthy",
  "timestamp": "2026-02-27T12:00:00Z",
  "providers": [
    {
      "provider": "anthropic",
      "state": "closed",
      "failure_count": 0,
      "failure_threshold": 5,
      "failure_window_seconds": 60.0,
      "recovery_timeout_seconds": 30.0,
      "last_failure_time": null,
      "last_success_time": 1709056790.123,
      "retry_after_seconds": null
    },
    {
      "provider": "deepseek",
      "state": "closed",
      "failure_count": 1,
      "failure_threshold": 5,
      "failure_window_seconds": 60.0,
      "recovery_timeout_seconds": 30.0,
      "last_failure_time": 1709056750.456,
      "last_success_time": 1709056789.789,
      "retry_after_seconds": null
    },
    {
      "provider": "google",
      "state": "closed",
      "failure_count": 0,
      "failure_threshold": 5,
      "failure_window_seconds": 60.0,
      "recovery_timeout_seconds": 30.0,
      "last_failure_time": null,
      "last_success_time": 1709056795.321,
      "retry_after_seconds": null
    },
    {
      "provider": "openai",
      "state": "closed",
      "failure_count": 0,
      "failure_threshold": 5,
      "failure_window_seconds": 60.0,
      "recovery_timeout_seconds": 30.0,
      "last_failure_time": null,
      "last_success_time": 1709056799.654,
      "retry_after_seconds": null
    }
  ]
}

Overall status

Value	Condition
`healthy`	All circuit breakers are closed
`degraded`	Some circuit breakers are open or half-open
`unhealthy`	All circuit breakers are open

Circuit breaker states

State	Description
`closed`	Provider is healthy — requests are proxied normally
`open`	Provider is failing — requests are rejected immediately with 503
`half_open`	Recovery probe in progress — a single request is allowed through to test the provider

Circuit breaker fields

Field	Type	Description
`provider`	string	Provider name (openai, anthropic, google, deepseek)
`state`	string	Circuit breaker state: `closed`, `open`, `half_open`
`failure_count`	integer	Failures in the current sliding window
`failure_threshold`	integer	Failures required to trip the circuit (default: 5)
`failure_window_seconds`	float	Sliding window duration in seconds (default: 60)
`recovery_timeout_seconds`	float	Time before a probe is allowed after circuit opens (default: 30)
`last_failure_time`	float or null	Monotonic timestamp of last failure
`last_success_time`	float or null	Monotonic timestamp of last success
`retry_after_seconds`	float or null	Seconds until the circuit transitions to half-open (only when open)

Detailed health check


GET /v1/health/detailed

Comprehensive gateway health check with per-provider status, infrastructure components, current metrics, cost vs budget, active circuit breakers, rate limit status, and triggered alerts. No authentication required. Designed for monitoring dashboards.

Response


{
  "overall_status": "healthy",
  "timestamp": "2026-02-27T12:00:00Z",
  "uptime_seconds": 86400.5,
  "components": {
    "gateway": "healthy",
    "redis": "healthy",
    "mongodb": "healthy"
  },
  "providers": {
    "openai": {"status": "up", "circuit_breaker": "closed"},
    "anthropic": {"status": "up", "circuit_breaker": "closed"},
    "google": {"status": "up", "circuit_breaker": "closed"},
    "deepseek": {"status": "up", "circuit_breaker": "closed"}
  },
  "metrics": {
    "total_requests": 15420,
    "error_rate": 0.02,
    "p50_latency_ms": 245,
    "p95_latency_ms": 890,
    "p99_latency_ms": 2100
  },
  "cost": {
    "today_usd": 42.50,
    "daily_budget_usd": 100.00,
    "utilization_pct": 42.5
  },
  "alerts": [],
  "rate_limits": []
}

Response fields

Field	Type	Description
`overall_status`	string	`"healthy"`, `"degraded"`, or `"unhealthy"`
`timestamp`	string	ISO 8601 timestamp
`uptime_seconds`	float	Seconds since gateway process started
`components`	object	Per-component status (gateway, redis, mongodb)
`providers`	object	Per-provider status with circuit breaker info
`metrics`	object	Request count, error rate, latency percentiles
`cost`	object	Today’s cost vs daily budget
`alerts`	array	Triggered alert conditions
`rate_limits`	array	Top 5 busiest organizations by current RPM

HTTP status codes

Code	Condition
`200`	Healthy or degraded (still operational)
`503`	Unhealthy (all providers down)

Check approval status


GET /v1/approvals/{approval_id}/status

Poll the status of a HITL approval request. Called by gateway callers who received a 202 response with an approval_id. Requires gateway API key authentication.

Path parameters

Parameter	Type	Description
`approval_id`	string	The approval ID from the 202 response

Headers

Header	Required	Description
`X-CM-API-Key`	Yes	Curate-Me gateway API key

Response


{
  "approval_id": "apr_abc123def456",
  "status": "pending",
  "org_id": "org_xyz789",
  "model": "gpt-4o",
  "estimated_cost": 12.50,
  "created_at": "2026-02-27T12:00:00Z"
}

Status values

Status	Description
`pending`	Awaiting human review
`approved`	Request approved — re-submit to proceed
`rejected`	Request rejected by a reviewer
`expired`	Approval request timed out

Error (not found)


HTTP/1.1 404 Not Found


{
  "error": {
    "message": "Approval request not found: apr_abc123def456",
    "type": "not_found_error",
    "param": "approval_id",
    "code": "not_found"
  }
}

Admin endpoints

The following endpoints are used by the dashboard to manage gateway configuration. They require admin authentication (dashboard JWT or API key with admin scopes).

Governance policies

Method	Endpoint	Description
`GET`	`/gateway/admin/policies`	List governance policies for the org
`POST`	`/gateway/admin/policies`	Create or update a governance policy
`DELETE`	`/gateway/admin/policies/{org_id}`	Delete a governance policy
`POST`	`/gateway/admin/policies/apply-preset`	Apply a policy preset

Usage and billing

Method	Endpoint	Description
`GET`	`/gateway/admin/usage`	Get usage statistics (paginated)
`GET`	`/gateway/admin/usage/daily`	Get daily cost breakdown
`GET`	`/gateway/admin/usage/{request_id}`	Get a single usage record
`GET`	`/gateway/admin/usage/export`	Export usage records as CSV
`GET`	`/gateway/admin/billing/summary`	Monthly billing summary
`GET`	`/gateway/admin/billing/export`	Monthly billing export (JSON/CSV)

Provider secrets

Method	Endpoint	Description
`POST`	`/gateway/admin/secrets`	Store a provider API key (encrypted)
`GET`	`/gateway/admin/secrets`	List stored secrets (metadata only, keys not exposed)
`POST`	`/gateway/admin/secrets/rotate`	Rotate a provider secret
`DELETE`	`/gateway/admin/secrets/{provider}`	Revoke a provider secret

Provider targets

Method	Endpoint	Description
`POST`	`/gateway/admin/provider-targets`	Create a provider target (e.g., Azure OpenAI, Ollama)
`GET`	`/gateway/admin/provider-targets`	List provider targets for the org
`GET`	`/gateway/admin/provider-targets/{id}`	Get a single provider target
`PATCH`	`/gateway/admin/provider-targets/{id}`	Update a provider target
`DELETE`	`/gateway/admin/provider-targets/{id}`	Delete a provider target
`POST`	`/gateway/admin/provider-targets/{id}/discover-models`	Discover models from the target (SSRF-safe)
`GET`	`/gateway/admin/provider-targets/{id}/catalog`	List discovered models

Model aliases

Method	Endpoint	Description
`POST`	`/gateway/admin/model-aliases`	Create a model alias
`GET`	`/gateway/admin/model-aliases`	List model aliases for the org
`GET`	`/gateway/admin/model-aliases/{id}`	Get a single model alias
`PATCH`	`/gateway/admin/model-aliases/{id}`	Update a model alias
`DELETE`	`/gateway/admin/model-aliases/{id}`	Delete a model alias

HITL approvals

Method	Endpoint	Description
`GET`	`/gateway/admin/approvals`	List pending approvals (paginated)
`GET`	`/gateway/admin/approvals/stats`	Counts of pending/approved/rejected
`GET`	`/gateway/admin/approvals/{id}`	Get full approval details
`POST`	`/gateway/admin/approvals/{id}/approve`	Approve a pending request
`POST`	`/gateway/admin/approvals/{id}/reject`	Reject a pending request

Root endpoint


GET /

Returns service identification and a list of available endpoints. No authentication required.


{
  "service": "Curate-Me AI Gateway",
  "version": "1.0.0",
  "status": "running",
  "docs": "/docs",
  "health": "/v1/health",
  "liveness": "/health",
  "metrics": "/metrics",
  "endpoints": {
    "openai_proxy": "POST /v1/chat/completions",
    "anthropic_proxy": "POST /v1/messages",
    "google_proxy": "POST /v1/google/chat/completions",
    "models": "GET /v1/models",
    "admin_policies": "GET/POST /gateway/admin/policies",
    "admin_usage": "GET /gateway/admin/usage",
    "admin_approvals": "GET /gateway/admin/approvals",
    "providers_health": "GET /v1/providers/health"
  }
}

Prometheus metrics


GET /metrics

Prometheus-compatible metrics endpoint. Returns gateway metrics in Prometheus exposition format. No authentication required.

Tracked metrics include:

Request count by provider, model, and status code
Request latency histograms
Governance block counts by reason
Cost accumulation by provider
Circuit breaker state changes