Skip to main content
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,
  "defaultArbitrationProfileId": "ap_001",
  "holdoutPercentage": 10,
  "enableExperiments": true,
  "enableBudgets": true,
  "enableGuardrails": true,
  "enableJourneys": false,
  "enableContentManagement": true,
  "enableBehavioralMetrics": true,
  "maxOffersPerDecision": 10,
  "defaultChannelTimeout": 5000,
  "retentionDays": 365,
  "approvalWorkflowEnabled": false,
  "mfaRequired": false,
  "theme": "dark",
  "locale": "en-US",
  "timezone": "America/New_York",
  "mlWorker": {
    "url": "https://ml-worker.example.com",
    "enabled": true
  }
}

​
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.
FieldTypeDescription
decisionTraceEnabledbooleanEnable forensic decision tracing.
decisionTraceSampleRatenumber (0-1)Fraction of decisions to trace (e.g., 0.1 = 10%).
defaultArbitrationProfileIdstringDefault arbitration profile for scoring.
holdoutPercentagenumber (0-100)Global holdout percentage for experimentation.
enableExperimentsbooleanEnable A/B experiment framework.
enableBudgetsbooleanEnable offer budget enforcement.
enableGuardrailsbooleanEnable guardrail policy checks.
enableJourneysbooleanEnable journey orchestration module.
enableContentManagementbooleanEnable content management module.
enableBehavioralMetricsbooleanEnable behavioral metrics tracking.
maxOffersPerDecisioninteger (1-100)Maximum offers returned per Recommend call.
defaultChannelTimeoutinteger (100-60000)Default channel delivery timeout in milliseconds.
retentionDaysinteger (1-3650)Default data retention period in days.
approvalWorkflowEnabledbooleanRequire approval for production changes.
mfaRequiredbooleanRequire multi-factor authentication.
themeenumUI theme: "dark", "light", "system".
localestring (max 10)Locale code (e.g., "en-US").
timezonestring (max 50)IANA timezone (e.g., "America/New_York").
mlWorkerobjectML worker configuration (see below).

​
ML Worker settings

FieldTypeDescription
mlWorker.urlstring (URL)ML worker endpoint URL. Empty string to clear.
mlWorker.enabledbooleanWhether the ML worker integration is active.

​
Example request

{
  "decisionTraceEnabled": true,
  "decisionTraceSampleRate": 0.05,
  "maxOffersPerDecision": 5
}

​
Response 200

Returns the full merged settings object after the update.

​
Error codes

CodeReason
400Validation 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

MethodMinimum role
GETadmin
PUTadmin

Settings

Learn more about tenant configuration in the platform UI.