Blocklists

Fluxer has eight blocklists for account access and user content. Each defines its accepted values, matching rules and metadata. Fluxer normalises a value when it adds the value and again when it checks the value.

Each list has its own Admin ACLs. A read needs the selected list’s check permission, an addition or an update needs its add permission, and a removal needs its remove permission. An account holding ban:ip:add writes to the ip list and to no other. Every operation records the audit reason on the Admin audit entries it produces, and each read produces one entry. An entry about one list has a target type built from the list name with each hyphen written as an underscore, so url-domain entries use url_domain.

Fluxer builds each permission name from ban:, the list name with each hyphen written as an underscore, and the verb, so the url-domain list uses ban:url_domain:check, ban:url_domain:add, and ban:url_domain:remove.

Blocklist types

ip and email gate account access and registration. phrase, url, url-domain, file-sha, avatar-hash, and profile-substring gate what an account may post, link, upload, or display. email stores nothing but the value. An ip row also stores a ban kind, a reason, an expiry, and its creation time. An ip row with an expiry stops applying when it expires, and Fluxer then deletes it.

Value	Description
ip1	IPv4 addresses, IPv6 addresses, and CIDR ranges denied service
email2	Exact email addresses blocked from registration and from being set on an account
phrase3	Phrases blocked from content
url4	Absolute http and https URLs blocked from being posted
url-domain5	Domains blocked from being linked
file-sha6	SHA-256 hashes blocked from being uploaded
avatar-hash7	Avatar hashes blocked from being set
profile-substring3 8	Substrings blocked from one named profile field

¹ Fluxer refuses an address with 400 IP_BAN_DECLINED when it is on the instance exemption list, and records the refusal in the Admin audit log

² Stored lowercased, so a mixed-case value does not create a second row

³ Canonicalised by NFKC normalisation, removal of control, format and variation-selector characters, lowercasing, and trimming. When Fluxer matches a value, it also normalises inserted whitespace, punctuation, and compatibility characters

⁴ Canonicalised before storage. A value Fluxer cannot canonicalise returns 400 INVALID_FORM_BODY naming url

⁵ Stored lowercased, in ASCII form, and without a trailing dot. A row matches that hostname, and with match_subdomains true it also matches every subdomain. A value whose leftmost label has * is a domain pattern

⁶ Stored as lowercase hexadecimal

⁷ Stored as the 8-character hash with any a_ animation prefix stripped and the rest lowercased, so the animated and static forms of one avatar are the same row

⁸ The only scoped list. Scope and substring together identify a row, so the same substring can be stored once per scope

The fields and the operations a list accepts differ from list to list. Read the fields array and the supports_ flags of a blocklist object before writing to a list.

Domain patterns

A url-domain value whose leftmost label has * is a pattern. Each * stands for any run of characters inside that one label, so *shop*.example.com matches shop.example.com and my-shop-2.example.com. The rest of the value is a literal domain, called the suffix.

A pattern only matches the label directly left of its suffix. It never matches the suffix itself, so *shop*.example.com does not block example.com. With match_subdomains true, the pattern also matches every subdomain of a matching host, such as www.shop.example.com. Blocking a whole suffix takes a plain domain row.

Fluxer refuses a pattern with 400 INVALID_FORM_BODY naming domain when:

• * appears outside the leftmost label
• the leftmost label has characters other than a-z, 0-9, -, and *
• the leftmost label has more than 3 * or fewer than 3 other characters
• the suffix is not a valid domain or is a public suffix such as com or co.uk

A domain under a shared hosting suffix, such as onrender.com or github.io, is a valid suffix. Fluxer folds a run of * into one before it stores the pattern.

Fluxer matches a pattern against the ASCII form of a hostname. An internationalised label is compared in its punycode form, so a pattern with a leading or trailing literal can miss it, while *shop* still matches it.

Link matching

