API Reference

Status: Current

Last reviewed: 2026-05-16

This page reflects routes registered in nexus-backend/src/main.rs.

Base URLs

Default local endpoints:

REST:  http://localhost:8081/api
Agent control: REALITY listener from NEXUS_REALITY_LISTEN_ADDR

Agent control uses SecureAgentService over the backend REALITY listener. The backend no longer exposes a separate plain gRPC listener. If REST is run only inside the backend container, expose 8081 explicitly or run the backend locally.

Authentication

Public:

Method	Path	Handler
POST	/api/auth/login	api::auth::login

Protected routes require the backend auth middleware.

Responses use the backend ApiResponse<T> envelope:

{
  "success": true,
  "data": {},
  "error": null
}

REST Routes

Auth

Method	Path	Handler
GET	/api/auth/me	api::auth::me
PUT	/api/auth/me	api::auth::update_account
PUT	/api/auth/password	api::auth::change_password
GET	/api/auth/users	api::auth::list_users
POST	/api/auth/users	api::auth::create_user

/api/auth/users requires admin. Current API does not expose delete, disable, or role-update routes for users.

Nodes

Method	Path	Handler
GET	/api/nodes	api::nodes::list_nodes
POST	/api/nodes	api::nodes::create_node
GET	/api/nodes/links	api::nodes::list_node_links
GET	/api/nodes/{id}	api::nodes::get_node
PUT	/api/nodes/{id}	api::nodes::update_node
DELETE	/api/nodes/{id}	api::nodes::delete_node
POST	/api/nodes/{id}/psk	api::nodes::reset_node_psk
POST	/api/nodes/{id}/config	api::config_push::push_node_config

Node creation can return a one-time control PSK. The backend stores only the per-node verifier and fingerprint fields added by migration 027.

POST /api/nodes/{id}/config refreshes the DB-backed runtime snapshot for the node. It does not accept inline L4 rule payloads. See Runtime Config Hot Reload for version, replay, rollback, apply report, and port conflict semantics.

Routes

Legacy route APIs still exist for compatibility.

Method	Path	Handler
GET	/api/routes	api::routes::list_routes
POST	/api/routes	api::routes::create_route
GET	/api/routes/{id}	api::routes::get_route
PUT	/api/routes/{id}	api::routes::update_route
DELETE	/api/routes/{id}	api::routes::delete_route
GET	/api/routes/{id}/hops	api::routes::get_route_hops

L4 Chains

L4 chains are the current primary gateway workflow.

Method	Path	Handler
GET	/api/l4-chains	api::tunnel_chains::list_chains
POST	/api/l4-chains	api::tunnel_chains::create_chain
GET	/api/l4-chains/{id}	api::tunnel_chains::get_chain
PUT	/api/l4-chains/{id}	api::tunnel_chains::update_chain
DELETE	/api/l4-chains/{id}	api::tunnel_chains::delete_chain
POST	/api/l4-chains/{id}/deploy	api::tunnel_chains::deploy_chain_handler

Port Management

Port Management exposes control-plane listener intent derived from enabled L4 chains, L3 services, and saved listener policies. It also exposes the runtime listener table most recently reported by agents.

Method	Path	Handler
GET	/api/nodes/ports	api::node_ports::list_node_ports
GET	/api/nodes/ports?node_id={id}	api::node_ports::list_node_ports
GET	/api/nodes/ports/runtime	api::node_ports::list_node_port_runtime
GET	`/api/nodes/ports/runtime?node_id={id}&transport={tcp	udp}&listen_addr={addr}&listen_port={port}`
PUT	/api/nodes/ports/policies	api::node_ports::upsert_node_port_policy

GET /api/nodes/ports returns:

• nodes: all node options for the console dropdown.
• items: listener rows keyed by nodeId, transport, listenAddr, and listenPort.
• defaultPriorityOrder: currently ["reality", "tls", "noise", "raw"].

items[].routes contains computed listener routes with:

