HTTP API

The backend exposes 37 JSON endpoints under /api/v1. All of them are generated from Go handlers via the in-tree apigen tool - the canonical spec is internal/server/openapi.gen.json and the typed TS client is frontend/src/shared/api/api.gen.ts. Hand-edit nothing.

How routes get registered

Each handler in internal/server/handlers.go carries a comment marker:

//api:route POST /api/v1/simulation/run
//api:header Remote-User={user}
func (s *Server) RunSimulation(user string, simCtx simulator.SimContext) (*simulator.DecisionResult, error) { ... }

go run ./apigen parses these markers and generates:

• internal/server/routes.gen.go - Gin route registration
• internal/server/openapi.gen.json - OpenAPI 3.1 document
• frontend/src/shared/api/models.gen.ts - TS types for every Go type used
• frontend/src/shared/api/api.gen.ts - typed fetch wrappers

Header-source params (Remote-User etc.) are stripped from the TS client - the proxy sets them. See auth for the trust model.

Routes

Index and search

Method	Path	Returns
GET	/api/v1/index	The full in-memory index snapshot
GET	/api/v1/search?q=...	SearchResult[] across every resource type
GET	/api/v1/segment/{segmentID}/policies	PolicyCoverage[] for one segment
GET	/api/v1/reachability?q=hostname	ReachabilityResult (segments + policies covering the hostname)

Reports (legacy quick views)

Method	Path	Returns
GET	/api/v1/reports/orphans	OrphanReport[] (segments without policy coverage)
GET	/api/v1/reports/overlaps	OverlapReport[] (domains in multiple segments)

Simulator

Method	Path	Returns
POST	/api/v1/simulation/run	Runs the FSM, persists if successful, returns DecisionResult
GET	/api/v1/simulation	SimulationRun[] paginated list
GET	/api/v1/simulation/{id}	One historical run
DELETE	/api/v1/simulation/{id}	Removes one run
GET	/api/v1/simulation/count	Total run count

Identity and meta

Method	Path	Returns
GET	/api/v1/me	Identity from Remote-* headers (post-strip)
GET	/api/v1/about	Build version, commit, date
POST	/api/v1/telemetry	Browser telemetry batch (page views + errors)
GET	/metrics	Prometheus metrics (in-cluster only)

Flow graph

Method	Path	Returns
POST	/api/v1/graph	FlowGraph filtered by the body’s selection
GET	/api/v1/routes	Full RouteMatrix (every reachable user-group to segment path)

Analytics

Method	Path	Returns
GET	/api/v1/analytics/blast-radius?id=...&type=...	BlastRadiusReport
GET	/api/v1/analytics/policy-shadows	PolicyShadowReport[]
GET	/api/v1/analytics/orphan-clusters	OrphanCluster[] (orphans grouped by segment group)
GET	/api/v1/analytics/domain-overlaps	DomainOverlapDetail[]
GET	/api/v1/analytics/connector-load	ConnectorLoadEntry[]
GET	/api/v1/analytics/scim-reach	ScimReachEntry[]

Raw ZPA passthrough

For the few cases where you want the raw resource list as the SDK returns it. Useful for debugging or building custom tooling on top.

Method	Path
GET	/api/v1/zpa/segments
GET	/api/v1/zpa/segment-groups
GET	/api/v1/zpa/access-policies
GET	/api/v1/zpa/app-connectors
GET	/api/v1/zpa/app-connector-groups
GET	/api/v1/zpa/server-groups
GET	/api/v1/zpa/scim-groups
GET	/api/v1/zpa/scim-attribute-headers
GET	/api/v1/zpa/scim-attribute-values?idp_id=...&header_id=...
GET	/api/v1/zpa/idp-controllers
GET	/api/v1/zpa/trusted-networks
GET	/api/v1/zpa/posture-profiles
GET	/api/v1/zpa/certificates
GET	/api/v1/zpa/client-types
GET	/api/v1/zpa/platforms

OpenAPI

The full spec lives at internal/server/openapi.gen.json. Drop it into Swagger UI, Insomnia, or your favorite client generator. It is regenerated on every go run ./apigen and committed.

Headers

Header	Set by	Used by
X-Request-Id	Server middleware (UUID per request, also echoed back)	Every log line + every response
Remote-User, Remote-Email, Remote-Groups, Remote-Name	Forward-auth proxy (Authelia via Caddy)	RunSimulation, GetMe, access log user field

Untrusted peers get the Remote-* headers stripped in middleware before any handler runs.