API:Protect

From MediaWiki.org
Jump to navigation Jump to search

Other languages:
Deutsch • ‎English • ‎dansk • ‎español • ‎français • ‎português • ‎română • ‎русский • ‎ไทย • ‎中文 • ‎日本語 • ‎한국어
MediaWiki version: 1.12

POST request to change a page's protection level.

API documentation[edit]


action=protect

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

Change the protection level of a page.

Parameters:
title

Title of the page to (un)protect. Cannot be used together with pageid.

pageid

ID of the page to (un)protect. Cannot be used together with title.

Type: integer
protections

List of protection levels, formatted action=level (e.g. edit=sysop). A level of all means everyone is allowed to take the action, i.e. no restriction.

Note: Any actions not listed will have restrictions removed.

This parameter is required.
Separate values with | or alternative. Maximum number of values is 50 (500 for bots).
expiry

Expiry timestamps. If only one timestamp is set, it'll be used for all protections. Use infinite, indefinite, infinity, or never, for a never-expiring protection.

Separate values with | or alternative. Maximum number of values is 50 (500 for bots).
Default: infinite
reason

Reason for (un)protecting.

Default: (empty)
tags

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

Values (separate with | or alternative):
cascade

Enable cascading protection (i.e. protect transcluded templates and images used in this page). Ignored if none of the given protection levels support cascading.

Type: boolean (details)
watch
Deprecated.

If set, add the page being (un)protected to the current user's watchlist.

Type: boolean (details)
watchlist

Unconditionally add or remove the page from the current user's watchlist, use preferences or do not change watch.

One of the following values: watch, unwatch, preferences, nochange
Default: preferences
token

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

This parameter is required.

Example[edit]

Protecting a page is a multi-step process:

  1. Log in using one of the methods described in API:Login .
  2. Get a CSRF token . This token is the same for all pages, but changes at every login.
  3. Send a POST request with the CSRF token in order to protect the page.

The sample code below covers the third step in detail.

POST request[edit]

Protect the Main Page for an infinite of time to allow only autoconfirmed users to edit it and only sysops to move it.

Response[edit]

{
    "protect": {
        "title": "Main Page",
        "reason": "",
        "protections": [
            {
                "edit": "autoconfirmed",
                "expiry": "infinite"
            },
            {
                "move": "sysop",
                "expiry": "infinite"
            }
        ]
    }
}

Sample code[edit]

protect.py

#!/usr/bin/python3

"""
    protect.py

    MediaWiki Action API Code Samples
    Demo of `Protect` module: Demo to change the edit protection level of a given page.

    MIT License
"""

import requests

S = requests.Session()

URL = "https://test.wikipedia.org/w/api.php"

# Step 1: Retrieve a login token
PARAMS_1 = {
    "action": "query",
    "meta": "tokens",
    "type": "login",
    "format": "json"
}

R = S.get(url=URL, params=PARAMS_1)
DATA = R.json()

LOGIN_TOKEN = DATA['query']['tokens']['logintoken']

# Step 2: Send a post request to login. Use of main account for login 
# is not supported. Obtain credentials via Special:BotPasswords
# (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & 
# lgpassword
PARAMS_2 = {
    "action": "login",
    "lgname": "bot_user_name",
    "lgpassword": "bot_password",
    "lgtoken": LOGIN_TOKEN,
    "format": "json"
}

R = S.post(URL, data=PARAMS_2)

# Step 3: While logged in, retrieve a CSRF token
PARAMS_3 = {
    "action": "query",
    "meta": "tokens",
    "type": "csrf",
    "format": "json"
}

R = S.get(url=URL, params=PARAMS_3)
DATA = R.json()

CSRF_TOKEN = DATA["query"]["tokens"]["csrftoken"]

# Step 4: Changing 'edit protection level' of a page using POST request
PARAMS_4 = {
    "title": "Main Page",
    "edit": "autoconfirmed",
    "move": "sysop",
    "expiry": "infinite",
    "token": CSRF_TOKEN,
    "action": "protect"
}

R = S.post(URL, data=PARAMS_4)
DATA = R.json()

print(DATA)

Possible errors[edit]

In addition to the standard error messages:

Code Info
notitle The title parameter must be set.
notoken The token parameter must be set.
noprotections The protections parameter must be set.
invalidexpiry Expiry time "expiry" is in the past.
This means the expiry timestamp was invalidly formatted, or is nonexistent (like November 31 or 24:05).
pastexpiry Expiry time "expiry" is in the past.
toofewexpiries number expiry timestamps were provided where number2 were needed.
This error is misnamed: it's also thrown when you specify too many expiry times
cantedit You can't protect this page because you can't edit it
create-titleexists Existing titles can't be protected with create.
missingtitle-createonly Missing titles can only be protected with create.
protect-invalidaction Invalid protection type "type".
protect-invalidlevel Invalid protection level "level".

Parameter history[edit]

  • v1.27: Introduced tags
  • v1.20: Introduced pageid
  • v1.17: Introduced watchlist. Deprecated watch
  • v1.15: Introduced watch

Additional Notes[edit]

  • This module requires protect rights.
  • For MediaWiki versions 1.19 and earlier, you can obtain a protect token through API:Info .
  • For MediaWiki 1.20-1.23, you can obtain a protect token through API:Tokens_(action) .

See also[edit]