KafkaGuard
Get started
FeaturesDocsEnterprisePricingBlogToolsGet started

API Reference

Complete REST API reference for the KafkaGuard On-Prem platform (v2.3.0). The API is available when running the on-prem stack.

Base URL: http://<your-host>:3001 (or https://<your-host> when behind nginx TLS)

Authentication

The API supports two authentication methods:

JWT Bearer Token

Obtain a token via POST /auth/login. Pass it as Authorization: Bearer <token>.

TOKEN=$(curl -s -X POST http://kafkaguard:3001/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@company.com","password":"your-password"}' \
  | jq -r '.token')

API Key (x-api-key header)

Create API keys in the dashboard under API Keys. Pass them as x-api-key: <key>. Required for CLI --upload and report generate --api.

curl -H "x-api-key: kg_onprem_abc123..." http://kafkaguard:3001/api/v1/scans

Scan Endpoints

List Scans

GET /api/v1/scans

Returns paginated scan history for the authenticated org.

Auth: Bearer JWT or API key

Response:

{
  "data": [
    {
      "id": "ea8a9a77-...",
      "cluster_id": "b647376d-...",
      "cluster_name": "prod-us",
      "score": 64,
      "status": "complete",
      "scanned_at": "2026-04-25T00:26:44Z",
      "policy_tier": "enterprise-default"
    }
  ],
  "total": 3
}

Get Scan Detail

GET /api/v1/scans/:id

Returns full scan result including findings.

Auth: Bearer JWT or API key

Get Raw Scan JSON

GET /api/v1/scans/:id/raw

Streams the MinIO-stored scan JSON blob — the exact output produced by the CLI scanner. Use this for kafkaguard report generate --scan-id.

Auth: Bearer JWT or API key

Security: Returns 404 for both unknown scan IDs and scan IDs belonging to other orgs (prevents enumeration).

Response: application/json — full ScanReport structure

kafkaguard report generate \
  --scan-id ea8a9a77-... \
  --api http://kafkaguard:3001 \
  --api-key $KAFKAGUARD_API_KEY \
  --format pdf \
  --output /tmp

Delete Scan

DELETE /api/v1/scans/:id

Deletes a scan and its stored JSON from MinIO.

Auth: Bearer JWT (admin role)

Ingest Scan (CLI Upload)

POST /api/v1/ingest

Accepts scan JSON from the CLI --upload flag. Creates the cluster record if it doesn't exist.

Auth: API key (x-api-key header)

Body: Scan JSON payload (same structure as scan-*.json output files)

kafkaguard scan \
  --bootstrap kafka:9092 \
  --upload http://kafkaguard:3001

Set KAFKAGUARD_API_KEY env var or the scan will fail with a 401.

Cluster Endpoints

List Clusters

GET /api/v1/clusters

Returns all clusters registered for the authenticated org.

Auth: Bearer JWT or API key

Response:

{
  "data": [
    {
      "id": "b647376d-...",
      "name": "prod-us",
      "bootstrap_servers": "kafka1:9092,kafka2:9092",
      "last_scan_at": "2026-04-25T00:26:44Z",
      "last_score": 64
    }
  ],
  "total": 1
}

Get Cluster Detail

GET /api/v1/clusters/:id

Returns cluster metadata and recent scan summary.

Auth: Bearer JWT or API key

Update Cluster

PATCH /api/v1/clusters/:id

Update cluster display name or metadata.

Auth: Bearer JWT

Body:

{ "name": "prod-us-east" }

Trend Endpoints

Available from v2.3.0. Powers the /dashboard/trends and /dashboard/compare pages.

Cluster Timeline

GET /api/v1/trends/:clusterId?period=90d

Returns compliance score time series for a single cluster.

Auth: Bearer JWT or API key

Query params:

ParamValuesDefaultDescription
period7d, 30d, 90d, 1y90dTime window

Response:

[
  { "scan_id": "ea8a9a77-...", "scanned_at": "2026-04-25T00:26:38Z", "score": 64 },
  { "scan_id": "c9fc5aa3-...", "scanned_at": "2026-04-25T00:26:41Z", "score": 64 }
]

Fleet Comparison

GET /api/v1/trends/compare?period=30d

Returns one summary record per cluster for the authenticated org — used by the Compare page fleet grid.

Auth: Bearer JWT or API key

Query params:

ParamValuesDefaultDescription
period7d, 30d, 90d, 1y30dTime window for sparkline and delta calculation

Response:

[
  {
    "cluster_id": "b647376d-...",
    "name": "prod-us",
    "current_score": 64,
    "delta_pct": -5,
    "last_scanned_at": "2026-04-25T00:26:44Z",
    "sparkline": [69, 67, 64]
  }
]

delta_pct is the raw score change (e.g. -5 = dropped 5 points) from the first scan in the period to the most recent.

API Key Endpoints

List API Keys

GET /api/v1/api-keys

Auth: Bearer JWT

Create API Key

POST /api/v1/api-keys

Auth: Bearer JWT

Body:

{ "label": "ci-pipeline" }

Response:

{
  "data": {
    "id": "7ea7ba67-...",
    "key": "kg_onprem_8b54135051da4897...",
    "label": "ci-pipeline"
  },
  "message": "Save this key — it will not be shown again"
}

Delete API Key

DELETE /api/v1/api-keys/:id

Auth: Bearer JWT

Health

GET /health/services

Returns status of all backing services. No authentication required.

Response:

{
  "postgres": { "status": "up", "latency": 7 },
  "redis":    { "status": "up", "latency": 3 },
  "minio":    { "status": "up", "latency": 12 },
  "worker":   { "status": "up", "latency": 0 }
}

Error Responses

All errors follow the same JSON shape:

{ "error": "scan not found", "statusCode": 404 }
StatusMeaning
400Bad request — invalid parameters
401Unauthenticated — missing or invalid token/key
403Forbidden — valid auth but insufficient role
404Resource not found (or cross-org access — same response to prevent enumeration)
409Conflict — resource already exists
500Internal server error — check server logs

Next Steps