API:Upload

There are three methods of uploading files via the API:


 * 1) Uploading a local file directly
 * 2) Uploading a local file in chunks using Firefogg chunked upload protocol
 * 3) Uploading a copy of a file elsewhere on the Web given by a URL

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

Token
To upload files, a token is required. This token is identical to the edit token and is the same regardless of 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.

Uploading

 * Parameters


 * filename - Target filename
 * comment - Upload comment. Also used as the initial page text for new files
 * token - Edit token
 * watch - Watch the page
 * ignorewarnings - Ignore any warnings
 * file - File contents
 * enablechunks - Set to use chunk mode
 * chunksessionkey - Used to sync uploading of chunks
 * chunk</tt> - Chunk contents
 * done</tt> - Set when the last chunk is being uploaded
 * url</tt> - Url to fetch the file from
 * asyncdownload</tt> - Set in conjunction with url</tt> to download the file asynchronously. Requires $wgEnableAsyncDownload = true</tt> in the wiki's local settings
 * httpstatus</tt> - Set to return the status of an asynchronous upload (specify the key in sessionkey)
 * sessionkey</tt> - Session key returned by a previous upload that failed due to warnings, or (with httpstatus) The upload_session_key of an asynchronous upload

Uploading directly
When uploading files directly, the request must use the POST method in "multipart/form-data" form, "application/x-www-form-urlencoded" will not work. The below is only a guide.

Chunked upload
See http://firefogg.org/dev/chunk_post.html for the relevant protocol. Note that responses will be in JSON format, regardless of the format specified in the request. Chunks must be sent in "multipart/form-data" form, "application/x-www-form-urlencoded" will not work. The below is only a guide.

Uploading from URL
This requires $wgAllowCopyUploads = true</tt> in the wiki's local settings and an account with the upload_by_url</tt> 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</tt> in the wiki's local settings.

Retrieving upload status
For asynchronous uploads using upload-by-url the initial response will include a session key; pass this with httpstatus</tt> parameter to fetch upload status. This session key does not remain valid across login sessions.