API:Upload

Please expand this page. The reason given is: needs more examples, more explanation of parameters, more detail of API responses including the possible warnings. More information might be found in a section of the talk page.

Contents

To upload files, an edit token is required and is the same regardless of the target filename, but changes at every login. Unlike other tokens, it cannot be obtained directly, so one must obtain and use an edit token instead. Edit tokens can be obtained via action=tokens (MW 1.20+), or by using the following method:

ignorewarnings: Ignore any warnings. This must be set to upload a new version of an existing image.

file: File contents

url: Url to fetch the file from

filekey: Key returned by a previous upload that failed due to warnings, or (with httpstatus) The upload_session_key of an asynchronous upload. Key that identifies a previous upload that was stashed temporarily. Formerly named sessionkey. 1.18+

sessionkey: Same as filekey, maintained for backward compatibility (deprecated in 1.18)

stash: If set, the server will not add the file to the repository and stash it temporarily 1.17+

chunk: Chunk contents 1.19+

offset: Offset of chunk in bytes 1.19+

filesize: Filesize of entire upload 1.19+

async: Make potentially large file operations asynchronous when possible 1.21+

asyncdownload: Make fetching a URL asynchronous 1.17+

leavemessage: If asyncdownload is used, leave a message on the user talk page if finished 1.17+

statuskey: Fetch the upload status for this file key (upload by URL) 1.17+

checkstatus: Only fetch the upload status for the given file key 1.21+

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 1.20 and above, but does not work correctly for SVGs (phab:T67724).

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.

This requires $wgAllowCopyUploads = true in the wiki's local settings and an account with the upload_by_url user right. By default this is done synchronously, so downloading large files may exceed PHP's max_execution_time and fail. Asynchronous mode will return a session key that can then be used to query the upload status (see below). Asynchronous mode requires $wgEnableAsyncDownload = true ($wgAllowAsyncCopyUploads = true in later versions) in the wiki's local settings.

Parts of this api (those related to section) are outdated. It was written for an older version of MediaWiki and may not apply to the most recent version. See the talk page for a possible discussion on this.

For checking the status of an in-progress upload to the stash, or checking the progress of a file being published from the stash: