API:Block

From MediaWiki.org
Jump to: navigation, search
Tools clipart.png This page is part of the MediaWiki action API documentation.
MediaWiki APIsAPI:Main page



MediaWiki action API

v · d · e
For the API for enumerating blocks, see API:Blocks.
MediaWiki version: 1.12

Token[edit | edit source]

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 | edit source]

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 | edit source]

  • 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.
  • 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)

Example[edit | edit source]

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

day&reason=Time%20out&nocreate=&noemail=&token=0123456789012345678901234567890123456789%2b%5c api.php?action=block&user=Example&expiry=1 day&reason=Time%20out&nocreate=&noemail=&token=0123456789012345678901234567890123456789%2b%5c day&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 | edit source]

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 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 e-mail through the wiki

Unblocking users[edit | edit source]

Users can be unblocked with action=unblock.

Parameters[edit | edit source]

One of id or user 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.
  • token: A previously obtained unblock token. Take care to properly urlencode the + and \.
  • reason: The reason for the unblock (optional).
  • gettoken: If set, a token will be returned. (deprecated in 1.20) (removed in 1.21)

Sample request[edit | edit source]

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 | edit source]

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.
Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Block&oldid=1653793"