Fluxer checks every link in user content against the url and url-domain lists. This covers bare links, autolinks in angle brackets, the target of a masked link, and the link URLs of rich embeds. Fluxer reads the hostname of each link the way a browser does. It ignores user information and the port, lowercases the hostname, converts it to ASCII, decodes percent escapes, and drops trailing dots.

Content blocklist categories

Every url, url-domain, file-sha, and avatar-hash row has a category naming where it came from. A row created through this resource without an explicit category is stored as manual.

Value	Description
manual	Added by an Admin through this resource
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

With blocklist feeds off, Fluxer ignores and removes every file-sha row in the malware_bazaar category that no Admin added.

The request field is a free string of 1 through 64 characters, so a value outside this registry is accepted and stored verbatim. Tolerate a stored category outside the registry.

Content blocklist severities

Every url, url-domain, file-sha, and avatar-hash row has a severity. A row created without an explicit severity is stored as 2.

The severity is a stored label for moderators. Fluxer refuses the content of every matching row whatever its severity, so a row stored as 0 or 1 blocks exactly like one stored as 2. Delete a row to stop it blocking.

Value	Name	Description
0	ALLOW	Labelled as content to allow
1	WARN	Labelled as content to warn about
2	BLOCK	Labelled as content to refuse
3	BLOCK_AND_REPORT	Labelled as content to refuse and report

Profile substring scopes

Value	Description
username	Match the substring against the account username
global_name	Match the substring against the account display name
nickname	Match the substring against a guild nickname
bio	Match the substring against the profile biography
pronouns	Match the substring against the profile pronouns

Blocklist object

One entry of the blocklist catalogue returned by List blocklists. The catalogue is fixed in each release and reports no counts.

Structure

Field	Type	Description
list_type	string	The blocklist type this entry describes
description	string	The human-readable summary of what the blocklist matches and how
value_field1	string	The request body field that has the value when adding
fields2	array[string]	The field names rows of this blocklist accept beyond the value (at most 8)
scoped3	boolean	Whether rows are scoped to a profile field and every operation has a scope
supports_bulk_create4	boolean	Whether Bulk add blocklist entries is accepted
supports_bulk_delete5	boolean	Whether Bulk remove blocklist entries is accepted
supports_update6	boolean	Whether Update blocklist entry is accepted

¹ ip names ip, email names email, url-domain names domain, phrase names phrase, url names url, file-sha names sha256_hex, avatar-hash names hashes, and profile-substring names substrings

² ip names duration_hours. Empty for email and phrase. url names category, severity, source_url, and notes. url-domain adds match_subdomains, file-sha adds content_type, and avatar-hash adds reason. profile-substring names scope, reason, and notes

³ True only for profile-substring

⁴ True only for file-sha

⁵ True only for avatar-hash and profile-substring

⁶ True for url, url-domain, file-sha, avatar-hash, and profile-substring

Example

{
  "list_type": "url-domain",
  "description": "Domains blocked from being linked, optionally covering every subdomain rooted at the domain. A value whose leftmost label contains * is a pattern that matches that one label under a registrable domain.",
  "value_field": "domain",
  "fields": ["match_subdomains", "category", "severity", "source_url", "notes"],
  "scoped": false,
  "supports_bulk_create": false,
  "supports_bulk_delete": false,
  "supports_update": true
}

Blocklist entry object

One stored row of one blocklist. Every field is present on every entry, and a field the row’s blocklist does not store is null.

Structure

Field	Type	Description
list_type	string	The blocklist type the row belongs to
value1	string	The canonical stored value (1-2048 characters)
scope2	?string	The profile substring scope the row is stored under
category3	?string	The content blocklist category the row was recorded under
severity3	?integer	The content blocklist severity label stored on the row
source_url3	?string	The feed or evidence URL the row was recorded from
notes4	?string	The internal note stored alongside the row
content_type5	?string	The media type hint recorded alongside a file-sha row
match_subdomains6	?boolean	Whether a url-domain row also covers subdomains
reason7	?string	The reason stored on the row
expires_at7	?ISO8601 timestamp	When the row expires
created_at8	?ISO8601 timestamp	When the row was added
created_by_user_id8	?snowflake	The Admin account that added the row, or null when unknown

