> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tenant Settings API
> Read and update tenant-level configuration including feature flags, thresholds, and integration settings.
The Tenant Settings API provides granular control over platform behavior for each tenant. Settings are stored as a JSON object on the tenant record and support partial updates (only changed keys need to be sent).
## Base path
```
/api/v1/tenant-settings
```
***
## Get tenant settings
```
GET /api/v1/tenant-settings
```
Returns the current tenant settings object. If no settings have been configured, returns an empty object.
### Response `200`
```json theme={null}
{
"decisionTraceEnabled": true,
"decisionTraceSampleRate": 0.1,
"defaultRankingProfileId": "rp_001",
"holdoutPercentage": 10,
"enableExperiments": true,
"enableBudgets": true,
"enableGuardrails": true,
"enableJourneys": false,
"enableContentManagement": true,
"enableBehavioralMetrics": true,
"maxOffersPerDecision": 10,
"defaultChannelTimeout": 5000,
"retentionDays": 365,
"approvalWorkflowEnabled": false,
"requirePublishApproval": false,
"mfaRequired": false,
"theme": "dark",
"locale": "en-US",
"timezone": "America/New_York",
"mlWorker": {
"url": "https://ml-worker.example.com",
"enabled": true
},
"flowIrEnabled": false,
"aiAutopilot": {
"mode": "suggest",
"sentinelAutoPause": false
}
}
```
`flowIrEnabled`, `requirePublishApproval`, and `aiAutopilot` are stored as real columns on the
`tenant_settings` table (not in the tenant `settings` JSONB), but the GET response merges all
sources into a single object so callers read and write one shape.
***
## Update tenant settings
```
PUT /api/v1/tenant-settings
```
Partially updates tenant settings. Only the provided keys are changed; all other settings are preserved. Nested objects (e.g., `mlWorker`) are deep-merged.
### Request body
All fields are optional. Only include the settings you want to change.
| Field | Type | Description |
| --------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `decisionTraceEnabled` | boolean | Enable forensic decision tracing. |
| `decisionTraceSampleRate` | number (0-1) | Fraction of decisions to trace (e.g., `0.1` = 10%). |
| `defaultRankingProfileId` | string | Default ranking profile for scoring. |
| `holdoutPercentage` | number (0-100) | Global holdout percentage for experimentation. |
| `enableExperiments` | boolean | Enable A/B experiment framework. |
| `enableBudgets` | boolean | Enable offer budget enforcement. |
| `enableGuardrails` | boolean | Module-visibility flag for the guardrails UI. Note: active [guardrail rules](/api-reference/guardrails) are **enforced on every Recommend request regardless of this flag** — enforcement is not gated by `enableGuardrails`. |
| `enableJourneys` | boolean | Enable journey orchestration module. |
| `enableContentManagement` | boolean | Enable content management module. |
| `enableBehavioralMetrics` | boolean | Enable behavioral metrics tracking. |
| `maxOffersPerDecision` | integer (1-100) | Maximum offers returned per Recommend call. |
| `defaultChannelTimeout` | integer (100-60000) | Default channel delivery timeout in milliseconds. |
| `retentionDays` | integer (1-3650) | Default data retention period in days. |
| `approvalWorkflowEnabled` | boolean | Require approval for production changes. |
| `requirePublishApproval` | boolean | Four-eyes publish gate. When `true`, `POST /api/v1/decision-flows/publish` requires a fresh approved [ApprovalRequest](/api-reference/approvals) (`entityType=decisionFlow`, `action=publish`) for the flow; one approval = one publish. Stored on the `tenant_settings.requirePublishApproval` column (not JSONB). Default: `false`. Surfaced as the "Publish approval (four-eyes)" toggle on the Settings page. |
| `mfaRequired` | boolean | Require multi-factor authentication. |
| `theme` | enum | UI theme: `"dark"`, `"light"`, `"system"`. |
| `locale` | string (max 10) | Locale code (e.g., `"en-US"`). |
| `timezone` | string (max 50) | IANA timezone (e.g., `"America/New_York"`). |
| `nbaEnabled` | boolean | Kill switch for NBA engine. When `false`, Recommend API returns offers sorted by priority only (no flow execution). Default: `true`. |
| `modelMaturityThreshold` | integer (0-10000) | Minimum interactions before a new offer gets full exposure in scoring. `0` disables the ramp entirely. Default: `100`. |
| `maturityRampColdStartFloor` | float (0.0-1.0) | Minimum exposure probability for offers with zero interactions under the maturity ramp. Default: `0.5` (raised from the legacy `0.20` so per-customer A/B comparisons stay reliable — pre-fix two customers comparing the same offer had a 64% chance of one side dropping it; with `0.5` that collision drops to 25%). Set lower for a more aggressive ramp, or `0.0` to fully gate cold-start by the deterministic roll. |
| `propensityScoreFloor` | float (0.0-0.5) | Minimum value any propensity component can take after learning. Prevents starvation: an offer accumulating only negative outcomes can still earn exposure. Default: `0.05`. Set to `0` to disable. |
| `propensitySmoothingWeight` | integer (>= 0) | Cold-start blend weight when an offer has some evidence but below the maturity threshold. Higher = stronger pull toward category/global prior. Default: `10`. |
| `interactionHistoryRetentionDays` | integer (30-9999) | Retention period for raw interaction history records. Default: `730` (\~2 years). |
| `summaryRetentionDays` | integer (30-9999) | Retention period for aggregated interaction summaries. Default: `2555` (\~7 years). |
| `rankingInfluencersEnabled` | boolean | When `true`, past outcomes influence future scoring of related offers by category. Boost clamped to `[-0.1, +0.1]`; final score clamped to `[0, 1]`. Default: `true`. |
| `flowIrEnabled` | boolean | Flow IR opt-in. When `true`, `POST /api/v1/pipelines` accepts `irVersion="1.0"` payloads and the AI Pipeline Mode is unlocked. Stored on the `tenant_settings.flowIrEnabled` column (not JSONB). Default: `false`. |
| `maturityRampMode` | enum | Maturity-ramp algorithm: `"bayesian_ci"` (Bayesian Confidence-Bound) or `"legacy_count"`. |
| `maturityWidthThreshold` | float (0.0-1.0) | Bayesian-CI ramp: confidence-interval width below which an offer is considered mature. |
| `maturityFloorDecayHalfLife` | number (1-1000) | Bayesian-CI ramp: half-life (in interactions) of the cold-start floor decay. |
| `upliftMethodDefault` | enum | Default uplift/CATE method when the `/uplift` endpoint is called without an explicit `?method=`: `"t_learner"` or `"x_learner"`. |
| `notificationSigningSecret` | string (max 256) | Slack signing secret used to verify the `X-Slack-Signature` header on `POST /api/v1/notifications/interactions`. |
| `teamsActionAuthToken` | string (max 256) | Bearer token for Microsoft Teams HttpPOST actions on adaptive cards. |
| `aiAutopilot` | object | Agentic-AI autonomy config (see below). Stored on the `tenant_settings.aiAutopilot` JSONB column. |
| `fairnessPolicy` | object | Pre-publish fairness hard-gate + continuous drift recheck config (see below). |
| `reportGuardrails` | object | Per-tenant caps for scheduled reports and LLM narration (see below). |
| `mlWorker` | object | ML worker configuration (see below). |
### ML Worker settings
| Field | Type | Description |
| ------------------ | ------------ | ---------------------------------------------- |
| `mlWorker.url` | string (URL) | ML worker endpoint URL. Empty string to clear. |
| `mlWorker.enabled` | boolean | Whether the ML worker integration is active. |
### AI Autopilot settings
Controls the agentic-AI autonomy level. Read by the [`ai-autopilot`](./cron#get-apiv1cronai-autopilot)
and [`ai-sentinel`](./cron#get-apiv1cronai-sentinel) cron jobs.
| Field | Type | Description |
| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `aiAutopilot.mode` | enum | Autonomy level: `"suggest"` (queue recommendations for review), `"auto_gated"` (auto-apply low-risk actions, queue the rest), or `"auto"` (auto-apply). |
| `aiAutopilot.sentinelAutoPause` | boolean | When `true`, the Decision Sentinel may auto-pause active flows on a detected regression. |
`aiAutopilot` is deep-merged: sending only `{ "mode": "auto_gated" }` preserves the existing `sentinelAutoPause`.
### Fairness policy settings
Opt-in pre-publish fairness hard-gate. When `enabled` is `true` and any configured threshold is
breached, `POST /api/v1/decision-flows/publish` returns `422` and refuses to publish.
| Field | Type | Description |
| ------------------------------------------------ | ------------------- | ------------------------------------------------------------------------------------ |
| `fairnessPolicy.enabled` | boolean | Turn the gate on. |
| `fairnessPolicy.sensitiveAttribute` | string (max 64) | Protected attribute to evaluate against. |
| `fairnessPolicy.thresholds.disparateImpactRatio` | float (0-1) | Minimum acceptable disparate-impact ratio. |
| `fairnessPolicy.thresholds.demographicParityGap` | float (0-1) | Maximum acceptable demographic-parity gap. |
| `fairnessPolicy.thresholds.equalOpportunityGap` | float (0-1) | Maximum acceptable equal-opportunity gap. |
| `fairnessPolicy.thresholds.giniCoefficient` | float (0-1) | Maximum acceptable Gini coefficient of decision-rate inequality. Default `0.2`. |
| `fairnessPolicy.minSampleSize` | integer (1-1000000) | Minimum sample before the gate evaluates. |
| `fairnessPolicy.continuousRecheck` | boolean | When `true`, `POST /api/v1/cron/fairness-recheck` auto-pauses active flows on drift. |
| `fairnessPolicy.override.approvedBy` | string | Four-eyes governance bypass — approver identity (required with `expiresAt`). |
| `fairnessPolicy.override.expiresAt` | string | ISO-8601 expiry of the bypass. |
### Report guardrails settings
| Field | Type | Description |
| ----------------------------------------- | ------------------ | ---------------------------------------------------------------- |
| `reportGuardrails.maxSchedulesPerTenant` | integer (1-100) | Max report schedules per tenant. Default `25`. |
| `reportGuardrails.minCronIntervalSeconds` | integer (60-86400) | Min seconds between consecutive schedule fires. Default `3600`. |
| `reportGuardrails.llmCallsPerMonth` | integer | Per-tenant monthly LLM-narration call budget. Default `2000`. |
| `reportGuardrails.defaultNarrativeOptOut` | boolean | When `true`, new report templates default to narrative-disabled. |
### Example request
```json theme={null}
{
"decisionTraceEnabled": true,
"decisionTraceSampleRate": 0.05,
"maxOffersPerDecision": 5
}
```
### Response `200`
Returns the full merged settings object after the update.
### Error codes
| Code | Reason |
| ----- | ---------------------------------------------------------------------------------------- |
| `400` | Validation error (unknown keys rejected via strict mode, invalid value types or ranges). |
The schema uses strict validation. Any unrecognized keys in the request body will cause a `400` error. Only the documented fields above are accepted.
***
## Role requirements
| Method | Minimum role |
| ------ | ------------ |
| GET | `admin` |
| PUT | `admin` |
Learn more about tenant configuration in the platform UI.