Admin API

The admin dashboard is backed by a JSON REST API under /admin/api, served on the gateway listen port. Every endpoint below is taken from the admin router's route table; response shapes are taken from the admin response models.

Note

The /admin* space — including this API — is protected by admin.auth_provider when set, but not by admin.allowed_ips (which is not enforced today). See Admin dashboard for how to lock it down.

Note

Write endpoints accept a JSON body over the gateway listener. Admin requests are bridged into the internal router with their method, path, query, headers and body intact, so handlers that deserialize a payload (route and upstream create/update, TLS upload, plugin config) receive it. Two limits still apply: configuration is immutable at runtime (PUT /admin/api/config/:key only records the change — see below), and resources owned by the Kubernetes operator or static config may be overwritten on the next reconcile.

Metrics & analytics01

Method	Path	Returns
`GET`	`/admin/api/stats`	`DashboardStats` — aggregate gateway stats.
`GET`	`/admin/api/metrics/realtime`	`DashboardStats` — same shape, for live refresh.
`GET`	`/admin/api/analytics?timeframe=24h`	`AnalyticsMetrics` — top routes, latency percentiles, traffic by method.
`GET`	`/admin/api/metrics/timeseries?metric=requests&period=1h`	Array of `{ timestamp, value }`. `metric` is one of `requests`, `errors`, `latency`, `connections`.
`GET`	`/admin/api/metrics/performance`	`PerformanceMetrics` — CPU/memory/connection figures.

DashboardStats:

{
  "total_requests": 0,
  "active_routes": 0,
  "avg_latency_ms": 0.0,
  "health_status": "healthy",
  "requests_per_second": 0.0,
  "error_rate": 0.0,
  "active_connections": 0,
  "cpu_usage": 0.0,
  "memory_usage": 0.0
}

AnalyticsMetrics:

{
  "timeframe": "24h",
  "request_volume": [],
  "latency_percentiles": { "p50": 0.0, "p90": 0.0, "p95": 0.0, "p99": 0.0 },
  "error_breakdown": {},
  "top_routes": [
    { "path": "/api/users", "requests": 0, "avg_latency": 0.0, "error_rate": 0.0 }
  ],
  "status_code_distribution": {},
  "traffic_by_method": {}
}

PerformanceMetrics:

{
  "cpu_usage": 0.0,
  "memory_usage": 0.0,
  "memory_total": 0,
  "memory_available": 0,
  "goroutines": 0,
  "gc_count": 0,
  "gc_pause_ms": 0.0
}

Note

goroutines, gc_count, and gc_pause_ms are carry-over field names in the model. Octopus is a Rust service; goroutines is populated with the active connection count and the GC fields are always 0.

Routes (CRUD)02

Method	Path	Description
`GET`	`/admin/api/routes`	List all routes — array of `RouteInfo`.
`POST`	`/admin/api/routes`	Create a route from a `RouteConfig` body (see the note above).
`GET`	`/admin/api/routes/:id`	A single `RouteInfo` by id, or `{ "error": "Route not found", "id": ... }`.
`PUT`	`/admin/api/routes/:id`	Replace a route (remove + add) from a `RouteConfig` body.
`DELETE`	`/admin/api/routes/:id`	Delete a route by id.

`GET /admin/api/routes` — the route-config endpoint

Returns an array of RouteInfo, combining each route's operational metrics with its effective configuration:

[
  {
    "id": "route-0",
    "path": "/api/users",
    "method": "GET",
    "upstream": "users-svc",
    "request_count": 0,
    "is_healthy": true,
    "avg_latency_ms": 0.0,
    "error_count": 0,
    "last_accessed": null,

    "priority": 0,
    "strip_prefix": null,
    "add_prefix": null,
    "auth_provider": null,
    "skip_auth": false,
    "require_roles": [],
    "require_scopes": [],
    "authz_rule": null,
    "timeout_ms": null,
    "rate_limit": null
  }
]

Field meanings:

Field	Type	Source
`id`	string	Synthetic id (`route-<index>`).
`path`	string	Route match path.
`method`	string	HTTP method.
`upstream`	string	Target upstream name.
`request_count`	integer	Requests recorded for this route.
`is_healthy`	boolean	Upstream health (from the health tracker; `true` if no tracker).
`avg_latency_ms`	number	Average latency for the route.
`error_count`	integer	Errors recorded for this route.
`last_accessed`	string \| null	Always `null` currently.
`priority`	integer	Route match priority (higher wins).
`strip_prefix`	string \| null	Prefix stripped before proxying.
`add_prefix`	string \| null	Prefix added before proxying.
`auth_provider`	string \| null	Auth provider enforced on the route.
`skip_auth`	boolean	Whether auth is skipped.
`require_roles`	string[]	Required roles.
`require_scopes`	string[]	Required scopes.
`authz_rule`	string \| null	Authorization rule expression.
`timeout_ms`	integer \| null	Per-route timeout.
`rate_limit`	object \| null	`{ "requests": <n>, "window_ms": <ms> }` if set.

