Full API Reference

All API responses follow the standard format:


{"success": true, "data": { ... }}
{"success": false, "error": "Description of what went wrong", "details": "err.Error()"}

Interactive API documentation is available at /docs/swagger (Swagger UI) and /docs/redoc (ReDoc). The raw OpenAPI spec is served at /api/v1/openapi.yaml.

Authentication

When authentication is enabled, all API endpoints (except /api/v1/auth/*) require either a session cookie or a Personal Access Token. Include a PAT as a Bearer token:


curl https://pilot.example.com/api/v1/cluster \
  -H "Authorization: Bearer pat_your_token_here"

Create tokens from the Pilot UI (user menu -> Access Tokens) or see Personal Access Tokens for details.

Health & Version

Method	Path	Description	License
`GET`	`/api/v1/health`	Liveness probe	No
`GET`	`/api/v1/ready`	Readiness probe (Kafka reachable)	No
`GET`	`/api/v1/version`	Version and build info	No
`GET`	`/api/v1/self-healing/status`	Self-healing loop status	No

Cluster

Method	Path	Description	License
`GET`	`/api/v1/cluster`	Basic cluster info	No
`GET`	`/api/v1/cluster/comprehensive`	Full cluster data (`?summary=true` to omit partition arrays)	No
`GET`	`/api/v1/cluster/logdirs`	Disk usage by broker (`?summary=true` for broker-level only)	No
`GET`	`/api/v1/cluster/health`	Broker and partition health	No
`GET`	`/api/v1/cluster/follower-lag`	Follower lag by cluster, broker, topic, partition	No
`POST`	`/api/v1/cluster/refresh-metadata`	Force metadata refresh	Yes

`GET /api/v1/cluster/follower-lag`

Returns follower replica offset lag aggregated at cluster, broker, topic, and partition levels. Useful for identifying brokers or topics where replication is falling behind.

Query parameters:

Parameter	Type	Default	Description
`topic`	string	-	Filter results to a single topic
`broker`	integer	-	Filter results to a single broker ID
`summary`	boolean	`false`	When `true`, returns only cluster-level and broker-level totals (omits topic and partition detail)

Response shape:


{
  "success": true,
  "data": {
    "cluster_total_lag": 4200,
    "cluster_max_lag": 850,
    "broker_lag": [
      { "broker_id": 1, "total_lag": 1200, "max_lag": 850, "replica_count": 45 },
      { "broker_id": 2, "total_lag": 1500, "max_lag": 600, "replica_count": 48 },
      { "broker_id": 3, "total_lag": 1500, "max_lag": 400, "replica_count": 47 }
    ],
    "topic_lag": [
      { "topic": "orders", "total_lag": 2000, "max_lag": 850, "partition_count": 12 }
    ],
    "partition_lag": [
      {
        "topic": "orders",
        "partition": 3,
        "replicas": [
          { "broker_id": 1, "offset_lag": 850, "is_leader": false },
          { "broker_id": 2, "offset_lag": 0, "is_leader": true }
        ]
      }
    ],
    "urp_classification": [
      {
        "topic": "orders",
        "partition": 7,
        "cause": "follower_lag",
        "lagging_brokers": [1]
      }
    ]
  }
}

When ?summary=true is used, the topic_lag, partition_lag, and urp_classification fields are omitted.

Partitions & Brokers

Method	Path	Description	License
`GET`	`/api/v1/partitions`	List partitions (`?minimal=true`, `?fields=f1,f2`)	No
`GET`	`/api/v1/brokers/racks`	Broker rack topology	No

Topics

Method	Path	Description	License
`GET`	`/api/v1/topics/{topic}/config`	Get topic configuration	No
`GET`	`/api/v1/topics/{topic}/config/explicit`	Get explicitly set config only	No
`PUT`	`/api/v1/topics/{topic}/config`	Update topic configuration	Yes
`PUT`	`/api/v1/topics/config/bulk`	Bulk update topic configuration	Yes
`GET`	`/api/v1/config/defaults`	Default broker configurations	No
`POST`	`/api/v1/topics/search`	Search topics by name	No

Proposals

Method	Path	Description	License
`POST`	`/api/v1/proposals/generate`	Generate a rebalancing proposal	No
`GET`	`/api/v1/proposals`	List stored proposals	No
`GET`	`/api/v1/proposals/{proposalId}`	Get proposal details	No
`POST`	`/api/v1/proposals/{proposalId}/apply`	Apply (execute) a proposal	Yes
`DELETE`	`/api/v1/proposals/{proposalId}`	Delete a proposal	No

Reassignments

Method	Path	Description	License
`POST`	`/api/v1/topics/{topic}/redistribute`	Redistribute all partitions of a topic	Yes
`POST`	`/api/v1/topics/{topic}/partitions/{partition}/redistribute`	Reassign a single partition	Yes
`POST`	`/api/v1/topics/{topic}/partitions/bulk`	Bulk reassignment	Yes
`POST`	`/api/v1/preferred-leader-election`	Cluster-wide preferred leader election	Yes
`POST`	`/api/v1/topics/{topic}/preferred-leader-election`	Topic-specific preferred leader election	Yes

Broker Maintenance

Method	Path	Description	License
`POST`	`/api/v1/brokers/{brokerId}/maintenance`	Enter maintenance mode	Yes
`DELETE`	`/api/v1/brokers/{brokerId}/maintenance`	Exit maintenance mode	Yes
`POST`	`/api/v1/brokers/{brokerId}/logdirs/move`	Move log directories	Yes

What-If & Simulation

Method	Path	Description	License
`POST`	`/api/v1/what-if/simulate`	Simulate cluster scenarios	No
`POST`	`/api/v1/blast-radius/analyze`	Analyze failure blast radius	No

Optimization

Method	Path	Description	License
`GET`	`/api/v1/optimize/partitions`	Partition count optimization recommendations	No

Consumer Groups

Method	Path	Description	License
`GET`	`/api/v1/consumer-groups`	List consumer groups	No
`GET`	`/api/v1/consumer-groups/summary`	Aggregated statistics	No
`GET`	`/api/v1/consumer-groups/{group}`	Group details with members	No
`GET`	`/api/v1/consumer-groups/{group}/lag`	Per-partition lag	No
`POST`	`/api/v1/consumer-groups/{group}/reset-offsets`	Reset consumer offsets	Yes
`DELETE`	`/api/v1/consumer-groups/{group}`	Delete a consumer group	Yes

Quotas

List & Analysis

Method	Path	Description	License
`GET`	`/api/v1/quotas`	List all quotas	No
`POST`	`/api/v1/quotas/resolve`	Resolve effective quotas	No

Entity-Specific CRUD

Each entity type supports GET (free), PUT (licensed), and DELETE (licensed):

Entity	Path
Default	`/api/v1/quotas/default`
Default User	`/api/v1/quotas/default-user`
Default Client ID	`/api/v1/quotas/default-client-id`
User	`/api/v1/quotas/user/{user}`
Client ID	`/api/v1/quotas/client-id/{clientId}`
User + Client ID	`/api/v1/quotas/user/{user}/{clientId}`

ACLs

Method	Path	Description	License
`GET`	`/api/v1/acls`	List ACL bindings	No
`POST`	`/api/v1/acls`	Create ACL bindings	Yes
`PUT`	`/api/v1/acls`	Update ACL bindings	Yes
`DELETE`	`/api/v1/acls`	Delete ACL bindings	Yes

Messages

Method	Path	Description	License
`GET`	`/api/v1/topics/{topic}/messages/tail`	Stream new messages over SSE	No
`GET`	`/api/v1/topics/{topic}/messages`	Fetch message range	No
`GET`	`/api/v1/topics/{topic}/messages/{partition}/{offset}`	Get single message	No
`GET`	`/api/v1/topics/{topic}/watermarks`	Partition watermarks	No

Audit Log

Method	Path	Description	License
`GET`	`/api/v1/audit-log`	List audit events (filterable by action, user, time, search)	No
`POST`	`/api/v1/audit-log/revert/preview`	Review reversal of a stored reassignment event against current placement	No
`POST`	`/api/v1/audit-log/revert`	Submit reversal of a supported audited action	Yes

Reassignment reversals require the stored event selector and a fresh review fingerprint. A nonempty reversal returns 202 with an executionId; acceptance does not mean the partitions have finished moving. See Audit Logging for supported actions and offset-reset limitations.

Chat

Available when PILOT_CHAT_ENABLED=true.

Method	Path	Description	License
`GET`	`/api/v1/chat/status`	Chat availability status	No
`POST`	`/api/v1/chat/conversations`	Create a conversation	No
`GET`	`/api/v1/chat/conversations`	List conversations	No
`GET`	`/api/v1/chat/conversations/{id}`	Get conversation with messages	No
`DELETE`	`/api/v1/chat/conversations/{id}`	Delete a conversation	No
`POST`	`/api/v1/chat/conversations/{id}/messages`	Send message (SSE streaming response)	No
`POST`	`/api/v1/chat/conversations/{id}/approve/{toolCallId}`	Approve pending mutation	No
`POST`	`/api/v1/chat/conversations/{id}/reject/{toolCallId}`	Reject pending mutation	No

Authentication

Available when authentication is configured.

Method	Path	Description	License
`GET`	`/api/v1/auth/providers`	List configured OAuth providers	No
`GET`	`/api/v1/auth/login/{provider}`	Initiate OAuth login flow	No
`GET`	`/api/v1/auth/callback/{provider}`	OAuth callback	No
`GET`	`/api/v1/auth/me`	Current authenticated user	No
`POST`	`/api/v1/auth/logout`	End session	No
`POST`	`/api/v1/auth/refresh`	Refresh access token	No

Access Tokens

Available when authentication is configured. Requires an OAuth session (PATs cannot manage other PATs).

Method	Path	Description	License
`GET`	`/api/v1/tokens`	List current user’s tokens	No
`POST`	`/api/v1/tokens`	Create a new personal access token	No
`DELETE`	`/api/v1/tokens/{tokenId}`	Revoke a token	No

MCP (Model Context Protocol)

Streamable HTTP transport for AI tool integrations (GitHub Copilot, Warp, Claude Desktop).

Method	Path	Description	License
`POST`	`/api/v1/mcp`	MCP Streamable HTTP endpoint	No

When authentication is enabled, include a PAT as a Bearer token in the Authorization header. See MCP - Authentication for client configuration examples.

License & Notices

Method	Path	Description	License
`GET`	`/api/v1/license`	License status and validation	No
`GET`	`/api/v1/third-party-notices`	Third-party license notices	No

Metrics

Method	Path	Description
`GET`	`/metrics`	Prometheus metrics

Static Assets

Path	Description
`/ui`	Pilot dashboard (embedded React UI)
`/docs/swagger`	Swagger UI
`/docs/redoc`	ReDoc UI
`/api/v1/openapi.yaml`	OpenAPI spec (YAML)
`/api/v1/openapi.json`	OpenAPI spec (JSON)