API:FAQ

This page is part of the MediaWiki API documentation.

Language:	English  • Deutsch

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
  • Send email
  • Patrol changes
  • Import pages
  • Change user group membership
  • Upload files
  • User options
• Watchlist feed
• Wikidata
• Extensions
• Using the API in MediaWiki and extensions
• Miscellaneous
• Implementation
• Client code

NOTE: This page is work in progress

Also read the quick start guide. It answers some questions not answered here and points to other useful pages.

How do I ...

get help?

1. Read this FAQ
2. Try to find the answer to your question in the API documentation here or on the self-documenting API home page
3. If you can't find the answer to your question on the web, you can ask your question on the mediawiki-api mailing list.

file a bug or a feature request?

If you have found a bug in the API or have a feature request, you can report it on Bugzilla. Be sure to search for existing bugs first (please don't file duplicate bugs) and choose "MediaWiki" for product and "API" for component when reporting a new bug against the API. If the functionality you're requesting or reporting a bug against is offered by an extension (e.g. AbuseFilter, FlaggedRevs), file it in that extension's component in the "MediaWiki extensions" product.

call the API?

The API is called by sending HTTP requests to api.php. For example, on the English Wikipedia, the URL is http://en.wikipedia.org/w/api.php ; other wikis have api.php with similar URLs: just use api.php where the usual URL has index.php. If you're trying to access the API on a third-party (non-Wikimedia-operated) wiki and can't figure out the URL of api.php, contact the wiki's owner.

From 1.17 onwards, MediaWiki supports RSD. An RSD marker is present on every page pointing to an RSD descriptor which indicates where to find the API.

control the output format?

Pass &format=someformat in the query string. See the list of output formats for more information.

detect errors?

An error response from the API will set the MediaWiki-API-Error HTTP header and return an <error>. For an example error response, see http://en.wikipedia.org/w/api.php?action=blah . See also the documentation about errors and warnings.

get the content of a page (wikitext)?

If you just want the raw wikitext without any other information whatsoever, it's best to use index.php's action=raw mode instead of the API: http://en.wikipedia.org/w/index.php?action=raw&title=Main_Page . Note that this'll just output plain wikitext without any formatting. See also the action=raw documentation

To get more information about the page and its latest version, use the API: http://en.wikipedia.org/w/api.php?action=query&prop=revisions&titles=Main_Page . See also the documentation for the prop=revisions module.

You can retrieve 50 pages per API request: http://en.wikipedia.org/w/api.php?action=query&prop=revisions&rvprop=content&titles=Main_Page%7CArticles This also works with generators.

get the content of a page (HTML)?

If you just want the HTML, it's best to use index.php's action=render mode instead of the API: http://en.wikipedia.org/w/index.php?action=render&title=Main_Page . See also the action=render documentation.

To get more information distilled from the wikitext at parse time (links, categories, sections, etc.), use the API parse module: http://en.wikipedia.org/w/api.php?action=parse&page=Main_Page . See also the documentation for the action=parse module.

Why ...

do I get HTTP 403 errors?

This could mean you're not passing a User-Agent HTTP header or that your User-Agent is empty or blacklisted m:User-Agent policy. See the quick start guide for more information. Also, it could mean that you're passing & in the query string of a GET request: Wikimedia blocks all such requests, use POST for them instead.

do I get the readapidenied error?

The wiki you're querying contains private content and requires users to log in in order to be able to read all pages. This means that a client needs to be logged in to query any information at all through the API. See the quick start guide for more information. It's not currently possible to query the contents of whitelisted pages without logging in, even though they're available in the regular user interface.

do I get badtoken errors?

This is usually because you're either not passing a token at all (read about tokens in the documentation of the module you're using) or because you're having trouble staying logged in. It's also possible you're reusing a type of token that can't be reused (see module documentation for details) or that you're using a token that's associated with an expired session. In general, when using cached tokens, refetch the token and try again before giving up.

do I get warnings instead of tokens (Action 'edit' is not allowed for the current user)?

You either don't have the right to execute the action you requested, or you're having trouble staying logged in.

is X not available through the API?

Not all features available in the user interface are available through the API. Such features weren't implemented either because no one has gotten around to it yet or because no one has requested them. For information about filing feature requests, see above.

does my API call on Wikimedia wikis just return an HTML error?

If you use API calls with POST requests make sure that these requests don't use Content-Type: multipart/form-data. This happens for instance if you use CURL to access the API and you pass your POST parameters as an array. The Squid proxy servers which are used at frontend servers at the Wikimedia wiki farm don't handle that correctly, thus an error is returned.

Instead, use the "value1=key1&value2=key2..." notation to pass the parameters as a string, similar to GET requests.

On other wikis which you access directly it doesn't make a difference.

Language:	English  • Deutsch