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).
Partially updates tenant settings. Only the provided keys are changed; all other settings are preserved. Nested objects (e.g., mlWorker) are deep-merged.
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 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 (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.
