Site cache group and per-site changes cache-sites
View or set the cache group used by one site and its per-site changes (added, modified, deleted rules and the ignore-params list).
Pick an endpoint to see its example call on the right.
Authentication
Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.
X-API-Key
Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).
Conventions
Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.
Times are RFC 3339 (UTC); amounts are in cents.
Writes return 200/201/204 on success; duplicates of a unique key return 409.
/api/v2/cache-sites/{id}Site cache group and per-site changes
Authentication: User (some parameters admin only)
/api/v2/cache-sites/{id}Change the cache group used by a site
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
expected_updated_at | string | Optimistic lock (used on update) - the updated_at of the resource as the caller read it. If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check; ignored on create. |
group_idRequired | integer | Group referenced explicitly; null = follows the default group. |
keep | boolean | Whether to keep the per-site changes when switching; omitted or true = keep and convert them by the group-change rules, false = drop them (clear) and follow the new group entirely. |
/api/v2/cache-sites/{id}/overlaySave the per-site cache changes
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
expected_updated_at | string | Optimistic lock (used on update) - the updated_at of the resource as the caller read it. If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check; ignored on create. |
overlayRequired | object | Per-site changes; null = none. |
/api/v2/cache-sites/{id}/overlayReset the site to its cache group as is
Authentication: User (some parameters admin only)
/api/v2/cache-sites/{id}/switch-previewPreview the site's rules after switching cache group
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
group_id | integer | Id of the target cache group (a platform group or one owned by the site's tenant); omit = follow the default group. |
keep | boolean | Whether to keep the per-site changes, default true; false = drop them and follow the new group entirely. |
Site cache group and per-site changes object
| Field | Type | Description |
|---|---|---|
counts | object | Summary counts after the switch. |
effective | CacheConfig | Cache rules, same as the cache field ({rules, ignore_params}) of the node contract schema/site.json; validated by the server against the contract. |
effective_group_id | integer | Group actually in effect; null = no usable group (the factory preset applies; no group rules are pushed). |
expected_updated_at | string | Optimistic lock (used on update) - the updated_at of the resource as the caller read it. If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check; ignored on create. |
group_id | integer | Group referenced explicitly; null = follows the default group. |
group_ignore_params | string[] | The group's own ignore-params list after the switch. |
group_name | string | Name of the group in effect after the switch; omitted when there is no usable group. |
ignore_params | string[] | The ignore-params list in effect after the switch. |
ignore_params_changed | boolean | Whether the ignore-params list is this site's own value (differs from the group). |
keep | boolean | Whether to keep the per-site changes when switching; omitted or true = keep and convert them by the group-change rules, false = drop them (clear) and follow the new group entirely. |
overlay | object | Per-site changes; null = none. |
overlay_count | integer | Number of changes: rule changes + 1 if the ignore-params list is changed. |
rows | CacheSwitchRow[] | Rules one by one in display order; deleted rows stay at their position in the group. |
site_id | integer | Site ID |
updated_at | string | updated_at of the site (the version of the site row, also bumped when the group or the per-site changes are changed); send it back as expected_updated_at when writing. |
Responses and errors
Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"code": "validation_failed",
"detail": "Invalid request parameters",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name is required"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}