Visual Layer Documentation: Visual Intelligence, At Scale

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.

User Management

Manage user accounts on self-hosted deployments.

Configuration

Environment-level configuration options for self-hosted deployments.

API Getting Started

Create a Dataset

Manage Datasets

Search

Guides

Self-Hosted Administration

Useful Scripts

Admin Settings

How This Helps

Prerequisites

Get a Setting

Query Parameters

Example

Response

Update a Setting

Request Body

Example

Response

Common Settings

Feature Toggles

System Configuration

Python Example

Response Codes

User Management

Configuration

How This Helps

​Prerequisites

​Get a Setting

​Query Parameters

​Example

​Response

​Update a Setting

​Request Body

​Example

​Response

​Common Settings

​Feature Toggles

​System Configuration

​Python Example

​Response Codes

​Related Resources

User Management

Configuration

Prerequisites

Get a Setting

Query Parameters

Example

Response

Update a Setting

Request Body

Example

Response

Common Settings

Feature Toggles

System Configuration

Python Example

Response Codes

Related Resources