Tenant Settings API

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`

{
  "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 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`.
`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 and ai-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

{
  "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`

Settings

Learn more about tenant configuration in the platform UI.

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

Tenant Settings API

Base path

Get tenant settings

Response `200`

Update tenant settings

Request body

ML Worker settings

AI Autopilot settings

Fairness policy settings

Report guardrails settings

Example request

Response `200`

Error codes

Role requirements

Settings

​Base path

​Get tenant settings

​Response 200

​Update tenant settings

​Request body

​ML Worker settings

​AI Autopilot settings

​Fairness policy settings

​Report guardrails settings

​Example request

​Response 200

​Error codes

​Role requirements

Settings

Base path

Get tenant settings

Response `200`

Update tenant settings

Request body

ML Worker settings

AI Autopilot settings

Fairness policy settings

Report guardrails settings

Example request

Response `200`

Error codes

Role requirements