API talk:Upload

Flag: Don't overwrite existing file
It would be nice if there was a flag that said: Don't overwrite any already existing file. This could help in preventing errors in bots, especially as Special:Upload mangles the filename a bit, so it's not entirely trivial to make sure a file of a given name does not already exist. --Tbleher 20:20, 14 February 2008 (UTC)
 * Good one. I'll keep this in mind. --Catrope 21:32, 17 February 2008 (UTC)

File Contents?
Could you be more specific on the file contents? Is it just a bunch of bytes, UUEncoded, HEX, or what?


 * Assuming you mean direct upload, the file content should be sent as part of the request in multipart/form-data format, so essentially yes, just a bunch of bytes. Gurch 05:03, 30 October 2009 (UTC)

I'm trying to do this with curl, but am having no luck with any kind of file content inclusion. Can you give an example? Here are some things I'm trying: curl -b cookies.txt -d "action=upload&filename=exported.xml&file=$(cat exported.xml)&format=xml&token=$UPLOADTOKEN" http://lookipedia.net/w/api.php

curl -b cookies.txt -d "action=upload&filename=exported.xml&file= text &format=xml&token=$UPLOADTOKEN" http://lookipedia.net/w/api.php

curl -b cookies.txt -d "action=upload&filename=exported.xml&file=TEST&format=xml&token=$UPLOADTOKEN" http://lookipedia.net/w/api.php

curl -b cookies.txt -d "action=upload&filename=exported.xml&file=@exported.xml&format=xml&token=$UPLOADTOKEN" http://lookipedia.net/w/api.php In all cases I get this error:  Pjrich 17:48, 10 October 2011 (UTC)

Upload by URL
I'm not having much more luck than you with uploading by URL. I did try retrieving httpstatus using the session key, and got the following result:

{u'upload': {u'content_length': u'5706', u'loaded': 5706, u'upload_session_key': u'12345'}}

But the file wasn't actually uploaded, and I don't see any way of determining what went wrong. --R&#39;n&#39;B 18:45, 29 October 2009 (UTC)


 * It was broken before, was fixed in r58337 -- Gurch 05:11, 30 October 2009 (UTC)

badtoken
my script for accessing my mediawiki works with edits, moves and deletes. upload does not work - i get a badtoken response: /api/error/@code=badtoken /api/error/@info=Invalid token The doc says the token should be requested with prop=info, while regular edit tokens that i use have prop=info|revisions. The titles param given in the api doc is Foo which is not helpful - what is the title to be used? It would be great to have a full working example. -- Seppl2013 (talk) 08:52, 28 August 2013 (UTC)

Unrecognized value for parameter action: upload
I'm trying to upload a file via wget. Login and fetching token is OK, but on upload...

wget --load-cookies cookies.txt -O upload.xml \ --post-data "action=upload&filename=atlasmw-export.xml&file=[content goes here]&token=$EDITTOKEN" \ $API

I get this:

&lt;error code=&quot;unknown_action&quot; info=&quot;Unrecognized value for parameter &amp;#039;action&amp;#039;: upload&quot; xml:space=&quot;preserve&quot;&gt;

Documentation says:

api.php ? action=upload & filename=Test.txt & file=file_contents_here & token=+\

What's wrong? Using MediaWiki 1.15.1. Jpatokal 03:32, 20 November 2009 (UTC)
 * It's a 1.16 feature. Max Semenik 05:45, 20 November 2009 (UTC)

overwrite: text parameter ignored
is there a good reason the text parameter is ignored when overwriting an existing file? imho it would make sense to overwrite the description, too. -- ∂ 23:55, 23 April 2010 (UTC)

Mediawiki Push Extension
Is anyone here familiar with the MW Push extension?

Trying to get it to work and not having much success.

The extension author has been less than helpful:

"In any case, I don't know what your issue is, so can't really help you any further."

I keep getting the same error:

Could not obtain an edit token on the target wiki

After reading and reading I suspect it might have something to do with the API Upload.

Any thoughts?

I had the same problem, it was something to do with my target media wiki installation, I re-installed a clean version (version 1.19.2) and it worked for me. This is a little vague sorry but perhaps that might help you if it isn't too much to do that, certainly something to try if you don't have any better options.

--Cgeroux (talk) 16:54, 15 October 2012 (UTC)

I'm not sure if this is the place to ask but I can only find one mention of the where the WikiMedia API can do a push. I'd like to know if you can get wikipedia to push a API request to a client to trigger an action? If so can you direct me to the API document(s) that discusses this?

--lukejmorrison (talk) 13:34, 2 June 2014 (EST New York)

Reverting to an earlier revision?
I'm not sure if this is the right place, but: Does anyone know if it's possible to revert to an earlier revision? A workaround using archived image URLs comes to mind, but the particular wiki has URL uploads disabled. --84.186.216.128 00:07, 24 February 2012 (UTC)

Async uploads
After digging through the code to find that  is was the correct parameter to allow an async upload, I now get the following error back:

Is there any plan to re-introduce this option? --Brian McNeil (talk) 12:13, 18 September 2012 (UTC)

Real World Examples
Although not an API example, the Html2Wiki extension invokes the internal methods for uploading a file in it's saveImage method. from https://git.wikimedia.org/blob/mediawiki%2Fextensions%2FHtml2Wiki/HEAD/specials%2FSpecialHtml2Wiki.php

Is there any real world example out there (as for the login API) how to use the upload API correctly? This could help many peoples. --Steviex2 (talk) 22:08, 7 February 2013 (UTC)


 * Real-world examples include:
 * Extension:UploadWizard (JavaScript using XHR)
 * Apps/Commons (Java and Objective-C implementations)
 * Wiki Loves Monuments app from last year (JavaScript using PhoneGap FileTransfer API)
 * --brion (talk) 01:02, 8 February 2013 (UTC)

...And Mobile Frontend. They are all big projects which I checked. What I really mean is a simple, basic code snipped like for the Login-API. The extensions are way too big to simply adapt it for own projects. Uploading into MediaWiki is a core feature which should be documented as well as the Login-API for developers. Since more and more people are coding in PHP and JQuery, I would be happy to see simple examples to use the Upload-API with this languages.

This should be a small step for a professional MW-dev but a big step for the community :-). PS: I can't understand why the internet is full of misunderstandings and time consuming trial and errors about this topic, while the original developers should know this few lines of code in every provided language very well. I also would appreciate informations wether we are talking about a file stream or a representation on disk. For example could we use  and or  . What would be a complete CURL-Realisation? Is the same possible with JQuery? What about the "same origin policy" in this context? --Steviex2 (talk) 01:44, 8 February 2013 (UTC)


 * I'll see about whipping up some PHP and JS examples... In the meantime, the thing to know about cross-origin policy is that you probably won't be able to make a successful authenticated POST request to the API from JavaScript on another domain unless it's on the short whitelist of Wikimedia sites. That is, you could upload a file to Commons from a gadget on Wikipedia, but not from an arbitrary web site. but if you route through your server, your PHP code can certainly do it. -- brion (talk) 16:30, 8 February 2013 (UTC)

Aha this is a very important point for people having more then one Wiki-installs and want to exchange files accross different domains. To choose the wrong tech here, could easily result in hours- may be days of useless efforts :-).


 * Note that for your own wiki installs, you can customize $wgCrossSiteAJAXdomains to whitelist more sites. --brion (talk) 21:08, 8 February 2013 (UTC)

Okay this makes sense now. Yesterday I was wondering when I made a little external login page for my Wikis- thank you. For the Upload-API I would prefer the CURL-way like many others too. By the way in general what about this XML-chunks in the API-Documentation? How would they be used? Is it only an abstraction to reflect the different programming languages, or can we use them in PHP too?

...after many many hours of trial and errors...still can't get it working with PHP-CURL while successfully login, getting the right edit token etc..
 * Example results we can get with good PHP-knowledge but less propper documentation level :-)
 * One of the parameters filekey, file, url, statuskey is required
 * post request failed The requested URL returned error: 41422
 * request failed: URI too long (longer than 8190)
 * The parameters url, filekey, statuskey can not be used together
 * Invalid Content-Length
 * No upload module set

PS: Some remarkable behaviors:  Update: After two days of trial and error, investigations, code reviewing etc. I got it working. I will need another day to clean up and fine tune...I guess this could be mutch easier with a better documentation level. 
 * The error "One of the parameters filekey, file, url, statuskey is required" is fired even we specify a file-parameter in the url may be because "file" is double checked against class WebRequestUpload which implies uploads can not simulated with CURL, the api needs server var "$_FILES['filename']" and therefor a real form upload which could lead to some serious confusions without mentioning it. ;-)
 * If we put file contents into the url this mostly exceeds the allowed length of an url. I can't believe that this is meant to be the standard way. I think in "PHP-CURL" param file in the url-notation is more a string then real "File contents".

PS: Anyway...I would like to see the promised code samples (for example JQuery) and will happily assist- If someone has the same problems.

--Steviex2 (talk) 22:37, 8 February 2013 (UTC)


 * I am having similar problems with PHP implementations, is it possible for you to share the code for this?

--Nischayn22 (talk) 08:11, 4 May 2013 (UTC) What about an example for calling the api internally(like edit) $api = new ApiMain(               new DerivativeRequest( $wgRequest, array(                       'action'     => 'upload',                        'file'       => 'blub',                        'filename'   => 'bla',                        'url'        => '',                        'token'      => $_POST["token"]                    ), false // was posted? ),               true // enable write?            ); $api->execute;


 * Does this work? I did not get internal API to work for uploads. --Osnard (talk) 07:47, 19 December 2014 (UTC)

Seems like the url-parameter is needed otherwise i get "One of the parameters filekey, file, url, statuskey is required" message. What is needed for the url-parameter?

--Michael MPI (talk) 08:08, 13 March 2013 (UTC)

Javascript/jQuery
Working, rather minimal example using HTML5 APIs and jQuery my thanks to the api mailinglist and Steviex2 --Simulo (talk) 15:03, 2 June 2013 (UTC)

Python with requests
The following should work with Python's  module: Hopefully it can save others time and headaches. Storkk (talk) 13:58, 8 December 2016 (UTC)

Filetype mime mismatch
Hi, I'm trying to upload an image with a multipart/form-data request, however I keep getting told that the file type isn't the same, whereas I am sure that it is. This is what I am sending to api.php:

-8d02f9ba3ddf82b Content-Disposition: form-data; name="action"

upload -8d02f9ba3ddf82b Content-Disposition: form-data; name="filename"

150px-6025526.png -8d02f9ba3ddf82b Content-Disposition: form-data; name="token"

XXXXXXXXXXXXXXXXXXXXXXXX+\ -8d02f9ba3ddf82b Content-Disposition: form-data; name="format"

json -8d02f9ba3ddf82b Content-Disposition: form-data; name="file"; filename="150px-6025526.png" Content-Type: image/png

 -8d02f9ba3ddf82b--

I cannot find the reason why I am being told the file type doesn't match. Any help would be greatly appreciated. CASIO F-91W (talk) 22:50, 4 June 2013 (UTC)

Real world example with PHP
As It took some time for me to figure out how to upload file with API, and I'm not alone, I'm providing my example.

This is just example for one to get a clue, it does work, but is far from being tidy, secure, universal, best possible method, able to process warnings, etc..

You'll need to get edit token, and also provide cookies. Hope it will save an hour or two for some people. --Xelgen (talk) 02:33, 6 March 2014 (UTC)

Real world wiki functions in VBscript/Windows Shell
After many hours of working my way through this I thought it might be helpful to provide the functions I've created that allow uploading a file. Yes it's long and not pretty, but is functional and should help provide pointers in the right direction.
 * Variable types are commented out as this was developed in MsAccess and then ported to Windows shell script (I was apparently bad in a past life).
 * Code written to upload images but should work for anything - the file to be uploaded is usually referred to as strImageFileName
 * File paths assumed to have a trailing slash (eg "C:\data\upload\")
 * Functions wikiLogin and getEditToken included for completeness

Hope it helps -- Qwaddles (talk) 23 April 2014

mw.Api
Is it at all possible to use mw.Api with this part of the API? It seems to only accepts an object, whereas this needs a FormData object. I'd rather not loose the benefits of mw.Api and use bare $.ajax. 124.180.3.50 07:51, 24 August 2014 (UTC)

Uploading Local Files with non-English characters in name
Uploading Local Files with non-English characters in name, with python 3.4.3 + requests 2.7 plugin.

MW version 1.23.1.

I get this error:

{'error': {'code': 'badupload_file', 'info': 'File upload param file is not a file upload; be sure to use multipart/form-data for your POST and include a filename in the Content-Disposition header.'}}


 * We are now on MediaWiki version 1.35.0-wmf1 but here's the answer for python3: the requests module relies on urllib3 in order to handle the filename, and things go awry there. You can work around the issue by rfc2047-encoding the title and using that converted title as the value of the title (first field) in the tuple set as the value of 'file'. That is, you would do . See the requests bug on github for more info and for sample code. -- ArielGlenn (talk) 19:48, 16 October 2019 (UTC)

Verify SSL
Is there a possibility to disable checking ssl certificates?

Mostly  would solve this problem.

$user = $this->getUser; doesn't get a user
Here's the first bit of my apiupload script. The only changed bit is the wfdebug line.

It returns:

Any idea why it seems like there should be a use stuck in that object, because it's whats causing my image uploads to fail, but I don't know why there isn't one. BTW, yes, I'm logged in.

Minimal working JavaScript
Here is a really simple no-frills working example in JavaScript, without event handling etc. It assumes the following:

1) an HTML input element that is of type "file" and has ID = "localfile", name = "localfile" 2) a valid csrf token in variable "yourCsrfToken" (this is not something specific to file upload. Look elsewhere if you don't know about csrf tokens in Mediawiki) 3) the URL of your wiki's API in variable "yourMediaWikiApiUrl" 4) a file named "somefile.jpg" has not already been uploaded to the wiki.

var yourCsrfToken = ; var yourMediaWikiApiUrl = ; var localfile = document.getElementById("localfile"); var file = localfile.files[0]; var fileName = "blueflower.jpg"; var comment = `

` var request = new XMLHttpRequest; request.open('POST', yourMediaWikiApiUrl, false); var formData = new FormData; formData.append("action", "upload"); formData.append("filename", fileName); formData.append("comment", comment); formData.append("token", yourCsrfToken); formData.append("file", file); request.setRequestHeader("Content-Disposition", "form-data"); request.send(formData); console.log(request.response);

Assuming the user has selected a file through the input element named "localfile", this will upload that file to the wiki, giving it the name "somefile.jpg". You can check the response in your console. --Henryfunk (talk) 21:06, 13 May 2018 (UTC)
 * Thanks Henryfunk. I encourage you to also add the page desciption.
 * : Upload comment. Also used as the initial page text for new files if text is not specified.
 * Yug (talk) 17:06, 21 September 2020 (UTC)
 * I added it. Yug (talk) 17:16, 21 September 2020 (UTC)

uploading images stored as base64 data
I am trying to use the api to upload an image that has been extracted from an html document which is in base64 data format.

Could you tell me:


 * is api upload able to upload images in this format?
 * what parameters do I need to give the api call (preferably in javascript using ajax to make the api call)

Many thanks DuncanCrane (talk) 14:49, 12 June 2020 (UTC)

Structured data?
What should be the way to add structured data (eg when uploading images to Wikimedia Commons)? I'm not very familiar with it but it seems Wikimedia is moving that way and some of the data that's uploaded in the image page description (eg geocoordinates) could also be added as structured data at upload time given a field in this API call.

Structured data is not part of the page description nor the documented API call so I guess it can't currently be added as part of the upload call.

Usually a bot will pick it up but that doesn't seem to be the right way, nor is making a separate API call.

--Trougnouf (talk) 14:05, 18 March 2021 (UTC)

Is a BOT really necessary?
Hello to all. I am building a tool on Toolforge where users are supposed to be allowed to send their images of objects of a Museum collection. I was trying to implement this functionallity and wasn't successful. Reading the examples, it seems that I have to request a Bot? Until today, I only created tools using OAuth consumers; The users logged in, allowed the tool, and then every contribution used the API on Wikidata. Below is what I tried to implement. I'm using Python and Flask. Ederporto (talk) 00:21, 23 May 2021 (UTC)


 * This page is not really watched (I followed this from phabricator). If you ask at Project:Support_desk, there's a better chance of you getting a response. Ammarpad (talk) 20:56, 25 May 2021 (UTC)


 * I made a post there, as you suggested. Thank you! Good contributions, Ederporto (talk) 21:51, 25 May 2021 (UTC)

Doc: Upload warnings - duplicate
At "Upload warnings" it says:

"duplicate: The uploaded file exists under a different (or the same) name. ..."

The "(or the same)" part seems potentially incorrect. (depending on the used mw-verion I guess)

As:

While test uploading a duplicate file to its current location/img-page-name.

I did get the "exists"(+name) & "nochange"(+timestamp) warnings. (Doc say "no-change" btw)

But there was no "duplicate" warning. (which seems a bit overkill away considering exists+nochange comes down to the same thing.)

(MediaWiki: 1.36.1)

... Hmm: (message editing) Switching from Visual to Source like to eats  statements.

... Erm: And then suddenly I lost all linebreaks in my message. ??? ... Ok!. Only double hard-line breaks it is.

MvGulik (talk) 16:03, 8 October 2022 (UTC)