From MediaWiki.org
Jump to navigation Jump to search

Other languages:
English • ‎español • ‎русский • ‎日本語
MediaWiki version: 1.16

POST request to upload a file.

There are three methods of uploading files via the API:

  1. Uploading a local file directly
  2. Uploading a copy of a file from a URL
  3. Uploading a local file in chunks (originally based on the Firefogg chunked upload protocol)

All of these methods require an account with the upload right.

API documentation[edit]


(main | upload)
  • This module requires read rights.
  • This module requires write rights.
  • This module only accepts POST requests.
  • Source: MediaWiki
  • License: GPL-2.0-or-later

Upload a file, or get the status of pending uploads.

Several methods are available:

  • Upload file contents directly, using the file parameter.
  • Upload the file in pieces, using the filesize, chunk, and offset parameters.
  • Have the MediaWiki server fetch a file from a URL, using the url parameter.
  • Complete an earlier upload that failed due to warnings, using the filekey parameter.

Note that the HTTP POST must be done as a file upload (i.e. using multipart/form-data) when sending the file.


Target filename.


Upload comment. Also used as the initial page text for new files if text is not specified.

Default: (empty)

Change tags to apply to the upload log entry and file page revision.

Values (separate with | or alternative):

Initial page text for new files.


Watch the page.

Type: boolean (details)

Unconditionally add or remove the page from the current user's watchlist, use preferences or do not change watch.

One of the following values: watch, preferences, nochange
Default: preferences

Ignore any warnings.

Type: boolean (details)

File contents.

Must be posted as a file upload using multipart/form-data.

URL to fetch the file from.


Key that identifies a previous upload that was stashed temporarily.


Same as filekey, maintained for backward compatibility.


If set, the server will stash the file temporarily instead of adding it to the repository.

Type: boolean (details)

Filesize of entire upload.

The value must be between 0 and 4,294,967,296.
Type: integer

Offset of chunk in bytes.

The value must be no less than 0.
Type: integer

Chunk contents.

Must be posted as a file upload using multipart/form-data.

Make potentially large file operations asynchronous when possible.

Type: boolean (details)

Only fetch the upload status for the given file key.

Type: boolean (details)

A "csrf" token retrieved from action=query&meta=tokens

This parameter is required.


Making any POST request is a multi-step process:

  1. Log in, via one of the methods described in API:Login .
  2. GET a CSRF token :
  3. Send a POST request, with the CSRF token to upload a file.

Example 1: Upload a local file directly[edit]

When uploading files directly, the request must use multipart/form-data as Content-Type or enctype, application/x-www-form-urlencoded will not work.

POST request[edit]


  "upload": {
    "filename": "File_1.jpg",
    "result": "Success",
    "imageinfo": {
      "url": "https://upload.wikimedia.org/wikipedia/test/3/39/File_1.jpg",
      "html": "<p>A file with this name exists already, please check <strong><a class=\"mw-selflink selflink\">File:File 1.jpg</a></strong> if you are not sure if you want to change it.\n</p>\n<div class=\"thumb tright\"><div class=\"thumbinner\" style=\"width:182px;\"><a           href=\"/w/index.php?title=Special:Upload&amp;wpDestFile=File_1.jpg\" class=\"new\" title=\"File:File 1.jpg\">File:File 1.jpg</a>  <div class=\"thumbcaption\"></div></div></div>\n",
      "width": 474,
      "size": 26703,
      "bitdepth": 8,
      "mime": "image/jpeg",
      "userid": 42588,
      "mediatype": "BITMAP",
      "descriptionurl": "https://test.wikipedia.org/wiki/File:File_1.jpg",
      "extmetadata": {
        "ObjectName": {
          "value": "File 1",
          "hidden": "",
          "source": "mediawiki-metadata"
        "DateTime": {
          "value": "2019-03-06 08:43:37",
          "hidden": "",
          "source": "mediawiki-metadata"
      "comment": "",
      "commonmetadata": [],
      "descriptionshorturl": "https://test.wikipedia.org/w/index.php?curid=0",
      "sha1": "2ffadd0da73fab31a50407671622fd6e5282d0cf",
      "parsedcomment": "",
      "metadata": [
          "name": "MEDIAWIKI_EXIF_VERSION",
          "value": 2
      "canonicaltitle": "File:File 1.jpg",
      "user": "Mansi29ag",
      "timestamp": "2019-03-06T08:43:37Z",
      "height": 296

Sample code[edit]



    MediaWiki Action API Code Samples
    Demo of `Upload` module: Sending POST request to upload a file directly

    MIT license

import requests

S = requests.Session()
URL = "https://test.wikipedia.org/w/api.php"
FILE_PATH = 'f.jpg'

# Step 1: Retrieve a login token
PARAMS_1 = {
    "action": "query",
    "meta": "tokens",
    "type": "login",
    "format": "json"

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

LOGIN_TOKEN = DATA["query"]["tokens"]["logintoken"]

# Step 2: Send a POST request to login. 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_2 = {
    "action": "login",
    "lgname": "bot_username",
    "lgpassword": "bot_password",
    "format": "json",
    "lgtoken": LOGIN_TOKEN

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

# Step 3: Obtain a CSRF token
PARAMS_3 = {
    "action": "query",

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

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

# Step 4: POST request to upload a file directly
PARAMS_4 = {
    "action": "upload",
    "filename": "file_1.jpg",
    "format": "json",
    "token": CSRF_TOKEN,
    "ignorewarnings": 1

FILE = {'file':('file_1.jpg', open(FILE_PATH, 'rb'), 'multipart/form-data')}

R = S.post(URL, files=FILE, data=PARAMS_4)
DATA = R.json()

Example 2: Upload file from URL[edit]

This requires $wgAllowCopyUploads = true in the wiki's local settings and an account with the upload_by_url user right.

POST request[edit]


Sample code[edit]

Example 3: Upload file in chunks[edit]

Since uploading a huge file in a single HTTP POST can be unreliable, the API also supports a chunked upload mode, where you make multiple requests with portions of the file. This is available in MediaWiki version 1.20 and above, although prior to version 1.25, SVGs could not be uploaded via chunked uploading. This is used by Extension:UploadWizard in browsers supporting FileAPI, uploading files in chunks of 1 megabyte, but you may choose your own size. This works in conjunction with the stash mode, to build a file up in pieces and then commit it at the end.

Step 1: Pass content for the first chunk[edit]

For all the chunks except the last chunk you will receive this:

Step 2: Pass filekey parameter for second and further chunks[edit]

You will obtain the filekey parameter from the previous continue result as well:

For the last chunk, you will receive this:

Step 3: Final upload using the filekey to commit the upload out of the stash area[edit]

The result from the final upload will include the complete, accurate imageinfo object, comparable to what you would get from a non-chunked upload.

Sample code[edit]

Possible errors[edit]

Code Info
mustbeloggedin You must be logged in to upload this file.
permissiondenied The action you have requested is limited to users in one of the groups: Administrators, Uploaders.
fileexists-shared-forbidden A file with this name exists already in the shared file repository.

If you still want to upload your file, please go back and use a new name.

chunk-too-small Minimum chunk size is n bytes for non-final chunks.
stashfailed This file did not pass file verification.

Parameter history[edit]

  • v1.21: Introduced async checkstatus
  • v1.19: Introduced offset filesize chunk
  • v1.18: Introduced stash filekey
  • v1.17: Introduced stash, statuskey, leavemessage, asyncdownload
  • v1.18: Deprecated sessionkey
  • v1.17: Deprecated watch

Additional notes[edit]

  • To check the status of an in-progress upload to the stash or the progress of a file being published from the stash, send a POST request:
  • Below is an example of a multipart POST to /api.php?action=upload, representing a single chunk. Note that you must unstash the file for it to appear in the Wiki once you have successfully uploaded all your chunks.

See also[edit]