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.

Model name in URL: website_design_settings — DB table: website_design_settings

The Design Setting Object

FieldTypeDescription
setting_idintegerUnique setting ID (primary key, read-only)
setting_namestringMachine-readable name identifying this design setting (EG primary_color, header_font); max 255 characters required on create
setting_valuetextCurrent value for this setting (EG a hex color code, font name, or numeric option) required on create
layout_groupstringThe layout or theme group this setting belongs to (EG default_layout); max 255 characters required on create
revision_timestamptimestampTimestamp of the last modification to this record (auto-managed)

List Design Settings

GET /api/v2/website_design_settings/get

Example Request

Copy
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

Copy
{
  "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

GET /api/v2/website_design_settings/get/{setting_id}

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/website_design_settings/get/3" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "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

POST /api/v2/website_design_settings/create

Example Request

Copy
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

Copy
{
  "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

PUT /api/v2/website_design_settings/update

Example Request

Copy
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

Copy
{
  "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

DELETE /api/v2/website_design_settings/delete

Example Request

Copy
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

Copy
{
  "status": "success",
  "message": "website_design_settings record was deleted"
}

Read Design Settings Context

GET /api/v2/website_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.

Permission: the API key needs the GET permission of Design Settings (/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

ParameterTypeDescription
namesstringOptional. 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.

FieldTypeDescription
valuesobjectEach 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
missingarray of stringRequested names that have no record on the site
duplicatesarray of objectNames stored in more than one record, each as {"name", "ids"} with the setting_id of every copy. Their values are not included in values
labelsobjectFor 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
addonsobjectEach add-on that controls design settings options, mapped to true when it is active on the site and false when it is not
layouts_activebooleantrue when an active website layout supplies the site's head code and CSS instead of the design settings records

Example Request

Copy
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

Copy
{
  "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

POST /api/v2/website_design_settings/apply

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.

Permission: the API key needs the POST, PUT and DELETE permissions of Design Settings (/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

ParameterTypeDescription
changesstring (JSON)Required. One form field holding a JSON object with the keys below. Unknown keys are refused

The changes Object

KeyTypeDescription
setarray of objectSettings 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
deletearray of objectSettings to delete, each {"name", "expect"}. Deleting a name with no record does nothing
expectstring or nullOptional, 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
refreshbooleanOptional, 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_header or website_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.
  • value is missing or is not a string, or expect is not a string or null.
  • An entry carries a key other than name, value and expect (name and expect for 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.

FieldTypeDescription
statusstringapplied
changedarray of objectEach setting written, as {"name", "before", "after", "created", "deleted"}. before is null for a created setting and after is null for a deleted one
unchangedarray of stringNames whose change would not have altered anything, so nothing was written for them
cachestringsuccess or failed for the settings cache refresh, or skipped when refresh was false or nothing was written

Example Request

Copy
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

Copy
{
  "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)

Copy
{
  "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 gets default_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 under not_restored any 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 expect protects 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.