API Reference

Authentication

All API endpoints (except health check and shared views) require authentication. Browsers use the session cookie obtained by logging in:

POST /api/auth/login
Content-Type: application/json

{ "password": "your-password" }

Development automation

When the Server is started from the repository with bun run dev:server, the launcher binds the API to loopback and creates an ephemeral 256-bit development credential. Agents and local scripts should use the request wrapper; they do not need to handle or print the credential:

bun run dev:server:request -- GET /api/topologies
bun run dev:server:request -- POST /api/topologies/example/rebuild
bun run dev:server:request -- PATCH /api/topologies/example/discovery-policy \
  --json '{"nodes":[]}'

The wrapper uses the standard Authorization: Bearer scheme. This path is available only when NODE_ENV=development, requires the API to be bound to 127.0.0.1 or ::1, accepts only normalized /api/* paths, and refuses to send the generated credential to any remote HTTP or HTTPS origin. Production continues to accept session authentication only. The credential is stored in a gitignored owner-only file while the API is running and is removed on shutdown.

Starting apps/server/api directly with bun run dev does not create this credential; use the server-level command above when automating API access.

Machine-readable contract

GET /api/openapi.json returns the OpenAPI 3.1 contract. It requires the same administrator session or development Bearer credential as management endpoints:

bun run dev:server:request -- GET /api/openapi.json

Request and response schemas are the source of truth for migrated routes, and request schemas also perform runtime validation. Migration is incremental: the document currently covers health, system information, the admin runtime status, data source CRUD, and topology CRUD; the manually documented endpoints below remain available while their contracts move to the generated document.

For repository development, bun run openapi:generate writes the deterministic apps/server/api/openapi.json snapshot and the web client's generated TypeScript definitions. The web data source and topology CRUD clients consume those definitions with openapi-fetch. CI checks artifact drift and requires every management route to exist either in OpenAPI or in the explicit legacy migration ledger.

Shared views (public, token-scoped)

The only endpoints reachable without a session are the share routes below (plus /api/health). A share token grants read-only access to a single topology — or, for a dashboard, to just the topology/data-source ids that dashboard's widgets reference. Responses are projected to a public shape: internal fields (the resource's own share token, data-source ids, host mappings, port aliases, timestamps) are never returned.

A dashboard-scoped request whose :id is not referenced by the dashboard's layout returns 404, so the token cannot enumerate unrelated resources. The management endpoints below (/api/topologies/:id, /api/dashboards/:id, /api/datasources/:id/alerts, …) always require authentication.

HTTP Endpoints

Data Sources

Topologies

Dashboards

Plugins

Webhooks

Webhook endpoints do not use session authentication. Each request must instead carry the webhook secret configured on the source, supplied via the X-Webhook-Secret header (preferred) or a ?secret= query parameter. The secret is compared in constant time; a missing secret returns 401, an unknown target returns 404, and a wrong secret returns 401.

The general form is POST /api/webhooks/:type/:id, where :id is the id of the source (shown in its settings, not the secret itself). type=topology re-fetches a webhook-mode topology source's graph; any other type is dispatched to the matching data-source plugin — currently only grafana handles webhooks.

Other

WebSocket

Connect to ws://<host>/ws for real-time metrics streaming.

Client Messages

// Subscribe to topology updates
{ "type": "subscribe", "topology": "<topology-id>" }

// Filter specific nodes/links
{ "type": "filter", "nodes": ["router1"], "links": ["link-0"] }

Server Messages

{
  "type": "metrics",
  "data": {
    "nodes": {
      "router1": { "status": "up" }
    },
    "links": {
      "link-0": {
        "status": "up",
        "utilization": { "in": 45.2, "out": 12.8 }
      }
    },
    "timestamp": 1705849200000
  }
}