Main module

Status: The MediaWiki API is a mature and stable interface that is actively supported and improved. While we try to avoid it, we may occasionally need to make breaking changes; subscribe to the mediawiki-api-announce mailing list for notice of updates.

Erroneous requests: When erroneous requests are sent to the API, an HTTP header will be sent with the key "MediaWiki-API-Error" and then both the value of the header and the error code sent back will be set to the same value. For more information see API: Errors and warnings.

Maximum lag can be used when MediaWiki is installed on a database replicated cluster. To save actions causing any more site replication lag, this parameter can make the client wait until the replication lag is less than the specified value. In case of excessive lag, error code maxlag is returned with a message like Waiting for $host: $lag seconds lagged.See Manual: Maxlag parameter for more information.

Type: integer

smaxage

Set the s-maxage HTTP cache control header to this many seconds. Errors are never cached.

Type: integer

Default: 0

maxage

Set the max-age HTTP cache control header to this many seconds. Errors are never cached.

Type: integer

Default: 0

assert

Verify the user is logged in if set to user, or has the bot user right if bot.

One of the following values: user, bot

assertuser

Verify the current user is the named user.

Type: user name

requestid

Any value given here will be included in the response. May be used to distinguish requests.

When accessing the API using a cross-domain AJAX request (CORS), set this to the originating domain. This must be included in any pre-flight request, and therefore must be part of the request URI (not the POST body).

For authenticated requests, this must match one of the origins in the Origin header exactly, so it has to be set to something like https://en.wikipedia.org or https://meta.wikimedia.org. If this parameter does not match the Origin header, a 403 response will be returned. If this parameter matches the Origin header and the origin is whitelisted, the Access-Control-Allow-Origin and Access-Control-Allow-Credentials headers will be set.

For non-authenticated requests, specify the value *. This will cause the Access-Control-Allow-Origin header to be set, but Access-Control-Allow-Credentials will be false and all user-specific data will be restricted.

uselang

Language to use for message translations. action=query&meta=siteinfo with siprop=languages returns a list of language codes, or specify user to use the current user's language preference, or specify content to use this wiki's content language.

Default: user

errorformat

Format to use for warning and error text output.

plaintext

Wikitext with HTML tags removed and entities replaced.

wikitext

Unparsed wikitext.

html

HTML.

raw

Message key and parameters.

none

No text output, only the error codes.

bc

Format used prior to MediaWiki 1.29. errorlang and errorsuselocal are ignored.

One of the following values: plaintext, wikitext, html, raw, none, bc

Default: bc

errorlang

Language to use for warnings and errors. action=query&meta=siteinfo with siprop=languages returns a list of language codes, or specify content to use this wiki's content language, or specify uselang to use the same value as the uselang parameter.

Default: uselang

errorsuselocal

If given, error texts will use locally-customized messages from the MediaWiki namespace.

This module accepts additional parameters depending on the available authentication requests. Use action=query&meta=authmanagerinfo with amirequestsfor=change (or a previous response from this module, if applicable) to determine the requests available and the fields that they use.

Post to this module, supplying loginreturnurl and any relevant fields.

Check the status in the response.

If you received PASS or FAIL, you're done. The operation either succeeded or it didn't.

If you received UI, present the new fields to the user and obtain their submission. Then post to this module with logincontinue and the relevant fields set, and repeat step 4.

If you received REDIRECT, direct the user to the redirecttarget and wait for the return to loginreturnurl. Then post to this module with logincontinue and any fields passed to the return URL, and repeat step 4.

If you received RESTART, that means the authentication worked but we don't have a linked user account. You might treat this as UI or as FAIL.

Return URL for third-party authentication flows, must be absolute. Either this or logincontinue is required.

Upon receiving a REDIRECT response, you will typically open a browser or web view to the specified redirecttarget URL for a third-party authentication flow. When that completes, the third party will send the browser or web view to this URL. You should extract any query or POST parameters from the URL and pass them as a logincontinue request to this API module.

logincontinue

This request is a continuation after an earlier UI or REDIRECT response. Either this or loginreturnurl is required.

This module accepts additional parameters depending on the available authentication requests. Use action=query&meta=authmanagerinfo with amirequestsfor=login (or a previous response from this module, if applicable) to determine the requests available and the fields that they use.

Examples:

Start the process of logging in to the wiki as user Example with password ExamplePassword.

Post to this module, supplying createreturnurl and any relevant fields.

Check the status in the response.

If you received PASS or FAIL, you're done. The operation either succeeded or it didn't.

If you received UI, present the new fields to the user and obtain their submission. Then post to this module with createcontinue and the relevant fields set, and repeat step 4.

If you received REDIRECT, direct the user to the redirecttarget and wait for the return to createreturnurl. Then post to this module with createcontinue and any fields passed to the return URL, and repeat step 4.

If you received RESTART, that means the authentication worked but we don't have a linked user account. You might treat this as UI or as FAIL.

If action=query&meta=authmanagerinfo returned true for hasprimarypreservedstate, requests marked as primary-required should be omitted. If it returned a non-empty value for preservedusername, that username must be used for the username parameter.

Return URL for third-party authentication flows, must be absolute. Either this or createcontinue is required.

