Admin Settings

View and update runtime configuration settings on self-hosted Visual Layer deployments.

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

Parameter	Type	Required	Description
key	string	Yes	Setting 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

Field	Type	Required	Description
key	string	Yes	Setting name in UPPER_SNAKE_CASE.
value	any	Yes	New 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

Setting	Type	Default	Description
DATASET_SNAPSHOTS_ENABLED	boolean	true	Enable dataset snapshot support.
VL_CHAT_ENABLED	boolean	varies	Enable the VL Chat AI assistant.
ENRICHMENT_INLINE_FLOW_ENABLED	boolean	false	Enable the inline enrichment workflow.
DATASET_SHARE_ENABLED	boolean	true	Allow dataset sharing between users.
ADD_MEDIA_ENABLED	boolean	true	Allow adding media to existing datasets.
DELETE_DATASET_ENABLED	boolean	true	Allow dataset deletion.

System Configuration

Setting	Type	Default	Description
LOG_LEVEL	string	INFO	Application log level: DEBUG, INFO, WARNING, ERROR, CRITICAL.
SWAP_RGB_CHANNELS_FOR_TIFF_HEIC	boolean	false	Swap 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 Code	Meaning
200	Request successful.
400	Setting name does not exist in the application configuration.
403	Forbidden — not an on-prem deployment, or insufficient admin privileges.
500	Internal Server Error — contact support if this persists.

---

Related Resources

User Management

Manage user accounts on self-hosted deployments.

Configuration

Environment-level configuration options for self-hosted deployments.