HolmesGPT HTTP API Reference

HolmesGPT HTTP API Reference

REST API documentation for HolmesGPT server deployments.

Overview

HolmesGPT provides a REST API for programmatic access when deployed in Kubernetes. The API supports both synchronous requests and Server-Sent Events (SSE) for streaming responses.

Base URL

After Helm installation:

http://holmesgpt-holmes.<namespace>.svc.cluster.local

For local testing:

kubectl port-forward -n holmesgpt svc/holmesgpt-holmes 8080:80
# Base URL: http://localhost:8080

Endpoints

GET /api/model

List available AI models.

Request:

curl http://localhost:8080/api/model

Response:

{
  "models": ["sonnet", "opus", "gpt4", "gpt4o"]
}

POST /api/chat

General-purpose conversational interface.

Request:

curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "ask": "what pods are unhealthy in production namespace?",
    "model": "sonnet",
    "conversation_history": [],
    "include_tool_calls": true
  }'

Parameters:

Response:

{
  "analysis": "Based on my investigation...",
  "sections": {
    "alert_explanation": "...",
    "key_findings": "...",
    "root_causes": "...",
    "next_steps": "..."
  },
  "conversation_history": [...],
  "tool_calls": [...],
  "metadata": {
    "token_count": 1500,
    "model": "sonnet"
  }
}

POST /api/investigate

Automated incident investigation.

Request:

curl -X POST http://localhost:8080/api/investigate \
  -H "Content-Type: application/json" \
  -d '{
    "alert_name": "KubePodCrashLooping",
    "alert_labels": {
      "namespace": "production",
      "pod": "api-gateway-xxx"
    },
    "model": "sonnet"
  }'

Parameters:

Response:

{
  "analysis": "Investigation complete...",
  "sections": {
    "alert_explanation": "This alert fires when...",
    "key_findings": "1. Pod restarted 5 times...",
    "root_causes": "Memory limit exceeded...",
    "next_steps": "1. Increase memory limits..."
  },
  "tool_calls": [
    {
      "tool": "kubectl_get_pods",
      "parameters": {"namespace": "production"},
      "result": "...",
      "status": "success"
    }
  ]
}

POST /api/stream/investigate

Streaming investigation with SSE.

Request:

curl -X POST http://localhost:8080/api/stream/investigate \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "alert_name": "HighMemoryUsage",
    "model": "sonnet"
  }'

SSE Event Types:

Example SSE Stream:

event: start_tool_calling
data: {"tool": "kubectl_get_pods"}

event: tool_calling_result
data: {"tool": "kubectl_get_pods", "status": "success", "result": "..."}

event: ai_message
data: {"content": "I found several issues..."}

event: ai_answer_end
data: {"analysis": "...", "sections": {...}}

POST /api/issue_chat

Discuss specific issues with context.

Request:

curl -X POST http://localhost:8080/api/issue_chat \
  -H "Content-Type: application/json" \
  -d '{
    "ask": "what are the next steps?",
    "model": "sonnet",
    "issue_context": {
      "previous_analysis": "Memory limit issue identified...",
      "alert_name": "KubePodCrashLooping"
    },
    "conversation_history": [...]
  }'

POST /api/workload_health_check

Kubernetes workload health analysis.

Request:

curl -X POST http://localhost:8080/api/workload_health_check \
  -H "Content-Type: application/json" \
  -d '{
    "workload_name": "api-gateway",
    "workload_type": "Deployment",
    "namespace": "production",
    "model": "sonnet",
    "include_alert_history": true
  }'

Parameters:

POST /api/workload_health_chat

Conversational workload health discussion.

Request:

curl -X POST http://localhost:8080/api/workload_health_chat \
  -H "Content-Type: application/json" \
  -d '{
    "ask": "why is memory usage increasing?",
    "workload_name": "api-gateway",
    "namespace": "production",
    "model": "sonnet",
    "conversation_history": [...]
  }'

Response Structure

Standard Response

{
  "analysis": "Full text analysis...",
  "sections": {
    "alert_explanation": "Explanation of the alert/issue",
    "key_findings": "Important discoveries",
    "root_causes": "Identified root causes",
    "next_steps": "Recommended actions"
  },
  "conversation_history": [
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."}
  ],
  "tool_calls": [
    {
      "tool": "tool_name",
      "parameters": {"param": "value"},
      "result": "output",
      "status": "success"
    }
  ],
  "metadata": {
    "token_count": 1500,
    "context_window_used": 0.3,
    "truncated": false,
    "model": "sonnet"
  }
}

