AgentsIQ
Kafka Analyser ▾
Kafka Analyser Overview API Reference

📚 Kafka Analyser API Reference

REST API endpoints for Kafka cluster monitoring, analysis and configuration

v1.1.0 Port 8003 FastAPI Base URL: http://<host>:8003

Authentication

All endpoints require: X-API-Key: <BACKEND_API_KEY> header

The backend orchestrator injects the Anthropic API key per-request; agents never store secrets.

Health & Chat

GET /health
Agent health check. Used by backend registry to verify agent is running.
Response
{ "status": "ok", "agent": "kafka-analyser", "version": "0.1.0" }
Example
curl -X GET http://localhost:8003/health
POST /invoke
Chat invoke (non-streaming). Runs Claude tool-use loop for question answering.
Request Body
session_id (string) — Chat session ID for history tracking
user_message (string) — User question or command
context (object) — Query context (optional)
  • cluster_id — ID of target cluster (optional)
  • has_data — Boolean flag if cluster has loaded data
Response
response — Claude's text response
metadata.tokens_used — Token count for billing
chart (object, optional) — Chart data if response includes visualization
Example
curl -X POST http://localhost:8003/invoke \ -H "X-API-Key: your-api-key" \ -H "Content-Type: application/json" \ -d '{ "session_id": "abc123", "user_message": "What is the consumer lag trend?", "context": {"cluster_id": 1, "has_data": true} }'
POST /invoke/stream
Streaming chat invoke. Response is SSE (Server-Sent Events) stream of text chunks.
Request Body
Same as /invoke
Response
SSE stream of chunks ending with [DONE]

Dashboard Overview

GET /dashboard/overview
Cluster health overview with broker counts, topic metrics, and anomaly summary.
Query Parameters
cluster_id (integer, optional) — Cluster to query (uses first if not provided)
Response
cluster — Cluster metadata (name, health_score, broker/topic/partition counts, URP count)
brokers — Array of broker summaries
anomaly_count — Total active anomalies
critical_count — Critical severity anomalies
warning_count — Warning severity anomalies
GET /dashboard/counts
Alert and anomaly counts summary for quick KPI rendering.
Response
total_brokers — Total brokers in cluster
active_brokers — Currently healthy brokers
total_topics — Topic count
total_consumer_groups — Consumer group count
active_anomalies — Unresolved anomalies
critical_anomalies — Critical severity count

Dashboard Metrics

GET /dashboard/brokers
Per-broker metrics sorted by broker ID.
Query Parameters
cluster_id (integer) — Cluster to query
Response
Array of broker objects with: broker_id, cpu_pct, heap_pct, gc_pause_ms, request_handler_idle_pct, urp_count, messages_in_per_sec, disk_pct
GET /dashboard/consumer-groups
Consumer group lag analysis sorted worst-first.
Query Parameters
cluster_id (integer) — Cluster to query
Response
Array of groups with: group_name, total_lag, lag_trend (growing|stable|recovering), lag_rate_per_min, state, topics subscribed
GET /dashboard/topics
Topic metrics sorted by message rate (throughput worst-first).
Query Parameters
cluster_id (integer) — Cluster to query
Response
Array of topics with: topic name, partition/replication counts, messages_in_per_sec, bytes in/out per sec, retention_pct, size_bytes
GET /dashboard/topics/detail
Detailed topic view with historical metrics.
Query Parameters
cluster_id (integer) — Cluster ID
topic (string) — Topic name
Response
topic — Topic name
metrics — Current metrics snapshot
history — Time-series history (last 24 hours)

Kafka Ecosystem

