API:Options

This page is part of the MediaWiki API documentation.

Language:	English  • 日本語

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

MediaWiki version:

1.20

Token

To change options, an options token is required. Options tokens can be obtained via action=tokens with type=options (MW 1.20+), or by using the following method:

Obtaining an options token

api.php?action=tokens&type=options

Changing options

Options can be changed using action=options.

While this API is primarily intended for changing options which are registered by MediaWiki core or extensions and available on Special:Preferences, since Gerrit #I5f9ba5 you can also use it to set arbitrary user options that can be used by user-scripts or external editors.

These arbitrary options have three limits imposed on them:

• the key must start with the prefix userjs-
• the length of the key must not be more than 255 bytes
• the key must consist only of ASCII letters, numbers, hyphens and underscores (a-z, A-Z, 0-9, _, -)

There are currently no hard limits on the length or contents of the value, nor is there a limit on the number of user options you can set at once. You can even store a complex tree of data within a user option by encoding it as a JSON string.

Parameters

• token: The token obtained in the previous request. Take care to urlencode the trailing +\ as %2B%5C.
• reset: Resets all preferences to the site defaults.
• change: Pipe-separated list of changes, formatted name=value (e.g. skin=vector), value cannot contain pipe characters.

Note: Providing only names of options without equal sign (e.g. hideminor|skin) results in resetting them. In the case of an arbitrary userjs- name/value pair, the resetting results in the removal of the name/value pair; in other words - deletion.

• optionname: A name of a option which should have an optionvalue set.
• optionvalue: A value of the option specified by the optionname, can contain pipe characters.

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 (for example, a user signature) use an optionname & optionvalue pair.

Available Options

The following is an example list obtained with /w/api.php?action=query&format=json&meta=userinfo&uiprop=options for a Wikipedia (MW 1.24) account.

Note that most of the options listed here and defined by various MediaWiki extensions, like Echo, VisualEditor, WikiLove, Gadgets or EducationProgram, among others.

• ccmeonemails: 0
• cols: 80
• date: "mdy"
• diffonly: 0
• disablemail: 0
• editfont: "default"
• editondblclick: 0
• editsectiononrightclick: 0
• enotifminoredits: 0
• enotifrevealaddr: 0
• enotifusertalkpages: 1
• enotifwatchlistpages: 0
• extendwatchlist: "1"
• fancysig: "1"
• forceeditsummary: "1"
• gender: "male"
• hideminor: 0
• hidepatrolled: 0
• imagesize: 2
• math: 0
• minordefault: 0
• newpageshidepatrolled: 0
• nickname: user signature
• norollbackdiff: 0
• numberheadings: 0
• previewonfirst: 0
• previewontop: 1
• rcdays: "14"
• rclimit: "100"
• rows: 25
• showhiddencats: false
• shownumberswatching: 1
• showtoolbar: 1
• skin: "vector"
• stubthreshold: 0
• thumbsize: "3"
• underline: 2
• uselivepreview: 0
• usenewrc: 0
• watchcreations: 1
• watchdefault: "1"
• watchdeletion: 0
• watchlistdays: "2"
• watchlisthideanons: 0
• watchlisthidebots: 0
• watchlisthideliu: 0
• watchlisthideminor: 0
• watchlisthideown: 0
• watchlisthidepatrolled: 0
• watchmoves: "1"
• wllimit: "300"
• useeditwarning: 1
• prefershttps: 1
• flaggedrevssimpleui: 1
• flaggedrevsstable: 0
• flaggedrevseditdiffs: true
• flaggedrevsviewdiffs: false
• usebetatoolbar: 1
• usebetatoolbar-cgd: 1
• multimediaviewer-enable: true
• visualeditor-enable: 0
• visualeditor-betatempdisable: 0
• visualeditor-enable-experimental: 0
• visualeditor-enable-language: 0
• visualeditor-hidebetawelcome: 0
• wikilove-enabled: 1
• mathJax: false
• echo-subscriptions-web-page-review: true
• echo-subscriptions-email-page-review: false
• ep_showtoplink: false
• ep_bulkdelorgs: false
• ep_bulkdelcourses: true
• ep_showdyk: true
• echo-subscriptions-web-education-program: true
• echo-subscriptions-email-education-program: false
• echo-notify-show-link: true
• echo-show-alert: true
• echo-email-frequency: 0
• echo-email-format: "html"
• echo-subscriptions-email-system: true
• echo-subscriptions-web-system: true
• echo-subscriptions-email-user-rights: true
• echo-subscriptions-web-user-rights: true
• echo-subscriptions-email-other: false
• echo-subscriptions-web-other: true
• echo-subscriptions-email-edit-user-talk: 1
• echo-subscriptions-web-edit-user-talk: true
• echo-subscriptions-email-reverted: false
• echo-subscriptions-web-reverted: true
• echo-subscriptions-email-article-linked: false
• echo-subscriptions-web-article-linked: false
• echo-subscriptions-email-mention: false
• echo-subscriptions-web-mention: true
• echo-subscriptions-web-edit-thank: true
• echo-subscriptions-email-edit-thank: false
• echo-subscriptions-web-flow-discussion: true
• echo-subscriptions-email-flow-discussion: false
• gettingstarted-task-toolbar-show-intro: true
• uls-preferences: ""
• language: "en"
• variant-gan: "gan"
• variant-iu: "iu"
• variant-kk: "kk"
• variant-ku: "ku"
• variant-shi: "shi"
• variant-sr: "sr"
• variant-tg: "tg"
• variant-uz: "uz"
• variant-zh: "zh"
• searchNs0: true
• searchNs1: false
• searchNs2: "1"
• searchNs3: false
• searchNs4: "1"
• searchNs5: false
• searchNs6: "1"
• searchNs7: false
• searchNs8: "1"
• searchNs9: false
• searchNs10: "1"
• searchNs11: false
• searchNs12: "1"
• searchNs13: false
• searchNs14: "1"
• searchNs15: false
• searchNs100: false
• searchNs101: false
• searchNs108: false
• searchNs109: false
• searchNs118: false
• searchNs119: false
• searchNs446: false
• searchNs447: false
• searchNs710: false
• searchNs711: false
• searchNs828: false
• searchNs829: false
• gadget-teahouse: ""
• gadget-ReferenceTooltips: 1
• gadget-DRN-wizard: 1
• gadget-charinsert: 1
• gadget-refToolbar: 1
• gadget-mySandbox: 1
• betafeatures-vector-compact-personal-bar: "0"
• cirrussearch-default: "0"
• pagetriage-lastuse: timestamp
• popups: "0"
• timecorrection: "ZoneInfo|60|Europe/London"
• uls-compact-links: "0"
• usecodeeditor: "1"
• userjs-arbitraryKeyName: arbitrary value
• watchlisttoken: token

Example

Note: 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 a single option

api.php?action=options&token=58b54e0bab4a1d3fd3f7653af38e75cb%2B\&change=hideminor=1

Resetting all options and changing a single option

api.php?action=options&token=58b54e0bab4a1d3fd3f7653af38e75cb%2B\&reset&change=hideminor=1

Changing three options

api.php?action=options&token=58b54e0bab4a1d3fd3f7653af38e75cb%2B\&change=hideminor=1|skin=vector&optionname=nickname&optionvalue=custom-signa|ture

Possible errors

In addition to the usual stuff:

Code	Info
notloggedin	Anonymous users cannot change preferences
nochanges	No changes were requested

See also

• API:Meta#userinfo / ui for reading existing options.