API:Block

From MediaWiki.org
Jump to: navigation, search
Tools clipart.png This page is part of the MediaWiki API documentation.
Language: English  • Deutsch • 日本語
MediaWiki API

Quick overview:

v · d · e
MediaWiki version: = 1.12

Token[edit | edit source]

To (un)block a user, a(n) (un)block token is required. This token is equal to the edit token and the same for all blocks, but changes at every login. A(n) (un)block token can be obtained the following ways:

Obtaining a block token

api.php?action=query&prop=info&intoken=block&titles=User:Bob
Result
The following content has been placed in a collapsed box for improved usability. 
<?xml version="1.0"?>
<api>
  <query>
    <pages>
      <page ns="2" title="User:Bob" missing="" starttimestamp="2008-10-27T12:15:36Z"
        blocktoken="101089c295402adff96016ca002480c8+\" />
    </pages>
  </query>
</api>
The above content has been placed in a collapsed box for improved usability.

Obtaining an unblock token

api.php?action=query&prop=info&intoken=unblock&titles=User:Bob
Result
The following content has been placed in a collapsed box for improved usability. 
<<?xml version="1.0"?>
<api>
  <query>
    <pages>
      <page ns="2" title="User:Bob" missing="" starttimestamp="2008-10-27T12:15:36Z"
        unblocktoken="101089c295402adff96016ca002480c8+\" />
    </pages>
  </query>
</api>
The above content has been placed in a collapsed box for improved usability.

Blocking users[edit | edit source]

Users can be blocked with action=block.

Parameters[edit | edit source]

  • user: The username, IP address or IP range you want to block.
  • token: The token obtained in the previous request. Take care to urlencode the + as %2B.
  • expiry: Expiry timestamp. Relative expiry times, like 5 months or 2 weeks are also accepted. If set to infinite, infinity, never, or not set at all, the block will never expire.
  • 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.

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 Bob for 1 day, disabling account creation and email

api.php?action=block&user=Bob&expiry=1%20day&reason=Time%20out&nocreate&noemail&token=bffd6f4fbd23ed07254ec3cec8fa69da%2B\
Result
The following content has been placed in a collapsed box for improved usability. 
<?xml version="1.0" encoding="utf-8"?>
<api>
  <block
    user="Bob"
    userID="147"
    expiry="20070906231113"
    reason="Time out"
    nocreate=""
    noemail=""
  />
</api>
The above content has been placed in a collapsed box for improved usability.

Possible errors[edit | edit source]

In addition to the usual stuff:

  • code: nouser
    • info: The user parameter must be set
  • code: notoken
    • info: The token parameter must be set
  • code: permissiondenied
    • info: You don't have permission to block users
      • On most wikis, blocking users is restricted to sysops, but other wikis may have stricter rules.
  • code: invalidrange
    • info: Invalid IP range
  • code: rangedisabled
    • info: Blocking IP ranges has been disabled
  • code: invalidip
    • info: Invalid IP address specified
  • code: invalidexpiry
    • info: Invalid expiry time
  • code: alreadyblocked
    • info: The user you tried to block was already blocked
  • code: pastexpiry
    • info: Expiry time is in the past
  • code: cantblock
    • info: You don't have permission to block users
  • code: canthide
    • info: You don't have permission to hide user names from the block log
      • This feature has to be enabled explicitly in LocalSettings.php.
  • code: cantblock-email
    • info: 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]

  • 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: The token obtained in the previous request. Take care to urlencode the + as %2B.
  • gettoken: If set, a token will be returned.
  • reason: The reason for the unblock (optional).

Sample request[edit | edit source]

Unblocking Bob, and apologizing

api.php?action=unblock&user=Bob&token=bffd6f4fbd23ed07254ec3cec8fa69da%2B\&reason=Sorry%20Bob
Result
The following content has been placed in a collapsed box for improved usability. 
<?xml version="1.0" encoding="utf-8"?>
<api>
  <unblock
    id="17"
    user="Bob"
    reason="Sorry Bob"
  />
</api>
The above content has been placed in a collapsed box for improved usability.

Possible errors[edit | edit source]

In addition to the usual stuff:

  • code: notarget
    • info: Either the id or the user parameter must be set
  • code: notoken
    • info: The token parameter must be set
  • code: idanduser
    • info: The id and user parameters can't be used together
  • code: blockedasrange
    • info: IP address ``address'' was blocked as part of range ``range''. You can't unblock the IP invidually, but you can unblock the range as a whole.
  • code: cantunblock
    • info: The block you specified was not found. It may have been unblocked already
  • code: permissiondenied
    • info: You don't have permission to unblock users
      • On most wikis, unblocking users is restricted to sysops, but other wikis may have stricter rules.
Retrieved from "http://www.mediawiki.org/w/index.php?title=API:Block&oldid=774372"