Value-added protection schemes protect-schemes
One scheme each for replay, data leak and web tamper protection (one per tenant; admins edit the platform scheme); saving also updates sites that follow the scheme, sites with their own settings are left alone; part of WAF Enhanced.
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/protect-schemes/leakGet the data leak protection scheme
Authentication: User (some parameters admin only)
/api/v2/protect-schemes/leakSave the data leak protection scheme
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
auto_join | object | The rule that sites newly entering the range join the scheme automatically; omitted when off. |
customRequired | SiteLeakGuardCustom[] | Custom regular expressions, at most 16. |
detectRequired | SiteLeakGuardDetect | Action per built-in pattern; omit a pattern to not check it. |
enabled | boolean | Scheme master switch: when on, sites following the scheme use it; when off, those sites are turned off (their values kept) and the auto-join rule is paused. False if never saved. |
excludeRequired | string[] | Path prefixes that are not checked (a trailing * is optional), at most 32. |
expected_updated_at | string | Optimistic lock - the updated_at as the caller read it (when null, i.e. never saved, use 1970-01-01T00:00:00Z). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check. |
observe_daysRequired | integer | Days a site observes when turned on by the scheme (record only, no action); 0 = act right away. |
override_custom | boolean | Omit or false only - sites with their own settings are left alone (counted in apply.skipped_custom); use reset to scheme to override them. |
selection | object | Sites to add to the scheme this time; send only when the switch is on after saving and the range was changed. Omit to add no sites. |
/api/v2/protect-schemes/replayGet the replay protection scheme
Authentication: User (some parameters admin only)
/api/v2/protect-schemes/replaySave the replay protection scheme
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
action | ReplayGuardAction | Without a token or on replay: block = 403; challenge = JS challenge. Omitted = block. |
app_salt | string | Signing salt (app key, 32-byte hex); with app_sign on but no salt, signed headers are never accepted. |
app_sign | boolean | App signature check - requests carrying the signature headers are checked by signature, no token needed. |
auto_join | object | The rule that sites newly entering the range join the scheme automatically; omitted when off. |
bind_ip | boolean | Also bind the token to the client IP (a new IP invalidates it). |
enabled | boolean | Scheme master switch: when on, sites following the scheme use it; when off, those sites are turned off (their values kept) and the auto-join rule is paused. False if never saved. |
expected_updated_at | string | Optimistic lock - the updated_at as the caller read it (when null, i.e. never saved, use 1970-01-01T00:00:00Z). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check. |
methods | ReplayGuardMethod[] | Protected methods; omitted = POST/PUT/PATCH/DELETE. |
override_custom | boolean | Omit or false only - sites with their own settings are left alone (counted in apply.skipped_custom); use reset to scheme to override them. |
paths | ReplayGuardPath[] | Protected API paths, at most 64; empty = nothing protected. |
selection | object | Sites to add to the scheme this time; send only when the switch is on after saving and the range was changed. Omit to add no sites. |
ttl_s | integer | Token lifetime in seconds, also used for signed-header timestamps; omitted = 120. |
/api/v2/protect-schemes/replay/suggestionsList suggested replay protection endpoints
Authentication: User (some parameters admin only)
/api/v2/protect-schemes/tamperGet the web tamper protection scheme
Authentication: User (some parameters admin only)
/api/v2/protect-schemes/tamperSave the web tamper protection scheme
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
actionRequired | ReplayGuardAction | Without a token or on replay: block = 403; challenge = JS challenge. Omitted = block. |
auto_join | object | The rule that sites newly entering the range join the scheme automatically; omitted when off. |
enabled | boolean | Scheme master switch: when on, sites following the scheme use it; when off, those sites are turned off (their values kept) and the auto-join rule is paused. False if never saved. |
expected_updated_at | string | Optimistic lock - the updated_at as the caller read it (when null, i.e. never saved, use 1970-01-01T00:00:00Z). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check. |
modeRequired | string | What counts as tampering: structure = structural changes only; full = any change to the page. |
observe_daysRequired | integer | Days a site observes when turned on by the scheme (record only, no action); 0 = act right away. |
override_custom | boolean | Omit or false only - sites with their own settings are left alone (counted in apply.skipped_custom); use reset to scheme to override them. |
scopesRequired | SiteTamperScope[] | Protected scopes, at most 50. |
selection | object | Sites to add to the scheme this time; send only when the switch is on after saving and the range was changed. Omit to add no sites. |
/api/v2/protect-schemes/{kind}/applyApply the scheme to sites in bulk
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
auto_join | object | The rule that sites newly entering the range join the scheme automatically; omitted when off. |
dry_run | boolean | When true, only return the counts of what would happen; nothing is written. |
mode | string | What counts as tampering: structure = structural changes only; full = any change to the page. |
override_custom | boolean | Omit or false only - sites with their own settings are left alone (counted in apply.skipped_custom); use reset to scheme to override them. |
selection | object | Sites to add to the scheme this time; send only when the switch is on after saving and the range was changed. Omit to add no sites. |
/api/v2/protect-schemes/{kind}/sitesList the sites that have this protection set up
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
q | string | Fuzzy search by domain or site name (case-insensitive). |
status | ProtectSchemeSiteStatus | Filter by status. |
source | ProtectSiteSource | Filter by source: scheme = follows the scheme; custom = set for the site alone (including turned off). |
/api/v2/protect-schemes/{kind}/sites/bulkReset or turn off this protection for many sites
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
actionRequired | ReplayGuardAction | Without a token or on replay: block = 403; challenge = JS challenge. Omitted = block. |
filter | ProtectSchemeSiteFilter | The same filters as the list; expanded to a set of sites by the server. |
ids | integer[] | Site ids. |
Value-added protection schemes object
| Field | Type | Description |
|---|---|---|
action | ReplayGuardAction | Without a token or on replay: block = 403; challenge = JS challenge. Omitted = block. |
app_salt | string | Signing salt (app key, 32-byte hex); with app_sign on but no salt, signed headers are never accepted. |
app_sign | boolean | App signature check - requests carrying the signature headers are checked by signature, no token needed. |
applied | integer | Sites written (to be written on dry_run). |
apply | object | Result of applying this save to sites (only in the save response). |
auto_join | object | The rule that sites newly entering the range join the scheme automatically; omitted when off. |
bind_ip | boolean | Also bind the token to the client IP (a new IP invalidates it). |
counts | ProtectSchemeCounts | Site counts among the sites visible to the caller: total, turned on, following the scheme, set alone, and excluded by plan. |
custom | SiteLeakGuardCustom[] | Custom regular expressions, at most 16. |
demoted_sites | integer | Sites switched to their own settings with values kept because their owner lacks WAF Enhanced (only in the save response). |
detect | SiteLeakGuardDetect | Action per built-in pattern; omit a pattern to not check it. |
domain | string | Primary domain (the site name when there is none). |
dry_run | boolean | When true, only return the counts of what would happen; nothing is written. |
enabled | boolean | Scheme master switch: when on, sites following the scheme use it; when off, those sites are turned off (their values kept) and the auto-join rule is paused. False if never saved. |
exclude | string[] | Path prefixes that are not checked (a trailing * is optional), at most 32. |
expected_updated_at | string | Optimistic lock - the updated_at as the caller read it (when null, i.e. never saved, use 1970-01-01T00:00:00Z). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check. |
failed | ProtectSchemeFailure[] | Sites that could not be handled, with the reason; at most 100. |
failed_total | integer | Total sites that could not be handled (larger than failed when truncated). |
filter | ProtectSchemeSiteFilter | The same filters as the list; expanded to a set of sites by the server. |
gate | ProtectSchemeGate | WAF Enhanced status of the scheme owner (the tenant or the platform): full = editable; readonly and basic = may only be reduced. |
ids | integer[] | Site ids. |
is_default | boolean | True when the scheme has never been saved and the settings are defaults (not stored); omitted once saved. |
items | ReplaySchemeSuggestion[] | Ordered by POST count descending, at most 3; empty when there is no data or ClickHouse is unavailable. |
matched | integer | Sites in the range the caller can see. |
methods | ReplayGuardMethod[] | Protected methods; omitted = POST/PUT/PATCH/DELETE. |
mode | string | What counts as tampering: structure = structural changes only; full = any change to the page. |
observe_days | integer | Days a site observes when turned on by the scheme (record only, no action); 0 = act right away. |
observe_until | integer | End of the observation period (Unix milliseconds); set only for leak protection that is on and still observing, null when expired, never observing, off, or for other protections. |
override_custom | boolean | Omit or false only - sites with their own settings are left alone (counted in apply.skipped_custom); use reset to scheme to override them. |
owner | string | Owner username. |
paths | ReplayGuardPath[] | Protected API paths, at most 64; empty = nothing protected. |
scopes | SiteTamperScope[] | Protected scopes, at most 50. |
selection | object | Sites to add to the scheme this time; send only when the switch is on after saving and the range was changed. Omit to add no sites. |
site_id | integer | Site id. |
skipped_custom | integer | Sites left alone because they have their own settings (override_custom is false). |
skipped_gate | integer | Sites not written because their owner's WAF Enhanced is not full. |
source | ProtectSiteSource | Where the site's setting comes from: scheme = follows the scheme (changes when the scheme is saved); custom = set for this site alone (including turned off and rows migrated from before). |
status | ProtectSchemeSiteStatus | Status of the site's setting: enabled; disabled; pending = on but the tamper baseline is still queued; capture_failed = on but baseline capture failed repeatedly and stopped retrying (the last two exist for web tamper protection only). |
tenant_id | integer | Owner user id. |
today_blocked | integer | Block and error-page count today (UTC), excluding hits during the observation period (leak protection only, same basis as counts.today_blocked in the scheme response); null for other protections, or when ClickHouse is unavailable or the query fails. |
today_hits | integer | Hits today (data leak protection = masked plus blocked outside the observation period, i.e. today_masked + today_blocked; web tamper protection = pages found tampered today); null for replay protection. |
today_masked | integer | Masking count today (UTC), excluding hits during the observation period (leak protection only, same basis as counts.today_masked in the scheme response); null for other protections, or when ClickHouse is unavailable or the query fails. |
ttl_s | integer | Token lifetime in seconds, also used for signed-header timestamps; omitted = 120. |
updated_at | string | Version (null if never saved); use expected_updated_at on update. |
updated_sites | integer | Sites following the scheme that this save updated (only in the save response). |
will_change | integer | dry_run only: sites that would change for the mode (turned on or joined for enable, updated for update, turned off for disable). |
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"
}