API Reference - Website Settings

Link: https://support.brilliantdirectories.com/support/solutions/articles/12000108661

← Back to API Reference | Getting Started

Website Settings

Website Settings is the key/value store behind the platform's site-wide configuration. Each record stores a single setting (field) along with its current value (result), grouped by a category and rendered in the admin UI according to field_type and display_name. This is what powers the admin panels under Settings → Advanced Settings and related configuration pages. Most integrations read these values; create/update/delete should be used with care because changing the wrong field can affect platform behavior.

Model name in URL: website_settings — DB table: website_settings

The Website Setting Object

FieldTypeDescription
idintegerUnique website setting ID (primary key, read-only)
categorystringSetting category grouping (EG general, email, seo); max 255 characters required on create
fieldstringSetting field key referenced from code (EG site_name, default_search_url); max 255 characters; must be unique across the table required on create
resulttextCurrent value of the setting required on create
date_updatedstringDate the setting was last updated (format: YYYYMMDDHHmmss)
desctextDescription of what this setting controls
display_namestringHuman-readable label shown in the admin UI
sortintegerDisplay order within the admin UI category
field_typestringInput control rendered in the admin UI (EG text, textarea, select, checkbox)
Refreshing the site cache after changes: After creating or updating settings through the API, the live site will continue to serve the old cached values until the cache is refreshed. Use the website_settings/refreshCache endpoint to refresh the cache programmatically.

Retrieve a Website Setting

GET /api/v2/website_settings/get/{id}

Returns a single website setting record by its id.

Example Request

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

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "id": "42",
      "category": "general",
      "field": "site_name",
      "result": "My Directory",
      "date_updated": "20240115103000",
      "desc": "The public site name shown in the header",
      "display_name": "Site Name",
      "sort": "1",
      "field_type": "text"
    }
  ],
  "total": "1",
  "current_page": 1,
  "total_pages": 1
}

Create a Website Setting

POST /api/v2/website_settings/create

Creates a new website setting record. The category, field, and result fields are required. The field must be unique across the table.

Required Fields

ParameterTypeDescription
categorystringRequired — setting category grouping
fieldstringRequired — unique field key used in code
resulttextRequired — setting value

Example Request

Copy
curl -X POST "https://www.yourdomain.com/api/v2/website_settings/create" \
  -H "X-Api-Key: your-api-key-here" \
  -d "category=general" \
  -d "field=custom_welcome_message" \
  -d "result=Welcome+to+our+directory" \
  -d "display_name=Welcome+Message" \
  -d "field_type=textarea" \
  -d "sort=10"

Example Response

Copy
{
  "status": "success",
  "message": {
    "id": "412",
    "category": "general",
    "field": "custom_welcome_message",
    "result": "Welcome to our directory",
    "display_name": "Welcome Message",
    "field_type": "textarea",
    "sort": "10"
  }
}

Update a Website Setting

PUT /api/v2/website_settings/update

Updates an existing setting. The id is required in the request body. Only include the fields you want to change.

Example Request

Copy
curl -X PUT "https://www.yourdomain.com/api/v2/website_settings/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "id=412" \
  -d "result=Welcome+to+our+brand+new+directory"

Example Response

Copy
{
  "status": "success",
  "message": {
    "id": "412",
    "category": "general",
    "field": "custom_welcome_message",
    "result": "Welcome to our brand new directory",
    "display_name": "Welcome Message",
    "field_type": "textarea",
    "sort": "10"
  }
}

Delete a Website Setting

DELETE /api/v2/website_settings/delete

Deletes a setting record. The id is required.

Caution: Deleting a setting that the platform expects to find (EG a built-in field the codebase reads at runtime) can break site functionality. Only delete settings you created via the API or that you are certain are no longer referenced.

Example Request

Copy
curl -X DELETE "https://www.yourdomain.com/api/v2/website_settings/delete" \
  -H "X-Api-Key: your-api-key-here" \
  -d "id=412"

Example Response

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