MediaWiki version:
1.20

POST request to change preferences of the current user.

API documentation


Special:ApiHelp/options

Example

Making any POST request is a multi-step process:

  1. Log in, via one of the methods described on API:Login.
  2. Get an Edit token.
  3. Send a POST request, with the CSRF token, to take action on a page.

The sample code below covers the final step in detail.

POST request

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

Changing three options

Result
<?xml version="1.0" encoding="utf-8"?>
<api options="success" />

Response

{
    "options": "success"
}

Sample code

Python

#!/usr/bin/python3

"""
    change_user_options.py

    MediaWiki API Demos
    Demo of `Options` module: POST request to change three options
    for current user

    MIT license
"""

import requests

S = requests.Session()

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

# Step 1: GET request to fetch login token
PARAMS_0 = {
    "action": "query",
    "meta": "tokens",
    "type": "login",
    "format": "json"
}

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

LOGIN_TOKEN = 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
PARAMS_1 = {
    "action": "login",
    "lgname": "bot_user_name",
    "lgpassword": "bot_password",
    "lgtoken": LOGIN_TOKEN,
    "format": "json"
}

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

# Step 3: GET request to fetch CSRF token
PARAMS_2 = {
    "action": "query",
    "meta": "tokens",
    "format": "json"
}

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

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

# Step 4: POST request to change user options
# You can check out the large list of options you can change
# at https://www.mediawiki.org/wiki/API:Options
PARAMS_3 = {
    "action": "options",
    "format": "json",
    "token": CSRF_TOKEN,
    "change": "language=en|skin=vector",
    "optionname": "nickname",
    "optionvalue": "custom-signa|ture"
}

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

print(DATA)

PHP

<?php

/*
    change_user_options.php

    MediaWiki API Demos
    Demo of `Options` module: POST request to change three options
    for current user
    MIT license
*/

$endPoint = "https://test.wikipedia.org/w/api.php";

$login_Token = getLoginToken(); // Step 1
loginRequest( $login_Token ); // Step 2
$csrf_Token = getCSRFToken(); // Step 3
change_options( $csrf_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 CSRF token
function getCSRFToken() {
	global $endPoint;

	$params3 = [
		"action" => "query",
		"meta" => "tokens",
		"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"]["csrftoken"];
}

// Step 4: POST request to edit a page
function change_options( $csrftoken ) {
	global $endPoint;

	$params4 = [
		"action" => "options",
		"change" => "language=en|skin=timeless",
		"optionname" => "nickname",
		"optionvalue" => "custom-signa|ture",
		"token" => $csrftoken,
		"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

/*  
    change_user_options.js
 
    MediaWiki API Demos
    Demo of `Options` module: POST request to change two options
    for current user

    MIT license
*/

var request = require('request').defaults({jar: true}),
    url = "https://test.wikipedia.org/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;
        }
        getCsrfToken();
    });
}

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

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

