API:Block

From MediaWiki.org
Jump to: navigation, search
This page is part of the MediaWiki action API documentation.


MediaWiki action API

v · d · e
For the API for enumerating blocks, see API:Blocks.
Unblock
Unblock a user.
This module cannot be used as a GeneratorAPI:generator.
Prefix none
Required rights block
Post only? Yes
Generated help Current
Version added
≥ 1.12
Block
Block a user.
This module cannot be used as a GeneratorAPI:generator.
Prefix none
Required rights block
Post only? Yes
Generated help Current
Version added
≥ 1.12

Token[edit]

To block or unblock a user, a token is required. This token is equal to the edit token and the same for all blocks, but changes at every login. For MediaWiki 1.24 onwards, the needed token can be obtained via meta=tokens with the type set to csrf. For MediaWiki 1.20–1.23, see API:Tokens (action); for older versions, see API:Info or use the now-removed gettoken parameter.

Obtaining a block/unblock token

api.php?action=query&meta=tokens [try in ApiSandbox]
Result 
{
    "query": {
        "tokens": {
            "csrftoken": "0123456789012345678901234567890123456789+\\"
        }
    }
}

Blocking users[edit]

Users can be blocked with action=block. This must be sent as a POST request. As such, don't forget to append an = to parameters with no value (e.g., autoblock=, not just autoblock).

Parameters[edit]

  • user: The username, IP address or IP range you want to block.
  • token: A previously obtained block token. Take care to properly urlencode the + and \.
  • expiry: Expiry timestamp. Relative expiry times, like 5 months or 2 weeks are also accepted. If set to infinite, never, or not set at all, the block will never expire. (Default: never)
  • reason: The reason for the block (optional).
  • anononly: If set, only anonymous logins from the user's IP will be blocked, thus forcing the user to log in or create an account in order to be able to edit.
  • nocreate: If set, block account creation from the user's IP.
  • autoblock: If set, automatically block the IP address last used by this user, and any subsequent IPs they try to login from.
  • noemail: If set, prevent the user from sending email through Special:Emailuser. (Requires the "blockemail" right.)
  • hidename: Hide the username from the block log. (Requires the "hideuser" right.)
  • allowusertalk: Allow the user to edit their own talk page (depends on $wgBlockAllowsUTEdit) 1.14+
  • reblock: If the user is already blocked, overwrite the existing block 1.14+
  • watchuser: Watch the user/IP's user and talk pages 1.18+
  • gettoken: If set, a block token will be returned, and no other action will be taken (Deprecated in 1.20) (Removed in 1.21)
  • tags: Tags to apply to the entry in the block log. 1.29+

Example[edit]

Note: In this example, all parameters are passed in a GET request just for the sake of simplicity. However, action=block requires POST requests; GET requests will cause an error. Blocking Example for 1 day, disabling account creation and email

api.php?action=block&user=Example&expiry=1%20day&reason=Time%20out&nocreate=&noemail=&token=0123456789012345678901234567890123456789%2b%5c [try in ApiSandbox]
Result 
{
  "block": {
    "user": "Example",
    "userID": 2,
    "expiry": "2015-02-25T07:27:50Z",
    "id": "8",
    "reason": "Time out"
    "nocreate": "",
    "noemail": ""
  }
}

Possible errors[edit]

In addition to the usual stuff:

Code Info
nouser The user parameter must be set
notoken The token parameter must be set
permissiondenied You don't have permission to block users
Note: On most wikis, blocking users is restricted to sysops, but other wikis may have stricter rules.
invalidrange Invalid IP range
rangedisabled Blocking IP ranges has been disabled
invalidip Invalid IP address specified
invalidexpiry Invalid expiry time
alreadyblocked The user you tried to block was already blocked
pastexpiry Expiry time "$1" is in the past.
cantblock You don't have permission to block users.
canthide You don't have permission to hide user names from the block log.
Note: This feature has to be enabled explicitly in LocalSettings.php.
cantblock-email You don't have permission to block users from sending email through the wiki.



action=block

(main | block)
  • This module requires read rights.
  • This module requires write rights.
  • This module only accepts POST requests.
  • Source: MediaWiki
  • License: GPL-2.0+

Block a user.

Parameters:
user

