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
• Authentication
  • Login
  • Logout
• Queries
  • Meta information
  • Properties
  • Lists
• Search suggestions
• Expanding templates and rendering
• 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
  • Send e-mail
  • Patrol changes
  • Import pages
  • Change user group membership
  • Upload files
  • User options
• Watchlist feed
• Extensions
• Using the API in MediaWiki and extensions
• Miscellaneous
• Implementation
• Client code

MediaWiki version:

1.20

Token

To change options, an options token is required. It can be obtained as follows:

Obtaining an options token

api.php ? action=tokens & type=options

<?xml version="1.0" encoding="utf-8"?>
<api>
  <tokens optionstoken="58b54e0bab4a1d3fd3f7653af38e75cb+\" />
</api>

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 change I5f9ba5b0 you can also use it to set semi-arbitrary preferences that can be used for example by user-script or external editors.

These semi-arbitrary options have three limits imposed on them:

• the key must start with userjs- prefix
• 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 nor contents of the value, as well as on the number of additional preferences.

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. Providing only names of options without equal sign (e.g. hideminor|skin) results in resetting them.
• 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.

A parameter change cannot be used to set a value which contains pipe character "|", as it is used by the API to separate options. If you need to set such value (for example user signature) use optionname & optionvalue pair.

Example

Note: In this example, all parameters are passed in a GET request just 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

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

Resetting all options and changing a single option

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

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

Changing three options

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

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

Possible errors

In addition to the usual stuff:

• code: notloggedin
  • info: Anonymous users cannot change preferences
• code: nochanges
  • info: No changes were requested