yourls-api is a JavaScript library that provides bindings for the YOURLS API using JSONP.

This library is only compatible with YOURLS version 1.5.1 or newer as it requires JSONP support.


yourls.connect(url[, credentials])

This is the first step and where you'll provide the URL of the YOURLS API you wish to connect to, baring in mind that the URL should point to the yourls-api.php file and not just its directory. If you're going to be connecting to a private YOURLS installation you'll also need to provide either the username/password or the signature token if you're wanting to use passwordless API requests (the signature token takes precedence here).

var exampl = yourls.connect('', {
//username: 'admin',
//password: 'qwerty',
  signature: '3002a61584'

Despite the name no connection or authentication is carried out at this point and this initial method simply stores these values to prevent you from specifying them with every API call.


yourls.shorten(url[, keyword], callback(data)[, context])

This method shortens the URL provided optionally using a custom keyword/hash.

exampl.shorten('', 'yourls', function(data) {
  console.log(data.shorturl); //


yourls.stats([filter, ][limit, ]callback(data)[, context])

This method fetches the statistics on all your links but also allows you to filter and limit what is returned.

exampl.stats('last', 1, function(data) {
  var myLink = data.links.link_1;
  console.log(myLink.shorturl);         //
  console.log(myLink.url);              //
  console.log(myLink.title);            // yourls-api · neocotic
  console.log(myLink.clicks);           // 1987
  // Overall statistics
  console.log(data.stats.total_links);  // 12
  console.log(data.stats.total_clicks); // 2012

URL Information


Unlike the other API calls this constructs an instance of a yourls.url for the URL provided (which should be a shortened URL).

var myUrl = exampl.url('');

Once you have this instance more operations become available that are applicable only to the URL provided here.


yourls.url.expand(callback(data)[, context])

This method fetches the original long URL for your link.

myUrl.expand(function(data) {
    console.log(data.keyword);  // yourls
    console.log(data.shorturl); //
    console.log(data.longurl);  //


yourls.url.stats(callback(data)[, context])

This method fetches the statistics for your link.

myUrl.stats(function (data) {
    console.log(; //
    console.log(;      //
    console.log(;    // yourls-api · neocotic
    console.log(;   // 1987


The API exposes some properties and methods which may only be useful to users in special cases.


Relinquish yourls-api's control of the yourls global variable. If another library uses this variable calling this method will reassign it back to that library.


The current version of yourls-api.


If you have any problems with this library or would like to see the changes currently in development browse our issues.


Take a look at the documentation to get a better understanding of what the code is doing.

If that doesn't help, feel free to follow me on Twitter, @neocotic.