> ## Documentation Index
> Fetch the complete documentation index at: https://www.stratus.run/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Health Check

> Check API health and model availability

## Overview

The `/health` endpoint provides real-time status information about the Stratus API, loaded models, LLM provider availability, and vault connectivity.

<Info>
  **No authentication required** - This endpoint is publicly accessible for monitoring and debugging.
</Info>

## Use Cases

<CardGroup cols={2}>
  <Card title="Monitoring" icon="heartbeat">
    Monitor API availability and model status
  </Card>

  <Card title="Service Discovery" icon="magnifying-glass">
    Discover available models and providers
  </Card>

  <Card title="Debugging" icon="bug">
    Troubleshoot connection and availability issues
  </Card>

  <Card title="Health Checks" icon="stethoscope">
    Integrate with load balancers and monitoring tools
  </Card>
</CardGroup>

## Request

No parameters required. Simple GET request:

```bash theme={null}
GET https://api.stratus.run/health
```

## Response

```json theme={null}
{
  "status": "healthy",
  "stratus_models_loaded": ["base"],
  "llm_providers": ["openai", "anthropic", "google", "openrouter"],
  "vault": "connected",
  "brain": {
    "loaded": true,
    "checkpoint": "/home/formation/stratus_checkpoints/policy_probe/policy_probe_v4_best.pt",
    "device": "cuda",
    "num_actions": 903,
    "random_baseline_nats": 6.8057,
    "sentence_transformers": true,
    "tool_matching": "sentence-transformers"
  },
  "version": "1.0.0",
  "git_sha": "2abf045f"
}
```

### Response Fields

<ResponseField name="status" type="string">
  Overall API health status. Returns `"healthy"` when the service is running.
</ResponseField>

<ResponseField name="stratus_models_loaded" type="string[]">
  Array of loaded Stratus world model sizes (e.g., `["base"]`).
</ResponseField>

<ResponseField name="llm_providers" type="string[]">
  Array of registered LLM provider names. Current providers: `openai`, `anthropic`, `google`, `openrouter`.
</ResponseField>

<ResponseField name="vault" type="string">
  Supabase Vault connection status for encrypted LLM key storage: `"connected"` or `"disabled"`.
</ResponseField>

<ResponseField name="brain" type="object">
  Policy head and world model status.

  <Expandable title="brain fields">
    <ResponseField name="brain.loaded" type="boolean">
      Whether the policy head checkpoint is loaded and ready.
    </ResponseField>

    <ResponseField name="brain.device" type="string">
      Compute device (`"cuda"` or `"cpu"`).
    </ResponseField>

    <ResponseField name="brain.num_actions" type="integer">
      Size of the action vocabulary (currently 903).
    </ResponseField>

    <ResponseField name="brain.sentence_transformers" type="boolean">
      Whether sentence-transformers is loaded for semantic tool matching.
    </ResponseField>

    <ResponseField name="brain.tool_matching" type="string">
      Tool matching strategy: `"sentence-transformers"` (semantic) or `"keyword"` (fallback).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="version" type="string">
  API version string.
</ResponseField>

<ResponseField name="git_sha" type="string">
  Git commit SHA of the deployed build.
</ResponseField>

## Status Interpretation

### Overall Status

| Status    | Meaning                 | Action           |
| --------- | ----------------------- | ---------------- |
| `healthy` | All systems operational | No action needed |

### Vault Status

| Status      | Meaning                                                             |
| ----------- | ------------------------------------------------------------------- |
| `connected` | LLM key management available                                        |
| `disabled`  | Vault not configured — `/v1/account/llm-keys` endpoints unavailable |

## Examples