GET /dashboard/connectors
KafkaConnect connector status and task health.
Query Parameters
cluster_id (integer) — Cluster to query
Response
Array of connectors with: connector_name, connector_type (source/sink), state (running/failed/paused), failed_tasks, total_tasks
GET /dashboard/schema-registry
Schema Registry subjects and version tracking.
Query Parameters
cluster_id (integer) — Cluster to query
Response
subjects — Array of {subject, version, compatibility level}
GET /dashboard/zookeeper
ZooKeeper cluster health and leader status.
Query Parameters
cluster_id (integer) — Cluster to query
Response
status — healthy | degraded | down
leader — Current leader node
followers — List of follower nodes
outstanding_requests — Pending requests count
avg_latency_ms — Average request latency
GET /dashboard/kafka-connect
KafkaConnect cluster info and connector status.
Query Parameters
cluster_id (integer) — Cluster to query
Response
version — KafkaConnect version
commit — Git commit hash
kafka_cluster_id — Cluster UUID
connectors — List of running connectors
GET /dashboard/mirrormaker
MirrorMaker cross-cluster replication status.
Query Parameters
cluster_id (integer) — Cluster to query
Response
source_cluster — Source cluster name
target_cluster — Target cluster name
replication_lag — Lag in messages
mirror_mode — active | passive
topics_mirrored — Count of replicated topics

AI Insights & Trends

GET /dashboard/insights
AI-generated cluster insights and detected anomalies.
Query Parameters
cluster_id (integer) — Cluster to analyze
Response
insights — Array of Claude-generated insights
anomalies — Array of {severity, category, description, detected_at, resolved_at}
GET /dashboard/overview/lag-trend
Consumer lag trend over time window.
Query Parameters
cluster_id (integer) — Cluster to query
window_minutes (integer, default 60) — History window
Response
data_points — Array of {timestamp, total_lag, groups_growing}
GET /dashboard/topics/history
Topic throughput history over time period.
Query Parameters
cluster_id (integer) — Cluster ID
topic (string) — Topic name
hours (integer, default 24) — History depth
Response
topic — Topic name
history — Array of {hour_bucket, avg_msgs, max_msgs}

Search & Discovery

GET /dashboard/topics/search
Search topics by name pattern.
Query Parameters
cluster_id (integer) — Cluster to search
q (string) — Search term (partial match)
Response
topics — Array of matching topics with partition_count, messages_in_per_sec
GET /dashboard/groups/search
Search consumer groups by name pattern.
Query Parameters
cluster_id (integer) — Cluster to search
q (string) — Search term (partial match)
Response
groups — Array of matching groups with total_lag, state

Settings & Configuration

GET /settings
Get current cluster configuration.
Response
clusters — Array of configured clusters with id, name, environment, source_type, bootstrap_servers, enabled, status
POST /settings/clusters
Add or update a Kafka cluster connection.
Request Body
name (string) — Display name
environment (string) — prod, staging, dev
source_type (string) — synthetic, real, prometheus
bootstrap_servers (string) — Kafka bootstrap address(es)
auth_type (string) — none, sasl, tls
sasl_username (string, optional) — SASL credentials
sasl_password (string, optional) — SASL credentials (encrypted)
tls_enabled (boolean) — TLS encryption
schema_registry_url (string, optional) — Schema Registry endpoint
zookeeper_url (string, optional) — ZooKeeper endpoint
kafka_connect_url (string, optional) — KafkaConnect endpoint
Response
ok — Boolean success
cluster_id — ID of created/updated cluster
DELETE /settings/clusters/{cluster_id}
Remove a cluster connection.
Response
ok — Boolean success
deleted — Cluster ID that was removed
POST /settings/clusters/{cluster_id}/test
Test cluster connectivity and collect basic info.
Response
ok — Boolean success (connection works)
latency_ms — Round-trip time to broker
broker_count — Number of brokers discovered
kafka_version — Kafka broker version
POST /settings/generate-synthetic
Generate synthetic cluster data for demo and testing.
Request Body
broker_count (integer, default 3) — Number of brokers
topic_count (integer, default 10) — Number of topics
consumer_groups (integer, default 5) — Consumer groups to create
Response
ok — Boolean success
cluster_id — ID of synthetic cluster
brokers — Count created
topics — Count created
consumer_groups — Count created

HTTP Status Codes

  • 200 OK — Request succeeded
  • 202 Accepted — Async operation accepted (future enhancement)
  • 400 Bad Request — Invalid parameters or malformed request
  • 401 Unauthorized — Missing or invalid X-API-Key header
  • 404 Not Found — Resource not found (cluster, topic, group)
  • 500 Internal Server Error — Server error or Kafka connectivity issue