API:Rollback

Translate this page

This page is part of the MediaWiki Action API documentation.

MediaWiki version:

≥ 1.12

POST request to revert the last series of edits made by one user to a given page.

This functionality is identical to the one provided by the rollback links in the graphical interface on history page.

API documentation

The following documentation is the output of Special:ApiHelp/rollback, automatically generated by the pre-release version of MediaWiki that is running on this site (MediaWiki.org).

action=rollback

(main | rollback)

This module requires read rights.
This module requires write rights.
This module only accepts POST requests.
Source: MediaWiki
License: GPL-2.0-or-later

Undo the last edit to the page.

If the last user who edited the page made multiple edits in a row, they will all be rolled back.

https://www.mediawiki.org/wiki/Special:MyLanguage/API:Rollback

Specific parameters:

Other general parameters are available.

title

Title of the page to roll back. Cannot be used together with pageid.

pageid

Page ID of the page to roll back. Cannot be used together with title.

Type: integer

tags

Tags to apply to the rollback.

Values (separate with | or alternative): AWB, convenient-discussions

user

Name of the user whose edits are to be rolled back.

This parameter is required.

Type: user, by any of username, IP, Temporary user, interwiki name (e.g. "prefix>ExampleName") and user ID (e.g. "#12345")

summary

Custom edit summary. If empty, default summary will be used.

Default: (empty)

markbot

Mark the reverted edits and the revert as bot edits.

Type: boolean (details)

watchlist

Unconditionally add or remove the page from the current user's watchlist, use preferences (ignored for bot users) or do not change watch.

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

Default: preferences

watchlistexpiry

Watchlist expiry timestamp. Omit this parameter entirely to leave the current expiry unchanged.

Type: expiry (details)

token

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

For compatibility, the token used in the web UI is also accepted.

This parameter is required.

Examples:

Roll back the last edits to page MediaWiki by user Example.: api.php?action=rollback&title=MediaWiki&user=Example&token=123ABC [open in sandbox]
Roll back the last edits to page MediaWiki by IP user 192.0.2.5 with summary Reverting vandalism, and mark those edits and the revert as bot edits.: api.php?action=rollback&title=MediaWiki&user=192.0.2.5&token=123ABC&summary=Reverting%20vandalism&markbot=1 [open in sandbox]

Example

Making any POST request is a multi-step process:

Log in, via one of the methods described in API:Login .
GET a CSRF token :
api.php?action=query&format=json&meta=tokens [try in ApiSandbox]
Send a POST request, with the CSRF token, to take action on a page and in this process gain editpage rights to the given page:
api.php?action=edit&format=json&title=Sandbox&appendtext=Hello&token=sampleCsrfToken123+\ [try in ApiSandbox]
GET a rollback token:
- If your wiki is using MediaWiki 1.24+, follow these instructions:
  api.php?action=query&meta=tokens&type=rollback [try in ApiSandbox]
- Rollback tokens aren't universal: they are not only different for every login, but also depend on the title of the page and the name of the user whose edits are to be rolled back. For MediaWiki 1.23 or earlier, follow these instructions:
  api.php?action=query&prop=revisions&rvtoken=rollback [try in ApiSandbox]

POST request

Send a POST request, with a rollback token to revert a user's edits to the Sandbox page.

In this example, all parameters are passed in a GET request just for the sake of simplicity. However, action=rollback requires POST requests; GET requests will cause an error.

api.php?action=rollback&format=json&title=Sandbox&user=41.190.3.231&token=d36a517a732991d5aaafae8bd40eee4a5c7bf75a+\\ [try in ApiSandbox]

Response

The Response section below is for the final POST request, to revert the edits to the Sandbox page.

{
    "rollback": {
        "title": "Sandbox",
        "pageid": 94542,
        "summary": "Reverted edits by [[Special:Contributions/41.190.3.231|41.190.3.231]] ([[User talk:41.190.3.231|talk]]) to last revision by [[User:Didicodes|Didicodes]]",
        "revid": 381084,
        "old_revid": 381083,
        "last_revid": 381070
    }
}

The revision IDs in the response are:

revid - The ID of the new revision created by the rollback.
old_revid - The ID of the newest revision being rolled back. Before the rollback, this was the current revision.
last_revid - The ID of the revision being restored by the rollback. This is the newest revision having been rolled back.

Sample code

Python

#!/usr/bin/python3