RouteConfig (the POST/PUT body shape):

{
  "id": null,
  "path": "/api/users",
  "method": "GET",
  "upstream": "users-svc",
  "timeout_ms": null,
  "retry_count": null,
  "circuit_breaker": null,
  "rate_limit": null
}

Plugins03

Method	Path	Description
`GET`	`/admin/api/plugins`	List plugins (`PluginInfo`).
`GET`	`/admin/api/plugins/:id`	Get one plugin.
`POST`	`/admin/api/plugins/:id/toggle`	Enable/disable a plugin.
`PUT`	`/admin/api/plugins/:id/config`	Update plugin config (body).

Logs & monitoring04

Method	Path	Returns
`GET`	`/admin/api/logs`	Log entries (`ActivityLogEntry`).
`GET`	`/admin/api/activity`	Recent activity (up to 50 entries) as `ActivityLogEntry`.
`GET`	`/admin/api/health`	Health checks (`HealthCheckInfo`).
`GET`	`/admin/api/security/events`	Security events (`SecurityEvent`).

Configuration05

Method	Path	Description
`GET`	`/admin/api/config`	List configuration items (`ConfigItem`).
`PUT`	`/admin/api/config/:key`	Note a config update (does not mutate runtime).

GET /admin/api/config returns a curated list of ConfigItems, each:

{
  "key": "server.listen",
  "value": "0.0.0.0:8080",
  "description": "Server listen address",
  "editable": false
}

Keys surfaced today include server.listen, server.workers, server.request_timeout_ms, server.max_body_size, compression.enabled, farp.enabled, observability.logging.level, and observability.metrics.enabled.

Warning

Configuration is immutable at runtime. PUT /admin/api/config/:key only logs the request and returns { "success": true, "message": "... requires restart to take effect" }; it does not change the running configuration.

Upstreams, services & circuits06

Method	Path	Returns
`GET`	`/admin/api/upstreams`	Upstream clusters with per-instance health (`UpstreamClusterInfo`).
`GET`	`/admin/api/services`	Configured services.
`GET`	`/admin/api/circuits`	Circuit-breaker state per upstream.
`GET`	`/admin/api/health/checks`	Detailed health-check results.
`GET`	`/admin/api/openapi.json`	Generated OpenAPI document for the gateway.

FARP07

Method	Path	Returns
`GET`	`/admin/api/farp/services`	Registered FARP services (`FarpServiceInfo`).
`GET`	`/admin/api/farp/services/:name`	Detail for one FARP service.
`GET`	`/admin/api/farp/schema/openapi`	Federated OpenAPI schema across FARP services.

System, auth & gRPC08

Method	Path	Returns
`GET`	`/admin/api/system/info`	`SystemInfo` — version, uptime, host, OS/arch, CPU count, memory.
`GET`	`/admin/api/auth/providers`	Configured auth providers.
`GET`	`/admin/api/auth/config`	Auth configuration.
`GET`	`/admin/api/grpc/services`	gRPC service mappings.

SystemInfo:

{
  "version": "0.1.0",
  "uptime_seconds": 0,
  "start_time": "2026-01-01 00:00:00",
  "hostname": "octopus-0",
  "os": "linux",
  "arch": "aarch64",
  "num_cpus": 8,
  "total_memory": 0
}

Real-time events09

Method	Path	Description
`GET`	`/admin/ws`	WebSocket upgrade for live dashboard events.

Admin dashboard — the UI and how to protect this API.
Metrics — Prometheus endpoint (distinct from this JSON API).
Configuration → Admin — the admin block.

← Previous

Admin dashboard

Kubernetes

Admin API

Admin API

Metrics & analytics01

Routes (CRUD)02

GET /admin/api/routes — the route-config endpoint

Plugins03

Logs & monitoring04

Configuration05

Upstreams, services & circuits06

FARP07

System, auth & gRPC08

Real-time events09

Related10

Got somethinghard to build?

`GET /admin/api/routes` — the route-config endpoint

Got something
hard to build?