CC filters cc-filters
How matched requests are handled: rate limiting or a challenge (JS, slider, captcha and so on).
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/cc-filtersList CC filters
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
sort | string | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
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 |
name | string | Filter by name substring. |
owner | string | platform = platform objects only; tenant = tenant objects only. |
/api/v2/cc-filtersCreate CC filter
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
count_key | string | Who to count by (rate/challenge): ip = client IP (default, existing behavior); ja4 = TLS fingerprint only, regardless of IP — real visitors sharing the fingerprint are counted together, so it is allowed with the log action only (a rule item with ban/deny is rejected with 422); to punish use ip_ja4 = same IP and same fingerprint combined. Plaintext requests have no fingerprint, so ja4/ip_ja4 fall back to IP. Not used by url_auth (must be ip). |
des | string | Remark; empty if omitted (omitting it on update also clears it, since the update replaces the whole object). |
kind | string | Challenge type (required for challenge): js/redirect/slide/captcha/click/delay_jump/rotate/cookie; not used for rate. |
maxRequired | integer | Requests allowed within the window. |
mode | string | Required for url_auth: signing scheme. a = ?<sign_arg>=md5(key+path+timestamp)&<time_arg>=timestamp; b = ?<sign_arg>=timestamp-random-uid-md5(path-timestamp-random-uid-key). |
nameRequired | string | Name |
per_uri_max | integer | rate: per-URI limit; 0 = unlimited. |
sign_arg | string | Required for url_auth: name of the signature query parameter (letters, digits, underscore, hyphen). |
sign_use_max | integer | url_auth: how many times the same signature may be used; 0 = unlimited. |
time_arg | string | Required for url_auth with mode=a: name of the timestamp query parameter; not used with mode=b. |
ttl_s | integer | Required for url_auth (1 to 2592000): maximum difference in seconds between the signed timestamp and the current time. |
typeRequired | string | rate = request rate; challenge = challenge (the type is given by kind); url_auth = URL signature check (the signing key is the site's config.url_auth_salt). |
window_sRequired | integer | Counting window in seconds. |
/api/v2/cc-filters/{id}Get CC filter
Authentication: User (some parameters admin only)
/api/v2/cc-filters/{id}Update CC filter
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
count_key | string | Who to count by (rate/challenge): ip = client IP (default, existing behavior); ja4 = TLS fingerprint only, regardless of IP — real visitors sharing the fingerprint are counted together, so it is allowed with the log action only (a rule item with ban/deny is rejected with 422); to punish use ip_ja4 = same IP and same fingerprint combined. Plaintext requests have no fingerprint, so ja4/ip_ja4 fall back to IP. Not used by url_auth (must be ip). |
des | string | Remark; empty if omitted (omitting it on update also clears it, since the update replaces the whole object). |
kind | string | Challenge type (required for challenge): js/redirect/slide/captcha/click/delay_jump/rotate/cookie; not used for rate. |
maxRequired | integer | Requests allowed within the window. |
mode | string | Required for url_auth: signing scheme. a = ?<sign_arg>=md5(key+path+timestamp)&<time_arg>=timestamp; b = ?<sign_arg>=timestamp-random-uid-md5(path-timestamp-random-uid-key). |
nameRequired | string | Name |
per_uri_max | integer | rate: per-URI limit; 0 = unlimited. |
sign_arg | string | Required for url_auth: name of the signature query parameter (letters, digits, underscore, hyphen). |
sign_use_max | integer | url_auth: how many times the same signature may be used; 0 = unlimited. |
time_arg | string | Required for url_auth with mode=a: name of the timestamp query parameter; not used with mode=b. |
ttl_s | integer | Required for url_auth (1 to 2592000): maximum difference in seconds between the signed timestamp and the current time. |
typeRequired | string | rate = request rate; challenge = challenge (the type is given by kind); url_auth = URL signature check (the signing key is the site's config.url_auth_salt). |
window_sRequired | integer | Counting window in seconds. |
/api/v2/cc-filters/{id}Delete CC filter
Authentication: User (some parameters admin only)
CC filters object
| Field | Type | Description |
|---|---|---|
builtin | boolean | Built-in object; cannot be deleted. |
count_key | string | Who to count by (rate/challenge): ip = client IP (default, existing behavior); ja4 = TLS fingerprint only, regardless of IP — real visitors sharing the fingerprint are counted together, so it is allowed with the log action only (a rule item with ban/deny is rejected with 422); to punish use ip_ja4 = same IP and same fingerprint combined. Plaintext requests have no fingerprint, so ja4/ip_ja4 fall back to IP. Not used by url_auth (must be ip). |
created_at | string | Created at |
des | string | Remark; empty if omitted (omitting it on update also clears it, since the update replaces the whole object). |
id | integer | Record ID |
kind | string | Challenge type (required for challenge): js/redirect/slide/captcha/click/delay_jump/rotate/cookie; not used for rate. |
max | integer | Requests allowed within the window. |
mode | string | Required for url_auth: signing scheme. a = ?<sign_arg>=md5(key+path+timestamp)&<time_arg>=timestamp; b = ?<sign_arg>=timestamp-random-uid-md5(path-timestamp-random-uid-key). |
name | string | Name |
per_uri_max | integer | rate: per-URI limit; 0 = unlimited. |
sign_arg | string | Required for url_auth: name of the signature query parameter (letters, digits, underscore, hyphen). |
sign_use_max | integer | url_auth: how many times the same signature may be used; 0 = unlimited. |
tenant_id | integer | Owning tenant; null = platform object (built-in or created by an admin, read-only for tenants). |
time_arg | string | Required for url_auth with mode=a: name of the timestamp query parameter; not used with mode=b. |
ttl_s | integer | Required for url_auth (1 to 2592000): maximum difference in seconds between the signed timestamp and the current time. |
type | string | rate = request rate; challenge = challenge (the type is given by kind); url_auth = URL signature check (the signing key is the site's config.url_auth_salt). |
updated_at | string | Updated at |
window_s | integer | Counting window in seconds. |
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"
}