Skip to main content
This API is available on self-hosted deployments only. See Self-Hosting for setup instructions.

How This Helps

The Admin Settings API allows administrators to view and change runtime configuration without restarting the application. Toggle feature flags, adjust thresholds, and fine-tune system behavior — all changes take effect immediately.

​
Prerequisites

  • A self-hosted Visual Layer deployment (RUN_MODE=ONPREM).
  • An authenticated session. If user management is enabled, the Admin workspace role is required.

​
Get a Setting

Retrieve the current value of a configuration setting. 
GET /api/v1/admin/settings?key={key}

​
Query Parameters

ParameterTypeRequiredDescription
keystringYesSetting name in UPPER_SNAKE_CASE. Hyphens are automatically converted to underscores.

​
Example

curl "https://<your-vl-domain>/api/v1/admin/settings?key=DATASET_SNAPSHOTS_ENABLED"

​
Response

{
  "value": "true"
}
The endpoint returns the value from the runtime settings database if it has been overridden. Otherwise, it returns the application default. All values are returned as strings.

​
Update a Setting

Change a configuration setting at runtime. The new value takes effect immediately for all subsequent API requests. 
POST /api/v1/admin/settings
Content-Type: application/json

​
Request Body

FieldTypeRequiredDescription
keystringYesSetting name in UPPER_SNAKE_CASE.
valueanyYesNew value. Stored as a string regardless of type.

​
Example

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"key": "VL_CHAT_ENABLED", "value": "true"}' \
  "https://<your-vl-domain>/api/v1/admin/settings"

​
Response

{
  "value": "true"
}
Setting changes take effect immediately for all users. Test changes in a non-production environment first. Invalid setting names return a 400 error — only settings that exist in the application configuration can be modified.

​
Common Settings

The following settings are commonly adjusted on self-hosted deployments:

​
Feature Toggles

SettingTypeDefaultDescription
DATASET_SNAPSHOTS_ENABLEDbooleantrueEnable dataset snapshot support.
VL_CHAT_ENABLEDbooleanvariesEnable the VL Chat AI assistant.
ENRICHMENT_INLINE_FLOW_ENABLEDbooleanfalseEnable the inline enrichment workflow.
DATASET_SHARE_ENABLEDbooleantrueAllow dataset sharing between users.
ADD_MEDIA_ENABLEDbooleantrueAllow adding media to existing datasets.
DELETE_DATASET_ENABLEDbooleantrueAllow dataset deletion.

​
System Configuration

SettingTypeDefaultDescription
LOG_LEVELstringINFOApplication log level: DEBUG, INFO, WARNING, ERROR, CRITICAL.
SWAP_RGB_CHANNELS_FOR_TIFF_HEICbooleanfalseSwap RGB channels when processing TIFF and HEIC images.

​
Python Example

import requests

VL_BASE_URL = "https://<your-vl-domain>"
session = requests.Session()
# Authenticate via OIDC flow first, then use the session cookie

# Check current setting
resp = session.get(
    f"{VL_BASE_URL}/api/v1/admin/settings",
    params={"key": "VL_CHAT_ENABLED"},
)
resp.raise_for_status()
print(f"VL_CHAT_ENABLED: {resp.json()['value']}")

# Enable a feature
resp = session.post(
    f"{VL_BASE_URL}/api/v1/admin/settings",
    json={"key": "VL_CHAT_ENABLED", "value": "true"},
)
resp.raise_for_status()
print(f"Updated to: {resp.json()['value']}")

​
Response Codes

See Error Handling for the error response format.
HTTP CodeMeaning
200Request successful.
400Setting name does not exist in the application configuration.
403Forbidden — not an on-prem deployment, or insufficient admin privileges.
500Internal Server Error — contact support if this persists.

User Management

Manage user accounts on self-hosted deployments.

Configuration

Environment-level configuration options for self-hosted deployments.