Nanoseconds Produce Minutes


    0.18.0 • Public • Published


    Node.js CI

    MediaWiki API client written in node.js

    Download stats


    • Node.js 14+


    Using npm

    npm install nodemw

    Or Download the latest stable version via GitHub.

    Development version

    git clone


    • HTTP requests are stored in the queue and performed in parallel with limited number of "threads" (i.e. there's no risk of flooding the server)
    • articles creation / edit / move / delete
    • file uploads (using given content or via provided URL)
    • Special:Log processing
    • listing articles in categories
    • and much more

    Where it's used

    First script

    An example script can be found in /examples directory.

    cd examples
    node pagesInCategory.js

    You can enter debug mode by setting DEBUG enviromental variable:

    DEBUG=1 node examples/pagesInCategory.js

    You can enter dry-run mode (all "write" operations like edits and uploads will be disabled) by setting DRY_RUN environmental variable (or dryRun entry in the config):

    DRY_RUN=1 node examples/pagesInCategory.js

    Running unit tests

    npm test

    How to use it?

    Creating a bot instance

      var bot = require('nodemw');
      // pass configuration object
      var client = new bot({
        protocol: 'https',           // Wikipedia now enforces HTTPS
        server: '',  // host name of MediaWiki-powered site
        path: '/w',                  // path to api.php script
        debug: false                 // is more verbose when set to true
      client.getArticle('foo', function(err, data) {
        // error handling
        if (err) {
        // ...

    Config file

    nodemw can use config files as well as objects directly provided to bot object constructor.

     // read config from external file
     var client = new bot('config.js');

    Config file is a JSON-encoded object with the following fields (see /examples/config-DIST.js file):

          "protocol": "https",  // default to 'http'
          "server": "",  // host name of MediaWiki-powered site
          "path": "/w",                  // path to api.php script
          "debug": false,                // is more verbose when set to true
          "username": "foo",             // account to be used when logIn is called (optional)
          "password": "bar",             // password to be used when logIn is called (optional)
          "domain" : "",     // domain to be used when logIn is called (optional)
          "userAgent": "Custom UA",      // define custom bot's user agent
          "concurrency": 5               // how many API requests can be run in parallel (defaults to 3)

    Making direct API calls

    nodemw allows you make direct calls to MediaWiki API (example querying Semantic MediaWiki API):

    var bot = require('nodemw'),
      client = new bot({
    		server: '',
    		path: '/w'
    	params = {
    		action: 'ask',
    		query: '[[Modification date::+]]|?Modification date|sort=Modification date|order=desc'
    	}; /* api.php parameters */, function(err /* Error instance or null */, info /* processed query result */, next /* more results? */, data /* raw data */) {
    	console.log(data && data.query && data.query.results);

    Bot methods

    The last parameter of each function in nodemw API is a callback which will be fired when the requested action is done.

    Callbacks use node.js style - err is always passed as the first argument.

    bot.logIn(username, password, callback)

    Log-in using given credentials - read more

    bot.getCategories(prefix, callback)

    Gets the list of all categories on a wiki


    Gets the list of all pages from the main namespace (excludes redirects) - read more

    bot.getPagesInCategory(category, callback)

    Gets the list of pages in a given category - read more

    bot.getPagesInNamespace(namespace, callback)

    Gets the list of pages in a given namespace - read more

    bot.getPagesByPrefix(prefix, callback)

    Gets the list of pages by a given prefix - read more

    bot.getPagesTranscluding(page, callback)

    Gets the list of pages that transclude the given pages - read more

    bot.getArticle(title, [redirect,] callback)

    Gets article content and redirect info - read more

    bot.getArticleRevisions(title, callback)

    Gets all revisions of a given article - read more

    bot.getArticleCategories(title, callback)

    Gets all categories a given article is in - read more

    bot.getArticleInfo(title, callback)

    Gets all info of a given article - read more

    bot.edit(title, content, summary, minor, callback)

    Creates / edits an article (and mark the edit as minor if minor is set to true) - read more

    bot.append(title, content, summary, callback)

    Adds given content to the end of the page - read more

    bot.prepend(title, content, summary, callback)

    Adds given content to the beginning of the page - read more

    bot.addFlowTopic(title, topic, content, callback)

    Add a Flow topic - read more

    bot.delete(title, reason, callback)

    Deletes an article - read more

    bot.purge(titles, callback)

    Purge a given list of articles (titles or page IDs can be provided) - read more

    By providing Category:Foo as titles argument you can purge all pages in a given category (available since MW 1.21)

    bot.protect(title, protections, options, callback)

    Protect a page (A title or page ID can be provided) - read more

    The protections value is an Array of protection information in the format:

        action: string,
        level?: string = 'all',
        expiry?: string | number = 'never'

    Calls to the Protect endpoint are not additive. Each call must include a list of all intended protections, including any already in place. Each call will replace all existing protections.

    bot.sendEmail(username, subject, text, callback)

    Send an email to an user - read more

    bot.getToken(title, action, callback)

    Returns token required for a number of MediaWiki API operations - read more / for MW 1.24+


    Gets information about current bot's user (including rights and rate limits) - read more

    bot.whois(username, callback)

    Gets information about a specific user (including rights, current block, groups) - read more

    bot.whoare(usernames, callback)

    Gets information about specific users (including rights, current block, groups) - read more

    bot.createAccount(username, password, callback)

    Create account using given credentials - read more

    bot.move(from, to, summary, callback)

    Moves (aka renames) given article - read more


    Gets list of all images on a wiki

    bot.getImageUsage(filename, callback)

    Gets list of all articles using given image

    bot.getImagesFromArticle(title, callback)

    Get list of all images that are used on a given page - read more

    bot.getImageInfo(filename, callback)

    Gets metadata (including uploader, size, dimensions and EXIF data) of given image

    bot.getLog(type, start, callback)

    Get entries form Special:Log - read more

    bot.expandTemplates(content, title, callback)

    Returns XML with preprocessed wikitext - read more

    bot.parse(content, title, callback)

    Returns parsed wikitext - read more

    bot.fetchUrl(url, callback)

    Makes a GET request to provided resource and returns its content.

    bot.getRecentChanges(start, callback)

    Returns entries from recent changes (starting from a given point)

    bot.getSiteInfo(props, callback)

    Returns site information entries - read more

    bot.getSiteStats(props, callback)

    Returns site statistics (number of articles, edits etc) - read more


    Returns the version of MediaWiki given site uses - read more

    client.getQueryPage(queryPage, callback)

    Returns entries from QueryPage-based special pages

    bot.upload(filename, content, summary /* or extraParams */, callback)

    Uploads a given raw content as a File:[filename] - read more

    bot.uploadByUrl(filename, url, summary /* or extraParams */, callback)

    Uploads a given external resource as a File:[filename]

    bot.uploadVideo(fileName, url, callback)

    Uploads a given video as a File:[filename] (Wikia-specific API)

    bot.getTemplateParamFromXml(tmplXml, paramName)

    Gets a value of a given template parameter from article's preparsed content (see expandTemplates)

    bot.getExternalLinks(title, callback)

    Gets all external links used in article

    bot.getBacklinks(title, callback)

    Gets all articles that links to given article, callback)

    Performs a search


    bot.getConfig(key, def)

    Gets config entry value (returns def value if not found)

    bot.setConfig(key, val)

    Sets config entry value

    bot.diff(old, current)

    Returns a diff colored using ANSI colors (powered by diff)

    Wikia-specific bot methods

    They're grouped in bot.wikia "namespace".


    Get wiki-specific settings (like ThemeDesigner colors and hubs).

    bot.wikia.getUser(userId, callback)

    Get information (avatar, number of edits) about a given user

    bot.wikia.getUsers(userIds, callback)

    Get information (avatar, number of edits) about a given set of users (by their IDs)


    npm i nodemw

    DownloadsWeekly Downloads






    Unpacked Size

    55.1 kB

    Total Files


    Last publish


    • macbre