Upon receiving a REDIRECT response, you will typically open a browser or web view to the specified redirecttarget URL for a third-party authentication flow. When that completes, the third party will send the browser or web view to this URL. You should extract any query or POST parameters from the URL and pass them as a createcontinue request to this API module.

createcontinue

This request is a continuation after an earlier UI or REDIRECT response. Either this or createreturnurl is required.

This module accepts additional parameters depending on the available authentication requests. Use action=query&meta=authmanagerinfo with amirequestsfor=create (or a previous response from this module, if applicable) to determine the requests available and the fields that they use.

Example:

Start the process of creating user Example with password ExamplePassword.

Timestamp when the editing process began, used to detect edit conflicts. An appropriate value may be obtained using curtimestamp when beginning the edit process (e.g. when loading the page content to edit).

If you received PASS or FAIL, you're done. The operation either succeeded or it didn't.

If you received UI, present the new fields to the user and obtain their submission. Then post to this module with linkcontinue and the relevant fields set, and repeat step 4.

If you received REDIRECT, direct the user to the redirecttarget and wait for the return to linkreturnurl. Then post to this module with linkcontinue and any fields passed to the return URL, and repeat step 4.

If you received RESTART, that means the authentication worked but we don't have a linked user account. You might treat this as UI or as FAIL.

Return URL for third-party authentication flows, must be absolute. Either this or linkcontinue is required.

Upon receiving a REDIRECT response, you will typically open a browser or web view to the specified redirecttarget URL for a third-party authentication flow. When that completes, the third party will send the browser or web view to this URL. You should extract any query or POST parameters from the URL and pass them as a linkcontinue request to this API module.

linkcontinue

This request is a continuation after an earlier UI or REDIRECT response. Either this or linkreturnurl is required.

This module accepts additional parameters depending on the available authentication requests. Use action=query&meta=authmanagerinfo with amirequestsfor=link (or a previous response from this module, if applicable) to determine the requests available and the fields that they use.

action=login (lg)

This action should only be used in combination with Special:BotPasswords; use for main-account login is deprecated and may fail without warning. To safely log in to the main account, use action=clientlogin.

Remove a change tag from the database, including removing the tag from all revisions, recent change entries and log entries on which it is used.

activate

Activate a change tag, allowing users to apply it manually.

deactivate

Deactivate a change tag, preventing users from applying it manually.

This parameter is required.

One of the following values: create, delete, activate, deactivate

tag

Tag to create, delete, activate or deactivate. For tag creation, the tag must not exist. For tag deletion, the tag must exist. For tag activation, the tag must exist and not be in use by an extension. For tag deactivation, the tag must be currently active and manually defined.

This parameter is required.

reason

An optional reason for creating, deleting, activating or deactivating the tag.

Title of the page from which history will be merged. Cannot be used together with fromid.

fromid

Page ID of the page from which history will be merged. Cannot be used together with from.

Type: integer

to

Title of the page to which history will be merged. Cannot be used together with toid.

toid

Page ID of the page to which history will be merged. Cannot be used together with to.

Type: integer

timestamp

Timestamp up to which revisions will be moved from the source page's history to the destination page's history. If omitted, the entire page history of the source page will be merged into the destination page.

List of changes, formatted name=value (e.g. skin=vector). If no value is given (not even an equals sign), e.g., optionname|otheroption|..., the option will be reset to its default value. If any value passed contains the pipe character (|), use the alternative multiple-value separator for correct operation.

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

optionname

The name of the option that should be set to the value given by optionvalue.

list=prefixsearch (ps)

Despite the similarity in names, this module is not intended to be equivalent to Special:PrefixIndex; for that, see action=query&list=allpages with the apprefix parameter. The purpose of this module is similar to action=opensearch: to take user input and provide the best-matching titles. Depending on the search engine backend, this might include typo correction, redirect avoidance, or other heuristics.

list=random (rn)

Pages are listed in a fixed sequence, only the starting point is random. This means that if, for example, Main Page is the first random page in the list, List of fictional monkeys will always be second, List of people on stamps of Vanuatu third, etc.

Also include local messages, i.e. messages that don't exist in the software but do exist as in the MediaWiki namespace.
This lists all MediaWiki-namespace pages, so it will also list those that aren't really messages such as Common.js.

Expiry timestamps. May be relative (e.g. 5 months or 2 weeks) or absolute (e.g. 2014-09-18T12:34:56Z). If only one timestamp is set, it will be used for all groups passed to the add parameter. Use infinite, indefinite, infinity, or never for a never-expiring user group.

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

Seconds since 1970-01-01T00:00:00Z as a 1 to 13 digit integer (excluding 0)

The string now

alternative multiple-value separator

Parameters that take multiple values are normally submitted with the values separated using the pipe character, e.g. param=value1|value2 or param=value1%7Cvalue2. If a value must contain the pipe character, use U+001F (Unit Separator) as the separator and prefix the value with U+001F, e.g. param=%1Fvalue1%1Fvalue2.

Templated parameters

Templated parameters support cases where an API module needs a value for each value of some other parameter. For example, if there were an API module to request fruit, it might have a parameter fruits to specify which fruits are being requested and a templated parameter {fruit}-quantity to specify how many of each fruit to request. An API client that wants 1 apple, 5 bananas, and 20 strawberries could then make a request like fruits=apples|bananas|strawberries&apples-quantity=1&bananas-quantity=5&strawberries-quantity=20.