API Reference - Design Settings
Link: https://support.brilliantdirectories.com/support/solutions/articles/12000108116
← Back to API Reference | Getting Started
Design Settings
Design Settings control the visual appearance and layout configuration of the directory site. Each record stores a named setting (EG colors, fonts, layout options) along with its current value and the layout group it belongs to. These settings drive the site's theme rendering engine and are typically managed through the admin Design panel.
website_design_settings — DB table: website_design_settingsThe Design Setting Object
| Field | Type | Description |
|---|---|---|
setting_id | integer | Unique setting ID (primary key, read-only) |
setting_name | string | Machine-readable name identifying this design setting (EG primary_color, header_font); max 255 characters required on create |
setting_value | text | Current value for this setting (EG a hex color code, font name, or numeric option) required on create |
layout_group | string | The layout or theme group this setting belongs to (EG default_layout); max 255 characters required on create |
revision_timestamp | timestamp | Timestamp of the last modification to this record (auto-managed) |
List Design Settings
Example Request
curl -X GET "https://www.yourdomain.com/api/v2/website_design_settings/get?limit=25" \ -H "X-Api-Key: your-api-key-here"
Example Response
{
"status": "success",
"message": [
{
"setting_id": "3",
"setting_name": "website_id",
"setting_value": "3579",
"layout_group": "default_layout",
"revision_timestamp": "2016-02-12 18:18:02"
}
],
"total": "769",
"current_page": 1,
"total_pages": 31,
"next_page": "MipfKjI1"
}Retrieve a Design Setting
Example Request
curl -X GET "https://www.yourdomain.com/api/v2/website_design_settings/get/3" \ -H "X-Api-Key: your-api-key-here"
Example Response
{
"status": "success",
"message": [
{
"setting_id": "3",
"setting_name": "website_id",
"setting_value": "3579",
"layout_group": "default_layout",
"revision_timestamp": "2016-02-12 18:18:02"
}
],
"total": "1",
"current_page": 1,
"total_pages": 1
}Create a Design Setting
Example Request
curl -X POST "https://www.yourdomain.com/api/v2/website_design_settings/create" \ -H "X-Api-Key: your-api-key-here" \ -d "setting_name=custom_accent_color" \ -d "setting_value=%23FF6600" \ -d "layout_group=default_layout"
Example Response
{
"status": "success",
"message": {
"setting_id": "5737",
"setting_name": "custom_accent_color",
"setting_value": "#FF6600",
"layout_group": "default_layout",
"revision_timestamp": null
}
}Update a Design Setting
Example Request
curl -X PUT "https://www.yourdomain.com/api/v2/website_design_settings/update" \ -H "X-Api-Key: your-api-key-here" \ -d "setting_id=5737" \ -d "setting_value=%23CC5500"
Example Response
{
"status": "success",
"message": {
"setting_id": "5737",
"setting_name": "custom_accent_color",
"setting_value": "#CC5500",
"layout_group": "default_layout",
"revision_timestamp": "2026-04-03 10:00:00"
}
}Delete a Design Setting
Example Request
curl -X DELETE "https://www.yourdomain.com/api/v2/website_design_settings/delete" \ -H "X-Api-Key: your-api-key-here" \ -d "setting_id=5737"
Example Response
{
"status": "success",
"message": "website_design_settings record was deleted"
}Read Design Settings Context
Reads the current values of several design settings by name in one call, and reports which names have no record, which names are stored more than once, and the status of the add-ons that control design settings options. Use it before Apply Design Settings Changes to read the values that the change will be checked against.
/api/v2/website_design_settings/get/{setting_id}), on the Advanced Endpoints tab of the key's Permissions. A key without it receives HTTP 403.Request Parameters
| Parameter | Type | Description |
|---|---|---|
names | string | Optional. Comma-separated setting names, sent in the query string. Each name is 1 to 64 letters, digits, _ or -; at most 1,000 names per call. Omit it to read every design setting on the site |
Response Fields
All fields are inside message.
| Field | Type | Description |
|---|---|---|
values | object | Each requested setting that has exactly one record, mapped to its current value. Names match exactly, including letter case: a request for Custom_1 when the record is stored as custom_1 lists it under missing |
missing | array of string | Requested names that have no record on the site |
duplicates | array of object | Names stored in more than one record, each as {"name", "ids"} with the setting_id of every copy. Their values are not included in values |
labels | object | For a setting whose whole value is a text label token (EG %%%streaming_blog_title%%%), the label's name mapped to the text the site displays for it (EG Read Our Blog Articles). Empty when no returned value is a label token |
addons | object | Each add-on that controls design settings options, mapped to true when it is active on the site and false when it is not |
layouts_active | boolean | true when an active website layout supplies the site's head code and CSS instead of the design settings records |
Example Request
curl -X GET "https://www.yourdomain.com/api/v2/website_design_settings/context?names=custom_1,custom_2,custom_accent_color" \ -H "X-Api-Key: your-api-key-here"
Example Response
{
"status": "success",
"message": {
"values": {
"custom_1": "rgb(255, 255, 255)",
"custom_2": "rgb(41, 41, 41)"
},
"missing": [
"custom_accent_color"
],
"duplicates": [],
"labels": {},
"addons": {
"post_carousel_slider": true,
"global_keyword_search": true,
"sell_feature_post": true,
"clickable_maps": true,
"streaming_featured_members": true,
"featured_blog_article_slider": true,
"events_calendar": true,
"google_translate": true,
"add_to_favorites": true,
"bookmark_counter": true,
"filter_by_star_rating": true,
"location_autofill": true,
"albums_search_results_slider": true,
"grid_view_search_reults": true,
"google_map_search_results": true,
"personal_post_feed": true,
"announcement_bar": true,
"adblock_blocker": true,
"recurring_events": true,
"homepage_background_slideshow": true
},
"layouts_active": false
}
}An invalid name returns HTTP 400 with "message": "Invalid setting name: <name>". Any request method other than GET returns HTTP 405 Invalid Request Method.
Apply Design Settings Changes
Creates, updates and deletes several design settings in one call. The call is all or nothing: every change is checked before anything is written, and if any change is refused, nothing is written and the response names each refused change with its reason. The response reports each setting's value before and after, so a change can be undone by sending the before values back.
/api/v2/website_design_settings/create, /update and /delete), all three, because one call can create, update and delete. A key missing any of them receives HTTP 403.Request Parameters
| Parameter | Type | Description |
|---|---|---|
changes | string (JSON) | Required. One form field holding a JSON object with the keys below. Unknown keys are refused |
The changes Object
| Key | Type | Description |
|---|---|---|
set | array of object | Settings to create or update, each {"name", "value", "expect"}. value is a string and is trimmed before it is saved. A name with no record is created; setting an empty value on a name with no record does nothing |
delete | array of object | Settings to delete, each {"name", "expect"}. Deleting a name with no record does nothing |
expect | string or null | Optional, on any set or delete entry. A string: the change is refused unless the stored value still equals it. null: the change is refused unless the setting has no record. Omit it to skip the check |
refresh | boolean | Optional, defaults to true. When true, the site's settings cache is refreshed after the changes are saved, so they show on the live site. false saves the changes without refreshing the cache |
One call can hold up to 100 changes across set and delete, and must hold at least one. A name may appear only once per call. A change that would leave the stored value as it is (the same value, or a delete of a name with no record) is reported under unchanged and not written.
Refused Changes
A change is refused, and nothing in the call is written, when:
- The name is not 1 to 64 letters, digits,
_or-, or is a number. - The name is
website_head,website_css,website_headerorwebsite_footer, or one of those names ending in_old, in any letter case. These hold site-wide code and are not changed by this endpoint. - The name appears more than once in the call.
valueis missing or is not a string, orexpectis not a string ornull.- An entry carries a key other than
name,valueandexpect(nameandexpectfor a delete). - The stored value no longer matches
expect:`name` changed since it was read. Read again. - The name is stored in more than one record (the reason lists their ids), or is stored under a different letter case (the reason names the stored spelling).
The checks run in two stages. The checks on names and the shape of each entry (the first five above) run first; the checks against the stored values (the last two) run only once every entry has passed the first stage, so a call refused in the first stage does not report stored-value problems yet. A refused call returns HTTP 400 with "message": "Nothing was written. N item(s) refused." and a refused list of {"item", "reason"}.
Response Fields
All fields are inside message.
| Field | Type | Description |
|---|---|---|
status | string | applied |
changed | array of object | Each setting written, as {"name", "before", "after", "created", "deleted"}. before is null for a created setting and after is null for a deleted one |
unchanged | array of string | Names whose change would not have altered anything, so nothing was written for them |
cache | string | success or failed for the settings cache refresh, or skipped when refresh was false or nothing was written |
Example Request
curl -X POST "https://www.yourdomain.com/api/v2/website_design_settings/apply" \
-H "X-Api-Key: your-api-key-here" \
--data-urlencode 'changes={"set":[{"name":"custom_2","value":"rgb(40, 40, 40)","expect":"rgb(41, 41, 41)"},{"name":"custom_accent_color","value":"#FF6600","expect":null}],"delete":[{"name":"old_accent_color"}]}'Example Response
{
"status": "success",
"message": {
"status": "applied",
"changed": [
{
"name": "custom_2",
"before": "rgb(41, 41, 41)",
"after": "rgb(40, 40, 40)",
"created": false,
"deleted": false
},
{
"name": "custom_accent_color",
"before": null,
"after": "#FF6600",
"created": true,
"deleted": false
}
],
"unchanged": [
"old_accent_color"
],
"cache": "success"
}
}Example Response (refused)
{
"status": "error",
"message": "Nothing was written. 2 item(s) refused.",
"refused": [
{
"item": "custom_1",
"reason": "`custom_1` changed since it was read. Read again."
},
{
"item": "custom_2",
"reason": "`custom_2` changed since it was read. Read again."
}
]
}How Apply Saves Changes
- Values are saved the same way the Design Settings page saves them. The Read Design Settings Context endpoint returns them exactly as sent, after trimming.
- An updated setting keeps its
layout_group; a created setting getsdefault_layout. - Only one apply call runs at a time on a site. A call that cannot start within 5 seconds returns
Another change to this site's design settings is in progress. Try again.and writes nothing. - If saving fails part way through, the changes already saved are put back and the response says
every change was put back, or lists undernot_restoredany setting that could not be. - Each call that writes a change adds one entry to the Activity Tracker listing every setting created, updated or deleted, with its old and new values.
- The Design Settings page and the Update a Design Setting endpoint do not wait for an apply call, so
expectprotects against another apply call but cannot block a save made at the same moment through those.
Any request method other than POST returns HTTP 405 Invalid Request Method.