Error Response

{
  "error": "error_code",
  "message": "Human-readable error message",
  "details": {
    "field": "additional info"
  }
}

Error Codes

Authentication

By default, the API has no authentication. For production, add authentication via:

Kubernetes NetworkPolicy

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: holmesgpt-api
  namespace: holmesgpt
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: holmes
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              name: allowed-namespace

Ingress with Authentication

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: holmesgpt
  annotations:
    nginx.ingress.kubernetes.io/auth-type: basic
    nginx.ingress.kubernetes.io/auth-secret: holmesgpt-auth
spec:
  rules:
    - host: holmesgpt.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: holmesgpt-holmes
                port:
                  number: 80

Rate Limiting

AI Provider Rate Limits

HolmesGPT API responses are subject to the rate limits of the underlying AI provider. When limits are exceeded, the API returns a rate_limited error:

{
  "error": "rate_limited",
  "message": "AI provider rate limit exceeded. Retry after 60 seconds.",
  "details": {
    "provider": "anthropic",
    "retry_after_seconds": 60
  }
}

Client-Side Rate Limiting

For production deployments, implement client-side rate limiting:

Python Example:

import time
from functools import wraps

def rate_limit(max_calls: int, period: int):
    """Decorator to rate limit API calls."""
    calls = []
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            now = time.time()
            # Remove old calls outside the period
            calls[:] = [c for c in calls if now - c < period]
            if len(calls) >= max_calls:
                sleep_time = period - (now - calls[0])
                time.sleep(sleep_time)
            calls.append(time.time())
            return func(*args, **kwargs)
        return wrapper
    return decorator

@rate_limit(max_calls=10, period=60)  # 10 calls per minute
def ask_holmes(question: str) -> dict:
    # API call implementation
    pass

Kubernetes-Level Rate Limiting

Use Ingress annotations for cluster-level rate limiting:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: holmesgpt
  annotations:
    nginx.ingress.kubernetes.io/limit-rps: "10"
    nginx.ingress.kubernetes.io/limit-connections: "5"
    nginx.ingress.kubernetes.io/limit-burst-multiplier: "2"

Recommended Limits by Use Case

Usage Examples

Python Client

import requests

HOLMES_URL = "http://localhost:8080"

def ask_holmes(question: str, model: str = "sonnet") -> dict:
    response = requests.post(
        f"{HOLMES_URL}/api/chat",
        json={
            "ask": question,
            "model": model,
            "include_tool_calls": True
        }
    )
    response.raise_for_status()
    return response.json()

def investigate_alert(alert_name: str, labels: dict) -> dict:
    response = requests.post(
        f"{HOLMES_URL}/api/investigate",
        json={
            "alert_name": alert_name,
            "alert_labels": labels,
            "model": "sonnet"
        }
    )
    response.raise_for_status()
    return response.json()

# Usage
result = ask_holmes("what pods are crashing?")
print(result["analysis"])

JavaScript/Node.js Client

const axios = require('axios');

const HOLMES_URL = 'http://localhost:8080';

async function askHolmes(question, model = 'sonnet') {
  const response = await axios.post(`${HOLMES_URL}/api/chat`, {
    ask: question,
    model: model,
    include_tool_calls: true
  });
  return response.data;
}

async function streamInvestigation(alertName) {
  const response = await fetch(`${HOLMES_URL}/api/stream/investigate`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'text/event-stream'
    },
    body: JSON.stringify({
      alert_name: alertName,
      model: 'sonnet'
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    console.log(decoder.decode(value));
  }
}

// Usage
askHolmes('check cluster health').then(console.log);

Curl Examples

# Basic chat
curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{"ask": "list unhealthy pods", "model": "sonnet"}'

# With conversation history
curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "ask": "tell me more about the first one",
    "model": "sonnet",
    "conversation_history": [
      {"role": "user", "content": "list unhealthy pods"},
      {"role": "assistant", "content": "Found 3 unhealthy pods..."}
    ]
  }'

# Workload health check
curl -X POST http://localhost:8080/api/workload_health_check \
  -H "Content-Type: application/json" \
  -d '{
    "workload_name": "nginx",
    "workload_type": "Deployment",
    "namespace": "default",
    "model": "sonnet"
  }'