Governance API

The governance endpoint is the heart of TheWARDN. Every AI action passes through this endpoint to receive a verdict before execution.

Govern an Action

POST /govern

Submit an action for governance evaluation. Returns a verdict determining whether the action should be executed.

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body:

Field	Type	Required	Description
agent_id	string	Yes	ID of the registered agent
action_type	string	Yes	Type of action (e.g., deploy_code, data_query, send_email)
target_service	string	Yes	Target system or service
environment	string	No	Environment (production, staging, development). Default: production
confidence	object	No	Confidence scores per dimension
reasoning	string	No	Agent's reasoning for this action
metadata	object	No	Additional context (model_id for L6, data_classes, etc.)

Confidence Object:

{
  "incident": 0.92,
  "fix": 0.88,
  "containment": 0.95
}

Each dimension is a float between 0.0 and 1.0.

Metadata Object (Optional):

{
  "model_id": "gpt-4o",
  "access_channel": "AZURE",
  "data_classes": ["PII", "PHI"],
  "estimated_tokens": 5000
}

Including model_id activates L6 Model Governance pre-checks.

Example Request

curl -X POST https://api.thewardn.ai/govern \
  -H "Authorization: Bearer wdn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_abc123",
    "action_type": "deploy_code",
    "target_service": "production-api",
    "environment": "production",
    "confidence": {
      "incident": 0.95,
      "fix": 0.90,
      "containment": 0.92
    },
    "reasoning": "Deploying hotfix for critical API timeout bug",
    "metadata": {
      "model_id": "claude-sonnet-4-20250514",
      "access_channel": "API"
    }
  }'

Response — CLEARED

{
  "execute": true,
  "verdict": "CLEARED",
  "tier": "A",
  "seq": 42,
  "hash": "a3f2b8c9d4e5f6a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
  "l6": {
    "verdict": "CLEARED",
    "model_id": "claude-sonnet-4-20250514",
    "provider": "anthropic",
    "mode": "ENFORCEMENT",
    "violations": [],
    "violations_count": 0,
    "estimated_cost_usd": 0.0045
  }
}

Response — HELD

{
  "execute": false,
  "verdict": "HELD",
  "tier": "B",
  "seq": 43,
  "hash": "b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4",
  "escrow_id": "esc_xyz789",
  "timeout_at": "2026-04-10T20:24:03Z",
  "message": "Confidence below floor: fix=0.70 < 0.75"
}

Response — BLOCKED

{
  "execute": false,
  "verdict": "BLOCKED",
  "tier": "X",
  "seq": 44,
  "hash": "c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5",
  "reason": "SGP_VIOLATION",
  "rule_violated": "NO_PRODUCTION_WITHOUT_REVIEW",
  "message": "Action blocked by Sentinel Governance Principle"
}

Response Fields

Field	Type	Description
execute	boolean	Whether the agent should execute the action
verdict	string	CLEARED, HELD, or BLOCKED
tier	string	A, B, C, or X
seq	integer	Monotonic sequence number for this audit record
hash	string	SHA-256 hash of the sealed audit record
escrow_id	string	Only present if HELD — ID for escrow management
timeout_at	string	Only present if HELD — when the escrow expires
reason	string	Only present if BLOCKED — reason code
rule_violated	string	Only present if X-tier BLOCKED — specific SGP rule
message	string	Human-readable explanation
l6	object	Only present if L6 model governance evaluated
governance_mode	string	Only present if not ENFORCED
original_verdict	string	Only present in AUDIT_ONLY mode — what verdict would have been

Governance Modes

GET /governance-mode

Get the current governance mode for your tenant.

{
  "mode": "ENFORCED",
  "expires_at": null
}

PUT /governance-mode

Change governance mode. Requires ARCHITECT role.

{
  "mode": "AUDIT_ONLY",
  "duration_hours": 24
}

Mode	Behavior
ENFORCED	All verdicts enforced (default)
AUDIT_ONLY	Verdicts logged but all actions CLEARED
DISABLED	No evaluation, immediate pass-through

WARNING

DISABLED mode should only be used in emergencies. All actions bypass governance with no audit trail.

Dashboard

GET /dashboard

Get governance statistics for your tenant.

{
  "total_governed": 12547,
  "total_cleared": 11892,
  "total_held": 498,
  "total_blocked": 157,
  "active_agents": 12,
  "active_policies": 8,
  "governance_mode": "ENFORCED",
  "monthly_used": 3421,
  "monthly_limit": 50000
}