API:Block

This page is part of the MediaWiki API documentation.

MediaWiki API

Quick overview:

• Quick start guide
• FAQ
  • Etiquette and usage limits
• Tutorial
• Formats
• Error reporting
• Restricting usage
• Cross-site requests
• Authentication
  • Login
  • Logout
  • Account creation
• Queries
  • Meta information
  • Properties
  • Lists
• Search suggestions
• Parsing wikitext and expanding templates
• Purging pages' caches
• Parameter information
• Changing wiki content
  • Create and edit pages
  • Move pages
  • Rollback
  • Delete pages
  • Restore deleted revisions
  • (Un)protect pages
  • (Un)block users
  • (Un)watch pages
  • Mark revisions of watched pages as visited
  • Send email
  • Patrol changes
  • Import pages
  • Change user group membership
  • Upload files
  • User options
  • Tokens
  • Page language
• Watchlist feed
• Wikidata
• Extensions
• Using the API in MediaWiki and extensions
• Miscellaneous
• Implementation
• Client code
• Asserting

For the API for enumerating blocks, see API:Blocks.

MediaWiki version:

1.12

Token

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 via action=tokens with the type set to (un)block (MW 1.20+), or by using the following method:

Obtaining a block token

api.php?action=query&prop=info&intoken=block&titles=User:Bob

Obtaining an unblock token

api.php?action=query&prop=info&intoken=unblock&titles=User:Bob

Blocking users

Users can be blocked with action=block.

Parameters

• 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.
• 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)
• reblock: If the user is already blocked, overwrite the existing block
• watchuser: Watch the user/IP's user and talk pages

Don't forget to append = even to parameters with no value, for example &autoblock doesn't work, &autoblock= does work

Example

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\

Possible errors

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

Users can be unblocked with action=unblock.

Parameters

• 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

Unblocking Bob, and apologizing

api.php?action=unblock&user=Bob&token=bffd6f4fbd23ed07254ec3cec8fa69da%2B\&reason=Sorry%20Bob

Possible errors

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.