Overview

Monitor provider health, circuit-breaker states, p50/p95/p99 latency metrics, and budget guard alerts. Inspect connection cooldowns and model lockouts in real time.

Authentication

All requests require a valid Bearer token or session cookie. Obtain a token via POST /api/auth/login or configure REQUIRE_API_KEY=false for local development.

Endpoints

GET /api/monitoring/health

System health check

Returns system health including uptime, memory, circuit breakers, rate limits

curl https://localhost:20128/api/monitoring/health \
  -H "Authorization: Bearer $NERVE_TOKEN"

Payloads

See the full OpenAPI specification at GET /api/openapi/spec or docs/openapi.yaml for detailed request/response schemas.

Nerve — Monitoring & Health

Requires NERVE_URL and NERVE_KEY. See entry-point SKILL for setup.

System health

curl $NERVE_URL/api/health \
  -H "Authorization: Bearer $NERVE_KEY"

Returns: uptime, memory, active connections, circuit breaker states, rate limit status, cache stats.

Unauthenticated quick check:

curl $NERVE_URL/api/health
# → {"ok":true}

Provider circuit breakers

Circuit breakers prevent traffic from hitting failing providers.

States: CLOSED (normal), OPEN (blocked), HALF_OPEN (probe mode — auto-recovers).

curl $NERVE_URL/api/monitoring/health \
  -H "Authorization: Bearer $NERVE_KEY"

Response includes circuitBreakers array with per-provider state and resetAt timestamp.

Per-provider metrics (p50/p95/p99)

curl $NERVE_URL/api/providers/metrics \
  -H "Authorization: Bearer $NERVE_KEY"

Response shape per provider:

{
  "provider": "anthropic",
  "requests": 1247,
  "successRate": 0.994,
  "latency": { "p50": 820, "p95": 2100, "p99": 3800 },
  "circuitState": "CLOSED",
  "tokensUsed": 2847000
}

Via MCP (if Nerve is your MCP server)

nerve_get_health            → full system health snapshot
nerve_get_provider_metrics  → p50/p95/p99 + circuit state per provider
nerve_get_session_snapshot  → cost, tokens, errors for current session
nerve_check_quota           → quota balance + percent remaining + reset time
nerve_db_health_check       → diagnose + auto-repair database drift

Quota check

curl $NERVE_URL/api/quota \
  -H "Authorization: Bearer $NERVE_KEY"

Returns used/total tokens and requests per provider/account, with resetAt timestamps.

Budget guard (spend limit)

Set a session spending limit that degrades or blocks requests when hit:

curl -X POST $NERVE_URL/api/budget/guard \
  -H "Authorization: Bearer $NERVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "limitUsd": 5.00,
    "action": "degrade",
    "degradeTo": "openai/gpt-4o-mini"
  }'

action options:

• degrade — switch to a cheaper model when limit is hit
• block — return 429 when limit is hit
• alert — continue but add X-Budget-Warning header

MCP audit log

Nerve logs every MCP tool call to mcp_audit table. Query via API:

curl "$NERVE_URL/api/mcp/status" \
  -H "Authorization: Bearer $NERVE_KEY"

Returns: server status, heartbeat, recent audit activity summary.

Errors

• 503 on health endpoint → Nerve is starting up; retry in 5s
• Circuit breaker OPEN → provider is temporarily blocked; check resetAt to know when it auto-recovers
• 429 budget_exceeded → budget guard limit reached; raise limit or wait for reset