The Docs

YOURLS version 1.7.1 is available. Please update!



No, anyone can shorten URLs anonymously. However, to see the access statistics of your short URLs, an account is required. You can sign up for free here.


If you register, you will have access to a convenient user interface. It allows to shorten URLs, of course, and also to list the short URLs for all URLs you ever shortened. You can share short URLs on here.


Yes, this is possible: simply stay logged in while using the bookmarklets. You can close the browser's tab after logging in. The state of being logged in is stored in a cookie. Only when you log out again, this cookie is removed immediately.

  • Maximum length of custom keyword is 200 characters
  • That makes about 8 sexdecillions of centillions of available URLs (seriously. That's a 355 digits number).
The shortener uses Base 36 encoding for the the short URLs. For short URLs, Base 36 encoding uses

Indeed. It's intented since Base 36 is used (see above). Letters that don't belong to the character set, eg @#! or ABC, are removed.


The shortener comes with handy bookmarklets for easier link shortening and sharing. You will find them on the start page (just click the 'Bookmarklets' button).

  • The Shorten and the Custom Bookmarklet will take you to a new page where you can easily share your brand new short URL.
  • The Popup and the Custom Popup Bookmarklet will pop the short URL without leaving the page you are viewing. Please do not use these two bookmarklets for URLs starting with https://, as this does not work.
  • The bookmarklets without "Custom" in their name will generate a short URL with a random keyword, whereas the bookmarklets with "Custom" in their name will prompt you for a custom keyword first.

If you select text on the page you're viewing before clicking on the bookmarklet link of the

  • Shorten and the Custom Bookmarklet, and the
  • Twitter and the Tumblr Bookmarklet,

you can share the marked text as a description along with the link you're shortening.



  • Generate or get existing short URLs, with sequential or custom keyword.
  • Anyone can create short URLs, even without an account (an account however is needed if you also want to see the short URLs access statistics later on).
  • Created short URLs can be attached to your account by authenticating yourself for it.
  • Get click statistics about your links (requires an account, you can sign up for free here).
  • Output format: JSON, XML, or simple raw text.
  • Authenticate yourself either with login/password or using your token as a secure passwordless mechanism.


You need to send parameters to /yourls-api.php either via GET or POST (remember to URL encode parameters if via GET). These parameters are:

  • A valid username / password pair, or your token.
  • The requested action: "shorturl" (get short URL for a link), "expand" (get long URL of a shorturl), "url-stats" (get stats about one short URL).
  • With action = "shorturl" :
    • the url to shorten
    • optional keyword and title for custom short URLs
    • output format: either "jsonp", "json", "xml" or "simple"
  • With action = "expand" :
    • the shorturl to expand (can be either abc or
    • output format: either "jsonp", "json", "xml" or "simple"
  • With action = "url-stats" :
    • the shorturl for which to get stats (can be either abc or
    • output format: either "jsonp", "json", or "xml"
  • It is possible to use the shorturl action without giving a username / password combination, or yourtoken. In this case, the generated short URL will not get attached to any account.
  • No authentication parameters are required for "expand" actions.
  • You must be authenticated as the owner of a short URL to see its stats. If the short URL is not in the account corresponding to the given username / password combination, or to yourtoken, an error code will be returned.

Sample return

	<?xml version="1.0" encoding="iso-8859-1"?>
	<title>The Page Title</title>
	<date>2009-06-23 18:08:07</date>
	(ID: shorter) 
	added to
	<title>The Page Title</title>