API and dashboard

The API is the HTTP surface that the dashboard talks to. It is read-only — Traefik is configured by providers, not by API calls — so the API is mostly an inspection layer over the runtime configuration.

Code map

File	Purpose
pkg/api/handler.go	Top-level HTTP router and request dispatch.
pkg/api/handler_overview.go	/api/overview — counts of routers, services, middlewares per protocol.
pkg/api/handler_entrypoint.go	/api/entrypoints — static-config entry points.
pkg/api/handler_http.go	/api/http/{routers,services,middlewares} — HTTP runtime objects.
pkg/api/handler_tcp.go	/api/tcp/... — TCP variants.
pkg/api/handler_udp.go	/api/udp/... — UDP variants.
pkg/api/handler_certificate.go	/api/certificates — TLS certificate inventory.
pkg/api/handler_support_dump.go	/api/support-dump — diagnostic bundle.
pkg/api/criterion.go	Pagination / filtering / sort parameters.
pkg/api/sort.go	Stable sort orders for each resource type.
pkg/api/debug.go	/debug/pprof/... when API debug is enabled.
pkg/api/dashboard/	Static dashboard asset handler.

Endpoints

GET /api/overview
GET /api/entrypoints
GET /api/entrypoints/{name}
GET /api/http/routers
GET /api/http/routers/{name}
GET /api/http/services
GET /api/http/services/{name}
GET /api/http/middlewares
GET /api/http/middlewares/{name}
GET /api/tcp/routers
GET /api/tcp/services
GET /api/tcp/middlewares
GET /api/udp/routers
GET /api/udp/services
GET /api/certificates
GET /api/version
GET /api/support-dump

Each list endpoint accepts:

• search — substring match on name.
• status — enabled / disabled / warning.
• serviceName, middlewareName, provider — relational filters.
• page, per_page — pagination.
• sort_by, sort_order — see pkg/api/sort.go for allowed fields.

Where the data comes from

pkg/config/runtime.Configuration is the single source of truth. The API handler holds a pointer that is swapped each time the configuration watcher applies a new snapshot. The pkg/server/router/router.go builder is responsible for populating the runtime model with Status, Err, and Using cross-references.

A typical request flow:

sequenceDiagram
    participant Client as Dashboard / curl
    participant H as pkg/api/handler.go
    participant R as runtime.Configuration

    Client->>H: GET /api/http/routers?search=api
    H->>H: parse query into criterion
    H->>R: snapshot HTTPRouterInfos
    H->>H: filter + sort + paginate
    H-->>Client: JSON response

The handler does not lock the runtime configuration during the read — instead, the apply path replaces the underlying map atomically. Reads see either the previous full snapshot or the next one, never a torn state.

Insecure mode and authentication

Out of the box the API is exposed only on the internal traefik entry point. Two flags change that:

• --api.insecure=true mounts the API on the default entry point at :8080 — convenient for development, dangerous in production.
• --api.dashboard=true mounts the dashboard at /dashboard/ and the API at /api/.
• --api.debug=true mounts pprof endpoints under /debug/pprof/.

For production deployments, the API is typically protected by a router rule restricting access to internal networks and a basic-auth or forward-auth middleware in front. There is no built-in authentication.

The dashboard

webui/ is a Vue 3 + Vite + TypeScript single-page app. It calls the JSON endpoints listed above and displays:

• Overview cards (routers / services / middlewares totals).
• Lists of routers, services, middlewares, certificates per protocol.
• Per-resource detail panes showing the status, errors, configuration, and cross-references.
• Entry-point overview.

Build steps:

1. yarn build produces webui/static/index.html plus assets.
2. webui/embed.go uses //go:embed to bake those into the binary.
3. pkg/api/dashboard/dashboard.go serves the embedded filesystem at /dashboard/.

The dashboard is fully static — there is no runtime-configurable theming or feature flagging beyond what the API returns.

Support dump

pkg/api/handler_support_dump.go builds a redacted diagnostic bundle. It includes the static configuration (with credentials stripped via pkg/redactor), a snapshot of the runtime configuration, and recent logs. The output is a .tar.gz suitable for attaching to a support ticket.

Certificate inventory

pkg/api/handler_certificate.go exposes the TLS manager's current certificate store. Each entry shows the SANs, the certificate's not-before/not-after, the resolver that issued it (if any), and which routers reference it. The dashboard's certificates page renders this directly.

Tests

• pkg/api/handler_test.go — generic dispatch and ACL.
• pkg/api/handler_http_test.go, handler_tcp_test.go, handler_udp_test.go — per-protocol filtering and pagination.
• pkg/api/handler_overview_test.go — counts derivation.
• pkg/api/sort_test.go — sort stability.
• pkg/api/handler_certificate_test.go — certificate-store rendering.

Entry points for modification

• A new resource type needs both a runtime-model field and a handler registration in pkg/api/handler.go.
• A new sort key or filter goes into pkg/api/criterion.go and pkg/api/sort.go.
• The dashboard calls REST endpoints — adding a column usually means adding a field to the JSON response and updating the Vue page in webui/src/.