Admin API

The Admin API is an HTTP server built into the control plane that provides inspection, querying, and management endpoints. It serves as the backend for the Nantian Gateway dashboard and exposes a JSON API that operators can use directly for scripting and automation.

The server listens on the address configured by adminAddr (default :18081). It supports optional TLS and bearer token authentication.

Security model

The Admin API has two authentication levels:

• none: No authentication required. Used for /livez and /readyz health probes.
• bearer-when-configured: If a bearer token is configured (via adminAuth.bearerToken or adminAuth.bearerTokenFile), requests must include an Authorization: Bearer <token> header. If no token is configured, these endpoints are open.

The bearer token is resolved at startup. If resolution fails, the control plane refuses to start. This ensures you don’t accidentally run an unauthenticated admin API when you intended to secure it.

Caution

The Admin API provides full read access to your gateway configuration, including secrets, backend addresses, and route details. Never expose adminAddr to external networks without TLS and authentication. See TLS / mTLS for configuration details.

Endpoint reference

Health probes

GET /livez

Returns 200 OK with ok if the server is running. Used by Kubernetes liveness probes.

Auth: none Response: text/plain

ok

GET /readyz

Returns 200 OK with ok if the server is ready. Readiness is determined by the configured readinessMode:

• gate (default): Ready when the startup gate is open (all components started)
• snapshot: Ready when the startup gate is open and at least one snapshot has been published
• nodes: Ready when the startup gate is open, at least one snapshot has been published, and at least one data plane node is connected

Auth: none Response: text/plain

ok

Snapshot and configuration

GET /v1/summary

Returns a high-level summary of the current gateway state.

Auth: bearer-when-configured Response: application/json

{
  "snapshotVersion": "abc123def456",
  "generatedAt": "2026-06-06T12:00:00Z",
  "listenerCount": 4,
  "httpRouteCount": 12,
  "grpcRouteCount": 2,
  "streamRouteCount": 1,
  "routeCount": 15,
  "backendCount": 8,
  "secretCount": 5,
  "nodeCount": 3,
  "connectedNodeCount": 3,
  "readyNodeCount": 3,
  "currentVersionNodeCount": 3,
  "currentVersionReadyCount": 3,
  "driftedNodeCount": 0,
  "readyListenerCount": 4,
  "warningListenerCount": 0,
  "failedListenerCount": 0,
  "warnings": []
}

GET /v1/snapshot-sync

Returns the current state of the snapshot syncer, including the last sync time, sync period, and whether a sync is currently in progress.

Auth: bearer-when-configured Response: application/json

GET /v1/snapshot

Returns the full IR snapshot as JSON. This is the configuration that is currently being served to data planes. The response includes listeners, routes, backends, secrets, and policy configurations.

Auth: bearer-when-configured Response: application/json

Listeners

GET /v1/listeners

Lists all listeners from the current snapshot. Each listener includes its name, port, protocol, TLS configuration, hostname, and attached route count.

Auth: bearer-when-configured Response: application/json

Query parameters:

• namespace — filter by namespace
• hostname — filter by hostname (substring match)

GET /v1/listeners/{name}

Returns detailed information about a specific listener, including attached routes, TLS configuration, and backend references.

Auth: bearer-when-configured Response: application/json

Routes

GET /v1/routes

Lists all routes from the current snapshot. Returns routes of all types: HTTP, gRPC, TCP, UDP, and TLS.

Auth: bearer-when-configured Response: application/json

Query parameters:

• namespace — filter by namespace
• kind — filter by route kind (HTTPRoute, GRPCRoute, TCPRoute, UDPRoute, TLSRoute)
• listener — filter by parent listener name

GET /v1/routes/{kind}/{namespace}/{name}

Returns detailed information about a specific route, including its match rules, filters, backend references, and attached policies.

Auth: bearer-when-configured Response: application/json

Backends

GET /v1/backends

Lists all backends from the current snapshot. Returns Service backends, AIService backends, and custom backends with their endpoint addresses, health status, and load balancing configuration.

Auth: bearer-when-configured Response: application/json

Query parameters:

• namespace — filter by namespace

GET /v1/backends/{namespace}/{name}

Returns detailed information about a specific backend, including its endpoint list, health check configuration, and load balancing policy.

Auth: bearer-when-configured Response: application/json

Nodes

GET /v1/nodes

Lists all known data plane nodes. Each node entry includes its connection status, snapshot version, uptime, and health.

Auth: bearer-when-configured Response: application/json

GET /v1/nodes/{name}

Returns detailed information about a specific data plane node, including its status history and configuration drift information.

Auth: bearer-when-configured Response: application/json

Infrastructure

GET /v1/infrastructure

Returns infrastructure-level information including the Kubernetes namespace, node details, and resource counts.

Auth: bearer-when-configured Response: application/json

Resource management

GET /v1/resources

Lists Kubernetes resources managed by the gateway. Supports filtering by namespace, kind, and label selector.

Auth: bearer-when-configured Response: application/json

Query parameters:

• namespace — filter by namespace
• kind — filter by resource kind (e.g., Gateway, HTTPRoute, Secret)
• labels — filter by label selector

GET /v1/resources/{kind}/{namespace}/{name}

Returns a single Kubernetes resource. The response includes the full object as JSON with metadata, spec, and status.

Auth: bearer-when-configured Response: application/json

Queries

GET /v1/queries

Executes a resource query against the cluster. Supports filtering, sorting, and field selection.

Auth: bearer-when-configured Response: application/json

Data plane aggregation

GET /v1/dataplane

When data plane aggregation is configured, this endpoint returns aggregated information from all connected data plane instances, including their individual admin API responses.

Auth: bearer-when-configured Response: application/json

Metrics

GET /v1/metrics

Returns the current state of control plane metrics. This is the same data exposed on the Prometheus metrics endpoint but filtered to the metrics namespace.

Auth: bearer-when-configured Response: application/json

Chatbot

POST /v1/chat

Provides a natural language interface for querying gateway state. Accepts a JSON body with a user query and returns a structured response with relevant gateway information.

Auth: bearer-when-configured Request: application/json Response: application/json

Rate limiting and timeouts

The Admin API server applies these limits:

Limit	Default	Description
maxRequestBodyBytes	2 MB	Maximum request body size
maxResponseBodyBytes	8 MB	Maximum response body size
readHeaderTimeout	5s	Maximum time to read request headers
readTimeout	30s	Maximum time to read the full request
writeTimeout	30s	Maximum time to write the response
idleTimeout	2m	Maximum idle time for keep-alive connections

Metrics

The Admin API emits request-level metrics through the nantian_gateway_controlplane_admin_requests_total and nantian_gateway_controlplane_admin_request_duration_seconds metrics, partitioned by HTTP method, normalized route, and status class. These are scraped by Prometheus through the main metrics endpoint on :18082.

What’s next

• API Reference: Admin API — OpenAPI specification and client libraries
• Operations: Metrics Reference — complete Prometheus metrics catalog
• Configuration: Control Plane — admin server configuration