API overview

API overview

VerifAIer exposes one FastAPI application (vailidator.api.routes:app). It speaks JSON over HTTP, is local-first (default base URL http://localhost:8000), and is organized into three authentication tiers. The reported service version comes from GET /health.

curl

curl -s http://localhost:8000/health
# {"status":"ok","version":"1.4.2"}

flowchart TD
  REQ["HTTP request"] --> T{"path prefix?"}
  T -->|"/api/v1/* + /health /validate /pipeline /dev/audit /sentinel/verify"| OPEN["OPEN TIER, no auth"]
  T -->|"/api/auth/* /api/vai/* /api/orgs/* /api/observability/* /api/security/* /api/billing/*"| SESS["SESSION TIER, vai_session cookie OR X-Session-Token header"]
  T -->|"/api/control/* (data endpoints)"| KEY["API-KEY TIER, X-API-Key: vrf_..."]
  OPEN --> R["JSON response (local-first, no egress)"]
  SESS --> A1{"valid session?"}
  KEY --> A2{"valid key?"}
  A1 -->|no| E401["401 Authentication required / Invalid or expired session"]
  A2 -->|no| E401b["401 Authentication required / Invalid credentials · 403 revoked"]
  A1 -->|yes| R
  A2 -->|yes| R

Versioning

• URL versioning. The governance API is namespaced under /api/v1/*. The v1 segment is the API version; new capabilities are added as new /api/v1 endpoints, and existing response bodies grow only additively (new optional fields), preserving older clients.
• Object versioning. Every domain object carries its own *_version string, schema_version (evidence "1.0"), receipt_version, trust_version, passport_version, etc. Consumers can branch on these independently of the URL version. See the schemas.
• Service version. /health reports the FastAPI app version (1.4.2), distinct from the API (v1) and object versions.

Local-first / no-egress posture

The API makes no outbound network calls by default. It is designed to run on your own infrastructure, laptop, VPC, air-gapped or sovereign, and the docs site itself vendors all assets (including diagrams) so nothing phones home.

• No egress on the evidence path. The default AI provider is a deterministic offline mock. A live provider makes an outbound call only when explicitly enabled, keyed and in live mode (triple-gated).
• Assessment endpoints never leave the box. Compliance / risk / quality / trust / passport / reputation / registry / signals operate purely on the evidence you POST, no model calls, no telemetry.
• Secrets stay server-side. API keys are read from the server environment; callers never send provider keys and never receive them. See security considerations.
• Persistence is local. The registry defaults to in-memory; the durable option is a local JSON store. No external database is required.

Complete API documentation index

All thirty topics in this API documentation set: