API:Upload

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  right.

Example
Making any POST request is a multi-step process:


 * 1. Log in, via one of the methods described in.


 * 2. GET a :


 * 3. Send a POST request, with the CSRF token to upload a file.

Example 1: Upload a local file directly
When uploading files directly, the request must use  as Content-Type or enctype,   will not work.

Sample code
upload_file_directly.py

Example 2: Upload file from URL
This requires  in the wiki's local settings and an account with the   user right.

Example 3: Upload file in chunks
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 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


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

Step 2: Pass filekey parameter for second and further chunks
You will obtain the  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


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

Parameter history

 * v1.21: Introduced
 * v1.19: Introduced
 * v1.18: Introduced
 * v1.17: Introduced,  ,  ,
 * v1.18: Deprecated
 * v1.17: Deprecated

Additional notes

 * 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, 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.

User-Agent:  Content-Type: multipart/form-data; boundary=--24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Host: commons.wikimedia.org Cookie: Connection: Keep-Alive

--24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="filename" Content-Length: 20

UploadTest356456.png --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="offset" Content-Length: 1

0 --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="format" Content-Length: 4

json --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="ignorewarnings" Content-Length: 1

1 --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="filesize" Content-Length: 3

971 --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="token" Content-Length: 42

 --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="stash" Content-Length: 1

1 --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="chunk"; filename="1.png" Content-Type: application/octet-stream Content-Length: 971

 --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b--

Example
Making any POST request is a multi-step process:


 * 1. Log in, via one of the methods described in.


 * 2. GET a :


 * 3. Send a POST request, with the CSRF token to upload a file.

Example 1: Upload a local file directly
When uploading files directly, the request must use  as Content-Type or enctype,   will not work.

Sample code
upload_file_directly.py

Example 2: Upload file from URL
This requires  in the wiki's local settings and an account with the   user right.

Example 3: Upload file in chunks
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 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


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

Step 2: Pass filekey parameter for second and further chunks
You will obtain the  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


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

Parameter history

 * v1.21: Introduced
 * v1.19: Introduced
 * v1.18: Introduced
 * v1.17: Introduced,  ,  ,
 * v1.18: Deprecated
 * v1.17: Deprecated

Additional notes

 * 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, 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.

User-Agent:  Content-Type: multipart/form-data; boundary=--24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Host: commons.wikimedia.org Cookie: Connection: Keep-Alive

--24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="filename" Content-Length: 20

UploadTest356456.png --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="offset" Content-Length: 1

0 --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="format" Content-Length: 4

json --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="ignorewarnings" Content-Length: 1

1 --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="filesize" Content-Length: 3

971 --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="token" Content-Length: 42

 --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="stash" Content-Length: 1

1 --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b Content-Disposition: form-data; name="chunk"; filename="1.png" Content-Type: application/octet-stream Content-Length: 971

 --24b7c3bb-fb4d-45c3-937c-11c2e0c2525b--