Username, IP address, or IP address range to block. Cannot be used together with userid

Type: user name
userid

User ID to block. Cannot be used together with user.

Type: integer
expiry

Expiry time. May be relative (e.g. 5 months or 2 weeks) or absolute (e.g. 2014-09-18T12:34:56Z). If set to infinite, indefinite, or never, the block will never expire.

Default: never
reason

Reason for block.

Default: (empty)
anononly

Block anonymous users only (i.e. disable anonymous edits for this IP address).

Type: boolean (details)
nocreate

Prevent account creation.

Type: boolean (details)
autoblock

Automatically block the last used IP address, and any subsequent IP addresses they try to login from.

Type: boolean (details)
noemail

Prevent user from sending email through the wiki. (Requires the blockemail right).

Type: boolean (details)
hidename

Hide the username from the block log. (Requires the hideuser right).

Type: boolean (details)
allowusertalk

Allow the user to edit their own talk page (depends on $wgBlockAllowsUTEdit).

Type: boolean (details)
reblock

If the user is already blocked, overwrite the existing block.

Type: boolean (details)
watchuser

Watch the user's or IP address's user and talk pages.

Type: boolean (details)
tags

Change tags to apply to the entry in the block log.

Values (separate with | or alternative):
token

A "csrf" token retrieved from action=query&meta=tokens

This parameter is required.
Examples:
Block IP address 192.0.2.5 for three days with reason First strike.
api.php?action=block&user=192.0.2.5&expiry=3%20days&reason=First%20strike&token=123ABC [open in sandbox]
Block user Vandal indefinitely with reason Vandalism, and prevent new account creation and email sending.
api.php?action=block&user=Vandal&expiry=never&reason=Vandalism&nocreate=&autoblock=&noemail=&token=123ABC [open in sandbox]

Unblocking users[edit]

Users can be unblocked with action=unblock.

Parameters[edit]

Only one of id, user, or userid must be specified.

  • id: The ID of the block you want to undo. Block IDs can be obtained through list=blocks
  • user: The username, IP address or IP range you want to unblock.
  • userid: User ID to unblock. Cannot be used together with id or user. 1.29+
  • token: A previously obtained unblock token. Take care to properly urlencode the + and \.
  • reason: The reason for the unblock (optional).
  • tags: Change tags to apply to the entry in the block log. 1.27+
  • gettoken: If set, a token will be returned. (Deprecated in 1.20) (Removed in 1.21)

Sample request[edit]

Unblocking Example and apologizing

api.php?action=unblock&user=Example&token=0123456789012345678901234567890123456789%2b%5c&reason=Sorry%20Example [try in ApiSandbox]
Result 
{
  "id": "16",
  "user": "Example",
  "userid": 2,
  "reason": "Sorry Example"
}

Possible errors[edit]

In addition to the usual stuff:

Code Info
notarget Either the id or the user parameter must be set
notoken The token parameter must be set
idanduser The id and user parameters can't be used together
blockedasrange IP address "address" was blocked as part of range "range". You can't unblock the IP individually, but you can unblock the range as a whole.
cantunblock The block you specified was not found. It may have been unblocked already
permissiondenied You don't have permission to unblock users. Note: On most wikis, unblocking users is restricted to sysops, but other wikis may have different rules.



action=unblock

(main | unblock)
  • This module requires read rights.
  • This module requires write rights.
  • This module only accepts POST requests.
  • Source: MediaWiki
  • License: GPL-2.0+

Unblock a user.

Parameters:
id

ID of the block to unblock (obtained through list=blocks). Cannot be used together with user or userid.

Type: integer
user

Username, IP address or IP address range to unblock. Cannot be used together with id or userid.

userid

User ID to unblock. Cannot be used together with id or user.

Type: integer
reason

Reason for unblock.

Default: (empty)
tags

Change tags to apply to the entry in the block log.

Values (separate with | or alternative):
token

A "csrf" token retrieved from action=query&meta=tokens

This parameter is required.
Examples:
Unblock block ID #105.
api.php?action=unblock&id=105 [open in sandbox]
Unblock user Bob with reason Sorry Bob.
api.php?action=unblock&user=Bob&reason=Sorry%20Bob [open in sandbox]
Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Block&oldid=2661326"