// Step 4: POST request to change the user options
function change_options(csrf_token) {
    var params_3 = {
        action: "options",
        change: "language=en|skin=timeless",
        token: csrf_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

/*
	change_user_options.js

	MediaWiki API Demos
	Demo of `Options` module: POST request to change three options
    for current user

	MIT License
*/

var params = {
		action: 'options',
		change: 'language=en|skin=monobook',
		optionname: 'nickname',
		optionvalue: 'custom-signa|ture',
		format: 'json'
	},
	api = new mw.Api();

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

Available options

The following is an example list obtained with /w/api.php?action=query&format=json&meta=userinfo&uiprop=options for a English Wikipedia, MediaWiki 1.40.0-wmf.14 (c526317) (December 2022) account. Most of the options listed here are defined by various MediaWiki extensions, like Echo , VisualEditor , WikiLove , or Gadgets or GrowthExperiments , among others.
* enotifusertalkpages: 0
  • vector-limited-width: 1
  • vector-page-tools-pinned: 1
  • flaggedrevssimpleui: 1
  • flaggedrevsstable: 0
  • flaggedrevseditdiffs: True
  • flaggedrevsviewdiffs: False
  • flaggedrevswatch: False
  • globaluserpage: True
  • rcenhancedfilters-seen-highlight-button-counter: 0
  • advancedsearch-disable: False
  • usebetatoolbar: 1
  • wikieditor-realtimepreview: 0
  • usecodemirror: 0
  • betafeatures-auto-enroll: False
  • popupsreferencepreviews: 0
  • popups-reference-previews: 0
  • visualeditor-autodisable: 0
  • visualeditor-betatempdisable: 0
  • visualeditor-editor: wikitext
  • visualeditor-enable: 1
  • visualeditor-enable-experimental: 0
  • visualeditor-enable-language: 0
  • visualeditor-hidebetawelcome: 0
  • visualeditor-hidetabdialog: 0
  • visualeditor-newwikitext: 0
  • visualeditor-tabs: remember-last
  • visualeditor-visualdiffpage: 0
  • mobile-editor:
  • math: mathml
  • echo-subscriptions-web-page-review: True
  • echo-subscriptions-email-page-review: False
  • echo-subscriptions-web-login-fail: True
  • echo-subscriptions-email-login-fail: True
  • echo-subscriptions-web-login-success: False
  • echo-subscriptions-email-login-success: True
  • echo-email-frequency: 0
  • echo-dont-email-read-notifications: False
  • echo-subscriptions-web-edit-thank: True
  • echo-subscriptions-email-edit-thank: False
  • discussiontools-betaenable: 0
  • discussiontools-editmode:
  • discussiontools-newtopictool: 1
  • discussiontools-newtopictool-createpage: 1
  • discussiontools-replytool: 1
  • discussiontools-sourcemodetoolbar: 1
  • discussiontools-topicsubscription: 1
  • discussiontools-autotopicsub: 0
  • discussiontools-visualenhancements: 1
  • usecodeeditor: 1
  • revisionslider-disable: False
  • twocolconflict-enabled: 1
  • eventlogging-display-web: 0
  • eventlogging-display-console: 0
  • uls-preferences:
  • compact-language-links: 1
  • echo-subscriptions-web-cx: True
  • cx: False
  • cx-enable-entrypoints: True
  • cx-entrypoint-fd-status: notshown
  • cx_campaign_newarticle_shown: False
  • rcshowwikidata: 0
  • wlshowwikibase: 0
  • echo-subscriptions-web-oauth-owner: True
  • echo-subscriptions-email-oauth-owner: True
  • echo-subscriptions-web-oauth-admin: True
  • echo-subscriptions-email-oauth-admin: True
  • ores-damaging-flag-rc: False
  • oresDamagingPref: soft
  • rcOresDamagingPref: soft
  • oresHighlight: False
  • oresRCHideNonDamaging: False
  • oresWatchlistHideNonDamaging: False
  • ipinfo-use-agreement: 0
  • twl-notified: None
  • ccmeonemails: 0
  • date: default
  • diffonly: 0
  • disablemail: 0
  • editfont: monospace
  • editondblclick: 0
  • editsectiononrightclick: 0
  • email-allow-new-users: 1
  • enotifminoredits: False
  • enotifrevealaddr: 0
  • enotifwatchlistpages: 0
  • extendwatchlist: 0
  • fancysig: 0
  • forceeditsummary: 0
  • gender: unknown
  • hideminor: 0
  • hidepatrolled: 0
  • hidecategorization: 1
  • imagesize: 2
  • minordefault: 0
  • newpageshidepatrolled: 0
  • nickname:
  • pst-cssjs: 1
  • norollbackdiff: 0
  • previewonfirst: 0
  • previewontop: 1
  • rcdays: 7
  • rcenhancedfilters-disable: 0
  • rclimit: 50
  • search-match-redirect: True
  • search-special-page: Search
  • searchlimit: 20
  • search-thumbnail-extra-namespaces: True
  • showhiddencats: False
  • shownumberswatching: 1
  • showrollbackconfirmation: 0
  • skin: vector
  • thumbsize: 4
  • underline: 2
  • uselivepreview: 0
  • usenewrc: 0
  • watchcreations: True
  • watchdefault: 0
  • watchdeletion: 0
  • watchuploads: 1
  • watchlistdays: 3
  • watchlisthideanons: 0
  • watchlisthidebots: 0
  • watchlisthideliu: 0
  • watchlisthideminor: 0
  • watchlisthideown: 0
  • watchlisthidepatrolled: 0
  • watchlisthidecategorization: 1
  • watchlistreloadautomatically: 0
  • watchlistunwatchlinks: 0
  • watchmoves: 0
  • watchrollback: 0
  • wlenhancedfilters-disable: 0
  • wllimit: 250
  • useeditwarning: 1
  • prefershttps: 1
  • requireemail: 0
  • skin-responsive: 1
  • wikilove-enabled: 1
  • echo-cross-wiki-notifications: 1
  • growthexperiments-addimage-desktop: 1
  • timecorrection: System|0
  • centralnotice-display-campaign-type-advocacy: 1
  • centralnotice-display-campaign-type-article-writing: 1
  • centralnotice-display-campaign-type-photography: 1
  • centralnotice-display-campaign-type-event: 1
  • centralnotice-display-campaign-type-fundraising: 1
  • centralnotice-display-campaign-type-governance: 1
  • centralnotice-display-campaign-type-maintenance: 1
  • centralnotice-display-campaign-type-special: 1
  • language: en
  • variant: en
  • variant-ban: ban
  • variant-en: en
  • variant-crh: crh
  • variant-gan: gan
  • variant-iu: iu
  • variant-kk: kk
  • variant-ku: ku
  • variant-sh: sh-latn
  • variant-shi: shi
  • variant-sr: sr
  • variant-tg: tg
  • variant-tly: tly
  • variant-uz: uz
  • variant-zh: zh
  • searchNs0: 1
  • searchNs1: 0
  • searchNs2: 0
  • searchNs3: 0
  • searchNs4: 0
  • searchNs5: 0
  • searchNs6: 0
  • searchNs7: 0
  • searchNs8: 0
  • searchNs9: 0
  • searchNs10: 0
  • searchNs11: 0
  • searchNs12: 0
  • searchNs13: 0
  • searchNs14: 0
  • searchNs15: 0
  • searchNs100: 0
  • searchNs101: 0
  • searchNs118: 0
  • searchNs119: 0
  • searchNs710: 0
  • searchNs711: 0
  • searchNs828: 0
  • searchNs829: 0
  • searchNs2300: 0
  • searchNs2301: 0
  • searchNs2302: 0
  • searchNs2303: 0
  • multimediaviewer-enable: 1
  • mf_amc_optin: 0
  • gadget-modrollback: 0
  • gadget-confirmationRollback-mobile: 1
  • gadget-removeAccessKeys: 0
  • gadget-searchFocus: 0
  • gadget-GoogleTrans: 0
  • gadget-ImageAnnotator: 0
  • gadget-imagelinks: 0
  • gadget-Navigation_popups: 0
  • gadget-exlinks: 0
  • gadget-search-new-tab: 0
  • gadget-PrintOptions: 0
  • gadget-revisionjumper: 0
  • gadget-Twinkle: 0
  • gadget-HideCentralNotice: 0
  • gadget-ReferenceTooltips: 1
  • gadget-formWizard: 1
  • gadget-Prosesize: 0
  • gadget-find-archived-section: 0
  • gadget-geonotice: 1
  • gadget-watchlist-notice: 1
  • gadget-WatchlistBase: 1
  • gadget-WatchlistGreenIndicators: 1
  • gadget-WatchlistGreenIndicatorsMono: 1
  • gadget-WatchlistChangesBold: 0
  • gadget-SubtleUpdatemarker: 1
  • gadget-defaultsummaries: 0
  • gadget-citations: 0
  • gadget-DotsSyntaxHighlighter: 0
  • gadget-HotCat: 0
  • gadget-wikEdDiff: 0
  • gadget-ProveIt: 0
  • gadget-ProveIt-classic: 0
  • gadget-Shortdesc-helper: 0
  • gadget-wikEd: 0
  • gadget-afchelper: 0
  • gadget-charinsert: 1
  • gadget-legacyToolbar: 0
  • gadget-extra-toolbar-buttons: 1
  • gadget-refToolbar: 1
  • gadget-EditNoticesOnMobile: 1
  • gadget-edittop: 0
  • gadget-UTCLiveClock: 0
  • gadget-purgetab: 0
  • gadget-ExternalSearch: 0
  • gadget-CollapsibleNav: 0
  • gadget-MenuTabsToggle: 0
  • gadget-dropdown-menus: 0
  • gadget-CategoryAboveAll: 0
  • gadget-addsection-plus: 0
  • gadget-CommentsInLocalTime: 0
  • gadget-OldDiff: 0
  • gadget-NoAnimations: 0
  • gadget-disablesuggestions: 0
  • gadget-NoSmallFonts: 0
  • gadget-topalert: 0
  • gadget-metadata: 0
  • gadget-JustifyParagraphs: 0
  • gadget-righteditlinks: 0
  • gadget-PrettyLog: 0
  • gadget-switcher: 1
  • gadget-SidebarTranslate: 0
  • gadget-Blackskin: 0
  • gadget-dark-mode-toggle: 0
  • gadget-VectorClassic: 0
  • gadget-widensearch: 0
  • gadget-DisambiguationLinks: 0
  • gadget-markblocked: 0
  • gadget-responsiveContent: 0
  • gadget-responsiveContentTimeless: 1
  • gadget-HideInterwikiSearchResults: 0
  • gadget-XTools-ArticleInfo: 0
  • gadget-ShowMessageNames: 0
  • gadget-DebugMode: 0
  • gadget-contribsrange: 0
  • gadget-BugStatusUpdate: 0
  • gadget-RTRC: 0
  • gadget-script-installer: 0
  • gadget-XFDcloser: 0
  • gadget-mobile-sidebar: 0
  • gadget-addMe: 0
  • gadget-NewImageThumb: 0
  • gadget-StickyTableHeaders: 0
  • gadget-MobileMaps: 0
  • gadget-ShowJavascriptErrors: 0
  • gadget-PageDescriptions: 0
  • gadget-autonum: 0
  • gadget-wide-vector-2022: 0
  • gadget-dark-mode: 0
  • cirrussearch-pref-completion-profile: fuzzy
  • popups: 0
  • echo-email-format: html
  • echo-subscriptions-email-system: True
  • echo-subscriptions-web-system: True
  • echo-subscriptions-push-system: True
  • echo-subscriptions-email-system-noemail: False
  • echo-subscriptions-web-system-noemail: True
  • echo-subscriptions-push-system-noemail: True
  • echo-subscriptions-email-system-emailonly: False
  • echo-subscriptions-web-system-emailonly: True
  • echo-subscriptions-push-system-emailonly: True
  • echo-subscriptions-email-user-rights: True
  • echo-subscriptions-web-user-rights: True
  • echo-subscriptions-push-user-rights: True
  • echo-subscriptions-email-other: False
  • echo-subscriptions-web-other: True
  • echo-subscriptions-push-other: True
  • echo-subscriptions-email-edit-user-talk: 0
  • echo-subscriptions-web-edit-user-talk: True
  • echo-subscriptions-push-edit-user-talk: True
  • echo-subscriptions-email-reverted: False
  • echo-subscriptions-web-reverted: True
  • echo-subscriptions-push-reverted: True
  • echo-subscriptions-email-article-linked: False
  • echo-subscriptions-web-article-linked: False
  • echo-subscriptions-push-article-linked: False
  • echo-subscriptions-email-mention: False
  • echo-subscriptions-web-mention: True
  • echo-subscriptions-push-mention: True
  • echo-subscriptions-email-mention-failure: False
  • echo-subscriptions-web-mention-failure: False
  • echo-subscriptions-push-mention-failure: False
  • echo-subscriptions-email-mention-success: False
  • echo-subscriptions-web-mention-success: False
  • echo-subscriptions-push-mention-success: False
  • echo-subscriptions-email-emailuser: False
  • echo-subscriptions-web-emailuser: True
  • echo-subscriptions-push-emailuser: True
  • echo-subscriptions-email-thank-you-edit: False
  • echo-subscriptions-web-thank-you-edit: True
  • echo-subscriptions-push-thank-you-edit: True
  • echo-subscriptions-push-page-review: True
  • echo-subscriptions-push-login-fail: True
  • echo-subscriptions-push-login-success: True
  • echo-subscriptions-push-edit-thank: True
  • echo-subscriptions-email-dt-subscription: False
  • echo-subscriptions-web-dt-subscription: True
  • echo-subscriptions-push-dt-subscription: True
  • echo-subscriptions-email-dt-subscription-archiving: False
  • echo-subscriptions-web-dt-subscription-archiving: True
  • echo-subscriptions-push-dt-subscription-archiving: True
  • echo-subscriptions-email-cx: False
  • echo-subscriptions-push-cx: True
  • echo-subscriptions-email-ge-mentorship: False
  • echo-subscriptions-web-ge-mentorship: True
  • echo-subscriptions-push-ge-mentorship: True
  • echo-subscriptions-email-wikibase-action: False
  • echo-subscriptions-web-wikibase-action: True
  • echo-subscriptions-push-wikibase-action: True
  • growthexperiments-help-panel-tog-help-panel: False
  • homepage_mobile_discovery_notice_seen: True
  • growthexperiments-homepage-suggestededits-guidance-blue-dot: {"vector":{"link-recommendation":true,"image-recommendation":true},"minerva":{"link-recommendation":true,"image-recommendation":true}}
  • growthexperiments-homepage-se-topic-filters-mode: OR
  • growthexperiments-homepage-enable: False
  • growthexperiments-homepage-pt-link: False
  • growthexperiments-tour-help-panel: True
  • growthexperiments-tour-homepage-mentorship: True
  • growthexperiments-tour-homepage-welcome: True
  • growthexperiments-tour-homepage-discovery: True
  • growthexperiments-tour-newimpact-discovery: False
  • growthexperiments-starred-mentees:
  • growthexperiments-mentor-dashboard-seen: 0
  • growthexperiments-mentor-dashboard-last-update: None
  • growthexperiments-mentee-overview-presets: {"usersToShow":10,"filters":{"minedits":1,"maxedits":500}}
  • growthexperiments-homepage-mentorship-enabled: 1
  • growthexperiments-mentorship-weight: 2

Possible errors

In addition to {{ll|API:Errors and warnings#Standard error messages|the usual stuff}}:

Code Info
notloggedin Anonymous users cannot change preferences
nochangesNo changes were requested.

Parameter history

  • 1.21: Introduced resetkinds

Additional notes

  • This API is primarily intended for changing options which are registered by MediaWiki core or extensions and available on Special:Preferences.
  • You can also use the API to set arbitrary user options that can be used by user scripts or external editors. These options must begin with the prefix userjs-.
  • There is currently no limit on the number of user options you can set at once. You can store data within a user option by encoding it as a JSON string.
  • Providing only names of options without equal sign results in resetting them (e.g. hideminor|skin). In the case of an arbitrary userjs- key/value pair, the resetting results in its deletion.
  • The change parameter cannot be used to set a value which contains a pipe character |, as it is used by the API to separate options. If you need to set such a value (e.g., a user signature) use an optionname & optionvalue pair.
  • The following limits apply to all user options:
    • The byte length of the key must be <= 255.
    • The byte length of the value must be <= 65535.
    • The key must consist only of ASCII letters, numbers, hyphens and underscores (a-z, A-Z, 0-9, _, -).

See also

  • API:Userinfo - for reading existing options.
This article is issued from Mediawiki. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.