{"id":13526029,"url":"https://github.com/neocotic/yourls-api","last_synced_at":"2025-08-10T03:32:36.452Z","repository":{"id":57404220,"uuid":"1926003","full_name":"neocotic/yourls-api","owner":"neocotic","description":"JavaScript bindings for the YOURLS API","archived":false,"fork":false,"pushed_at":"2017-03-24T17:00:18.000Z","size":97,"stargazers_count":26,"open_issues_count":9,"forks_count":8,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-03T19:51:31.493Z","etag":null,"topics":["yourls","yourls-api"],"latest_commit_sha":null,"homepage":"https://neocotic.com/yourls-api","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neocotic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-06-20T21:24:26.000Z","updated_at":"2025-02-25T03:52:37.000Z","dependencies_parsed_at":"2022-09-11T00:51:12.178Z","dependency_job_id":null,"html_url":"https://github.com/neocotic/yourls-api","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/neocotic/yourls-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neocotic%2Fyourls-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neocotic%2Fyourls-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neocotic%2Fyourls-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neocotic%2Fyourls-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neocotic","download_url":"https://codeload.github.com/neocotic/yourls-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neocotic%2Fyourls-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269672001,"owners_count":24457110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["yourls","yourls-api"],"created_at":"2024-08-01T06:01:24.492Z","updated_at":"2025-08-10T03:32:36.407Z","avatar_url":"https://github.com/neocotic.png","language":"JavaScript","readme":"    Y88b   d88P  .d88888b.  888     888 8888888b.  888      .d8888b.\n     Y88b d88P  d88P\" \"Y88b 888     888 888   Y88b 888     d88P  Y88b\n      Y88o88P   888     888 888     888 888    888 888     Y88b.\n       Y888P    888     888 888     888 888   d88P 888      \"Y888b.\n        888     888     888 888     888 8888888P\"  888         \"Y88b.\n        888     888     888 888     888 888 T88b   888           \"888\n        888     Y88b. .d88P Y88b. .d88P 888  T88b  888     Y88b  d88P\n        888      \"Y88888P\"   \"Y88888P\"  888   T88b 88888888 \"Y8888P\"\n                                              d8888 8888888b. 8888888\n                                             d88888 888   Y88b  888\n                                            d88P888 888    888  888\n                                           d88P 888 888   d88P  888\n                                          d88P  888 8888888P\"   888\n                                         d88P   888 888         888\n                                        d8888888888 888         888\n                                       d88P     888 888       8888888\n\n[![Build Status](https://img.shields.io/travis/neocotic/yourls-api/develop.svg?style=flat-square)](https://travis-ci.org/neocotic/yourls-api)\n[![Dev Dependency Status](https://img.shields.io/david/dev/neocotic/yourls-api.svg?style=flat-square)](https://david-dm.org/neocotic/yourls-api?type=dev)\n[![License](https://img.shields.io/npm/l/yourls-api.svg?style=flat-square)](https://github.com/neocotic/yourls-api/blob/master/LICENSE.md)\n[![Release](https://img.shields.io/npm/v/yourls-api.svg?style=flat-square)](https://www.npmjs.com/package/yourls-api)\n\n[YOURLS API](https://github.com/neocotic/yourls-api) is a JavaScript library that provides bindings for\n[YOURLS](https://yourls.org) URL shortener servers.\n\n* [Install](#install)\n* [API](#api)\n* [Migrating from v1](#migrating-from-v1)\n* [Bugs](#bugs)\n* [Contributors](#contributors)\n* [License](#license)\n\n## Install\n\nInstall using the package manager for your desired environment(s):\n\n``` bash\n$ npm install --save yourls-api\n# OR:\n$ bower install --save yourls-api\n```\n\nYou'll need to have at least [Node.js](https://nodejs.org) installed and you'll only need [Bower](https://bower.io) if\nyou want to install that way instead of using `npm`. And, although this library can be installed via `npm` it is only\nintended for use in the browser. `npm` installations are supported for the many web bundlers out there now.\n\nIf you want to simply download the file to be used in the browser you can find them below:\n\n* [Development Version](https://cdn.rawgit.com/neocotic/yourls-api/master/dist/yourls.js) (TODO - [Source Map](https://cdn.rawgit.com/neocotic/yourls-api/master/dist/yourls.js.map))\n* [Production Version](https://cdn.rawgit.com/neocotic/yourls-api/master/dist/yourls.min.js) (TODO - [Source Map](https://cdn.rawgit.com/neocotic/yourls-api/master/dist/yourls.min.js.map))\n\n## API\n\nThe API has been designed to be as simple and human-friendly as possible and attempts to hide the majority of work when\ndealing with the YOURLS API from you.\n\nAll methods of the API return a reference to the API itself to enable a clean chaining of method calls, if desired.\n\nAll requests that are sent to YOURLS servers are asynchronous and callback methods are used to track these. Callback\nmethods are passed the most is deemed (by this library) to be the most important information from the response as the\nfirst argument and the entire response as the second argument.\n\nThe following documentation contains some examples of the results that can be expected from YOURLS, however, it doesn't\ncover everything. It's recommended that you play around with making requests and inspecting/logging results and\nresponses to see all of the data that is available.\n\n### Connecting\n\n``` javascript\nyourls.connect(url[, credentials][, options])\n```\n\nThis is the first step and is where you'll provide the `url` of the YOURLS API that you wish to connect to. It **must**\npoint to the `yourls-api.php` file or its equivalent (e.g. if it's been renamed or using URL rewrites). You can only\nconnect to a single YOURLS server at a time.\n\n``` javascript\n// Simple connection to public server\nyourls.connect('https://example.com/yourls-api.php')\n```\n\nIf you're going to be connecting to a private YOURLS server, you'll also need to provide `credentials` that can be used\nto authenticate with it. The recommended method is to specify the `signature` token and use the\n[passwordless API requests](http://code.google.com/p/yourls/wiki/PasswordlessAPI) as the signature token can be reset\neasily.\n\n``` javascript\n// Passwordless connection to private server\nyourls.connect('https://example.com/yourls-api.php', {\n  signature: '3002a61584'\n})\n```\n\nHowever, it's even better if you use a time-limited signature token as it's somewhat more secure. That said; this\nlibrary leaves it up to you to provide the signature token as an md5 sum (which should be made from a concatenation of\nthe `timestamp` passed in and the signature token, and in that order). It's also worth noting that the timestamp should\nbe in seconds, not milliseconds, since Unix Epoch.\n\nAlthough it is possible to create md5 sums in the browser with the use of a third-party JavaScript library, at that\npoint you signature token has probably already been exposed. The best bet is for your server to calculate the md5 sum\nand then pass it and the timestamp on which it was based to your frontend to be consumed by this library.\n\n``` javascript\n// Time-limited passwordless connection to private server\nyourls.connect('https://example.com/yourls-api.php', {\n  signature: md5(1477947900 + '3002a61584'),\n  timestamp: 1477947900\n})\n```\n\nThis library does also support the more traditional `username`/`password` combination as well.\n\n``` javascript\n// Basic authentication connection to private server\nyourls.connect('https://example.com/yourls-api.php', {\n  username: 'admin',\n  password: 'qwerty'\n})\n```\n\n\u003e **IMPORTANT:** When sending `GET` requests, by design, all information will be included in the URL of the request\n\u003e This includes data as well as *any credentials* used to authenticate with the API. You have been warned.\n\u003e This is unavoidable when sending requests in the JSONP format but, when using the JSON format, you can send `POST`\n\u003e requests, which means that your data is sent inside the body of the request. Combine this with HTTPS and your data and\n\u003e credentials cannot be sniffed over the network.\n\nAs you may have noticed; this method also accepts the following entirely optional `options`:\n\nOption | Description                         | Default\n------ | ----------------------------------- | ---------\nformat | Format in which requests are sent   | `\"jsonp\"`\nmethod | HTTP method to be used for requests | `\"GET\"`\n\n``` javascript\n// Does the same as specifying no options (i.e. using defaults)\nyourls.connect('https://example.com/yourls-api.php', null, {\n  format: 'jsonp',\n  method: 'GET'\n})\n\n// Best practice if you want to secure the data you're transmitting and you've setup CORS, if needed\nyourls.connect('https://example.com/yourls-api.php', {\n  signature: '3002a61584'\n}, {\n  format: 'json',\n  method: 'POST'\n})\n```\n\nThe following formats are supported with the corresponding HTTP methods:\n\nFormat | HTTP Methods\n------ | ------------\njson   | GET, POST\njsonp  | GET\n\n\u003e **IMPORTANT:** The YOURLS server must be running version **1.5.1** or newer in order to send requests in the JSONP\n\u003e format.\n\nDespite the name of this method, no connection or authentication is carried out at this point and this initial method\nsimply stores these values to prevent you from having to specify them with every API call.\n\n### Disconnecting\n\n``` javascript\nyourls.disconnect()\n```\n\nCalling this method simply clears any previously stored connection information and, despite the name of this method, no\nlive connections are actually terminated.\n\n### Shortening\n\n``` javascript\nyourls.shorten(url[, descriptor], callback(result, response))\n```\n\nThis method shortens the `url` provided with a keyword/hash that is generated by the YOURLS server.\n\n``` javascript\n// Shorten a URL with a random keyword\nyourls.shorten('https://github.com/neocotic/yourls-api', function(result, response) {\n  console.log(result.shorturl)\n  //=\u003e \"https://example.com/abc123\"\n  console.log(result.title)\n  //=\u003e \"https://github.com/neocotic/yourls-api\"\n  console.log(result.url.keyword)\n  //=\u003e \"abc123\"\n})\n```\n\nOptionally, this method can take a `descriptor` containing additional information including the `keyword` to be used for\nthe short URL that is created and a `title` that is to be associated with it. As a shortcut, the keyword can be passed\nas the `descriptor` itself.\n\n``` javascript\n// Shorten a URL with a predefined keyword \nyourls.shorten('https://github.com/neocotic/yourls-api', 'yourls', function(result, response) {\n  console.log(result.shorturl)\n  //=\u003e \"https://example.com/yourls\"\n  console.log(result.title)\n  //=\u003e \"https://github.com/neocotic/yourls-api\"\n  console.log(result.url.keyword)\n  //=\u003e \"yourls\"\n})\n\n// Shorten a URL with a predefined keyword and title \nyourls.shorten('https://github.com/neocotic/yourls-api', { keyword: 'yourls', title: 'YOURLS API' }, function(result, response) {\n  console.log(result.shorturl)\n  //=\u003e \"https://example.com/yourls\"\n  console.log(result.title)\n  //=\u003e \"YOURLS API\"\n  console.log(result.url.keyword)\n  //=\u003e \"yourls\"\n})\n```\n\n### Statistics\n\n``` javascript\nyourls.stats([criteria, ]callback(result, response))\n```\n\nThis method fetches the statistics for all links.\n\n``` javascript\n// Get link statistics\nyourls.stats(function(result, response) {\n  console.log(result.stats.total_clicks)\n  //=\u003e \"98765\"\n  console.log(result.stats.total_links)\n  //=\u003e \"123\"\n})\n```\n\nOptionally, this method can take a `criteria` containing search criteria for a sub-set of links which can be included in\nthe result. This includes the `filter` (either `\"top\"`, `\"bottom\"`, `\"rand\"`, or `\"last\"`), which can be used to control\nsorting, as well as `limit` and `start`, which can be used for pagination lookups. As a shortcut, the limit can be\npassed as the `criteria` itself. The minimum required in order to do this is for a `limit` to be specified.\n\n``` javascript\n// Get top 10 links\nyourls.stats(10, function(result, response) {\n  console.log(result.links.length)\n  //=\u003e 10\n  console.log(result.links[0].shorturl)\n  //=\u003e \"https://example.com/yourls\"\n  console.log(result.stats.total_links)\n  //=\u003e \"123\"\n})\n\n// Get second page of 5 newest links\nyourls.stats({ filter: 'last', limit: 5, start: 5 }, function(result, response) {\n  console.log(result.links.length)\n  //=\u003e 5\n  console.log(result.links[0].shorturl)\n  //=\u003e \"https://example.com/abc123\"\n  console.log(result.stats.total_links)\n  //=\u003e \"123\"\n})\n```\n\n---\n\n``` javascript\nyourls.db.stats(callback(result, response))\n```\n\nThis method does exactly the same as `yourls.stats` except that it *only* returns the statistics for all links.\n\n``` javascript\n// Get link statistics\nyourls.db.stats(function(result, response) {\n  console.log(result.total_clicks)\n  //=\u003e \"98765\"\n  console.log(result.total_links)\n  //=\u003e \"123\"\n})\n```\n\n### URL Information\n\n``` javascript\nyourls.url(url)\n```\n\nUnlike other API calls, this method returns a wrapper for making API calls that specific to a given shortened `url`,\nwhich can be the keyword instead, if desired.\n\n``` javascript\n// Both do the same thing:\nvar yourls = yourls.url('https://example.com/yourls')\nvar yourls = yourls.url('yourls')\n```\n\nJust like the top-level API methods, all of the URL-specific methods return a reference to the URL wrapper to enable a\nclean chaining of method calls, if desired.\n\n#### Expanding\n\n``` javascript\nyourls.url(url).expand(callback(result, response))\n```\n\nThis method expands the shortened `url` into the original (long) URL.\n\n``` javascript\n// Get more details for link\nyourls.url('https://example.com/yourls').expand(function(result, response) {\n  console.log(result.keyword)\n  //=\u003e \"yourls\"\n  console.log(result.longurl)\n  //=\u003e \"https://github.com/neocotic/yourls-api\"\n  console.log(result.shorturl)\n  //=\u003e \"https://example.com/yourls\"\n})\n```\n\n#### Statistics\n\n``` javascript\nyourls.url(url).stats(callback(result, response))\n```\n\nThis method fetches the statistics for the shortened `url`.\n\n``` javascript\n// Get statistics only for this link\nyourls.url('https://example.com/yourls').stats(function(result, response) {\n  console.log(result.clicks)\n  //=\u003e \"123\"\n  console.log(result.title)\n  //=\u003e \"neocotic/yourls-api: JavaScript bindings for the YOURLS API\"\n  console.log(result.url)\n  //=\u003e \"https://github.com/neocotic/yourls-api\"\n})\n```\n\n### Versions\n\n``` javascript\nyourls.version([db, ]callback(result, response))\n```\n\nThis methods fetches the version of YOURLS running on the connected server.\n\n``` javascript\n// Get YOURLS version\nyourls.version(function(result, response) {\n  console.log(result.version)\n  //=\u003e \"1.7\"\n})\n```\n\nOptionally, a `db` flag can be enabled for the YOURLS database version to also be included in the result.\n\n``` javascript\n// Get YOURLS database version as well\nyourls.version(true, function(result, response) {\n  console.log(result.version)\n  //=\u003e \"1.7\"\n  console.log(result.db_version)\n  //=\u003e \"482\"\n})\n```\n\n---\n\n``` javascript\n// Get version of this library\nconsole.log(yourls.VERSION)\n//=\u003e \"2.1.0\"\n```\n\nThe current version of this library.\n\n## Migrating from v1\n\nIf you've been using v1 then you can find details about what's changed and a guide on how to migrate to v2 below:\n\nhttps://github.com/neocotic/yourls-api/wiki/Migrating-from-v1\n\nYou can also find the code and documentation for the v1 below:\n\nhttps://github.com/neocotic/yourls-api/tree/1.0.0\n\n## Bugs\n\nIf you have any problems with this library or would like to see changes currently in development you can do so\n[here](https://github.com/neocotic/yourls-api/issues).\n\nHowever, if you believe that your issue is with YOURLS itself, please take a look a\n[their issues](https://github.com/YOURLS/YOURLS/issues) instead.\n\n## Contributors\n\nIf you want to contribute, you're a legend! Information on how you can do so can be found in\n[CONTRIBUTING.md](https://github.com/neocotic/yourls-api/blob/master/CONTRIBUTING.md). We want your suggestions and pull\nrequests!\n\nA list of YOURLS API contributors can be found in\n[AUTHORS.md](https://github.com/neocotic/yourls-api/blob/master/AUTHORS.md).\n\n## License\n\nCopyright © 2017 Alasdair Mercer\n\nSee [LICENSE.md](https://github.com/neocotic/yourls-api/blob/master/LICENSE.md) for more information on our MIT license.\n","funding_links":[],"categories":["Integrations"],"sub_categories":["3rd party Integrations and Frameworks"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneocotic%2Fyourls-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneocotic%2Fyourls-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneocotic%2Fyourls-api/lists"}