Upload scan settings upload-scan-settings
Platform-wide upload scanning (files in multipart form uploads only): master switch, dangerous extensions, double extensions, disguised files, webshell signatures, antivirus, per-file limit, scan timeout, action and exceptions; admin only. Webshell signatures, antivirus and the sha256 blocklist belong to the paid feature 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/upload-scan-settingsGet upload scan settings
Authentication: Admin only
/api/v2/upload-scan-settingsUpdate upload scan settings
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
action | string | On a hit - block, log only, or observe for 3 days (log only, then block); dangerous files have no observation period. |
disguise | boolean | Disguised file detection (image extension but the magic bytes are a script or an executable). |
double_ext | boolean | Double extension detection (e.g. a.php.jpg, a.asp;.jpg). |
enabled | boolean | Master switch; false = no site is scanned. |
enhanced | string | WAF enhanced state - full (active), readonly (expired but within the read-only buffer, License.readonly_days, 7 days by default; enhanced items still work but are read-only) or basic (not purchased or past the buffer; enhanced items are off, settings kept); ignored on update. |
exceptions | UploadScanException[] | Exceptions - skip the signature when the site and path prefix match (empty sig = the path is not scanned). Entries that tenants added by marking false positives (source=false_positive) must be sent back unchanged on replace, otherwise they are overwritten. |
expected_updated_at | string | Optimistic lock - the updated_at as the caller read it (the version of the node.global config key, shared with CC and WAF settings; use 1970-01-01T00:00:00Z when the read value is null). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check. |
exts | string[] | Dangerous extensions (lowercase, without the dot); defaults to php phtml jsp jspx asp aspx ashx cer war sh cgi shtml when omitted. Families expand (php also covers php3-8 pht phtml phar, asp covers asa cdx cer, jsp covers jspx jspf, shtml covers shtm stm); dot-leading names (.php) are judged as extensions; while the list is non-empty, .htaccess, .user.ini and web.config are blocked too. A site may override with waf.upload_exts. |
max_file_mb | integer | Per-file scan limit in MB (default 20); larger files only get the extension check and are handled per oversize. |
observe_until | string | End of the observation period (set when action is observe); ignored on update, written by the server. |
on_parse_error | string | On multipart parse errors (bad delimiter, oversized header, truncated body, too many parts) - block or allow (pass and log); default block. |
on_timeout | string | On scan timeout (or failure to read the body) - allow (pass and log) or block (default allow). |
on_virus_error | string | On virus scan errors (clamd unreachable, read/write timeout, bad reply) - allow (pass and log) or block (default allow); clamd not installed or not running means no scan, not an error. |
oversize | string | Files over the limit - allow (pass and log) or block. |
sha256 | object[] | Local sha256 blocklist (WAF enhanced). |
sig | boolean | Webshell signatures (WAF enhanced). |
timeout_s | integer | Scan timeout per request in seconds (default 2). |
updated_at | string | Version in the response (updated_at of the node.global config key; null if never changed); ignored on update. |
virus | string | Antivirus (ClamAV, WAF enhanced) - off, mem4g (nodes with at least 4 GB memory) or all nodes. |
Upload scan settings object
| Field | Type | Description |
|---|---|---|
action | string | On a hit - block, log only, or observe for 3 days (log only, then block); dangerous files have no observation period. |
disguise | boolean | Disguised file detection (image extension but the magic bytes are a script or an executable). |
double_ext | boolean | Double extension detection (e.g. a.php.jpg, a.asp;.jpg). |
enabled | boolean | Master switch; false = no site is scanned. |
enhanced | string | WAF enhanced state - full (active), readonly (expired but within the read-only buffer, License.readonly_days, 7 days by default; enhanced items still work but are read-only) or basic (not purchased or past the buffer; enhanced items are off, settings kept); ignored on update. |
exceptions | UploadScanException[] | Exceptions - skip the signature when the site and path prefix match (empty sig = the path is not scanned). Entries that tenants added by marking false positives (source=false_positive) must be sent back unchanged on replace, otherwise they are overwritten. |
expected_updated_at | string | Optimistic lock - the updated_at as the caller read it (the version of the node.global config key, shared with CC and WAF settings; use 1970-01-01T00:00:00Z when the read value is null). If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check. |
exts | string[] | Dangerous extensions (lowercase, without the dot); defaults to php phtml jsp jspx asp aspx ashx cer war sh cgi shtml when omitted. Families expand (php also covers php3-8 pht phtml phar, asp covers asa cdx cer, jsp covers jspx jspf, shtml covers shtm stm); dot-leading names (.php) are judged as extensions; while the list is non-empty, .htaccess, .user.ini and web.config are blocked too. A site may override with waf.upload_exts. |
max_file_mb | integer | Per-file scan limit in MB (default 20); larger files only get the extension check and are handled per oversize. |
observe_until | string | End of the observation period (set when action is observe); ignored on update, written by the server. |
on_parse_error | string | On multipart parse errors (bad delimiter, oversized header, truncated body, too many parts) - block or allow (pass and log); default block. |
on_timeout | string | On scan timeout (or failure to read the body) - allow (pass and log) or block (default allow). |
on_virus_error | string | On virus scan errors (clamd unreachable, read/write timeout, bad reply) - allow (pass and log) or block (default allow); clamd not installed or not running means no scan, not an error. |
oversize | string | Files over the limit - allow (pass and log) or block. |
sha256 | object[] | Local sha256 blocklist (WAF enhanced). |
sig | boolean | Webshell signatures (WAF enhanced). |
timeout_s | integer | Scan timeout per request in seconds (default 2). |
updated_at | string | Version in the response (updated_at of the node.global config key; null if never changed); ignored on update. |
virus | string | Antivirus (ClamAV, WAF enhanced) - off, mem4g (nodes with at least 4 GB memory) or all nodes. |
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"
}