• source: l4_chain, l4_upstream, or l3_network.
• sourceLabel: display label for the source.
• matchKind: reality, sni, local_key, l3_context, or default.
• matchValue: the route-specific match string.
• nextHop: the next-hop endpoint or interface name.

GET /api/nodes/ports/runtime returns the current runtime state reported in agent heartbeat metadata:

• nodes: node runtime records.
• nodes[].reportedAt: timestamp of the heartbeat that carried runtime data.
• nodes[].listeners: runtime listeners filtered by optional query params.
• listeners[].state: agent listener state, such as running.
• listeners[].routes: the routes actually present in the agent runtime table.
• listeners[].bytesIn, bytesOut, activeSessions, totalSessions, errorSessions: runtime counters when reported by the agent.

PUT /api/nodes/ports/policies requires admin or operator and accepts:

{
  "nodeId": "node-uuid",
  "transport": "tcp",
  "listenAddr": "::",
  "listenPort": 443,
  "priorityOrder": ["reality", "tls", "noise", "raw"]
}

Supported priority labels are reality, tls, noise, and raw. transport is tcp or udp; QUIC shares the UDP listener namespace.

The backend normalizes priorityOrder by deduplicating labels and appending any missing labels in default order before saving.

The policy endpoint remains for API compatibility and automation. The current frontend Port Management page does not expose a policy save icon; it shows a draggable per-listener service list and loads runtime preview from /api/nodes/ports/runtime.

L4 Upstreams

Method	Path	Handler
GET	/api/l4-upstreams	api::upstreams::list_upstreams
POST	/api/l4-upstreams	api::upstreams::create_upstream
GET	/api/l4-upstreams/{id}	api::upstreams::get_upstream
PUT	/api/l4-upstreams/{id}	api::upstreams::update_upstream
DELETE	/api/l4-upstreams/{id}	api::upstreams::delete_upstream

GET /api/l4-upstreams returns a paginated items list of upstream records with server_names, health_check_interval_ms, and enabled. create_upstream requires name and endpoint. update_upstream does not accept name.

create_upstream accepts name, endpoint, optional server_names, and optional health_check_interval_ms. update_upstream accepts endpoint, server_names, health_check_interval_ms, and enabled. The API rejects the old health_check_path field.

Encryption Credentials

Method	Path	Handler
GET	/api/credentials	api::credentials::list_credentials
POST	/api/credentials	api::credentials::create_credential
PUT	/api/credentials/{id}	api::credentials::update_credential
DELETE	/api/credentials/{id}	api::credentials::delete_credential

Credential types are exposed through the unified credentials API. There is no current /api/certs route in src/main.rs; TLS certificate upload and self-signed generation are handled by /api/credentials with key_type: "tls_cert".

• x25519
• tls_cert
• reality

x25519 rows are stored in enc_keys. reality rows are stored in reality_profiles and reference an X25519 key. tls_cert rows are stored in certificates and are projected through the unified credential response.

Audit

Method	Path	Handler
GET	/api/audit	api::audit::list_audit_logs
POST	/api/audit/{id}/revert	api::audit::revert_audit_entry

Dashboard

Method	Path	Handler
GET	/api/dashboard/stats	api::dashboard::get_dashboard_stats

Settings

Method	Path	Handler
GET	/api/settings/connectivity	api::settings::get_connectivity_settings
PUT	/api/settings/connectivity	api::settings::update_connectivity_settings

gRPC Services

Current production agent control uses SecureAgentService, defined in common/proto/agent.proto.

RPC	Direction	Purpose
OpenSession	unary	Authenticates the node with the per-node control PSK and creates a secure control session.
Control	bidirectional stream	Carries encrypted hello, heartbeat, config request/update, and metrics frames.

The older AgentService RPCs still exist in the protobuf for compatibility and tests, but nexus-backend/src/main.rs registers SecureAgentServiceServer.

See Agent Control Protocol.