kubegraf — TypeScript/JavaScript client for the KubeGraf API

Official, dependency-free client for the KubeGraf API. Read your workspace's incidents and Agent Fleet, and run metered AI investigations. Fully typed — the types are generated from the OpenAPI spec, so the client can never drift from the contract.

KubeGraf is a paid subscription product. Authenticate with a workspace-scoped subscription API key (kgkey_…); usage counts against your plan and AI paths run on KubeGraf-managed infrastructure — never BYOK.

Install

npm install kubegraf

Requires Node ≥ 18 (uses the global fetch). No runtime dependencies.

Usage

import { KubeGraf, KubeGrafError } from "kubegraf";

const kg = new KubeGraf({ apiKey: process.env.KUBEGRAF_API_KEY! });

// Incidents (status: "open" | "acknowledged" | "resolved" | "false_positive")
const { incidents } = await kg.incidents.list({ status: "open", limit: 20 });
for (const inc of incidents ?? []) console.log(inc.id, inc.severity, inc.title);

// Agent Fleet
const { clusters } = await kg.clusters.list();
for (const c of clusters ?? []) console.log(c.name, c.status, c.nodes, c.pods);

// AI investigation (metered; requires a key with the `write` scope)
try {
  const res = await kg.investigations.start({ incident_id: "inc_123", mode: "deep" });
  console.log(res.analysis?.root_cause);
} catch (e) {
  if (e instanceof KubeGrafError) console.error(e.status, e.code, e.message);
}

Self-hosted

Point baseUrl at your install's host:

const kg = new KubeGraf({ apiKey: "kgkey_…", baseUrl: "https://kubegraf.your-company.com" });

Errors

Every non-2xx response throws KubeGrafError with .status (HTTP code, 0 for network/timeout), .code (machine-readable), and .detail (parsed body). 402 = plan quota exhausted / subscription inactive; 429 = rate limited.

Development

npm run generate   # regenerate src/schema.ts from ../openapi/openapi.yaml
npm run build      # tsc → dist/