Settings API

Manage tenant settings, organization information, and governance mode configuration.

Endpoints

GET /settings

Retrieve the current tenant settings.

Headers

Header	Value
Authorization	Bearer <api_key>

Response

{
  "notifications": {
    "email_on_violation": true,
    "email_on_escrow_timeout": true,
    "slack_webhook_url": null,
    "digest_frequency": "daily"
  },
  "governance": {
    "mode": "ENFORCED",
    "auto_release_escrow_minutes": 60,
    "default_escrow_timeout_minutes": 1440
  },
  "aria": {
    "enabled": true,
    "auto_suggest": true,
    "tone": "professional"
  },
  "data": {
    "retention_days": 90,
    "export_format": "json"
  }
}

---

PUT /settings

Update tenant settings. Partial updates are supported; only include the fields you want to change.

Request Body

{
  "notifications": {
    "email_on_violation": false,
    "digest_frequency": "weekly"
  },
  "governance": {
    "auto_release_escrow_minutes": 120
  }
}

Response

{
  "success": true,
  "settings": { }
}

TIP

Settings updates take effect immediately. There is no propagation delay.

---

GET /tenant

Get tenant information including subscription details and current usage.

Response

{
  "id": "tnt_x9y8z7",
  "name": "Acme Corp",
  "contact_email": "admin@acme.com",
  "tier": "business",
  "governance_mode": "ENFORCED",
  "monthly_used": 4521,
  "monthly_limit": 25000,
  "agents_registered": 8,
  "agents_limit": 50,
  "created_at": "2026-01-15T10:00:00Z"
}

Field	Type	Description
tier	string	Current subscription tier: free, personal_pro, startup, business, or enterprise
governance_mode	string	Current mode: ENFORCED, AUDIT_ONLY, or DISABLED
monthly_used	number	Governed actions consumed this billing period
monthly_limit	number	Maximum governed actions per billing period

---

PUT /tenant

Update tenant information.

Request Body

{
  "name": "Acme Corporation",
  "contact_email": "security@acme.com"
}

Field	Type	Description
name	string	Organization display name
contact_email	string	Primary contact email for notifications and alerts

Response

{
  "success": true,
  "tenant": {
    "id": "tnt_x9y8z7",
    "name": "Acme Corporation",
    "contact_email": "security@acme.com"
  }
}

---

GET /governance-mode

Get the current governance mode and any active timer.

Response

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

When a temporary mode is active:

{
  "mode": "AUDIT_ONLY",
  "timer": {
    "previous_mode": "ENFORCED",
    "expires_at": "2026-04-10T18:00:00Z",
    "remaining_minutes": 120
  }
}

---

PUT /governance-mode

Set the governance mode. Optionally set a timer to automatically revert to the previous mode.

Request Body

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

Field	Type	Required	Description
mode	string	Yes	One of: ENFORCED, AUDIT_ONLY, DISABLED
duration_hours	number	No	Auto-revert after this many hours. Omit for permanent change.

Response

{
  "success": true,
  "mode": "AUDIT_ONLY",
  "previous_mode": "ENFORCED",
  "reverts_at": "2026-04-10T18:00:00Z"
}

WARNING

Setting governance mode to DISABLED stops all policy evaluation. AI actions will pass through without any governance checks. Use this only for debugging and always set a duration_hours to ensure governance is automatically re-enabled.

---

Governance Modes

Mode	Behavior
ENFORCED	Full governance. Policies are evaluated and verdicts (CLEARED / HELD / BLOCKED) are enforced. This is the recommended production mode.
AUDIT_ONLY	Policies are evaluated and verdicts are logged, but all actions are allowed to proceed. Useful for initial rollout and policy tuning.
DISABLED	No policy evaluation. All actions pass through unmonitored. Use only for debugging.

TIP

When first integrating TheWARDN, start with AUDIT_ONLY mode to observe how your AI agents interact with policies before switching to ENFORCED.

---

Error Responses

Status	Code	Description
400	INVALID_MODE	The specified mode is not one of the three valid options
400	INVALID_DURATION	duration_hours must be between 1 and 720 (30 days)
403	PERMISSION_DENIED	Only users with ARCHITECT role can change governance mode