API Reference - Refresh Cache

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

← Back to API Reference | Getting Started

Refresh Cache

The Refresh Cache endpoint triggers a cache rebuild for the current website programmatically. It is the API equivalent of clicking the Refresh Live Website button in the admin panel. Use this endpoint after making changes through the API (creating widgets, updating settings, importing data, etc.) so the changes become visible on the live site without an admin having to push the button manually.

Model name in URL: website_settings — Action endpoint. Refreshes the current site's cache and always purges LiteSpeed cache regardless of scope.

Refresh the Cache

POST /api/v2/website_settings/refreshCache

Refreshes the cache for the website that owns the API key being used. Site identification is automatic; no website_id parameter is needed. All three parameters are optional.

Request Parameters

ParameterTypeDescription
scopestringComma-separated list of cache areas to refresh. Valid values: data_widgets, settings, web_pages, css, menus, sidebars. Omit this parameter to perform a full cache refresh (all areas)
fullbooleanApplies only when scope is omitted. When true, also runs the heavier maintenance operations: database table optimization and file permission fixes. Defaults to false. Ignored when scope is provided
verbosebooleanWhen true, the response includes per-area success/failure status and timing details. Defaults to false

Response Fields

FieldTypeDescription
statusstringsuccess or error
messagestringHuman-readable summary (EG Cache refreshed successfully) or, on error, the failure reason
areas_refreshedarray of stringList of cache areas that were refreshed in this call
scopestringThe scope that was refreshed; either the comma-separated area list passed in, or full when no scope was provided
fullbooleanIncluded only on full refreshes; indicates whether the heavier maintenance operations were run
detailsobjectIncluded only when verbose=true. Maps each refreshed area to {status, time_ms} (and error on failure)
total_time_msintegerIncluded only when verbose=true. Total time in milliseconds across all refreshed areas

Example Request — Full Refresh

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

Example Response — Full Refresh

Copy
{
  "status": "success",
  "message": "Cache refreshed successfully",
  "areas_refreshed": [
    "data_widgets",
    "settings",
    "web_pages",
    "css",
    "menus",
    "sidebars"
  ],
  "scope": "full",
  "full": false
}

Example Request — Scoped Refresh

Refresh only the widget cache and the menu cache, useful after creating widgets or editing menus through the API:

Copy
curl -X POST "https://www.yourdomain.com/api/v2/website_settings/refreshCache" \
  -H "X-Api-Key: your-api-key-here" \
  -d "scope=data_widgets,menus"

Example Response — Scoped Refresh

Copy
{
  "status": "success",
  "message": "Cache refreshed successfully",
  "areas_refreshed": [
    "data_widgets",
    "menus"
  ],
  "scope": "data_widgets,menus"
}

Example Request — Full Refresh with Maintenance

Equivalent to the admin UI Refresh Live Website button: full cache refresh plus database table optimization and file permission fixes:

Copy
curl -X POST "https://www.yourdomain.com/api/v2/website_settings/refreshCache" \
  -H "X-Api-Key: your-api-key-here" \
  -d "full=true"

Example Response — Full Refresh with Verbose Output

Adding verbose=true produces per-area timing data:

Copy
{
  "status": "success",
  "message": "Cache refreshed successfully",
  "areas_refreshed": [
    "data_widgets",
    "settings",
    "web_pages",
    "css",
    "menus",
    "sidebars",
    "db_optimization",
    "file_permissions"
  ],
  "scope": "full",
  "full": true,
  "details": {
    "data_widgets":     { "status": "success" },
    "settings":         { "status": "success" },
    "web_pages":        { "status": "success" },
    "css":              { "status": "success" },
    "menus":            { "status": "success" },
    "sidebars":         { "status": "success" },
    "db_optimization":  { "status": "success" },
    "file_permissions": { "status": "success" }
  },
  "total_time_ms": 4500
}
Note: Cache refresh runs synchronously and can take several seconds on large sites. The HTTP request will not return until the refresh completes. Plan client-side timeouts accordingly.

Errors

StatusCause
401Missing or invalid X-Api-Key header
400Returned with status: error when scope contains a value that is not in the valid areas list. The message field names the invalid value and lists the valid options
429Rate limit exceeded
405HTTP method other than POST