HTTP API Reference

The Nomotic API server exposes governance operations over HTTP. Start it with:

nomotic serve [--host 0.0.0.0] [--port 8420] [--ui] [--metrics] [--playground] [--sim-mode]

Default: http://127.0.0.1:8420

Authentication

API requests require an X-Api-Key header. Localhost requests (127.0.0.1, ::1) bypass authentication.

curl -H "X-Api-Key: your-key" http://localhost:8420/v1/health

---

Infrastructure

Health Check

GET /v1/health

Returns 200 OK with server health status.

Server Info

GET /v1/info

Returns version, issuer ID, and certificate count.

---

Dashboard UI Endpoints

Overview

GET /v1/ui/overview
GET /v1/ui/feed
GET /v1/ui/events          # SSE — Server-Sent Events for real-time updates
POST /v1/ui/export?format=html|json

Agent Status (F-10)

GET /v1/ui/agents                    # List all agents
GET /v1/ui/agents?archetype=<name>   # Filter by archetype
GET /v1/ui/agent/{agent_id}          # Single agent detail
GET /v1/ui/panels/agent-roster       # Agent roster panel data

Verdict Detail (F-04)

GET /v1/ui/verdict/{record_id}       # Full 14-dimension verdict breakdown

Drift Alerts (F-11)

GET  /v1/ui/drift-alerts
POST /v1/ui/drift-alerts/{id}/dismiss

Audit Trail (F-12)

GET  /v1/ui/audit?agent_id=&verdict=&archetype=&date_from=&date_to=&limit=&offset=
GET  /v1/ui/audit/export?format=csv|json
POST /v1/ui/audit/verify/{record_id}

Config Editor (F-14)

GET  /v1/ui/config
POST /v1/ui/config/validate
POST /v1/ui/config/download

---

Certificates

GET    /v1/certificates                      # List certificates
POST   /v1/certificates                      # Issue a certificate
GET    /v1/certificates/{cert_id}            # Get certificate
POST   /v1/certificates/{cert_id}/verify     # Verify certificate
POST   /v1/certificates/{cert_id}/verify/live # Live verification
PATCH  /v1/certificates/{cert_id}/suspend    # Suspend
PATCH  /v1/certificates/{cert_id}/reactivate # Reactivate
PATCH  /v1/certificates/{cert_id}/revoke     # Revoke
POST   /v1/certificates/{cert_id}/renew      # Renew
PATCH  /v1/certificates/{cert_id}/zone       # Transfer zone
GET    /v1/certificates/{cert_id}/reputation # Trust reputation
GET    /v1/verify/{cert_id}                  # Quick verify
GET    /v1/revocations                       # List revocations

---

Archetypes

GET  /v1/archetypes                  # List archetypes
POST /v1/archetypes                  # Register custom archetype
POST /v1/archetypes/validate         # Validate archetype name
GET  /v1/archetypes/{name}           # Get archetype details

---

Organizations

GET   /v1/organizations              # List organizations
POST  /v1/organizations              # Register organization
POST  /v1/organizations/validate     # Validate org name
GET   /v1/organizations/{name}       # Get organization
PATCH /v1/organizations/{name}/suspend # Suspend
PATCH /v1/organizations/{name}/revoke  # Revoke

---

Trust, Drift, Fingerprint

GET /v1/trust/{agent_id}             # Trust report
GET /v1/trust/{agent_id}/trajectory  # Trust trajectory
GET /v1/drift/{agent_id}             # Behavioral drift report
GET /v1/drift/explain/{agent_id}     # Drift causal analysis for agent
GET /v1/drift/explain/alert/{alert_id}  # Drift causal analysis for fleet alert
GET /v1/fingerprint/{agent_id}       # Behavioral fingerprint
GET /v1/alerts                       # Drift alerts
POST /v1/alerts/{agent_id}/{index}/acknowledge  # Acknowledge alert

---

Audit Trail

GET /v1/audit/{agent_id}/records     # Agent audit records
GET /v1/audit/{agent_id}/summary     # Audit summary
GET /v1/audit/{agent_id}/verify      # Verify chain integrity
GET /v1/audit/{agent_id}/export      # Export records
GET /v1/audit/{agent_id}/seal        # Chain seal

---

Override / Approval Queue (F-05)

GET  /v1/overrides/pending              # List pending overrides
GET  /v1/overrides/pending/{id}         # Get pending override
POST /v1/overrides/{id}/approve         # Approve override
POST /v1/overrides/{id}/deny            # Deny override
GET  /v1/overrides/history              # Override history
GET  /v1/overrides/{action_id}/status   # Override status
POST /v1/overrides/{id}/callback        # Register webhook callback
POST /v1/slack/interaction              # Slack interactive callback

---

Playground (F-17)

Requires --playground flag.

POST /v1/playground/evaluate       # Run evaluation
GET  /v1/playground/archetypes     # List available archetypes
GET  /v1/playground/presets        # List compliance presets
POST /v1/playground/export         # Export configuration

Evaluate Request Body

{
  "archetype": "healthcare-agent",
  "preset": "hipaa_aligned",
  "action_type": "read",
  "target": "patient/records",
  "trust_score": 0.7,
  "weight_overrides": {}
}

---

Fleet

GET /v1/fleet/health                # Fleet health overview
GET /v1/fleet/trust                 # Fleet trust distribution
GET /v1/fleet/denials               # Fleet denial analytics
GET /v1/fleet/critical              # Critical agents
GET /v1/fleet/agents                # All fleet agents
GET /v1/fleet/agents/{agent_id}     # Single fleet agent

---

Behavioral Trajectory Engine

GET /v1/trajectory/{agent_id}       # Get trajectory projection for an agent
GET /v1/trajectory/interventions    # List trajectory interventions (?agent_id=filter)

---

Fleet Simulation (F-22)

GET /v1/sim/stats                   # Simulation statistics
GET /v1/sim/status                  # Simulation status

---

Constitutional Rules

GET  /v1/constitution/rules          # List rules
GET  /v1/constitution/rules/{rule_id} # Get rule
POST /v1/constitution/verify         # Verify ruleset integrity

---

Human Engagement

GET  /v1/human-engagement/{reviewer_id}         # Reviewer stats
GET  /v1/human-engagement/{reviewer_id}/drift    # Reviewer drift
GET  /v1/human-engagement/{reviewer_id}/routing  # Routing patterns
POST /v1/human-engagement/event                  # Record engagement event
GET  /v1/human-engagement/alerts                 # Engagement alerts
GET  /v1/human-engagement/team/overview          # Team overview

---

Behavioral Command & Control

POST   /v1/control/directives              # Issue a behavioral directive
GET    /v1/control/directives              # List active directives
DELETE /v1/control/directives/{id}         # Expire a directive and undo effects

---

Counterfactual Behavioral Replay

POST /v1/replay                            # Replay agent history against alternative config
POST /v1/replay/compare                    # Compare two configs against same history