"""
    rollback.py

    MediaWiki API Demos
    Demo of `rollback` module: Sending post request to rollback the
    last edits made to 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",
    "format": "json"
}

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

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

# Step 4: POST request to edit a page
PARAMS_4 = {
    "action": "edit",
    "title": "Project:Sandbox",
    "token": CSRF_TOKEN,
    "format": "json",
    "appendtext": "Hello"
}

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

# Step 5: Retrieve a rollback token
PARAMS_5 = {
    "action": "query",
    "meta": "tokens",
    "type": "rollback",
    "format": "json"
}

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

ROLLBACK_TOKEN = DATA['query']['tokens']['rollbacktoken']

# Step 5: POST request to rollback a page
PARAMS_6 = {
    "action": "rollback",
    "format": "json",
    "title": "Project:Sandbox",
    "user": "bot_user_name",
    "token": ROLLBACK_TOKEN,
}

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

print(DATA)

PHP

<?php

/*
    rollback.php

    MediaWiki API Demos
    Demo of `rollback` module: Sending post request to rollback the
    edits of a given page.
    MIT license
*/

$endPoint = "http://dev.wiki.local.wmftest.net:8080/w/api.php";

$login_Token = getLoginToken(); // Step 1
loginRequest( $login_Token ); // Step 2
$rollback_Token = getRollbackToken(); // Step 3
rollback( $rollback_Token ); // Step 4

// Step 1: GET request to fetch login token
function getLoginToken() {
	global $endPoint;

	$params1 = [
		"action" => "query",
		"meta" => "tokens",
		"type" => "login",
		"format" => "json"
	];

	$url = $endPoint . "?" . http_build_query( $params1 );

	$ch = curl_init( $url );
	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
	curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
	curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );

	$output = curl_exec( $ch );
	curl_close( $ch );

	$result = json_decode( $output, true );
	return $result["query"]["tokens"]["logintoken"];
}

// Step 2: POST request to log in. Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest( $logintoken ) {
	global $endPoint;

	$params2 = [
		"action" => "login",
		"lgname" => "bot_user_name",
		"lgpassword" => "bot_password",
		"lgtoken" => $logintoken,
		"format" => "json"
	];

	$ch = curl_init();

	curl_setopt( $ch, CURLOPT_URL, $endPoint );
	curl_setopt( $ch, CURLOPT_POST, true );
	curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params2 ) );
	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
	curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
	curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );

	$output = curl_exec( $ch );
	curl_close( $ch );

}

// Step 3: GET request to fetch rollback token
function getRollbackToken() {
	global $endPoint;

	$params3 = [
		"action" => "query",
		"meta" => "tokens",
		"type" => "rollback",
		"format" => "json"
	];

	$url = $endPoint . "?" . http_build_query( $params3 );

	$ch = curl_init( $url );

	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
	curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
	curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );

	$output = curl_exec( $ch );
	curl_close( $ch );

	$result = json_decode( $output, true );
	return $result["query"]["tokens"]["rollbacktoken"];
}

// Step 4: POST request to rollback a page
function rollback( $rollback_Token ) {
	global $endPoint;

	$params4 = [
		"action" => "rollback",
		"title" => "Project:Sandbox",
		"user" => "10.0.2.2",
		"token" => $rollback_Token,
		"format" => "json"
	];

	$ch = curl_init();

	curl_setopt( $ch, CURLOPT_URL, $endPoint );
	curl_setopt( $ch, CURLOPT_POST, true );
	curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params4 ) );
	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
	curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
	curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );

	$output = curl_exec( $ch );
	curl_close( $ch );

	echo ( $output );
}

JavaScript

/*  
    rollback.js
 
    MediaWiki API Demos
    Demo of `rollback` module: Sending post request to rollback the
    edits of a given page.

    MIT license
*/

var request = require('request').defaults({jar: true}),
    url = "http://dev.wiki.local.wmftest.net:8080/w/api.php";

// Step 1: GET request to fetch login token
function getLoginToken() {
    var params_0 = {
        action: "query",
        meta: "tokens",
        type: "login",
        format: "json"
    };

    request.get({ url: url, qs: params_0 }, function (error, res, body) {
        if (error) {
            return;
        }
        var data = JSON.parse(body);
        loginRequest(data.query.tokens.logintoken);
    });
}

// Step 2: POST request to log in. 
// Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest(login_token) {
    var params_1 = {
        action: "login",
        lgname: "bot_username",
        lgpassword: "bot_password",
        lgtoken: login_token,
        format: "json"
    };

    request.post({ url: url, form: params_1 }, function (error, res, body) {
        if (error) {
            return;
        }
        getRollbackToken();
    });
}

// Step 3: GET request to fetch Rollback token
function getRollbackToken() {
    var params_2 = {
        action: "query",
        meta: "tokens",
        type: "rollback",
        format: "json"
    };

    request.get({ url: url, qs: params_2 }, function(error, res, body) {
        if (error) {
            return;
        }
        var data = JSON.parse(body);
        rollback(data.query.tokens.rollbacktoken);
    });
}

// Step 4: POST request to rollback a page
function rollback(rollback_token) {
    var params_3 = {
        action: "rollback",
        title: "Project:Sandbox",
        user: "10.0.2.2",
        token: rollback_token,
        format: "json"
    };

    request.post({ url: url, form: params_3 }, function (error, res, body) {
        if (error) {
            return;
        }
        console.log(body);
    });
}

// Start From Step 1
getLoginToken();

MediaWiki JS

/*
	rollback.js

	MediaWiki API Demos
	Demo of `rollback` module: Sending post request to rollback the
    last edits made to a given page.

	MIT License
*/

var params = {
		action: 'rollback',
		title: 'Sandbox',
		user: '10.0.2.2',
		format: 'json'
	},
	api = new mw.Api();

api.postWithToken( 'rollback', params ).done( function ( data ) {
	console.log( data );
} );

Permissions

Tracked in Phabricator
Task T212851

Rollback requires both the edit and the rollback right on the target page; currently, this means that OAuth consumers, bot passwords etc. require both the editpage and the rollback grant – rollback alone is not enough!

Possible errors

In addition to the usual stuff:

Code	Info
alreadyrolled	The page you tried to rollback was already rolled back
missingparams	One of the parameters `title` and `pageid` is required.
mustpostparams	The rollback module requires a POST request.
notitle	The `title` parameter must be set.
notoken	The `token` parameter must be set.
nouser	The `user` parameter must be set.
onlyauthor	The page you tried to rollback only has one author
permissiondenied	The action you have requested is limited to users in one of the groups: Administrators, Rollbackers

Parameter history

v1.24: Introduced pageid
v1.27: Introduced tags
v1.17: Introduced watchlist

Additional notes

Optionally, both the rollback and the edits being rolled back can be marked as bot, which hides them from Special:RecentChanges by default.