Decision API

Fairvisor Edge exposes a minimal HTTP API on port 8080.

Endpoints

Endpoint	Method	Purpose
`/v1/decision`	`POST`	Evaluate a request against the active policy bundle
`/v1/debug/session`	`POST`	Start per-user debug session (when debug secret is configured)
`/v1/debug/logout`	`POST`	End per-user debug session
`/livez`	`GET`	Liveness probe — always returns `200 ok`
`/readyz`	`GET`	Readiness probe — `200 ok` if a bundle is loaded
`/metrics`	`GET`	Prometheus metrics

POST /v1/decision

The primary endpoint. Evaluates the incoming request headers against the active policy bundle and returns 200 (allow) or 429 (reject).

Request

Header	Required	Description
`X-Original-Method`	Yes	HTTP method of the original request (`GET`, `POST`, …)
`X-Original-URI`	Yes	Full URI of the original request, including query string
`X-Original-Host`	Conditionally	Original request host. Required when using selector `hosts`.
`Authorization`	No	Bearer JWT; used for `jwt:<claim>` descriptor keys
`X-Forwarded-For`	No	Client IP chain; used for `ip:address` and `ip:country` keys
`X-ASN-Type`	No	Optional fallback input for `ip:type` when set by gateway/proxy
`X-Tor-Exit`	No	Optional override for `ip:tor` (`1/0`, `true/false`, `yes/no`)
Any custom header	No	Used when a policy references `header:<name>` limit keys

The request body is not consumed.

Response: 200 Allow

HTTP/1.1 200 OK
RateLimit-Limit: 1000
RateLimit-Remaining: 847
RateLimit-Reset: 1
RateLimit: "per-org-rps";r=847;t=1

Body is not part of the public contract (current implementation returns empty body on allow).

Response: 429 Reject

HTTP/1.1 429 Too Many Requests
Retry-After: 15
X-Fairvisor-Reason: token_bucket_exceeded
RateLimit-Limit: 1000
RateLimit-Remaining: 0
RateLimit-Reset: 15
RateLimit: "api-limits";r=0;t=15

Body: implementation-dependent (do not rely on it).

Debug session headers (optional)

When debug session is active, Fairvisor also returns debug headers such as:

X-Fairvisor-Debug-Policy
X-Fairvisor-Debug-Rule
X-Fairvisor-Debug-Reason

See Debug Session.

Response: 503 No bundle

If no policy bundle is loaded (e.g., immediately after startup before SaaS delivers config):

HTTP/1.1 503 Service Unavailable
X-Fairvisor-Reason: no_bundle_loaded

GET /livez

Always returns 200 while the nginx process is running. Use as a Kubernetes livenessProbe.

HTTP/1.1 200 OK

ok

GET /readyz

Returns 200 when a policy bundle is loaded and the engine is ready to process requests. Returns 503 during startup before the first bundle is applied.

HTTP/1.1 200 OK

{"status":"ready","policy_version":"...","policy_hash":"...","last_config_update":1736940000}

HTTP/1.1 503 Service Unavailable

{"status":"not_ready","reason":"no_policy_loaded"}

Use as a Kubernetes readinessProbe to hold traffic until the edge is ready.

GET /metrics

Returns Prometheus-format metrics.

HTTP/1.1 200 OK
Content-Type: text/plain; version=0.0.4

# HELP fairvisor_decisions_total Total decisions
# TYPE fairvisor_decisions_total counter
fairvisor_decisions_total{action="allow",reason="all_rules_passed",policy="policy-a",route="/api/v1"} 1542
fairvisor_decisions_total{action="reject",reason="token_bucket_exceeded",policy="policy-a",route="/api/v1"} 23
...

See Metrics for the full metric catalogue.

Mode differences

Aspect	`decision_service`	`reverse_proxy`
Host/method/URI source	`X-Original-Host`, `X-Original-Method`, `X-Original-URI`	nginx `$host`, `$request_method`, `$uri`
Response headers	Written directly to the decision response	Stored in `ngx.ctx`; written by `header_filter_by_lua_block`
Request body handling	Not consumed	Consumed/forwarded to backend

In reverse_proxy mode, callers do not call /v1/decision directly — Fairvisor Edge acts as a transparent proxy that enforces policy on every proxied request.

Authentication

The decision endpoint itself has no authentication. It is an internal service; expose it only to trusted callers (nginx internal location, Envoy cluster, VPC-internal network). Do not expose port 8080 to the public internet.