Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
18.5 KB
Raw Blame
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Blocklists
description: The safety blocklists, their value forms, and the operations that manage them.
---

import RouteHeader from '@/components/RouteHeader.astro';

Fluxer has eight blocklists, and each one blocks one kind of value, such as an IP address, a link or a file hash. Each list has three [Admin ACLs](/admin-api/#acl-registry) in the form `ban:<list>:<verb>`, with hyphens in the list name written as underscores. For example, `url-domain` uses `ban:url_domain:check`. You need `check` to read a list, `add` to add or update entries and `remove` to remove them.

## Blocklist types

Fluxer normalizes each value when you add or check it and stores the normalized form. The `url`, `url-domain`, `file-sha` and `avatar-hash` lists are content blocklists, and each of their entries has a category and a severity.

| Value | Description |
| --- | --- |
| ip | IPv4 addresses, IPv6 addresses and CIDR ranges denied service |
| email | Email addresses, or `@example.com` for a domain and its subdomains, that can't be used to sign up or be set on an account |
| phrase<sup>1</sup> | Phrases blocked from content |
| url | Absolute `http` and `https` URLs blocked from being posted |
| url-domain | Domains or [domain patterns](#domain-patterns) blocked from being linked |
| file-sha | SHA-256 hashes of files blocked from upload |
| avatar-hash | 8-character avatar hashes blocked from being set, with any `a_` prefix stripped |
| profile-substring<sup>1</sup> | Substrings blocked from one [profile field](#profile-substring-scopes) |

<sup>1</sup> Matching ignores case, Unicode look-alike forms, and whitespace, punctuation or invisible characters placed between letters

## Network blocks from decisions

A permanent suspension or an account deletion for a rule violation can block the addresses the account used in the last 30 days, through `block_networks` on [Suspend user](/admin-api/users/#suspend-user) and [Schedule user deletion](/admin-api/users/#schedule-user-deletion). Those `ip` entries belong to the [enforcement decision](/admin-api/enforcement/) and expire after 90 days unless the request sets another length.

A decision takes over a plain entry that has an expiry and keeps the later of the two expiries, so ending the decision also removes that block. Add it again if you still want it. A permanent plain entry or another decision's entry is left as it is, and the request lists the address in `skipped_ips` as `already_blocked`.

Ending the decision or executing the account's deletion removes its entries.

## Domain patterns

A `url-domain` value whose leftmost label has `*` is a pattern. Each `*` matches any run of characters in that one label. For example `*shop*.example.com` matches `shop.example.com` and `my-shop-2.example.com` but not `example.com`. With `match_subdomains` true, a pattern or plain domain also matches every subdomain.

Fluxer refuses a pattern with 400 `INVALID_FORM_BODY` when `*` is outside the leftmost label, when that label has characters other than `a-z`, `0-9`, `-` and `*`, or when it has more than 3 `*` or fewer than 3 other characters. It also refuses a pattern when the part after the leftmost label isn't a valid domain or is a public suffix such as `com` or `co.uk`.

## Content blocklist categories

A category says where an entry came from. The values below are the ones Fluxer uses, but `category` accepts any string.

| Value | Description |
| --- | --- |
| manual | Added by an Admin |
| urlhaus | Imported from URLhaus |
| phishtank | Imported from PhishTank |
| google_safe_browsing | Imported from Google Safe Browsing |
| malware_bazaar | Imported from MalwareBazaar |
| ncmec | Imported from an NCMEC hash set |
| gifct | Imported from a GIFCT hash set |
| stop_ncii | Imported from a StopNCII hash set |

## Content blocklist severities

Severity is only a label for moderators, and Fluxer blocks every matching entry, even one with severity 0.

| Value | Name | Description |
| --- | --- | --- |
| 0 | ALLOW | Content to allow |
| 1 | WARN | Content to warn about |
| 2 | BLOCK | Content to refuse |
| 3 | BLOCK_AND_REPORT | Content to refuse and report |

## Profile substring scopes

| Value | Description |
| --- | --- |
| username | The account username |
| global_name | The account display name |
| nickname | A guild nickname |
| bio | The profile bio |
| pronouns | The profile pronouns |

## Blocklist object

Describes one blocklist and the fields it accepts, and [List blocklists](#list-blocklists) returns one for each list. Check `fields` and the `supports_` flags before you write to a list.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| list_type | string | The [blocklist type](#blocklist-types) |
| description | string | A summary of what the list matches |
| value_field | string | The body field that has the value when adding |
| fields | array[string] | The other body fields the list accepts |
| scoped | boolean | Whether every operation needs a `scope`, which is true only for `profile-substring` |
| supports_bulk_create | boolean | Whether [Bulk add blocklist entries](#bulk-add-blocklist-entries) works on the list |
| supports_bulk_delete | boolean | Whether [Bulk remove blocklist entries](#bulk-remove-blocklist-entries) works on the list |
| supports_update | boolean | Whether [Update blocklist entry](#update-blocklist-entry) works on the list |

## Blocklist entry object

An entry stored in a blocklist. Every field is present, and a field the list doesn't use is null.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| list_type | string | The [blocklist type](#blocklist-types) |
| value | string | The normalized value, to send as `entry_value` or `after` (1-2048 characters) |
| scope | ?string | The [profile substring scope](#profile-substring-scopes) |
| category | ?string | The [content blocklist category](#content-blocklist-categories) |
| severity | ?integer | The [content blocklist severity](#content-blocklist-severities) |
| source_url | ?string | The feed or evidence URL |
| notes | ?string | The internal note |
| content_type | ?string | The media type hint of a `file-sha` entry |
| match_subdomains | ?boolean | Whether a `url-domain` entry also covers subdomains |
| reason<sup>1</sup> | ?string | The reason stored on an `ip` entry |
| expires_at | ?ISO8601 timestamp | When an `ip` entry expires |
| created_at | ?ISO8601 timestamp | When the entry was added |
| created_by_user_id | ?snowflake | The Admin who added the entry |

<sup>1</sup> `platform_admin_enforcement` for an entry added through these routes, or `enforcement_decision` for one an enforcement decision added

### Example

```json
{
  "list_type": "url-domain",
  "value": "malicious.example.com",
  "scope": null,
  "category": "urlhaus",
  "severity": 2,
  "source_url": "https://urlhaus.example.com/entry/912",
  "notes": null,
  "content_type": null,
  "match_subdomains": true,
  "reason": null,
  "expires_at": null,
  "created_at": "2026-01-22T07:41:19.003Z",
  "created_by_user_id": "1483920011884392448"
}
```

## Blocklist check object

What [Check blocklist entry](#check-blocklist-entry) returns for one value.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| banned | boolean | Whether the list blocks the value |
| expires_at | ?ISO8601 timestamp | When the matching `ip` block expires, or null when it is permanent |
| decision_id | ?snowflake | The [enforcement decision](/admin-api/enforcement/) the matching `ip` block belongs to |

## Blocklist entry creation object

The body of [Add blocklist entry](#add-blocklist-entry) has the value field for its `list_type` and any additional fields that list accepts.

### Value field

| Blocklist | Field | Accepted value |
| --- | --- | --- |
| ip | ip | IPv4 address, IPv6 address or CIDR range (1-45 characters) |
| email | email | Email address or `@domain` (1-254 characters) |
| phrase | phrase | Phrase (1-500 characters) |
| url | url | Absolute `http` or `https` URL (1-2048 characters) |
| url-domain | domain | Domain or [domain pattern](#domain-patterns) (1-253 characters) |
| file-sha | sha256_hex | Exactly 64 hexadecimal characters |
| avatar-hash | hashes | Array of hashes matching `^(a_)?[0-9a-fA-F]{8}$` (1-1000 items) |
| profile-substring | substrings | Array of substrings (1-1000 items of 1-500 characters) |

### Additional fields

| Field | Type | Description |
| --- | --- | --- |
| scope?<sup>1</sup> | string | The [profile substring scope](#profile-substring-scopes) |
| category?<sup>2</sup> | string | The [content blocklist category](#content-blocklist-categories) (1-64 characters, default `manual`) |
| severity?<sup>2</sup> | integer | The [content blocklist severity](#content-blocklist-severities) (0-3, default 2) |
| match_subdomains? | boolean | Whether a `url-domain` entry also covers subdomains (default true) |
| content_type? | string | The media type hint of a `file-sha` entry (1-128 characters) |
| source_url?<sup>2</sup> | string | The feed or evidence URL (1-2048 characters) |
| reason? | string | The reason for `avatar-hash` and `profile-substring`, kept in the audit entry (1-1024 characters) |
| notes? | string | The internal note, for every list but `ip`, `email` and `phrase` (1-1024 characters) |
| duration_hours? | integer | Hours until an `ip` entry expires, with `0` for permanent (0-8760, default 0) |

<sup>1</sup> Required for `profile-substring`

<sup>2</sup> Only for content blocklists

## List blocklists

<RouteHeader method="GET" path="/v1/admin/blocklists" auditReason />

Returns a [blocklist object](#blocklist-object) for each blocklist. You need the `check` permission for at least one list.

### Response body

| Field | Type | Description |
| --- | --- | --- |
| items | array[[blocklist](#blocklist-object) object] | All eight blocklists |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | response body | The catalog was returned |

The rate limit is 60 requests per minute, on the `admin:ban:operation` bucket.

## List blocklist entries

<RouteHeader method="GET" path="/v1/admin/blocklists/{list_type}/entries" auditReason />

Returns a page of [blocklist entry objects](#blocklist-entry-object) ordered by value. You need the list's `check` permission.

### Query parameters

| Field | Type | Description |
| --- | --- | --- |
| limit? | integer | Maximum entries to return (1-200, default 50) |
| after? | string | Return entries after this value (1-2048 characters) |
| scope?<sup>1</sup> | string | The [profile substring scope](#profile-substring-scopes) to list |

<sup>1</sup> Required for `profile-substring` and refused with 400 `INVALID_FORM_BODY` on every other list

### Response body

| Field | Type | Description |
| --- | --- | --- |
| items | array[[blocklist entry](#blocklist-entry-object) object] | The entries in this page |
| has_more | boolean | Whether another page exists |
| next_after | ?string | The value to send as `after` for the next page, or null on the last page |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | response body | The page was returned |

The rate limit is 60 requests per minute, on the `admin:ban:operation` bucket.

## Add blocklist entry

<RouteHeader method="POST" path="/v1/admin/blocklists/{list_type}/entries" auditReason />

Adds a value to the list, or up to 1000 values for `avatar-hash` and `profile-substring`. You need the list's `add` permission.

### JSON body

The body is one [blocklist entry creation object](#blocklist-entry-creation-object).

:::caution[Adding an entry overwrites the existing entry]
Adding a value that is already stored replaces its entry, and every optional field you leave out goes back to its default.
:::

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The values were written |
| 400 | [error response](/admin-api/#error-response) | `IP_BAN_DECLINED` when the address is on the instance exemption list |
| 409 | [error response](/admin-api/#error-response) | `IP_BAN_LINKED_TO_DECISION` with `decision_id` when the address belongs to an enforcement decision |

The rate limit is 60 requests per minute, on the `admin:ban:operation` bucket.

## Bulk add blocklist entries

<RouteHeader method="PUT" path="/v1/admin/blocklists/{list_type}/entries" auditReason />

Starts a background job that adds up to 10000 hashes to the `file-sha` list with category `manual` and severity 2, and returns its ID for [Get job](/admin-api/jobs/#get-job). You need `ban:file_sha:add`. Every other list returns 400 `INVALID_FORM_BODY`.

### JSON body

| Field | Type | Description |
| --- | --- | --- |
| sha256_list | array[string] | The SHA-256 hashes to add (1-10000 items of exactly 64 characters) |

### Response body

| Field | Type | Description |
| --- | --- | --- |
| job_id | snowflake | The ID of the job |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | response body | The job was queued |

The rate limit is 60 requests per minute, on the `admin:ban:operation` bucket.

## Bulk remove blocklist entries

<RouteHeader method="DELETE" path="/v1/admin/blocklists/{list_type}/entries" auditReason />

Removes up to 1000 values from the `avatar-hash` or `profile-substring` list. You need the list's `remove` permission. Every other list returns 400 `INVALID_FORM_BODY`.

### JSON body

| Field | Type | Description |
| --- | --- | --- |
| hashes?<sup>1</sup> | array[string] | Avatar hashes to remove (1-1000 items matching `^(a_)?[0-9a-fA-F]{8}$`) |
| scope?<sup>2</sup> | string | The [profile substring scope](#profile-substring-scopes) |
| substrings?<sup>2</sup> | array[string] | Substrings to remove (1-1000 items of 1-500 characters) |
| reason? | string | Ignored |
| notes? | string | Ignored |

<sup>1</sup> Required for `avatar-hash`

<sup>2</sup> Required for `profile-substring`

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The values were removed, or had no entry |

The rate limit is 60 requests per minute, on the `admin:ban:operation` bucket.

## Check blocklist entry

<RouteHeader method="GET" path="/v1/admin/blocklists/{list_type}/entries/{entry_value}" auditReason />

Returns a [blocklist check object](#blocklist-check-object) saying whether the list blocks a value. You need the list's `check` permission. Percent-encode `entry_value`.

A value can be blocked without an entry of its own when an `ip` address is inside a stored CIDR range or a `url-domain` hostname or URL matches a parent domain or a pattern. The `url` check doesn't look at the `url-domain` list.

### Query parameters

| Field | Type | Description |
| --- | --- | --- |
| scope?<sup>1</sup> | string | The [profile substring scope](#profile-substring-scopes) to check |

<sup>1</sup> Required for `profile-substring` and refused with 400 `INVALID_FORM_BODY` on every other list

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | [blocklist check](#blocklist-check-object) object | The value was checked |

The rate limit is 60 requests per minute, on the `admin:ban:operation` bucket.

## Update blocklist entry

<RouteHeader method="PATCH" path="/v1/admin/blocklists/{list_type}/entries/{entry_value}" auditReason />

Rewrites the fields of one entry, or creates it when it doesn't exist. You need the list's `add` permission. The `ip`, `email` and `phrase` lists return 400 `INVALID_FORM_BODY`.

### JSON body

| Field | Type | Description |
| --- | --- | --- |
| scope?<sup>1</sup> | string | The [profile substring scope](#profile-substring-scopes) |
| category? | string | The [content blocklist category](#content-blocklist-categories) (1-64 characters, default `manual`) |
| severity? | integer | The [content blocklist severity](#content-blocklist-severities) (0-3, default 2) |
| match_subdomains? | boolean | Whether a `url-domain` entry also covers subdomains (default true) |
| content_type? | string | The media type hint of a `file-sha` entry (1-128 characters) |
| source_url? | string | The feed or evidence URL (1-2048 characters) |
| reason? | string | The reason, kept in the audit entry (1-1024 characters) |
| notes? | string | The internal note (1-1024 characters) |

<sup>1</sup> Required for `profile-substring`

:::caution[An omitted field is written as its default]
Sending `{"severity": 3}` on a `url` entry also resets its category to `manual` and clears its source URL and notes. Send every field the entry should keep.
:::

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The entry was written |

The rate limit is 60 requests per minute, on the `admin:ban:operation` bucket.

## Remove blocklist entry

<RouteHeader method="DELETE" path="/v1/admin/blocklists/{list_type}/entries/{entry_value}" auditReason />

Removes one entry. You need the list's `remove` permission. Percent-encode `entry_value` and send the value as the entry stores it. An address inside a stored CIDR range has no entry of its own, and you unblock it by removing the range.

### Query parameters

| Field | Type | Description |
| --- | --- | --- |
| scope?<sup>1</sup> | string | The [profile substring scope](#profile-substring-scopes) of the entry |

<sup>1</sup> Required for `profile-substring` and refused with 400 `INVALID_FORM_BODY` on every other list

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The entry was removed, or there was none |
| 409 | [error response](/admin-api/#error-response) | `IP_BAN_LINKED_TO_DECISION` with `decision_id` when the address belongs to an enforcement decision |

The rate limit is 60 requests per minute, on the `admin:ban:operation` bucket.

## Block a user's current avatar

<RouteHeader method="POST" path="/v1/admin/users/{user_id}/avatar-block" auditReason />

Adds the user's current avatar hash to the `avatar-hash` list and returns it. You need `ban:avatar_hash:add`. The user keeps the avatar until you clear it with [Clear user profile fields](/admin-api/users/#clear-user-profile-fields). No user can set that image again while the hash is on the list.

### JSON body

| Field | Type | Description |
| --- | --- | --- |
| reason? | string | The reason, kept in the audit entry (1-1024 characters) |
| notes? | string | The internal note, which defaults to a note with the user ID (1-1024 characters) |

### Response body

| Field | Type | Description |
| --- | --- | --- |
| hash_short | string | The stored 8-character avatar hash |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | response body | The hash was added |
| 404 | [error response](/admin-api/#error-response) | `UNKNOWN_USER` when the account doesn't exist, or `NOT_FOUND` when it has no avatar |

The rate limit is 60 requests per minute, on the `admin:ban:operation` bucket.