---
title: "Full API Reference - Pilot Docs"
description: "Complete Pilot API endpoint reference"
url: "https://docs.calinora.io/api/reference/"
---

# Full API Reference

All API responses follow the standard format:

```json
{"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:

```bash
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](https://docs.calinora.io/configuration/authentication/#personal-access-tokens-pats) 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:**

```json
{
  "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](https://docs.calinora.io/configuration/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](https://docs.calinora.io/features/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) |