Make small

Public API

In order to allow easy integration of this service with other websites, and to allow other developers to make great use of this service in their scripts and applications, offers a public API that doesn't need any authentication to work.


  • Generate or get existing short URLs, with sequential or custom keyword
  • Get some statistics about existing shorten links.
  • Output format: JSON, XML, or simple raw text
  • No credentials needed; the API is public. Headers allowing cross-domain XMLHttpRequest are sent so you can do JavaScript requests from your pages.
  • Mostly compatible with YOURLS API, except that authentication is not needed, some methods are not supported for security reasons, and others return and can take extra parameters (such as hit limit, passcode, etc.)


You need to send parameters to either via GET or POST. These parameters are:

  • The requested action: "shorturl" (get short URL for a link), "expand" (get long URL of a shorturl) or "url-stats" (get stats about one short URL).
  • With action = "shorturl" :
    • the url to shorten
    • optional keyword for custom short URLs
    • optional title for custom title
    • optional hitlimit for when an short link shouldn't redirect more than a certain amount of hits. Don't specify or set to 0 (zero) for unlimited hits.
    • optional timelimit to set the longevity of the link in seconds. Don't specify or set to 0 (zero) to disable the time limit.
    • output format: either "json", "xml" or "simple"
  • With action = "expand" :
    • the shorturl to expand (can be either 'abc' or 'http://site/abc')
    • output format: either "json", "xml" or "simple"
    • note one thing: the API doesn't expand links that have reached their hit limit, or that have the discontinued Internet Toll feature enabled; it will return an error instead
  • With action = "url-stats" :
    • the shorturl for which to get stats (can be either 'abc' or 'http://site/abc')
    • output format: either "json" or "xml"
  • With action = "version" :
    • takes no parameters
    • outputs YOURLS backend version, API version and some other version information.
    • output format: either "json" or "xml"
  • Unlike with the default YOURLS API, action = "stats" is not supported for security and speed reasons.

Sample return

<?xml version="1.0" encoding="iso-8859-1"?>
  <title>A page with a very long URL</title>
  <date>2013-07-30 07:11:49</date>
  <ip> does not make public the IP address of the creator of a short url</ip>
<message>[...] added to database</message>
<title>A page with a very long URL</title>

The price and payoutaddr fields are part of the output for discontinued features and should be ignored.

Sample file

To see a PHP script that works with the YOURLS API (and thus, the API), click here.