Health API

The Health API provides unauthenticated endpoints for monitoring server status and bundle health. Use these endpoints in load balancer health checks, monitoring dashboards, and alerting systems.

Note

Both health endpoints are unauthenticated. They work regardless of whether NB_API_KEY is set.

GET /v1/health

Check overall server health and get a summary of bundle states.

Response:

{
  "status": "ok",
  "uptime": 3600,
  "bundles": [
    { "name": "bash", "state": "running" },
    { "name": "weather", "state": "running" },
    { "name": "postgres", "state": "crashed" }
  ]
}

Field	Type	Description
status	string	Always "ok" if the server is responding
uptime	number	Server uptime in seconds
bundles	array	Summary of each bundle’s name and state

Each bundle entry:

Field	Type	Description
name	string	Short server name
state	string	Lifecycle state: starting, running, crashed, dead, stopped

Example:

curl

curl http://localhost:27247/v1/health

Response

{
  "status": "ok",
  "uptime": 3600,
  "bundles": [
    { "name": "bash", "state": "running" },
    { "name": "weather", "state": "running" }
  ]
}

GET /v1/bundles/health

Get detailed health information for each installed bundle, including uptime and restart count. Use this endpoint when you need more detail than GET /v1/health provides.

Response:

[
  {
    "name": "bash",
    "state": "running",
    "uptime": 3600,
    "restartCount": 0
  },
  {
    "name": "weather",
    "state": "running",
    "uptime": 3580,
    "restartCount": 0
  },
  {
    "name": "postgres",
    "state": "crashed",
    "uptime": 0,
    "restartCount": 3
  }
]

Each entry:

Field	Type	Description
name	string	Short server name
state	string	Lifecycle state: starting, running, crashed, dead, stopped
uptime	number	Seconds since the bundle last started (0 if not running)
restartCount	number	Number of times the bundle has been restarted due to crashes

Example:

curl

curl http://localhost:27247/v1/bundles/health

Response

[
  {
    "name": "bash",
    "state": "running",
    "uptime": 3600,
    "restartCount": 0
  }
]

Health Check Patterns

Load Balancer

Use GET /v1/health as a lightweight liveness probe:

# Returns 200 if the server is running
curl -f http://localhost:27247/v1/health

Kubernetes

Configure liveness and readiness probes:

livenessProbe:
  httpGet:
    path: /v1/health
    port: 27247
  initialDelaySeconds: 5
  periodSeconds: 30
readinessProbe:
  httpGet:
    path: /v1/health
    port: 27247
  initialDelaySeconds: 3
  periodSeconds: 10

Monitoring

Poll GET /v1/bundles/health to track bundle stability over time. A high restartCount or persistent crashed/dead states indicate bundles that need attention.