¹ The exact string the single-entry operations and the after cursor accept for that row

² Non-null only on profile-substring

³ Non-null only on url, url-domain, file-sha, and avatar-hash, where category and severity are always set

⁴ Non-null only on url, url-domain, file-sha, avatar-hash, and profile-substring

⁵ Non-null only on file-sha

⁶ Non-null only on url-domain

⁷ Non-null only on ip. An address added through Add blocklist entry reads back with the reason platform_admin_enforcement. Its expires_at is null unless it was added with a positive duration_hours. A row past its expires_at is not listed

⁸ Both null on email and phrase, which store nothing but the value. created_by_user_id is also null on ip

The audit entry records the accepted reason

An avatar-hash or profile-substring write accepts reason, and both lists then report reason as null in this object.

Example

{
  "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

The decision Check blocklist entry returns for one value.

Structure

Field	Type	Description
banned1	boolean	Whether the value is currently blocked by the named blocklist
expires_at2	?ISO8601 timestamp	When the matching ban expires

¹ Reports the decision the enforcement path would make for this value

² Non-null only on ip when the matching ban has an expiry. Null when the ban is permanent, when nothing matches, and on every other blocklist

A block and a row are different things

A value can be blocked with no row of its own, as a single address covered by a stored CIDR range is. A row can exist while the value reads as not blocked, as an exempt address or an exempt email domain does.

Blocklist entry creation object

The body of Add blocklist entry has one shape per blocklist, and the list_type path segment selects the shape. The field that has the value differs per blocklist, and two of the nine take an array, so one request can add up to 1000 avatar hashes or profile substrings.

Value field

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

¹ Each value is canonicalised and written as its own row with its own Admin audit entry

² scope is required in the same body

Each field is a string, except hashes and substrings, which are array[string].

avatar-hash deduplicates the array after canonicalisation. profile-substring does not, so a substring repeated in one request is written once and audited once per occurrence. A profile-substring value that canonicalises to an empty string is skipped.

Additional fields

Field	Type	Description
scope?3	string	The profile substring scope to store the rows under
category?4	string	The content blocklist category (1-64 characters, default manual)
severity?4	integer	The content blocklist severity (0-3, default 2)
match_subdomains?5	boolean	Whether the row also covers subdomains (default true)
content_type?6	string	The media type hint (1-128 characters)
source_url?4	string	The feed or evidence URL (1-2048 characters)
reason?7	string	The reason (1-1024 characters)
notes?8	string	The internal note (1-1024 characters)
duration_hours?9	integer	Hours until the row expires (0-8760, default 0)

³ Required by profile-substring. Every other blocklist strips scope

⁴ Accepted only by url, url-domain, file-sha, and avatar-hash

⁵ Accepted only by url-domain

⁶ Accepted only by file-sha

⁷ Accepted only by avatar-hash and profile-substring, and recorded in the audit entry metadata

⁸ Accepted only by url, url-domain, file-sha, avatar-hash, and profile-substring

⁹ Accepted only by ip. 0 writes a permanent row. A positive value writes a row that stops applying after that many hours, and Fluxer then deletes it. Adding an address again replaces its expiry, so a permanent row can become temporary and a temporary row can become permanent

List blocklists

GET/v1/admin/blocklistsAudit reason

Returns one blocklist object for every blocklist this instance keeps. Requires any one of the check permissions.

The response is identical for every Admin.

Response body

Field	Type	Description
items1	array[blocklist object]	Every blocklist exposed by this instance

¹ Always the complete catalogue in one response. There is no cursor, no has_more, and no next_after

Response

Status	Body	Condition
200	response body	Catalogue was returned

Side effects

The operation records one Admin audit entry with action list_blocklists, target type blocklist, target ID 0, and metadata key result_count.

Rate limit

60 requests per minute for each authenticated user, on the admin:ban:operation bucket.

List blocklist entries

GET/v1/admin/blocklists/{list_type}/entriesAudit reason

Returns a value-ordered cursor page of blocklist entry objects. Requires the selected list’s check permission.

Path parameters

Field	Type	Description
list_type	string	The blocklist type

Query parameters

Field	Type	Description
limit?	integer	Maximum entries to return (1-200, default 50)
after?1	string	Return entries ordered strictly after this value (1-2048 characters)
scope?2	string	The profile substring scope to list

¹ Compared as a string against the canonical stored value. Fluxer does not validate it against the selected blocklist, so an impossible cursor returns no entries

² Required by profile-substring and rejected by every other blocklist

Response body

Field	Type	Description
items	array[blocklist entry object]	Entries in this page, ordered by value ascending
has_more	boolean	Whether another page can be fetched with next_after
next_after3	?string	The stored entry value to send as after, or null on the last page

³ A value cursor, so it is sent back verbatim as after

Response

Status	Body	Condition
200	response body	Entry page was returned
400	error response	scope is supplied on an unscoped blocklist or omitted on profile-substring, and the request returns INVALID_FORM_BODY

The cost of a page does not fall as the cursor advances, so walk a large list with the largest limit the operation accepts.

Side effects

The operation records one Admin audit entry with action list_blocklist_entries, the target type of the selected list, target ID 0, and metadata keys list_type, limit, result_count for the entries in this page, and has_more. profile-substring adds scope, and a supplied after adds has_after. The cursor value and the entry values are not recorded. A 400 records nothing.

Rate limit

60 requests per minute for each authenticated user, on the admin:ban:operation bucket.

Add blocklist entry

POST/v1/admin/blocklists/{list_type}/entriesAudit reason

Canonicalises the submitted value or values and writes them to the selected blocklist. Returns 204 with an empty body. Requires the selected list’s add permission.

Path parameters

Field	Type	Description
list_type	string	The blocklist type

JSON body

The body is one blocklist entry creation object. list_type selects the shape, so a body valid for one blocklist fails validation on another.

Adding a row overwrites the existing row

Every write is an upsert on the canonical value. An omitted optional field is written as its default, so re-adding a url without a category resets that row to manual. The previous values are not recoverable.

Response

Status	Body	Condition
204	empty	Values were written
400	error response	INVALID_FORM_BODY because the value is not valid for the list, or a field the blocklist does not accept was supplied

A body field the selected blocklist does not accept is stripped and never produces that 400. A url Fluxer cannot canonicalise returns 400 INVALID_FORM_BODY naming url in the errors array. A url-domain value that is not a valid domain or domain pattern returns the same 400 naming domain.

Fluxer refuses to add an ip with 400 IP_BAN_DECLINED when the address is on the instance exemption list.

The response has no body, so it does not report the canonical form that was stored. Read it back with List blocklist entries.

Side effects

Fluxer checks later requests against the written rows. For every list except email, other nodes see the rows after a short propagation delay. No Gateway Dispatch is emitted.

Fluxer records one Admin audit entry per written value, with that value in its metadata. An ip added with a positive duration_hours adds the metadata keys duration_hours and expires_at. A url-domain entry also records match_subdomains and pattern, which is true for a domain pattern. Fluxer records an entry for a refused ip too, under the action ban_ip_skipped_exempt, before it returns the 400.

Rate limit

60 requests per minute for each authenticated user, on the admin:ban:operation bucket.

Bulk add blocklist entries

PUT/v1/admin/blocklists/{list_type}/entriesAudit reason

Queues a background job that adds up to 10000 SHA-256 hashes to the file-sha blocklist and returns the job ID immediately. Requires ban:file_sha:add.

Only file-sha accepts this operation, reported as supports_bulk_create by List blocklists. Every other list type returns 400 INVALID_FORM_BODY.

Path parameters

Field	Type	Description
list_type	string	The blocklist type, which is file-sha here

JSON body

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

¹ The body enforces the length of each item. The job checks the alphabet and records a non-hexadecimal item as an invalid_sha256 failure

Response body

Field	Type	Description
job_id	snowflake	The background job applying the hashes

Response

Status	Body	Condition
200	response body	Job was queued
400	error response	The list type is not file-sha and the request returns INVALID_FORM_BODY

The operation returns before any hash is written. Read progress and the final counts from Get job, and stop the job with Cancel job. The job reports progress every 50 hashes and finishes with a summary naming how many were written and how many failed.

Every hash is written with the category manual, the severity 2, and a null content type, source URL, and note. The bulk path accepts no metadata, so a hash that needs any of those goes through Add blocklist entry or a later Update blocklist entry.

Side effects

Each hash is lowercased and replaces any existing entry. Changes become visible across the instance when the job stops, whether it ran to the end or was cancelled, so a cancelled job still enforces the hashes it already wrote. No Gateway Dispatch is emitted.

The request records one Admin audit entry with action queue_bulk_job, target type bulk_job, the job ID as target ID, and metadata keys task and entity_count. task is ban_file_shas, and entity_count is the number of submitted hashes.

The job records one Admin audit entry per written hash under the action ban_file_sha, with that hash in its metadata, exactly as Add blocklist entry does. It then records one aggregate entry under the action bulk_ban_file_shas, with the submitted, processed, successful, and failed counts. A cancelled job records the entries for the hashes it wrote and an aggregate entry marked cancelled.

Rate limit

60 requests per minute for each authenticated user, on the admin:ban:operation bucket.

Bulk remove blocklist entries

DELETE/v1/admin/blocklists/{list_type}/entriesAudit reason

Canonicalises up to 1000 values and removes their rows from the selected blocklist. Returns 204 with an empty body. Requires the selected list’s remove permission.

Only avatar-hash and profile-substring accept this operation, reported as supports_bulk_delete by List blocklists. Every other list type returns 400 INVALID_FORM_BODY.

Path parameters

Field	Type	Description
list_type	string	The blocklist type, which is avatar-hash or profile-substring here

JSON body

The body is selected by list_type.

Field	Type	Description
hashes?1	array[string]	Avatar hashes to remove (1-1000 items of 8 through 10 characters matching ^(a_)?[0-9a-fA-F]{8}$)
scope?2	string	The profile substring scope the substrings are stored under
substrings?2	array[string]	Substrings to remove (1-1000 items of 1 through 500 characters)
reason?3	string	Accepted and ignored
notes?3	string	Accepted and ignored

¹ avatar-hash only, where it is required and is the whole body

² profile-substring only, where both are required

³ profile-substring only. Fluxer records neither in the audit entry

Response

Status	Body	Condition
204	empty	Values were processed
400	error response	The list accepts no bulk removal, or the body fails validation, and the request returns INVALID_FORM_BODY

The operation is idempotent and reports no counts. A value with no stored row still returns 204. Read the list before and after to tell a removal from a no-op.

avatar-hash deduplicates the array after canonicalisation. profile-substring does not, so a substring repeated in one request is removed once and audited once per occurrence. A profile-substring value that canonicalises to an empty string is skipped.

Side effects

After the removal reaches every node, Fluxer no longer checks later requests against the removed entries. A value can remain blocked by another matching entry. No Gateway Dispatch is emitted.

The operation records one Admin audit entry per canonical value processed.

Rate limit

60 requests per minute for each authenticated user, on the admin:ban:operation bucket.

Check blocklist entry

GET/v1/admin/blocklists/{list_type}/entries/{entry_value}Audit reason

Reports whether one value is currently blocked by the selected blocklist and returns a blocklist check object. Requires the selected list’s check permission.

Path parameters

Field	Type	Description
list_type	string	The blocklist type
entry_value1	string	The percent-encoded value to check (1-2048 characters)

¹ Percent encoding is required because a canonical value can contain a slash. Fluxer checks the value for length alone, so a value in the wrong form returns 200 with banned false

Query parameters

Field	Type	Description
scope?2	string	The profile substring scope to check the value against

² Required by profile-substring and rejected by every other blocklist

Matching rule by blocklist

Blocklist	Rule
ip3 4	The address itself, any stored CIDR range containing it, and any stored address the instance treats as the same origin
email	Exact match on the lowercased address
phrase	Normalised phrase matching, so a disguised form of a stored phrase still reads as blocked
url5	Exact match on the canonicalised URL
url-domain6	The hostname, each parent domain stored with match_subdomains true, and each domain pattern covering the hostname
file-sha	Exact match on the lowercased hexadecimal digest
avatar-hash	Exact match after the a_ prefix is stripped and the hash is lowercased
profile-substring	Normalised substring matching within the named scope

³ Any value that is not a single address, including a CIDR range, always reads as not blocked. An address on the instance exemption list reads as not blocked even while a row exists

⁴ Two addresses are the same origin when they share a decision key, which is the exact address for IPv4 and the /64 prefix for IPv6

⁵ This check does not read the url-domain list, so a URL that a stored domain blocks reads as not blocked. Check the hostname separately

⁶ The value can be a hostname or an absolute http or https URL. Fluxer normalises the hostname as it does for link matching

Response

Status	Body	Condition
200	blocklist check object	Value was checked
400	error response	scope is supplied on an unscoped blocklist or omitted on profile-substring, and the request returns INVALID_FORM_BODY

A value with no row and no covering match returns 200 with banned false, so this operation never reports whether a specific row exists. Use List blocklist entries for that.

For every list except email, a row written on another node becomes visible here after a short propagation delay.

Side effects

The operation records one Admin audit entry with action check_blocklist_entry, the target type of the selected list, target ID 0, and metadata keys list_type and banned. profile-substring adds scope. The checked value is not recorded. A 400 records nothing.

Rate limit

60 requests per minute for each authenticated user, on the admin:ban:operation bucket.

Update blocklist entry

PATCH/v1/admin/blocklists/{list_type}/entries/{entry_value}Audit reason

Rewrites the stored fields of one row without removing and re-adding it. Returns 204 with an empty body. Requires the selected list’s add permission.

Only url, url-domain, file-sha, avatar-hash, and profile-substring accept this operation, reported as supports_update by List blocklists. A list with no stored fields has nothing to update and returns 400 INVALID_FORM_BODY.

Path parameters

Field	Type	Description
list_type	string	The blocklist type
entry_value	string	The percent-encoded canonical value of the row to write (1-2048 characters)

JSON body

The body is the creation shape of the selected blocklist with the value field removed, so the same field list and the same bounds apply.

Field	Type	Description
scope?1	string	The profile substring scope to write the row under
category?2	string	The content blocklist category (1-64 characters, default manual)
severity?2	integer	The content blocklist severity (0-3, default 2)
match_subdomains?3	boolean	Whether the row also covers subdomains (default true)
content_type?4	string	The media type hint (1-128 characters)
source_url?2	string	The feed or evidence URL (1-2048 characters)
reason?5	string	The reason (1-1024 characters)
notes?6	string	The internal note (1-1024 characters)

¹ Required by profile-substring. This operation takes no query parameters, so the scope goes in the body, and every other blocklist ignores it there

² Accepted only by url, url-domain, file-sha, and avatar-hash

³ Accepted only by url-domain

⁴ Accepted only by file-sha

⁵ Accepted only by avatar-hash and profile-substring, and recorded in the audit entry metadata

⁶ Accepted only by url, url-domain, file-sha, avatar-hash, and profile-substring

An omitted field is written as its default

Sending {"severity": 3} on a url row also resets its category to manual and clears its source URL and notes. Resend every field the row is meant to keep.

Response

Status	Body	Condition
204	empty	Row was written
400	error response	The list accepts no update, or the body fails validation, and the request returns INVALID_FORM_BODY

On the url blocklist, an entry_value Fluxer cannot canonicalise returns 400 INVALID_FORM_BODY naming url in the errors array. On the url-domain blocklist, an entry_value that is not a valid domain or domain pattern returns the same 400 naming domain.

The write is an upsert on the canonical value, so a value with no existing row is created. This operation never returns 404. A url blocked only by a stored url-domain row has no row of its own, and updating it through the URL silently creates a new exact-URL row.

Changing the scope of a profile-substring row writes a second row under the new scope and leaves the original in place. Removing the original takes Remove blocklist entry.

Side effects

After the change reaches every node, later matches use the updated fields. No Gateway Dispatch is emitted.

The write records one Admin audit entry under the same action an add records, with the canonical value but no previous values of the changed fields.

Rate limit

60 requests per minute for each authenticated user, on the admin:ban:operation bucket.

Remove blocklist entry

DELETE/v1/admin/blocklists/{list_type}/entries/{entry_value}Audit reason

Removes one row from the selected blocklist. Returns 204 with an empty body. Requires the selected list’s remove permission.

Path parameters

Field	Type	Description
list_type	string	The blocklist type
entry_value1	string	The percent-encoded canonical value of the row to remove (1-2048 characters)

¹ Canonicalised the same way it was on the add path and matched exactly, so a url blocked only by a broader url-domain row cannot be removed through the URL. A url-domain value that fails validation is lowercased and removed as written

Query parameters

Field	Type	Description
scope?2	string	The profile substring scope the row is stored under

² Required by profile-substring and rejected by every other blocklist

Response

Status	Body	Condition
204	empty	Value was processed
400	error response	scope is supplied on an unscoped blocklist or omitted on profile-substring, and the request returns INVALID_FORM_BODY

On the url blocklist, an entry_value Fluxer cannot canonicalise returns 400 INVALID_FORM_BODY naming url in the errors array.

Removal is idempotent. A value with no stored row returns 204 and still records an Admin audit entry, so this operation never returns 404 and never reports whether anything was removed.

Side effects

The removed row stops affecting subsequent blocklist decisions. For every list except email, other nodes stop applying it after a short propagation delay. A value can remain blocked by another matching row, such as a single address covered by a stored CIDR range. No Gateway Dispatch is emitted.

The removal records one Admin audit entry, with the canonical value in its metadata.

Rate limit

60 requests per minute for each authenticated user, on the admin:ban:operation bucket.

Block a user’s current avatar

POST/v1/admin/users/{user_id}/avatar-blockAudit reason

Adds the account’s current avatar hash to the avatar-hash blocklist and returns the stored hash. Requires ban:avatar_hash:add.

This is a shortcut over Add blocklist entry for blocking an avatar an Admin is looking at. The operation reads the current avatar hash and strips any a_ animation prefix, so the stored value is the 8-character form. It writes the same row an add writes, with the category manual, the severity 2, and a null source URL. It does not ban, suspend, or otherwise act on the account.

Path parameters

Field	Type	Description
user_id	snowflake	The account whose current avatar is blocked

JSON body

Both fields are optional, so an empty body and {} are both valid requests.

Field	Type	Description
reason?1	string	The reason (1-1024 characters)
notes?2	string	The internal note (1-1024 characters)

¹ Recorded in the metadata of the Admin audit entry, so no read of the row returns it

² Stored on the row. Omitting it stores the generated note banned via user shortcut user_id=<user_id>

Response body

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

Response

Status	Body	Condition
200	response body	Avatar hash was written
404	error response	UNKNOWN_USER when the account does not exist, or NOT_FOUND when the account has no avatar

The account keeps the blocked avatar until it next sets one. Clearing it is a separate request naming avatar in the fields array of Clear user profile fields.

The avatar hash is the first 8 characters of the MD5 digest of the image, so every account using that image has the same avatar hash, so blocking the hash blocks the image for every account.

Side effects

The hash blocks subsequent avatar uploads after the change propagates across the instance. No Gateway Dispatch is emitted.

Fluxer records one Admin audit entry under the action ban_avatar_hash, with the stored hash and the supplied reason.

Rate limit

60 requests per minute for each authenticated user, on the admin:ban:operation bucket.