Manage settings through the Settings API
The Settings API lets you read and update Databricks account, workspace, and user settings, including account and workspace-level feature previews, programmatically. This page explains how to discover the available settings and how to read and update them. For the list of settings available through the public API, see Settings API keys reference.
For the full endpoint reference, see the Settings REST API.
Workspace and account-level feature previews are also managed through the Settings v2 API, but they aren't listed in the Settings API keys reference because a preview eventually reaches end-of-life when the feature graduates or is removed. Discover the previews currently available to you through the settings-metadata endpoint. Every preview it returns is readable and updatable through the same get and update (PATCH) endpoints as any other setting.
Settings API model
The Settings v2 API is dynamic. A single, generalized API serves every setting, and new settings become available through it without a new API version, SDK release, or documentation update. Rather than a fixed, hand-maintained list of endpoints, you discover what is currently settable at runtime through the metadata endpoint.
A setting has a name, a value whose shape depends on the setting's type, and a scope that determines where it applies:
- Account settings apply across the account.
- Workspace settings apply to a single workspace.
- User preferences apply to a user in an account.
Some settings are available at more than one scope. Account and workspace settings generally require administrator permissions to read or update.
Endpoints by scope
Each scope has its own set of endpoints. Use the one that matches how the setting is managed:
Scope | Get | Update ( |
|---|---|---|
Account | ||
Workspace | ||
User preference |
|
|
Discover available settings
The setting names and their current metadata (including the value type you need for updates) are available from the metadata endpoint. This is the always up-to-date source of truth for what is currently settable in your workspace or account. The endpoint is paginated, so page through the results to retrieve the full list:
curl -n --request GET \
'https://<databricks-instance>/api/2.1/settings-metadata'
You can also list settings with the Databricks CLI:
databricks workspace-settings-v2 list-workspace-settings-metadata
For account settings, use the account-scoped metadata endpoint instead:
curl -n --request GET \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings-metadata'
Read a setting
A get response returns two values for each setting. The stored value is in the type field (for example, boolean_val) and is the value that has been set. The effective value is in the corresponding effective_* field (for example, effective_boolean_val) and is the value the server computes after applying defaults and any higher-scope overrides. For example, a boolean setting returns:
{
"name": "<key-name>",
"boolean_val": { "value": true },
"effective_boolean_val": { "value": true }
}
To read a workspace setting, call the get endpoint with the setting's key name:
curl -n --request GET \
'https://<databricks-instance>/api/2.1/settings/<key-name>'
To read an account setting, use the account-scoped path:
curl -n --request GET \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings/<key-name>'
To read a user preference, use the account-scoped user path. Reading and updating user preferences requires account administrator permissions:
curl -n --request GET \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>'
Update a setting
To update a setting, send a PATCH request whose body is the setting object, with the value carried in the field that matches the setting's type. Use list-workspace-settings-metadata (or the metadata endpoint) to determine the correct type field for a given setting. For example, to update a boolean workspace setting:
curl -n --request PATCH \
'https://<databricks-instance>/api/2.1/settings/<key-name>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "<key-name>",
"boolean_val": { "value": true }
}'
To update an account setting, send the same body to the account-scoped path:
curl -n --request PATCH \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings/<key-name>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "<key-name>",
"boolean_val": { "value": true }
}'
To update a user preference, send the request to the account-scoped user path. The example below updates a string-typed preference:
curl -n --request PATCH \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "<key-name>",
"string_val": { "value": "<value>" }
}'