JSON-RPC:Name ban

JSON Methods

• rpc: set_issuer, info, add_timer, del_timer
• stats: get
• log: send, list, subscribe, unsubscribe
• user: list, get, set_nick, set_username, set_realname, set_vhost, set_mode, set_snomask, set_oper
• whowas: get
• server: list, get, rehash, connect, disconnect
• channel: list, get, set_mode, set_topic, kick
• server_ban: list, get, add, del
• server_ban_exception: list, get, add, del
• spamfilter: list, get, add, del
• name_ban: list, get, add, del
• message: send_privmsg, send_notice, send_numeric, send_standard_reply
• connthrottle: status, set, reset,
• security_group: list, get

JSON Basics

• JSON-RPC Technical documentation

The name_ban.* JSON RPC calls can add, remove and list banned nicks and channels (q-lines).

Structure of a name ban

The following object is used in both request and responses. This is a server ban, such as a GLINE or Spamfilter. It is also used for ban exceptions (ELINE).

Variable	Description	Example value
type	Type of the server ban. One of: gline, kline, gzline, zline, spamfilter, qline, except, shun, local-qline, local-exception, local-spamfilter.	gline
type_string	Type of the server ban in a more friendly user printable string. Possibly prefixed with "Soft" eg "Soft G-Line".	G-Line
id	Unique ID for this TKL entry. (UnrealIRCd 6.2.6 and later)	G7K2MP9WQX3
name	The target of the ban or except. For Spamfilter this is the regex/matcher.	*@*.badisp.example.net
match	Target of the ban or except, a Match item object. This is only present for server bans and server ban exceptions if a mask/match is used in the config file. Only in that case match is present and name will be absent.	{ certfp "aabbccdd.."; }
set_by	Name of the person or server who set the ban	Syzop
set_at	Date/Time when the server ban was added	2022-05-23T11:02:06.000Z
set_at_string	Date/Time when the server ban was added in a more human printable string.	Mon May 23 11:02:06 2022
expire_at	Date/Time when the server ban will expire. NULL means: never.	2023-05-23T10:00:00.000Z
expire_at_string	Date/Time when the server ban will expire in a more human printable string. Uses "Never" for never.	Tue May 23 10:00:00 2023
duration_string	How long the ban will last from this point in time (human printable). Uses "permanent" for forever.	permanent
set_at_delta	How many seconds ago the ban was placed.	1800
reason	The reason of the ban	Lots of abuse from this ISP
spamfilter_id	If a server ban was placed by a spamfilter, this shows the TKL ID of the Spamfilter entry. Not to be confused with id which is OUR tkl id. (UnrealIRCd 6.2.6 and later)	SPAM5P9WQX3
exception_types	Only for ban exceptions! Specifies the exception types (letters). See HELPOP ELINE for a list of those letters.	kGzZsF
match_type	Only for spamfilters! The matching type. One of: simple, regex	regex
ban_action	Only for spamfilters! The action to take on spamfilter hit.	gline
spamfilter_targets	Only for spamfilters! Which targets the spamfilter must filter on.	cpnN
except	An exception to which this particular spamfilter does not apply, a Match item object. Rarely used. Only for spamfilters.	{ reputation-score 25; }
hits	For Spamfilters and server bans: the number of hits this entry had on this server (not network wide). For config-based spamfilters/bans this is reset after a server restart, for non-config-bans this is preserved via tkldb. (UnrealIRCd 6.2.6 and later)	2
last_hit_at	For Spamfilters and server bans: the timestamp of the last hit of this entry on this server (not network wide). For config-based spamfilters/bans this is reset after a server restart, for non-config-bans this is preserved via tkldb. (UnrealIRCd 6.2.6 and later)	2026-06-10T12:34:56.000Z
hits_except	For Spamfilters only: the number of hits by exempted users (which were unaffected) of this particular entry on this server (not network wide). This allows you to get an idea of "false positives" for this spamfilter. For config-based spamfilters/bans this is reset after a server restart, for non-config-bans this is preserved via tkldb. (UnrealIRCd 6.2.6 and later)	2
last_hit_except_at	For Spamfilters only: the timestamp of the last hit by an exempted user (which was unaffected) of this particular entry on this server (not network wide). This allows you to get an idea of "false positives" for this spamfilter. For config-based spamfilters/bans this is reset after a server restart, for non-config-bans this is preserved via tkldb. (UnrealIRCd 6.2.6 and later)	2026-06-10T12:34:56.000Z

NOTE: Only name bans are handled through name_ban.*.

API Calls

name_ban.list

List name bans (qlines).

Request arguments

No mandatory arguments

Example

{"jsonrpc": "2.0", "method": "name_ban.list", "params": {}, "id": 123}

name_ban.get

Retrieve all details of a single name ban (qline).

Request arguments

Mandatory arguments:

• name: name of the ban, eg *C*h*a*n*s*e*r*v*

Example

{"jsonrpc": "2.0", "method": "name_ban.get", "params": {"name":"*C*h*a*n*s*e*r*v*"}, "id": 123}

name_ban.add

Add a name ban (qline).

Request arguments

Mandatory arguments (see structure of a name ban for an explanation of the fields):

• name: banned name
• reason: reason for the ban

Optional arguments:

• set_by: who set the entry
• the duration (without this, it is a permanent name ban which is very common), either:
  • expire_at, OR
  • duration_string

Example request

{"jsonrpc": "2.0", "method": "name_ban.add", "params": {"name":"*blah*","reason":"testing the API"}, "id": 123}

name_ban.del

Delete a name ban (*LINE).

Request arguments

Mandatory arguments:

• name: banned name

Optional arguments:

• set_by: who unset the entry

Example

{"jsonrpc": "2.0", "method": "name_ban.del", "params": {"name":"*blah*"}, "id": 123}