API:Block
This page is part of the MediaWiki action API documentation. |
MediaWiki action API
- Introduction and quick start
- FAQ
- Tutorial
- Formats
- Error reporting
- Restricting usage
- Cross-site requests
- Authentication
- Queries
- Searching (by title, content, coordinates...)
- Parsing wikitext and expanding templates
- Purging pages' caches
- Parameter information
- Changing wiki content
- Create and edit pages
- Move pages
- Merge 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
- More...
- Watchlist feed
- Wikidata
- Extensions
- Using the API in MediaWiki and extensions
- Miscellaneous
- Implementation
- Client code
- Asserting
Unblock | ||
---|---|---|
Unblock a user. This module cannot be used as a Generator . |
||
Prefix | none | |
Required rights | block | |
Post only? | Yes | |
Generated help | Current | |
Version added |
|
Block | ||
---|---|---|
Block a user. This module cannot be used as a Generator . |
||
Prefix | none | |
Required rights | block | |
Post only? | Yes | |
Generated help | Current | |
Version added |
|
Contents
Token
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
Result |
---|
{
"query": {
"tokens": {
"csrftoken": "0123456789012345678901234567890123456789+\\"
}
}
}
|
Blocking users
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
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, like5 months
or2 weeks
are also accepted. If set toinfinite
,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
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
Result |
---|
{
"block": {
"user": "Example",
"userID": 2,
"expiry": "2015-02-25T07:27:50Z",
"id": "8",
"reason": "Time out"
"nocreate": "",
"noemail": ""
}
}
|
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 "$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. |
The following documentation is the output of Special:ApiHelp/block, automatically generated by the pre-release version of MediaWiki that is running on this site (MediaWiki.org). |
action=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.
- 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.
- 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
Users can be unblocked with action=unblock.
Parameters
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=blocksuser
: 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
Unblocking Example and apologizing
Result |
---|
{
"id": "16",
"user": "Example",
"userid": 2,
"reason": "Sorry Example"
}
|
Possible errors
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. |
The following documentation is the output of Special:ApiHelp/unblock, automatically generated by the pre-release version of MediaWiki that is running on this site (MediaWiki.org). |
action=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.
- 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.
- 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]