### Check API Health

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.stratus.run/health
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.stratus.run/health');
  const health = await response.json();

  if (health.status === 'healthy') {
    console.log('API is healthy');
    console.log('Loaded models:', health.stratus_models_loaded);
    console.log('Providers:', health.llm_providers);
  } else {
    console.warn('API status:', health.status);
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.get("https://api.stratus.run/health")
  health = response.json()

  if health['status'] == 'healthy':
      print('API is healthy')
      print(f"Loaded models: {health['stratus_models_loaded']}")
      print(f"Providers: {health['llm_providers']}")
  else:
      print(f"API status: {health['status']}")
  ```
</CodeGroup>

### Check Provider Registration

```typescript theme={null}
async function isProviderRegistered(provider: 'openai' | 'anthropic') {
  const response = await fetch('https://api.stratus.run/health');
  const health = await response.json();

  return (health.llm_providers as string[]).includes(provider);
}

// Use before making requests
const openaiAvailable = await isProviderRegistered('openai');
if (openaiAvailable) {
  // Proceed with OpenAI-based request
}
```

### Integration with Load Balancer

```python theme={null}
# Health check endpoint for Kubernetes/Docker
from flask import Flask, jsonify
import requests

app = Flask(__name__)

@app.route('/health')
def health_check():
    try:
        stratus_health = requests.get(
            "https://api.stratus.run/health",
            timeout=5
        ).json()

        if stratus_health['status'] == 'healthy':
            return jsonify({"status": "ok"}), 200
        else:
            return jsonify({"status": "degraded"}), 503
    except Exception as e:
        return jsonify({"status": "error", "message": str(e)}), 503
```

### Monitoring Dashboard

```typescript theme={null}
async function getHealthDashboard() {
  const response = await fetch('https://api.stratus.run/health');
  const health = await response.json();

  return {
    apiStatus: health.status,
    modelsLoaded: health.stratus_models_loaded as string[],
    providers: health.llm_providers as string[],
    vaultConnected: health.vault === 'connected',
    version: health.version
  };
}

// Display in UI
const dashboard = await getHealthDashboard();
console.log('Models loaded:', dashboard.modelsLoaded);
console.log('Providers:', dashboard.providers);
```

## Performance

| Metric           | Value                                |
| ---------------- | ------------------------------------ |
| **Latency**      | \<100ms (typically \~50ms)           |
| **Availability** | 99.9% uptime                         |
| **Rate Limit**   | No rate limit (public endpoint)      |
| **Caching**      | No caching recommended (live status) |

## Use in Production

### Health Check Polling

```typescript theme={null}
// Poll every 30 seconds
setInterval(async () => {
  try {
    const response = await fetch('https://api.stratus.run/health', {
      signal: AbortSignal.timeout(5000)
    });

    const health = await response.json();

    // Update internal status
    updateServiceStatus(health);

    // Alert if degraded
    if (health.status !== 'healthy') {
      alertOps('Stratus API degraded', health);
    }
  } catch (error) {
    alertOps('Stratus API unreachable', error);
  }
}, 30000);
```

### Circuit Breaker Pattern

```python theme={null}
import time
from enum import Enum

class CircuitState(Enum):
    CLOSED = "closed"
    OPEN = "open"
    HALF_OPEN = "half_open"

class StratusCircuitBreaker:
    def __init__(self, failure_threshold=3, timeout=60):
        self.state = CircuitState.CLOSED
        self.failures = 0
        self.failure_threshold = failure_threshold
        self.timeout = timeout
        self.last_failure_time = None

    def check_health(self):
        try:
            response = requests.get(
                "https://api.stratus.run/health",
                timeout=5
            )
            health = response.json()

            if health['status'] == 'healthy':
                self.on_success()
                return True
            else:
                self.on_failure()
                return False
        except:
            self.on_failure()
            return False

    def on_success(self):
        self.failures = 0
        self.state = CircuitState.CLOSED

    def on_failure(self):
        self.failures += 1
        self.last_failure_time = time.time()

        if self.failures >= self.failure_threshold:
            self.state = CircuitState.OPEN

    def can_request(self):
        if self.state == CircuitState.CLOSED:
            return True

        if self.state == CircuitState.OPEN:
            if time.time() - self.last_failure_time > self.timeout:
                self.state = CircuitState.HALF_OPEN
                return True
            return False

        # HALF_OPEN - try one request
        return True

# Usage
breaker = StratusCircuitBreaker()

if breaker.can_request() and breaker.check_health():
    # Make API request
    pass
else:
    # Use fallback
    pass
```

## Troubleshooting

### Endpoint Not Responding

**Symptoms:** Timeout or connection refused

**Possible Causes:**

* Network connectivity issues
* DNS resolution problems
* Firewall blocking HTTPS traffic

**Solution:**

```bash theme={null}
# Test connectivity
curl -v https://api.stratus.run/health

# Check DNS
nslookup api.stratus.run

# Check with different DNS
curl --dns-servers 8.8.8.8 https://api.stratus.run/health
```

### No Models Loaded

**Symptoms:** `stratus_models_loaded` is empty `[]`

**Meaning:** No Stratus world model is loaded — all chat/messages/rollout/embeddings requests will fail

**Action:**

1. Check `stratus_models_loaded` array
2. Contact support if models are not loading
3. Monitor for recovery

### Vault Disabled

**Symptoms:** `vault: "disabled"`

**Impact:** Cannot use `/v1/account/llm-keys` endpoints for encrypted key storage

**Workaround:** Pass LLM provider keys directly in requests (less secure but functional)

## Integration Examples

### With Prometheus

```python theme={null}
from prometheus_client import Gauge
import requests

stratus_health = Gauge('stratus_health', 'Stratus API health status', ['component'])

def collect_health_metrics():
    response = requests.get("https://api.stratus.run/health")
    health = response.json()

    # Overall status (1 = healthy, 0 = unhealthy)
    status_value = 1.0 if health['status'] == 'healthy' else 0.0
    stratus_health.labels(component='api').set(status_value)

    # Provider availability
    for provider in health['llm_providers']:
        stratus_health.labels(component=f'provider_{provider}').set(1.0)

    # Models loaded
    for model in health['stratus_models_loaded']:
        stratus_health.labels(component=f'model_{model}').set(1.0)
```

### With Datadog

```typescript theme={null}
import { StatsD } from 'node-dogstatsd';

const statsd = new StatsD();

async function reportHealthToDatadog() {
  const response = await fetch('https://api.stratus.run/health');
  const health = await response.json();

  // Send metrics
  statsd.gauge('stratus.health.status',
    health.status === 'healthy' ? 1 : 0
  );

  // Provider availability
  (health.llm_providers as string[]).forEach((provider) => {
    statsd.gauge(`stratus.provider.${provider}.available`, 1);
  });

  // Model availability
  (health.stratus_models_loaded as string[]).forEach((model) => {
    statsd.gauge(`stratus.model.${model}.loaded`, 1);
  });
}
```

## Related Endpoints

* [Models](/docs/api-reference/models) - List available model combinations
* [LLM Keys](/docs/api-reference/llm-keys) - Manage encrypted LLM keys (requires vault connection)

<Card title="Best Practices" icon="lightbulb">
  - Poll health endpoint every 30-60 seconds for production monitoring
  - Implement circuit breaker pattern to handle degraded states gracefully
  - Monitor vault connection if using LLM key management features
  - Set appropriate timeouts (5s recommended) to avoid blocking on health checks
</Card>