{ "version": 1, "name": "Shlink", "documents": [ { "id": "index.md", "kind": "page", "title": "Getting started", "description": "Shlink is a self-hosted URL shortener which provides both a REST and a CLI interface to interact with it.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/", "markdown": "https://sourcey-shlink.pages.dev/documentation/index.md", "file": "index.md", "searchText": "\n# Getting started {#getting-started}\n\n\nShlink is a self-hosted URL shortener which provides both a [REST](/documentation/api-docs/) and a [CLI](/documentation/command-line-interface/entry-point/) interface to interact with it.\n\nAdditionally, there's also an official [Shlink web client](/documentation/shlink-web-client/) which, by making use of Shlink's REST API, provides a beautiful web UI to handle multiple Shlink instances.\n\nThis documentation will walk you through the process of getting both Shlink and shlink-web-client installed, using one of the many available approaches.\n\nYou will also learn how it is architected, how to use it once installed, and answers to frequently asked questions.\n\n\n## Where to start {#where-to-start}\n\n\n\n\n\n\n\n\n**[Install Shlink](/documentation/install-docker-image/)**\n\nRun the official Docker image, or the dist file on a PHP runtime you choose.\n\n\n\n\n\n\n**[Configure it](/documentation/environment-variables/)**\n\nEvery environment variable, from the default domain to the database and cache.\n\n\n\n\n\n\n**[Go further](/documentation/advanced/)**\n\nDynamic redirects, multiple domains, imports, real-time updates and more.\n\n\n\n\n\n\n**[Automate with the REST API](/documentation/api-docs/)**\n\nAuthentication, errors and API key roles, then every endpoint for your release.\n\n\n\n\n\n\n**[Use the web client](/documentation/shlink-web-client/)**\n\nA web UI that manages short URLs across several Shlink instances.\n\n\n\n\n\n\n**[Connect your tools](/documentation/integrations/)**\n\nThe official PHP and JS SDKs, and apps that work with Shlink.\n\n\n\n\n\n\n## Table of contents {#table-of-contents}\n\n\n\n\n\n\n- [Install docker image](/documentation/install-docker-image/)\n- [Install from dist file](/documentation/install-dist-file/)\n- [Supported runtimes](/documentation/supported-runtimes/)\n - [RoadRunner](/documentation/supported-runtimes/serve-with-roadrunner/)\n - [FrankenPHP](/documentation/supported-runtimes/serve-with-franken-php/)\n - [Classic web server](/documentation/supported-runtimes/classic-web-server/)\n- [Supported db engines](/documentation/supported-db-engines/)\n- [GeoLite2 license key](/documentation/geolite-license-key/)\n- [Update your instance](/documentation/update-your-instance/)\n- [Tracking visits](/documentation/tracking-visits/)\n- [Some features](/documentation/some-features/)\n- [Environment variables](/documentation/environment-variables/)\n- [Long-running tasks](/documentation/long-running-tasks/)\n- [Dynamic redirects](/documentation/advanced/dynamic-rule-based-redirects-system/)\n- [Special redirects](/documentation/advanced/special-redirects/)\n- [Multiple domains](/documentation/advanced/multiple-domains/)\n- [Import short URLs](/documentation/advanced/import-short-urls/)\n- [Real-time updates](/documentation/advanced/real-time-updates/)\n- [Using Redis or Valkey](/documentation/advanced/using-redis-or-valkey/)\n- [Using a reverse proxy](/documentation/advanced/exposing-through-reverse-proxy/)\n- [Send visits to Matomo](/documentation/advanced/send-visits-to-matomo/)\n- [Shlink architecture](/documentation/advanced/shlink-architecture/)\n- [CLI entry point](/documentation/command-line-interface/entry-point/)\n- [Installation tool](/documentation/command-line-interface/installation-tool/)\n- [Authentication](/documentation/api-docs/authentication/)\n- [Error management](/documentation/api-docs/error-management/)\n- [API key roles](/documentation/api-docs/api-key-roles/)\n- [Installation](/documentation/shlink-web-client/installation/)\n- [Serve in sub path](/documentation/shlink-web-client/serve-in-sub-path/)\n- [Pre-configuring servers](/documentation/shlink-web-client/pre-configuring-servers/)\n- [Short Menu for Mac](/documentation/integrations/short-menu-mac/)\n- [Short Menu for iOS](/documentation/integrations/short-menu-ios/)\n- [GNOME Shell extension](/documentation/integrations/gnome-shell-extension/)\n- [Microsoft PowerToys Run](/documentation/integrations/microsoft-power-toys-run/)\n- [Shlink iOS shortcut](/documentation/integrations/shlink-ios-shortcut/)\n- [Troubleshooting](/documentation/troubleshooting/)\n\n\n\n\n", "documentId": "index", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/", "markdown": "https://sourcey-shlink.pages.dev/documentation/index.md" } ] }, { "id": "install-docker-image/index.md", "kind": "page", "title": "Install using a docker image", "description": "The docker image is probably the simplest installation use case, since it includes all dependencies and works standalone.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/install-docker-image/", "markdown": "https://sourcey-shlink.pages.dev/documentation/install-docker-image/index.md", "file": "install-docker-image/index.md", "searchText": "\n# Install using a docker image {#install-using-a-docker-image}\n\n\nThe docker image is probably the simplest installation use case, since it includes all dependencies and works standalone.\n\n\n\n> [!IMPORTANT]\n> **Note**\n>\n> Shlink docker images are published both in [Docker hub](https://hub.docker.com/r/shlinkio/shlink) and [Github Container Registry](https://github.com/shlinkio/shlink/pkgs/container/shlink).\n>\n> All examples use Docker hub images. In order to install images from Github Container Registry, use `ghcr.io/shlinkio/shlink` instead of `shlinkio/shlink`.\n\n\n\n\n## Usage {#usage}\n\n\nThe most basic way to run Shlink's docker image is by providing these mandatory env vars.\n\n- `DEFAULT_DOMAIN`: The custom short domain used for this Shlink instance. For example **s.test**.\n- `IS_HTTPS_ENABLED`: Either **true** or **false**.\n- `GEOLITE_LICENSE_KEY`: Your GeoLite2 license key. [Learn more](/documentation/geolite-license-key/) about this.\n\nTo run Shlink on top of a local docker service, and using an internal SQLite database, do the following:\n\n```bash\ndocker run \\\n --name my_shlink \\\n -p 8080:8080 \\\n -e DEFAULT_DOMAIN=s.test \\\n -e IS_HTTPS_ENABLED=true \\\n -e GEOLITE_LICENSE_KEY=kjh23ljkbndskj345 \\\n shlinkio/shlink:stable\n```\n\n\n### Generate first API key {#generate-first-api-key}\n\n\nOnce the Shlink container is running, you can interact with the [CLI entry point](/documentation/command-line-interface/entry-point/) by running `shlink` with any of the supported commands.\n\nOne of the main reasons you would want to do that, is to generate your first API key. For example, if the container is called `my_shlink`, you can do it with:\n\n```bash\ndocker exec -it my_shlink shlink api-key:generate\n```\n\nIf you can't interact with the container's shell (for example, when running Shlink in [Google Cloud Run](https://cloud.google.com/run) or similar), or if you wish to provide an initial API key yourself, starting with Shlink 3.3.0, you can do so by providing the `INITIAL_API_KEY` env var with an API key of your choice.\n\n```bash\ndocker run \\\n --name my_shlink \\\n [...] \\\n -e INITIAL_API_KEY= \\\n shlinkio/shlink:stable\n```\n\n\n### Interact with Shlink's CLI on a running container. {#interact-with-shlinks-cli-on-a-running-container}\n\n\nGenerating the first API key is not the only thing you can do with Shlink's CLI entry point inside the container's shell.\n\nYou can also list all tags:\n\n```bash\ndocker exec -it my_shlink shlink tag:list\n```\n\nOr locate remaining visits:\n\n```bash\ndocker exec -it my_shlink shlink visit:locate\n```\n\nAll Shlink commands will work the same way.\n\nYou can also list all available commands by just running this:\n\n```bash\ndocker exec -it my_shlink shlink\n```\n\n\n## Use an external DB {#use-an-external-db}\n\n\nThe image comes with a working SQLite database, but in production, it's strongly recommended using a distributed database.\n\nIt is possible to use a set of env vars to make this Shlink instance interact with an external MySQL, MariaDB, PostgreSQL or Microsoft SQL Server database.\n\n- `DB_DRIVER`: **[Mandatory]**. Use the value **mysql**, **maria**, **postgres** or **mssql** to prevent the SQLite database to be used.\n- `DB_NAME`: [Optional]. The database name to be used. Defaults to **shlink**.\n- `DB_USER`: **[Mandatory]**. The username credential for the database server.\n- `DB_PASSWORD`: **[Mandatory]**. The password credential for the database server.\n- `DB_HOST`: **[Mandatory]**. The host name of the server running the database engine.\n- `DB_PORT`: [Optional]. The port in which the database service is running.\n - Default value is based on the value provided for `DB_DRIVER`:\n - **mysql** or **maria** -> `3306`\n - **postgres** -> `5432`\n - **mssql** -> `1433`\n\n> PostgreSQL is supported since v1.16.1 and Microsoft SQL server since v2.1.0. Do not try to use them with previous versions.\n\nTaking this into account, you could run Shlink on a local docker service like this:\n\n```bash\ndocker run \\\n --name my_shlink \\\n -p 8080:8080 \\\n -e DEFAULT_DOMAIN=s.test \\\n -e IS_HTTPS_ENABLED=true \\\n -e GEOLITE_LICENSE_KEY=kjh23ljkbndskj345 \\\n -e DB_DRIVER=mysql \\\n -e DB_USER=root \\\n -e DB_PASSWORD=123abc \\\n -e DB_HOST=something.rds.amazonaws.com \\\n shlinkio/shlink:stable\n```\n\nYou could even link to a local database running on a different container:\n\n```bash\ndocker run \\\n --name my_shlink \\\n -p 8080:8080 \\\n [...] \\\n -e DB_HOST=some_mysql_container \\\n --link some_mysql_container \\\n shlinkio/shlink:stable\n```\n\n> If you have considered using SQLite but sharing the database file with a volume, read [this issue](https://github.com/shlinkio/shlink-docker-image/issues/40) first.\n\n\n## Other integrations {#other-integrations}\n\n\n\n### Use an external Redis or Valkey server {#use-an-external-redis-or-valkey-server}\n\n\nIf you plan to run more than one Shlink instance, there are some resources that should be shared ([Multi instance considerations](/documentation/install-docker-image/#multi-instance-considerations)).\n\nOne of those resources are the locks Shlink generates to prevent some operations to be run more than once in parallel. You can find more information [here](/documentation/advanced/using-redis-or-valkey/#shared-locks).\n\n\n### Integrations for real-time updates {#integrations-for-real-time-updates}\n\n\nShlink supports sending real-time updates to some queueing systems, like [Mercure](https://mercure.rocks/), [RabbitMQ](https://www.rabbitmq.com/) or [Redis pub/sub](https://redis.io/docs/latest/develop/interact/pubsub/).\n\nCheck the [real-time updates](/documentation/advanced/real-time-updates/) section to get more details on how to integrate with them.\n\n\n## Supported env vars {#supported-env-vars}\n\n\nA few env vars have been already used in previous examples, but this image supports others that can be used to customize its behavior.\n\nSee the full list of supported [Environment variables](/documentation/environment-variables/).\n\n\n## Multi-architecture {#multi-architecture}\n\n\nStarting on v2.3.0, Shlink's docker image is built for multiple architectures.\n\nThe only limitation is that images for architectures other than `amd64` will not have support for Microsoft SQL databases, since there are no official binaries.\n\n\n## Multi-instance considerations {#multi-instance-considerations}\n\n\nThese are some considerations to take into account when running multiple Shlink instances.\n\n- Some operations performed by Shlink should never be run more than once at the same time (like creating the database for the first time, or downloading the GeoLite2 database). For this reason, Shlink uses a locking system.\n\n However, these locks are locally scoped to each Shlink instance by default.\n\n You can (and should) share the locks among all Shlink instances by using a Redis or Valkey server/cluster. Just define the `REDIS_SERVERS` env var with the list of servers.\n\n\n## Versions {#versions}\n\n\nVersioning on this docker image works as follows:\n\n- `X.X.X`: when providing a specific version number, the image version will match the Shlink version it contains. For example, installing `shlinkio/shlink:2.9.1`, you will get an image containing Shlink v2.9.1.\n- `X.X`: when providing major and minor version numbers, the image version will match the latest patch for that combination. For example, installing `shlinkio/shlink:3.6`, you will get an image containing Shlink v3.6.4.\n- `X`: when providing major version number, the image version will match the latest minor version for it. For example, installing `shlinkio/shlink:3`, you will get an image containing Shlink v3.7.0.\n- `stable`: always holds the most recent stable tag. For example, if latest Shlink version is 3.0.0, installing `shlinkio/shlink:stable`, you will get an image containing shlink v3.0.0\n- `latest`: same as `stable`, but if the most recent release is an `alpha` or `beta` version, `latest` will point to it.\n\n\n### Runtime variations {#runtime-variations}\n\n\nBefore Shlink 4.0.0, you could add `-roadrunner` or `-openswoole` to the tag you wanted to install in order to get an image using RoadRunner (for example, `shlinkio/shlink:stable-roadrunner` or `shlinkio/shlink:3.4.0-roadrunner`) or openswoole (for example `shlinkio/shlink:3.4.0-openswoole`).\n\nStarting with v4.0.0, Shlink only ships images with RoadRunner, but you can still append `-roadrunner` to make sure you'll continue getting that runtime in case support is added for something else.\n\n\n### Non-root {#non-root}\n\n\nStarting with Shlink 4.0.0, Shlink docker images run as a non-root user for security reasons.\n\nFor versions 3.6.x and 3.7.x you could add `-non-root` to get a RoadRunner-based docker image using a non-privileged user.\n", "documentId": "install-docker-image", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/install-docker-image/", "markdown": "https://sourcey-shlink.pages.dev/documentation/install-docker-image/index.md" } ] }, { "id": "install-dist-file/index.md", "kind": "page", "title": "Install using a dist file", "description": "Install using a dist file", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/install-dist-file/", "markdown": "https://sourcey-shlink.pages.dev/documentation/install-dist-file/index.md", "file": "install-dist-file/index.md", "searchText": "\n# Install using a dist file {#install-using-a-dist-file}\n\n\nIf you are going to host Shlink yourself, you need to make sure your server fulfils its requirements:\n\n- PHP 8.3, 8.4 or 8.5\n- The next PHP extensions: json, curl, pdo, intl, gd and gmp/bcmath.\n - apcu extension is recommended if you don't plan to use RoadRunner.\n - ~xml extension is required if you want to generate QR codes in svg format.~ (QR code generation is deprecated, see [this issue](https://github.com/shlinkio/shlink/issues/2408) for details).\n - sockets and bcmath extensions are required if you want to integrate with a RabbitMQ instance, or use [RoadRunner to serve Shlink](/documentation/supported-runtimes/serve-with-roadrunner/).\n- MySQL, MariaDB, PostgreSQL, MicrosoftSQL or SQLite.\n - You will also need the corresponding pdo variation for the database you are planning to use: `pdo_mysql`, `pdo_pgsql` or `pdo_sqlsrv`.\n- One of the [supported runtimes](/documentation/supported-runtimes/).\n\n\n## Installation steps {#installation-steps}\n\n\n- Download the latest distributable file and decompress it at the location of your choice (you will find a dist file for every supported PHP version).\n
\n [Download](https://github.com/shlinkio/shlink/releases/latest)\n
\n\n- Create an empty database (not necessary if you are going to use SQLite).\n- Recursively grant write permissions to the `data` directory.\n- Set-up and customize Shlink by either:\n - Running the [installation tool](/documentation/command-line-interface/installation-tool/) (`vendor/bin/shlink-installer install`). It's an interactive tool that will guide you through the installation process.\n - Providing your configuration via [env vars](/documentation/environment-variables/) (since v2.9.0). Useful to pre-define the configuration or if you don't have shell access to the server.\n- Optionally, you can create a symlink to the `bin/cli` script in a folder which is in your path.
For example `/usr/local/bin` for linux systems. This will allow you to easily run Shlink from anywhere in the command line.\n- Generate your first API key (you will need it in order to interact with Shlink's API):\n - For Shlink older than 3.3.0, run `bin/cli api-key:generate`.\n - For Shlink 3.3.0 or newer, the installation tool will create an API key for you. Just copy-paste it.\n- Set-up Shlink's runtime:\n - [Serve Shlink using RoadRunner](/documentation/supported-runtimes/serve-with-roadrunner/).\n - [Serve Shlink with a classic web server](/documentation/supported-runtimes/classic-web-server/).\n- Finally, access to [https://app.shlink.io](https://app.shlink.io) and configure your server to start creating short URLs.\n", "documentId": "install-dist-file", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/install-dist-file/", "markdown": "https://sourcey-shlink.pages.dev/documentation/install-dist-file/index.md" } ] }, { "id": "supported-runtimes/index.md", "kind": "page", "title": "Supported runtimes", "description": "Shlink supports a number of ways to serve it. Each one of them has pros and cons, and depending on your technical knowledge and needs, you may prefer to choose one or another.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/supported-runtimes/", "markdown": "https://sourcey-shlink.pages.dev/documentation/supported-runtimes/index.md", "file": "supported-runtimes/index.md", "searchText": "\n# Supported runtimes {#supported-runtimes}\n\n\nShlink supports a number of ways to serve it. Each one of them has pros and cons, and depending on your technical knowledge and needs, you may prefer to choose one or another.\n\nThis document offers a comparison of all of them, to help you make the best decision.\n\n\n## RoadRunner {#roadrunner}\n\n\n[RoadRunner](https://roadrunner.dev/) is a PHP application server written in go, that can be installed directly with Shlink.\n\nIt lets you load Shlink in memory, and serve requests without reloading the service, which makes it very fast.\n\nIt also supports running heavy tasks in background (like updating the [GeoLite2](/documentation/geolite-license-key/) database file or notifying [real-time updates](/documentation/advanced/real-time-updates/)).\n\nThis makes it the current **officially recommended runtime**.\n\nFollow [the documentation](/documentation/supported-runtimes/serve-with-roadrunner/) in order to know how to get it up and running.\n\n\n## FrankenPHP {#frankenphp}\n\n\nSimilarly to RoadRunner, [FrankenPHP](https://frankenphp.dev/) is also a PHP application server written in go, with support for worker mode.\n\nIt also has a very good performance, but as opposed to RoadRunner, background tasks are not supported with this runtime.\n\nFollow [the documentation](/documentation/supported-runtimes/serve-with-franken-php/) in order to know how to install it and serve Shlink with it.\n\n\n## Classic web server {#classic-web-server}\n\n\nThis is the way traditionally PHP apps have been served.\n\nIt requires a web server (Nginx, Apache, etc.) and a FastCGI, like [php-fpm](https://www.php.net/manual/en/install.fpm.php).\n\nIt is the least performant option, as Shlink needs to be bootstrapped on every request, but at the same time it is the more predictable option and the one you may prefer if you have experience hosting other PHP apps.\n\nFollow [the documentation](/documentation/supported-runtimes/classic-web-server/) in order to know how to get it working.\n\n\n## Comparison {#comparison}\n\n\nNow that you know the options, follow this table in order to decide what's the best one for you and how to install it.\n\n| | RoadRunner | FrankenPHP | Classic web server |\n| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |\n| **Performance** | 90 | 80 | 30 |\n| **Stability under heavy load** | 100 | 100 | 70 |\n| **Hard to install** | Easy | Easy | Medium |\n| **[Reverse proxy](/documentation/advanced/exposing-through-reverse-proxy/)** | Recommended | Not needed | Not needed |\n| **HTTPS support** | Via reverse proxy | Built-in | Yes |\n| **[Real-time updates](/documentation/advanced/real-time-updates/)** | Supported ⚠ | Not supported | Not supported |\n| **GeoLite2 updates** | Supported | Via [long-running tasks](/documentation/long-running-tasks/) | Via [long-running tasks](/documentation/long-running-tasks/) |\n", "documentId": "supported-runtimes", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/supported-runtimes/", "markdown": "https://sourcey-shlink.pages.dev/documentation/supported-runtimes/index.md" } ] }, { "id": "supported-runtimes/serve-with-roadrunner/index.md", "kind": "page", "title": "Serve Shlink using RoadRunner", "description": "Starting with v3.3.0, Shlink can be served with RoadRunner.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/supported-runtimes/serve-with-roadrunner/", "markdown": "https://sourcey-shlink.pages.dev/documentation/supported-runtimes/serve-with-roadrunner/index.md", "file": "supported-runtimes/serve-with-roadrunner/index.md", "searchText": "\n# Serve Shlink using RoadRunner {#serve-shlink-using-roadrunner}\n\n\nStarting with v3.3.0, Shlink can be served with [RoadRunner](https://roadrunner.dev/).\n\nIt is a web server written in Go, that lets you load Shlink in memory and serve requests without bootstrapping the whole application on every request.\n\nIt works similarly to node.js, and is currently the **officially recommended runtime**.\n\n\n## Installing RoadRunner binary {#installing-roadrunner-binary}\n\n\nIn order to serve Shlink with RoadRunner, you have to first download its binary.\n\nLuckily, Shlink includes everything you need to do it, and it will resolve the proper one for your operating system and system architecture.\n\nJust run `php ./vendor/bin/rr get --no-interaction --location bin/ && chmod +x bin/rr` and you will get the binary named `rr` inside Shlink's `bin` folder.\n\nAfter that, run `./bin/rr serve -c config/roadrunner/.rr.yml` and the server will start and be available in the port you previously configured (`8080` by default).\n\n\n## Shlink as a system service {#shlink-as-a-system-service}\n\n\nThe command above is enough to \"start\" Shlink, but you probably don't want to do that manually every time.\n\nIf you use Linux, this page explains how to set up a [RoadRunner server as a systemd daemon](https://docs.roadrunner.dev/docs/app-server/systemd).\n\nJust make sure to replace `ExecStart` with `/path/to/shlink/bin/rr serve -c config/roadrunner/.rr.yml`, as explained there.\n", "documentId": "supported-runtimes/serve-with-roadrunner", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/supported-runtimes/serve-with-roadrunner/", "markdown": "https://sourcey-shlink.pages.dev/documentation/supported-runtimes/serve-with-roadrunner/index.md" } ] }, { "id": "supported-runtimes/serve-with-franken-php/index.md", "kind": "page", "title": "Serve Shlink using FrankenPHP", "description": "Starting with v4.6.0, it is possible to use FrankenPHP to serve Shlink, using its worker mode.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/supported-runtimes/serve-with-franken-php/", "markdown": "https://sourcey-shlink.pages.dev/documentation/supported-runtimes/serve-with-franken-php/index.md", "file": "supported-runtimes/serve-with-franken-php/index.md", "searchText": "\n# Serve Shlink using FrankenPHP {#serve-shlink-using-frankenphp}\n\n\nStarting with v4.6.0, it is possible to use [FrankenPHP](https://frankenphp.dev/) to serve Shlink, using its [worker mode](https://frankenphp.dev/docs/worker/).\n\n\n## Installing FrankenPHP binary {#installing-frankenphp-binary}\n\n\nThe first thing you need to do is getting the [official binary](https://frankenphp.dev/docs/#standalone-binary):\n\n```shell\ncurl https://frankenphp.dev/install.sh | sh\nmv frankenphp /usr/local/bin/\n```\n\n\n## Running Shlink with FrankenPHP {#running-shlink-with-frankenphp}\n\n\nNow, you can run the following command:\n\n```shell\nfrankenphp php-server --worker /path/to/shlink/bin/frankenphp-worker.php\n```\n\nWhere `/path/to/shlink` is the directory where you downloaded Shlink. The `frankenphp-worker.php` script is provided by Shlink.\n\nFrankenPHP supports many other configuration options. Take a look at [their documentation](https://frankenphp.dev/docs/config/) to customize it for your needs.\n", "documentId": "supported-runtimes/serve-with-franken-php", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/supported-runtimes/serve-with-franken-php/", "markdown": "https://sourcey-shlink.pages.dev/documentation/supported-runtimes/serve-with-franken-php/index.md" } ] }, { "id": "supported-runtimes/classic-web-server/index.md", "kind": "page", "title": "Serve Shlink with a classic web server", "description": "In order to be able to serve shlink, you need to put a web server with PHP integration in front of it.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/supported-runtimes/classic-web-server/", "markdown": "https://sourcey-shlink.pages.dev/documentation/supported-runtimes/classic-web-server/index.md", "file": "supported-runtimes/classic-web-server/index.md", "searchText": "\n# Serve Shlink with a classic web server {#serve-shlink-with-a-classic-web-server}\n\n\nIn order to be able to serve shlink, you need to put a web server with PHP integration in front of it.\n\nBoth Apache and Nginx are officially supported, but other web servers should work as well.\n\nHere you can find two simple examples of the virtual hosts needed for both Apache and Nginx (you may need to modify them depending on your setup).\n\n\n## Nginx {#nginx}\n\n\n```nginx\nserver {\n server_name s.test;\n listen 80;\n root /path/to/shlink/public;\n index index.php;\n charset utf-8;\n\n location / {\n try_files $uri $uri/ /index.php$is_args$args;\n }\n\n location ~ \\.php$ {\n fastcgi_split_path_info ^(.+\\.php)(/.+)$;\n fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;\n fastcgi_index index.php;\n include fastcgi.conf;\n }\n\n location ~ /\\.ht {\n deny all;\n }\n}\n```\n\n\n## Apache {#apache}\n\n\n```apache\n\n ServerName s.test\n DocumentRoot \"/path/to/shlink/public\";\n\n \n Options FollowSymLinks Includes ExecCGI\n AllowOverride all\n Order allow,deny\n Allow from all\n \n\n```\n", "documentId": "supported-runtimes/classic-web-server", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/supported-runtimes/classic-web-server/", "markdown": "https://sourcey-shlink.pages.dev/documentation/supported-runtimes/classic-web-server/index.md" } ] }, { "id": "supported-db-engines/index.md", "kind": "page", "title": "Supported database engines", "description": "Performance with all of them is pretty similar, and the only reason to not force you to use a specific one is so that you can use the one you are more comfortable with.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/supported-db-engines/", "markdown": "https://sourcey-shlink.pages.dev/documentation/supported-db-engines/index.md", "file": "supported-db-engines/index.md", "searchText": "\n# Supported database engines {#supported-database-engines}\n\n\nFor your own convenience, Shlink supports the most popular relational database engines:\n\n- [MySQL](https://www.mysql.com/)\n- [MariaDB](https://mariadb.org/)\n- [PostgreSQL](https://www.postgresql.org/)\n- [Microsoft SQL Server](https://www.microsoft.com/sql-server/)\n\nPerformance with all of them is pretty similar, and the only reason to not force you to use a specific one is so that you can use the one you are more comfortable with.\n\n\n\n> [!WARNING]\n> **Database availability**\n>\n> It is important to mention that Shlink expects the database to be **up and running** when it starts.\n>\n> If you are starting-up the database together with Shlink (like, via `docker compose` or similar), you may see some errors until the database is ready, and it's important to make sure Shlink container is configured to restart on error so that it \"retries\" a couple of times.\n\n\n\n\n## Migrating your database {#migrating-your-database}\n\n\nAt some point, and after successfully running Shlink for some time, you may need/want to move to a different database engine.\n\nThere are a number of reasons you may need to do this:\n\n- Migrating to another hosting which does not support the one you were using\n- You found a cheaper managed database, but it uses a different engine.\n- You started testing Shlink with SQLite and want to move to something more future-proof, but retaining your data.\n\nIn order to do this, the easiest approach is to set up a new Shlink instance with the new database, and then take advantage of the [import tool](/documentation/advanced/import-short-urls/#shlink-instance) to bring your data from the old one.\n\nOne of the sources from which this tool can import is another Shlink instance, for which it uses Shlink's API.\n\n\n## SQLite limitations {#sqlite-limitations}\n\n\nShlink also supports SQLite, but with the only intention that you can quickly spin-up Shlink and test it, and also to simplify automating a Shlink environment for the purpose of E2E testing and similar.\n\nIt's very important to understand that using SQLite for production **is not officially supported**, since you can quickly face problems and limitations when dealing with big amounts of data or high traffic.\n\nSome have even tried to use it together with docker, via docker volumes. That's just looking for trouble.\n\nMake sure that, once you have tested Shlink and want to use it long term, you move to one of the other supported engines.\n\n\n## Microsoft SQL limitations {#microsoft-sql-limitations}\n\n\nShlink tries to support the same database engines regardless how it is set up and installed. This includes the official docker image, which comes with pre-built drivers for all of them.\n\nThere's one limitation thought. If you try to use the docker image on an ARM architecture, you will find it does not include Microsoft SQL Server drivers.\n\nThe reason is that Microsoft does not provide an official driver for this architecture, so you will have to use one of the other databases if you plan to run Shlink in an ARM device.\n", "documentId": "supported-db-engines", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/supported-db-engines/", "markdown": "https://sourcey-shlink.pages.dev/documentation/supported-db-engines/index.md" } ] }, { "id": "geolite-license-key/index.md", "kind": "page", "title": "GeoLite2 license key", "description": "Shlink makes use of a GeoLite2 database, by MaxMind, to geolocate visits to your short URLs.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/geolite-license-key/", "markdown": "https://sourcey-shlink.pages.dev/documentation/geolite-license-key/index.md", "file": "geolite-license-key/index.md", "searchText": "\n# GeoLite2 license key {#geolite2-license-key}\n\n\nShlink makes use of a [GeoLite2](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data/) database, by [MaxMind](https://www.maxmind.com), to geolocate visits to your short URLs.\n\nTo make sure the data is always up-to-date, it downloads new versions of the database regularly.\n\nHowever, in order to do this, Shlink needs a GeoLite2 license key. These licenses are free, and you can easily generate one by following the instructions below.\n\n\n\n> [!IMPORTANT]\n> **Note**\n>\n> If you don't provide a GeoLite2 license key, Shlink will simply not geolocate visits.\n\n\n\n\n## Generate a license key {#generate-a-license-key}\n\n\nIn order to generate the license key, follow these steps.\n\n- Create a MaxMind [account for GeoLite2](https://www.maxmind.com/en/geolite2/signup).\n- Generate a [license key](https://www.maxmind.com/en/accounts/current/license-key). Its **important** that you save the value, as you will not be able to recover it afterwards.\n\n\n## Provide the license key to Shlink {#provide-the-license-key-to-shlink}\n\n\nOnce you have your license key, you will need to provide it to Shlink.\n\n- Via environment variable: use `GEOLITE_LICENSE_KEY` to set your license key.\n- Via [installation tool](/documentation/command-line-interface/installation-tool/): you will be asked to provide the license key when installing or updating Shlink, or you can use [set-option](/documentation/command-line-interface/installation-tool/#set-option) to set it later.\n", "documentId": "geolite-license-key", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/geolite-license-key/", "markdown": "https://sourcey-shlink.pages.dev/documentation/geolite-license-key/index.md" } ] }, { "id": "update-your-instance/index.md", "kind": "page", "title": "Update your Shlink instance", "description": "Shlink is designed so that updating an installation to a newer version is as easy as possible, without loosing any data while doing it.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/update-your-instance/", "markdown": "https://sourcey-shlink.pages.dev/documentation/update-your-instance/index.md", "file": "update-your-instance/index.md", "searchText": "\n# Update your Shlink instance {#update-your-shlink-instance}\n\n\nShlink is designed so that updating an installation to a newer version is as easy as possible, without loosing any data while doing it.\n\nHowever, the process may defer depending on how you installed Shlink.\n\n\n\n> [!WARNING]\n> **Important**\n>\n> It is recommended that you don't skip too many versions at a time when updating Shlink. If you have to, make sure to\n> back-up your database beforehand, in case the process needs to be rolled back. If your Shlink instance is out of date,\n> preferably update Shlink in sequential order using the latest patch release for every minor version. For example, to\n> go from version 3.2.1 to version 3.4.0, first update to 3.3.2, and then 3.4.0.\n\n\n\n\n## Update a docker image {#update-a-docker-image}\n\n\nThis is probably the simplest use case.\n\nWhen a new shlink version is released, it will come together with a new docker image tag.\n\nYou will just need to use the new one in order to get updated. The image itself will take care of updating the database, if needed, without loosing data in the process.\n\nEnv vars will be backwards compatible, and only major releases may drop support for some of existing ones, but when this happens, documentation will be provided on how to migrate.\n\n\n## Updating a self-hosted instance. {#updating-a-self-hosted-instance}\n\n\nIf you are hosting Shlink manually, you probably started by running the `install` command of the [installation tool](/documentation/command-line-interface/installation-tool/) (`vendor/bin/shlink-installer install`), which gets your instance set-up.\n\nThis tool also has an `update` command (`vendor/bin/shlink-installer update`). With it, you will be able to import the configuration from your previous installation folder, and provide any new configuration options. Any configuration option you previously provided will be kept the same.\n\nThat said, the process you should follow would be this:\n\n1. Rename your existing Shlink directory to something else (ie. `shlink` -> `shlink-old`).\n2. Download and extract the new version of Shlink, and set the directory name to that of the old version (ie. `shlink`).\n3. Run the `vendor/bin/shlink-installer update` script in the new version's directory to migrate your configuration over. You will be asked to provide the path to the old instance (ie. `shlink-old`).\n4. Restart the service (either Shlink if you are using RoadRunner, or the web server of your choice).\n", "documentId": "update-your-instance", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/update-your-instance/", "markdown": "https://sourcey-shlink.pages.dev/documentation/update-your-instance/index.md" } ] }, { "id": "tracking-visits/index.md", "kind": "page", "title": "Tracking visits", "description": "One of the most interesting features in Shlink is the visits tracking.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/tracking-visits/", "markdown": "https://sourcey-shlink.pages.dev/documentation/tracking-visits/index.md", "file": "tracking-visits/index.md", "searchText": "\n# Tracking visits {#tracking-visits}\n\n\nOne of the most interesting features in Shlink is the visits tracking.\n\nShlink will track every time your short URLs are opened, and then try to geolocate the visitor.\n\n\n## Considerations {#considerations}\n\n\nIn order to geolocate visits, Shlink makes use of a [GeoLite2](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data/) database, by [MaxMind](https://www.maxmind.com), which is used to match the location of the visitor's IP address.\n\nTo make sure your GeoLite2 db is always up-to-date, you will have to [configure your own license key](/documentation/geolite-license-key/).\n\nAlso, Shlink will make sure you fulfil most data protection regulations, by storing only an anonymized version of the visitor's IP address (unless deliberately opting-out of this behavior).\n\n\n## Orphan visits {#orphan-visits}\n\n\nStarting with v2.6.0, Shlink can also track visits to any URL that would usually result in a \"404 - Not found\" error, also known as **orphan visits**.\n\nThese visits can have one of these types:\n\n- `base_url`: Someone opened the base URL in which Shlink is hosted.\n- `invalid_short_url`: Someone opened a short-url-like URL, but it did not resolve an existing short URL, or it was disabled.\n- `regular_404`: Someone opened a route which Shlink didn't understand.\n\nThe visits will be tracked both if you configure [special redirects](/documentation/advanced/special-redirects/) from those three cases, but also if you leave Shlink serve a regular 404 status with a \"Not found\" template.\n\nIn case you don't need this, you can opt out from orphan visits tracking via [env vars](/documentation/environment-variables/#visits-tracking) or [installation tool's](/documentation/command-line-interface/installation-tool/) config options.\n\n\n## Disable tracking {#disable-tracking}\n\n\nSince v2.7.0, Shlink provides a more granular way to disable visits tracking, either completely or partially.\n\nVia configuration or [env vars](/documentation/environment-variables/#visits-tracking), you will be able to:\n\n- Completely disable tracking: All short URLs will display they had **0** visits.\n- Disable IP address tracking: The visits will be counted, but they will all show they come from an **unknown** location.\n- Disable referrer tracking: All visits will be counted and located, but Shlink will not track the **referrer**.\n- Disable user agent tracking: All visits will be counted and located, but Shlink will not track the **user agent**.\n", "documentId": "tracking-visits", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/tracking-visits/", "markdown": "https://sourcey-shlink.pages.dev/documentation/tracking-visits/index.md" } ] }, { "id": "some-features/index.md", "kind": "page", "title": "Some features", "description": "Here you'll find some extra Shlink features, which are not as evident, but you might still want to take advantage of.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/some-features/", "markdown": "https://sourcey-shlink.pages.dev/documentation/some-features/index.md", "file": "some-features/index.md", "searchText": "\n# Some features {#some-features}\n\n\nHere you'll find some extra Shlink features, which are not as evident, but you might still want to take advantage of.\n\nThis document also tries to clarify why some of these features work the way they do.\n\n- [Short URL title](#short-url-title)\n- [Query params forwarding](#query-params-forwarding)\n- [Extra path forwarding](#extra-path-forwarding)\n- [Multi-segment custom slugs](#multi-segment-custom-slugs)\n- [Short URLs trailing slash](#short-urls-trailing-slash)\n- [Short URLs mode](#short-urls-mode)\n- [Bot detection](#bot-detection)\n- [Remove expired links](#remove-expired-links)\n- [Email tracking](#email-tracking)\n- [Service healthiness](#service-healthiness)\n- [Device-specific redirects](#device-specific-redirects)\n- [QR Codes](#qr-codes)\n\n\n## Short URL title {#short-url-title}\n\n\nShlink v2.6.0 introduces the ability to optionally set a `title` for every short URL.\n\nThe title can be provided, but it's also possible to enable title auto-resolution. When that's enabled, and the title is not provided, Shlink will try to infer the title by calling the long URL and picking the value inside the `` tag.\n\nThe title can be changed later on. If the long URL is changed, it will also try to auto-resolve the new title, unless the title was originally provided during creation.\n\n\n## Query params forwarding {#query-params-forwarding}\n\n\nBy default, Shlink automatically forwards to the long URL all query params originally sent to the short URL.\n\nFor example, if you have a `https://exam.ple/abc123` URL that points to `https://www.google.com`, when users visit `https://exam.ple/abc123?foo=bar`, they will get redirected to `https://www.google.com?foo=bar`.\n\nIf for any reason the long URL already had query params, they will be merged with the ones sent to the short URL. In case of conflict, the value sent with the short URL will take precedence over the original URL one.\n\nFor example, if `https://exam.ple/abc123` points to `https://www.google.com?foo=bar`, when users visit `https://exam.ple/abc123?foo=overwritten&another=param`, they will get redirected to `https://www.google.com?foo=overwritten&another=param`.\n\n\n\n> [!IMPORTANT]\n> **Note**\n>\n> Starting with Shlink v2.9.0, this behavior can be overwritten on every individual short URL, allowing to disable the\n> query params forwarding if desired.\n\n\n\n\n## Extra path forwarding {#extra-path-forwarding}\n\n\nShlink can match short URLs either strictly (the exact short URL is expected), or as soon as the visited URL starts with an existing short code.\n\nIn the second case, you can make Shlink append the rest of the path to the long URL before redirection, or simply ignore it (Shlink 4.4.0 is required for the latter).\n\nFor example, if you have a `https://exam.ple/abc123` URL that points to `https://github.com`, you can make Shlink capture visits to `https://exam.ple/abc123/shlinkio` and redirect to either `https://github.com/shlinkio` (appending the extra path) or `https://github.com` (ignoring the extra path).\n\nWhen this happens, Shlink will track the visit as usual.\n\nThis behavior needs to be actively opted in, as it's disabled by default.\n\n\n## Multi-segment custom slugs {#multi-segment-custom-slugs}\n\n\nShlink 3.2.0 introduced the ability to create short URLs with multi-segment custom slugs.\n\nThat means that you can provide multiple parts separated by slashes as the custom slug, ending with something like `https://exam.ple/my/custom/campaign`.\n\nThis feature has some considerations though:\n\n- When this is enabled, any URL will match a potential short URL. That means any future orphan visit will have either `base_url` or `invalid_short_url` types, but never `regular_404`.\n- Because of previous point, this is considered a breaking change, and therefore, it's disabled by default, and you have to actively opt in.\n- If [Extra path forwarding](#extra-path-forwarding) is also enabled, there's always a chance of conflict. If you have both `https://exam.ple/foo` and `https://exam.ple/foo/bar`, when the second one is visited, it will match the first one, and the `/bar` part will be forwarded to the long URL.\n\n\n## Short URLs trailing slash {#short-urls-trailing-slash}\n\n\nStarting with Shlink 3.3.0, you can make the same short URL work whether it has a trailing slash or not. (This feature has to be explicitly enabled via [installation tool](/documentation/command-line-interface/installation-tool/) or [environment variables](/documentation/environment-variables/)).\n\nThis means that, while the feature is enabled, if you create the short URL `https://examp.le/foo` and a user ends up visiting `https://examp.le/foo/`, the visit will be properly captured and the user will be redirected.\n\nIn older versions of Shlink or when this is not enabled, visiting a short URL with trailing slash results in a 404.\n\nIf you want to support trailing slashes in any route known by Shlink and not only short URLs, you can configure the web server in front of Shlink to strip trailing slashes before calling it:\n\n- Nginx: https://hammerill.com/en/blog/trailing-nginx#you-dont-need-trailing-slashes\n- Apache: https://www.rewriteguide.com/apache-add-remove-trailing-slash/\n- Caddy: https://caddy.community/t/efficient-remove-trailing-slash-redirect/3289\n\n\n## Short URLs mode {#short-urls-mode}\n\n\nBy default, Shlink always matches short URLs in a `strict` mode, meaning it does a case-sensitive check when trying to determine which short URL has been visited.\n\nThis effectively means `https://s.test/aaabbb` and `https://s.test/AAABBB` are considered different URLs by Shlink.\n\nStarting with Shlink v3.5.0, you can customize this behavior, and make Shlink consider those two URLs to be the same.\n\nThis is achieved via the so called `loose` short URL mode (the mode can be set via [installation tool](/documentation/command-line-interface/installation-tool/) or [environment variables](/documentation/environment-variables/)).\n\n\n\n> [!WARNING]\n> Setting `loose` mode has a couple of considerations:\n>\n> - Shlink will no longer generate short codes with uppercase letters. Only lowercase and numbers will be taken into consideration.\n> - When providing a custom slug, Shlink will lowercase it, so if there's a URL with `aaabbb` and `AaaBbb` is provided, it will throw an error saying it already exists.\n> - On existing Shlink instances, already existing short URLs will not be changed in any way. If \"conflicting\" URLs already exist, they have to be fixed manually.\n> - Loose checks are done only for \"public\" URLs (short URLs, QR codes and email tracking). REST API endpoints do strict matches no matter what.\n\n\n\n\n## Bot detection {#bot-detection}\n\n\nStarting with v2.7.0, Shlink can now detect visits from potential bots or crawlers, based on the visitor's `User-Agent` header.\n\nOf course, there's never a 100% accuracy here, hence the **potential**.\n\nAll the endpoints serving visits will include the `potentialBot` flag with values `true` or `false`, and they also allow excluding potential bots from the result set.\n\n\n## Remove expired links {#remove-expired-links}\n\n\nSometimes you programmatically create \"temporary\" links that are meant to be used once or during a short period of time, and then get disabled via `maxVisits` or `validUntil`.\n\nAfter some time, you can end up with a bunch of short URLs consuming space, that are never going to receive new visits.\n\nWhile Shlink does not provide a mechanism to automatically delete them once expired, starting with Shlink 4.1.0, you can use the `short-url:delete-expired` command to delete all links that are considered expired by the conditions mentioned above.\n\nIt's up to you to configure this command to be run periodically if desired.\n\n\n## Email tracking {#email-tracking}\n\n\nShlink can track how many times an email has been opened, by taking advantage of its URL tracking capabilities.\n\nYou can track emails with any existing short URL, or create a new one pointing to a dummy long URL (the redirect itself is not important for this use case).\n\nThen, by appending `/track` to the short URL, you will have a new URL (for example, `https://example.com/abc123/track`) that resolves to a 1px transparent image. Add it to any email you want to track.\n\nThe image is effectively invisible, but every time the email is opened and the image is loaded, Shlink will count one visit.\n\n\n## Service healthiness {#service-healthiness}\n\n\nIn some situations you may want to know if your Shlink instance is healthy. Reasons might include monitoring, but also letting orchestrators know if one specific instance can respond to requests.\n\nShlink exposes a `/rest/health` endpoint, which does not require authentication, and can be used for this purpose.\n\nYou can find more information in the [API docs](/documentation/api/#operation-rest-health-get).\n\n\n## Device-specific redirects {#device-specific-redirects}\n\n\nShlink 3.5.0 introduced the possibility to dynamically redirect to different long URLs depending on the device used by the visitor.\n\nShlink v4.0.0 has moved this into a new [dynamic rule-based redirects system](/documentation/advanced/dynamic-rule-based-redirects-system/).\n\n\n## QR codes {#qr-codes}\n\n\nShlink comes with built-in support to generate QR codes for any short URL.\n\n\n\n> [!WARNING]\n> Starting with Shlink 4.5.0, generating QR codes through Shlink is considered deprecated. See [this\n> issue](https://github.com/shlinkio/shlink/issues/2408) for details.\n\n\n\nGetting a QR code URL is as simple as appending `/qr-code` to any short URL. So if your short URL is `https://exam.ple/abc123`, the URL which returns the binary QR code image is `https://exam.ple/abc123/qr-code`.\n\nThe image's default appearance can be customized via [installation tool](/documentation/command-line-interface/installation-tool/) or [env vars](/documentation/environment-variables/#qr-codes), but it can also be customized on the fly via query params:\n\n- `size`: It determines the width/height in pixels. Default value is 300 and accepts values from 50 to 1000.\n- `margin` _(since v2.6.0)_ : The space in pixels between the QR code itself and the border of the image. Default value is 0 and accepts positive numbers.\n- `format` _(since v2.4.0)_ : Can be `png` or `svg`. Default values is `png`.\n- `errorCorrection` _(since v2.8.0)_ : Can be `L` (Low), `M` (Medium), `Q` (Quartile) or `H` (High). Default value is `L`. [Learn more](https://www.qrcode.com/en/about/error_correction.html).\n- `roundBlockSize` _(since v2.10.0)_ : Can be `true` or `false`. Tells if the block size should be rounded, making the QR code more readable, but potentially adding some extra margin as a side effect.\n- `color` _(since v4.0.0)_ : Foreground color in hexadecimal, with 3 or 6 characters. Default value is `black` if not provided or provided value is not a color.\n- `bgColor` _(since v4.0.0)_ : Background color in hexadecimal, with 3 or 6 characters. Default value is `white` if not provided or provided value is not a color.\n\nFor example `https://exam.ple/abc123/qr-code?size=500&format=svg&margin=20&errorCorrection=Q&roundBlockSize=false`.\n\nSee the [\"endpoint\" docs](/documentation/api/v4/#operation-shortcode-qr-code-get) for more information.\n\n\n\n> [!WARNING]\n> **Considerations**\n>\n> * The total size of the image will be determined by the size + the margin times two. So, if the size is 500 and the\n> margin is 20, the resulting image will be 540x540 pixels. * The logo cannot be customized via query params, to avoid\n> public QR codes from being unintentionally associated with certain images.\n\n\n", "documentId": "some-features", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/some-features/", "markdown": "https://sourcey-shlink.pages.dev/documentation/some-features/index.md" } ] }, { "id": "environment-variables/index.md", "kind": "page", "title": "Environment variables", "description": "After installing Shlink, you will have to set it up, and customize different aspects of its behavior. One way to do this is via environment variables.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/environment-variables/", "markdown": "https://sourcey-shlink.pages.dev/documentation/environment-variables/index.md", "file": "environment-variables/index.md", "searchText": "\n# Environment variables {#environment-variables}\n\n\nAfter installing Shlink, you will have to set it up, and customize different aspects of its behavior. One way to do this is via **environment variables**.\n\nThis is the complete list of supported env vars. Right next to their name you will find the version in which they were introduced.\n\nStrikethrough env vars are deprecated.\n\n\n## Supported env vars {#supported-env-vars}\n\n\n- [General](#general)\n- [URL shortening](#url-shortening)\n- [Database](#database)\n- [Redirects](#redirects)\n- [Visits tracking](#visits-tracking)\n- [Robots.txt](#robotstxt)\n- [Cross-origin](#cross-origin)\n- [Real-time updates](#real-time-updates)\n- [Redis integration](#redis-integration)\n- [Mercure hub integration](#mercure-hub-integration)\n- [RabbitMQ integration](#rabbitmq-integration)\n- [Matomo integration](#matomo-integration)\n- [Specific for the docker image](#specific-for-the-docker-image)\n\n\n### General {#general}\n\n\n- `DEFAULT_DOMAIN`: The default short domain used for this Shlink instance. For example **s.test**.\n- `IS_HTTPS_ENABLED`: Tells if Shlink is served with https or not (`true` or `false`). It's still **up to you** to actually serve it with HTTPS.\n- `GEOLITE_LICENSE_KEY`: The license key used to download new GeoLite2 database files. Go to [GeoLite2 license key](/documentation/geolite-license-key/) to know how to generate it. Not providing a license key will completely disable visits geolocation.\n- `BASE_PATH`: The base path from which you plan to serve Shlink, in case you don't want to serve it from the root of the domain. It **has** to start with a bar, like `/shlink`. Defaults to `''`.\n- `TIMEZONE`: A timezone code as defined [in this list](https://www.php.net/manual/en/timezones.php). All dates stored by Shlink (visits, short URL creation, etc) will be considered to be on this timezone. By default, the default timezone set in PHP config will be used, which is `UTC` in the case of the docker image.\n- `CACHE_NAMESPACE` _(v3.7.0)_ : A prefix used for all cache keys generated by Shlink. It's important to set a unique value here if you have multiple Shlink instances sharing the same cache store (same server when not using redis, or same redis cluster), otherwise there could be collisions. Defaults to `Shlink`.\n- `TRUSTED_PROXIES` _(v4.5.0)_ : Either the amount of proxies in front of Shlink, or a comma-separated list of their IP addresses as fixed address (`100.200.80.40`), CIDR block (`192.168.10.0/24`) or wildcard pattern (`11.22.*.*`). It's important to set this if you have more than one reverse proxy in front of Shlink, so that the visitor's IP addresses can be properly determined.\n- `MEMORY_LIMIT` _(v4.1.0)_ : The maximum amount of memory that every Shlink process can use. You can provide a number, which will be the amount of memory in bytes, or a number followed by `K` for kilobytes, `M` for megabytes or `G` for gigabytes. You can also provide `-1` to set no memory limit. Defaults to `512M`.\n- `LOGS_FORMAT` _(v4.5.0)_ : The format in which Shlink generates logs. It can be `console` (the default) or `json`.\n\n\n\n> [!IMPORTANT]\n> **Note**\n>\n> When using RoadRunner, Shlink will spin-up one persistent process per web/job worker, which will run and consume memory until Shlink is restarted.\n>\n> With php-fpm, there will be one process per request that's killed once finished. The max amount of concurrent active processes can be configured using [`process.max`](https://www.php.net/manual/en/install.fpm.configuration.php).\n\n\n\n\n### URL shortening {#url-shortening}\n\n\n- `DEFAULT_SHORT_CODES_LENGTH`: The length you want generated short codes to have. It defaults to 5 and has to be at least 4, so any value smaller than that will fall back to 4.\n- `DELETE_SHORT_URL_THRESHOLD`: The amount of visits on short URLs which will not allow them to be deleted. If not provided, this restriction will be disabled.\n- `AUTO_RESOLVE_TITLES`: Used to automatically resolve the short URL's title based on the `<title />` tag in the long URL. Defaults to `true`.\n- `MULTI_SEGMENT_SLUGS_ENABLED`: Allows to create and handle multi-segment custom slugs when `true` is provided. Default value is `false`. See [multi-segment custom slugs](/documentation/some-features/#multi-segment-custom-slugs) for more information.\n- `SHORT_URL_TRAILING_SLASH`: Allows to enable support for trailing slashes in short URLs when `true` is provided. Default value is `false`. See [short URLs trailing slash](/documentation/some-features/#short-urls-trailing-slash) for more information.\n- `SHORT_URL_MODE` _(v3.5.0)_ : `strict` or `loose`. Determines how to match short URLs. Defaults to `strict`. See [short URLs mode](/documentation/some-features/#short-urls-mode) for more information.\n\n\n### Database {#database}\n\n\n- `DB_DRIVER`: **mysql**, **maria**, **postgres**, **mssql** or **sqlite**.\n- `DB_NAME`: The database name to be used when using an external database driver. Defaults to **shlink**.\n- `DB_USER`: The username credential to be used when using an external database driver.\n- `DB_PASSWORD`: The password credential to be used when using an external database driver.\n- `DB_HOST`: The host name of the database server when using an external database driver.\n- `DB_PORT`: The port in which the database service is running when using an external database driver. Default value is based on the value provided for `DB_DRIVER`:\n - **mysql** or **maria** -> `3306`\n - **postgres** -> `5432`\n - **mssql** -> `1433`\n- `DB_UNIX_SOCKET`: Alternatively to the `DB_HOST`, you can provide this to connect through unix sockets when using `mysql`, `maria` or `postgres` drivers.\n- `DB_USE_ENCRYPTION`: Whether it is desired to use an encrypted connection with the database or not. Defaults to `false`.\n\n\n\n> [!WARNING]\n> SQLite is intended for testing/automation purposes only. Using it in production is [not supported](/documentation/supported-db-engines/#sqlite-limitations), even less if mounted via docker volumes.\n>\n> There's a potential risk of breakage when updating Shlink, so make sure you move to any of the other alternatives if you plan to use Shlink long term.\n\n\n\n\n### Redirects {#redirects}\n\n\n- `REDIRECT_STATUS_CODE`: **301**, **302**, **308** or **307** (last two since v3.5.0). Determines the status code that should be used on redirects from short to long URLs. Setting **308** or **307** implicitly makes requests to short URLs work regardless the HTTP method. Defaults to **302**.\n- `REDIRECT_CACHE_LIFETIME`: Allows to set the amount of seconds that redirects should be cached when redirect status is 301 or 308. Default values is 30.\n- `DEFAULT_INVALID_SHORT_URL_REDIRECT`: If a URL is provided here, when a user tries to access an invalid short URL, and the visited domain does not have a redirect URL of its own, he/she will be redirected to this value. If this env var is not provided, the user will see a generic `404 - not found` page.\n- `DEFAULT_REGULAR_404_REDIRECT`: If a URL is provided here, when a user tries to access a URL not matching any supported by the router, and the visited domain does not have a redirect URL of its own, he/she will be redirected to this value. If this env var is not provided, the user will see a generic `404 - not found` page.\n- `DEFAULT_BASE_URL_REDIRECT`: If a URL is provided here, when a user tries to access Shlink's base URL, and the visited domain does not have a redirect URL of its own, he/she will be redirected to this value. If this env var is not provided, the user will see a generic `404 - not found` page.\n- `REDIRECT_EXTRA_PATH_MODE` _(v4.4.0)_ : Determines how Shlink should match short URLs when they start with a known short code. (See [Extra path forwarding](/documentation/some-features/#extra-path-forwarding) for more info).\n - **default** -> Only exact short URLs will match. Extra paths will result in a not-found short URL.\n - **append** -> The rest of the path will be appended to the long URL before redirection.\n - **ignore** -> The rest of the path will be ignored.\n- ~`REDIRECT_APPEND_EXTRA_PATH`~: This is deprecated since Shlink 4.4.0. Use `REDIRECT_EXTRA_PATH_MODE=append` instead.\n\n\n### Visits tracking {#visits-tracking}\n\n\n- `DISABLE_TRACKING`: Tells if visits tracking should be completely disabled. Defaults to `false` (see [Tracking visits](/documentation/tracking-visits/) for more info).\n- `TRACK_ORPHAN_VISITS`: Tells if [orphan visits](/documentation/tracking-visits/#orphan-visits) should be tracked or not. Defaults to `true` (see [Tracking visits](/documentation/tracking-visits/) for more info).\n- `DISABLE_TRACK_PARAM`: The name of a query param that can be used to visit short URLs avoiding the visit to be tracked. This feature won't be available if no value is provided (see [Tracking visits](/documentation/tracking-visits/) for more info).\n- `DISABLE_TRACKING_FROM`: A comma-separated list of IP address patterns from which all tracking should be disabled. It allows providing fixed IP addresses (`100.200.80.40`), CIDR blocks (`192.168.10.0/24`) or wildcard patterns (`11.22.*.*`)\n- `DISABLE_IP_TRACKING`: Tells if tracking of the IP address (and therefore visitors location) should be disabled. Defaults to `false` (see [Tracking visits](/documentation/tracking-visits/) for more info).\n- `DISABLE_REFERRER_TRACKING`: Tells if tracking of the referrer should be disabled. Defaults to `false` (see [Tracking visits](/documentation/tracking-visits/) for more info).\n- `DISABLE_UA_TRACKING`: Tells if tracking of the user agent should be disabled. Defaults to `false` (see [Tracking visits](/documentation/tracking-visits/) for more info).\n- `ANONYMIZE_REMOTE_ADDR`: Tells if IP addresses from visitors should be obfuscated before storing them in the database. Default value is `true` (see [Tracking visits](/documentation/tracking-visits/) for more info).\n \n\n> [!WARNING]\n> Setting this to <b>false</b> will make your Shlink instance no longer be in compliance with the GDPR and other\n> similar data protection regulations.\n\n\n\n\n### Robots.txt {#robotstxt}\n\n\n- `ROBOTS_ALLOW_ALL_SHORT_URLS` _(v4.2.0)_ : Whether all short URLs should be allowed via robots.txt or not. If set to `true`, the `crawlable` option set in individual short URLs will be ignored. Defaults to `false`.\n- `ROBOTS_USER_AGENTS` _(v4.2.0)_ : A comma-separated list of allowed user agents via robots.txt. Defaults to `*`.\n\n\n### Cross-origin {#cross-origin}\n\n\n- `CORS_ALLOW_ORIGIN` _(v4.5.0)_ : Determines for what origins Shlink will allow cross-domain requests. Possible values are:\n - `*`: `Access-Control-Allow-Origin` header is set to `*`, implicitly allowing all origins. This is the **default** value.\n - `<origin>`: `Access-Control-Allow-Origin` header is explicitly set to the value in the request's `Origin` header, allowing all origins, but browsers will apply fewer restrictions than with `*`.\n - A comma-separated list of origins: `Access-Control-Allow-Origin` header is explicitly set to the value in the request's `Origin` header, but only if it is one of the provided values. Otherwise, `Access-Control-Allow-Origin` won't be set at all, restricting requests from any other origin.\n- `CORS_ALLOW_CREDENTIALS` _(v4.5.0)_ : If set to `true`, the response will include `Access-Control-Allow-Credentials: true`, and the header won't be included at all otherwise. Defaults to `false`.\n- `CORS_MAX_AGE` _(v4.5.0)_ : Determines the value in `Access-Control-Max-Age` header. Defaults to 3600.\n\n\n### Real-time updates {#real-time-updates}\n\n\n- `REAL_TIME_UPDATES_TOPICS` _(v4.5.0)_ : A comma-separated list of the topics to which real-time updates should be sent, if at least one real-time updates integration is enabled. All topics are enabled if not provided. Possible values are:\n- `NEW_VISIT`: Notify when any short URL is visited, in a common topic.\n- `NEW_ORPHAN_VISIT`: Notify when a new non-orphan.\n- `NEW_SHORT_URL_VISIT`: Notify when a short URL is visited, on its own scoped topic.\n- `NEW_SHORT_URL`: Notify when a short URL is created.\n\n\n### Redis integration {#redis-integration}\n\n\n- `REDIS_SERVERS`: A comma-separated list of redis servers which Shlink uses for shared locks, cache, and optionally real-time updates through pub/sub (make sure to include the port number and credentials for every server).\n- `REDIS_SENTINEL_SERVICE`: The name of the sentinel service if you want to use redis sentinel. If this value is provided, the servers provided in `REDIS_SERVERS` will be considered sentinel instances.\n- `REDIS_SERVERS_USER` _(v4.6.0)_ : The user credential for redis server/s. Ignored when not using `REDIS_SENTINEL_SERVICE`.\n- `REDIS_SERVERS_PASSWORD` _(v4.6.0)_ : The password credential for redis server/s. Ignored when not using `REDIS_SENTINEL_SERVICE`.\n- `REDIS_PUB_SUB_ENABLED`: Tells if the configured redis instance/cluster should also be used to publish real-time updates via redis pub/sub. Defaults to `false`.\n\n\n### Mercure hub integration {#mercure-hub-integration}\n\n\n- `MERCURE_ENABLED` _(v4.5.0)_ : Whether mercure integration for real-time updates is enabled or not. Defaults to `false`. (Before Shlink 4.5, mercure integration was implicitly enabled just by providing a value for `MERCURE_PUBLIC_HUB_URL`).\n- `MERCURE_PUBLIC_HUB_URL`: The public URL of a mercure hub server to which Shlink will send updates. This URL will also be served to consumers that want to subscribe to those updates.\n- `MERCURE_INTERNAL_HUB_URL`: An internal URL for a mercure hub. Will be used only when publishing updates to mercure, and does not need to be public. If this is not provided but `MERCURE_PUBLIC_HUB_URL` was, the former one will be used to publish updates.\n- `MERCURE_JWT_SECRET`: The secret key that was provided to the mercure hub server, in order to be able to generate valid JWTs for publishing/subscribing to that server.\n\n\n### RabbitMQ integration {#rabbitmq-integration}\n\n\n- `RABBITMQ_ENABLED`: Tells if the integration with a RabbitMQ server for real-time updates should be enabled. Defaults to `false`.\n- `RABBITMQ_HOST`: The RabbitMQ server host name. This will be ignored if `RABBITMQ_ENABLED` is false.\n- `RABBITMQ_USE_SSL`: Whether connection is encrypted with SSL/TLS or not. Defaults to `false`. This will be ignored if `RABBITMQ_ENABLED` is false.\n- `RABBITMQ_PORT`: The RabbitMQ server port. Defaults to `5672`. This will be ignored if `RABBITMQ_ENABLED` is false.\n- `RABBITMQ_USER`: The RabbitMQ server username credential. This will be ignored if `RABBITMQ_ENABLED` is false.\n- `RABBITMQ_PASSWORD`: The RabbitMQ server password credential. This will be ignored if `RABBITMQ_ENABLED` is false.\n- `RABBITMQ_VHOST`: The RabbitMQ server VHost. Defaults to `/`. This will be ignored if `RABBITMQ_ENABLED` is false.\n\n\n### Matomo integration {#matomo-integration}\n\n\n- `MATOMO_ENABLED` _(v3.7.0)_ : Tells if visits should be sent to a Matomo instance. Defaults to `false`.\n- `MATOMO_BASE_URL` _(v3.7.0)_ : The external Matomo server URL. This will be ignored if `MATOMO_ENABLED` is false.\n- `MATOMO_SITE_ID` _(v3.7.0)_ : The site ID to be used for Shlink visits. This will be ignored if `MATOMO_ENABLED` is false.\n- `MATOMO_API_TOKEN` _(v3.7.0)_ : The API token so that Shlink can call Matomo's API. This will be ignored if `MATOMO_ENABLED` is false.\n\n\n### Specific for the docker image {#specific-for-the-docker-image}\n\n\nThese are the env vars that only the docker image take into consideration:\n\n- `PORT`: Can be used to set the port in which Shlink listens. Defaults to 8080 (Some cloud providers, like Google cloud or Heroku, expect to be able to customize exposed port by providing this env var).\n- `WEB_WORKER_NUM`: The amount of concurrent http requests this Shlink instance will be able to serve. Defaults to the amount of available CPUs.\n- `TASK_WORKER_NUM`: The amount of concurrent background tasks this Shlink instance will be able to execute. Defaults to the amount of available CPUs.\n- `SKIP_INITIAL_GEOLITE_DOWNLOAD`: If provided with value `true`, it will skip the initial GeoLite2 db file download, speeding-up the container start-up. As a side effect, first visits on this container will remain un-located until the file finishes downloading in background.\n- `INITIAL_API_KEY` _(v3.6.4)_ : An API key that will be created once during container start-up, with admin permissions.\n \n\n> [!WARNING]\n> **Considerations with the initial API key**\n>\n> * It will be ignored if other API keys already exist. * If the env var is removed at some point, that won't make the\n> API key to be deleted. * If the value is changed at some point, that won't make the API key to be edited. * Between\n> v3.3.0 and v3.6.3 it was possible to pass this env var to any non-docker Shlink instance, but that caused problems.\n> Now only the docker image takes it into consideration. Use the [installation\n> tool](/documentation/command-line-interface/installation-tool/#init) for non-docker installations.\n\n\n\n\n### QR codes {#qr-codes}\n\n\n\n\n> [!WARNING]\n> Starting with Shlink 4.5.0, generating QR codes through Shlink is considered deprecated. See [this\n> issue](https://github.com/shlinkio/shlink/issues/2408) for details.\n\n\n\n- `DEFAULT_QR_CODE_SIZE`: A value between 50 and 1000 to determine the default size of generated QR codes when the `size` query param is not provided. Defaults to 300.\n- `DEFAULT_QR_CODE_MARGIN`: A value greater than 0 to determine the default margin of generated QR codes when the `margin` query param is not provided. Defaults to 0.\n- `DEFAULT_QR_CODE_FORMAT`: One of **png** or **svg**, to determine the default format of generated QR codes when the `format` query param is not provided. Defaults to png.\n- `DEFAULT_QR_CODE_ERROR_CORRECTION`: One of **L** (Low), **M** (Medium), **Q** (Quartile) or **H** (High), to determine the default error correction of generated QR codes when the `errorCorrection` query param is not provided. Defaults to l.\n- `DEFAULT_QR_CODE_ROUND_BLOCK_SIZE`: Tells if the block size should be round on QR codes, making it more readable, but potentially adding some extra margin as a side effect. Defaults to `true`.\n- `QR_CODE_FOR_DISABLED_SHORT_URLS` _(v3.7.2)_ : Whether generating QR codes should work for disabled short URLs. Disabled short URLs are those which reached the maximum amount of visits, have a `validSince` date in the future, or a `validUntil` date in the past. Defaults to `true`.\n- `DEFAULT_QR_CODE_COLOR` _(v4.0.0)_ : The QR code foreground color. Defaults to `#000000` (black).\n- `DEFAULT_QR_CODE_BG_COLOR` _(v4.0.0)_ : The QR code background color. Defaults to `#FFFFFF` (white).\n- `DEFAULT_QR_CODE_LOGO_URL` _(v4.0.0)_ : A URL pointing to a logo that will be placed in the middle of the QR code. This one is experimental, as some images might break the QR code.\n\n\n## Secret env vars {#secret-env-vars}\n\n\nStarting with Shlink 4.0.0, you can pass any environment variable with the `_FILE` suffix. When you do that, Shlink treats its value as a file path, reads that file, and uses its value as the corresponding non-suffixed env var.\n\nFor example, if `DB_PASSWORD` is not set, but `DB_PASSWORD_FILE` is, Shlink will read it, and return its contents as the `DB_PASSWORD` value.\n\nThis is useful when used in combination with [docker compose secrets](https://docs.docker.com/compose/use-secrets/), as it prevents env vars containing secrets to leak their values to any intermediary system.\n\n\n\n> [!IMPORTANT]\n> **Considerations with secret env vars**\n>\n> * The logic to parse secret env vars is generic, so you can use this approach with any existing or future environment\n> variable. * The use of a `_FILE` suffix is a convention used by popular docker images. * If both the suffixed and\n> non-suffixed env vars are provided (for example, `DB_PASSWORD` and `DB_PASSWORD_FILE`), the latter will be ignored.\n\n\n\n\n## Considerations {#considerations}\n\n\nThere are a few things to have in mind.\n\n- Shlink has always supported configuration via environment variables when using the official docker image. However, it only supports env vars for other approaches since v2.9.0\n- Shlink also supports providing configuration options via the so-called [installation tool](/documentation/command-line-interface/installation-tool/). This is an interactive CLI tool that generates some \"hardcoded\" configuration after being executed.\n Before Shlink 3.0.0, this configuration will always take precedence over env vars, so you cannot combine the two of them.\n This limitation is not present starting with Shlink 3.0.0, where environment variables always have precedence.\n", "documentId": "environment-variables", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/environment-variables/", "markdown": "https://sourcey-shlink.pages.dev/documentation/environment-variables/index.md" } ] }, { "id": "long-running-tasks/index.md", "kind": "page", "title": "Long-running tasks", "description": "There are a few tasks Shlink needs to perform which are too heavy or time-consuming to be executed when a user visits a short URL.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/long-running-tasks/", "markdown": "https://sourcey-shlink.pages.dev/documentation/long-running-tasks/index.md", "file": "long-running-tasks/index.md", "searchText": "\n# Long-running tasks {#long-running-tasks}\n\n\nThere are a few tasks Shlink needs to perform which are too heavy or time-consuming to be executed when a user visits a short URL.\n\nIn order to redirect end users as fast as possible to the final URLs, these tasks have been left for you to configure when and how often should they be executed.\n\n\n\n> [!IMPORTANT]\n> **Note**\n>\n> These tasks are not strictly required when serving Shlink with\n> [RoadRunner](/documentation/supported-runtimes/serve-with-roadrunner/), as it has its own background jobs system that\n> Shlink uses to delegate these tasks.\n\n\n\n\n## Download GeoLite2 DB {#download-geolite2-db}\n\n\nThe `visit:download-db` command can be used to make sure your GeoLite2 db is up-to-date.\n\nGeoLite2 DBs do not change that frequently or that much, so you don't need to schedule this one with a very high frequency.\n\n\n## Locate visits {#locate-visits}\n\n\nShlink provides the command `visit:locate`, which will process all the IP addresses from visits in order to locate them. Those that have already been located will be skipped.\n\nShlink locates visits automatically just before redirecting end users. However, it might be a good idea to have previous scheduling in place, as a backup in case it fails.\n\n\n## Using cronjobs {#using-cronjobs}\n\n\nOne way to schedule any of the previous tasks is by making use of Unix cron jobs:\n\n- Locate visits every hour: `0 * * * * /path/to/shlink/bin/cli visit:locate -q -n`\n- Update the GeoLite2 db every 7 days: `0 0 * * 0 /path/to/shlink/bin/cli visit:download-db -q -n`\n\n_The `-q` and `-n` flags are available on any Shlink command. The first one will discard any output, and the second one ensure the command is run in a non-interactive mode._\n", "documentId": "long-running-tasks", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/long-running-tasks/", "markdown": "https://sourcey-shlink.pages.dev/documentation/long-running-tasks/index.md" } ] }, { "id": "advanced/index.md", "kind": "page", "title": "Advanced usage", "description": "At this point you probably have Shlink already up and running. However, there's still some advanced features you might find useful.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/index.md", "file": "advanced/index.md", "searchText": "\n# Advanced usage {#advanced-usage}\n\n\nAt this point you probably have Shlink already up and running. However, there's still some advanced features you might find useful.\n\nHere you will find information that will let you customize Shlink's behavior, and get the most out of it.\n\n\n\n\n\n- [Dynamic redirects](/documentation/advanced/dynamic-rule-based-redirects-system/)\n- [Special redirects](/documentation/advanced/special-redirects/)\n- [Multiple domains](/documentation/advanced/multiple-domains/)\n- [Import short URLs](/documentation/advanced/import-short-urls/)\n- [Real-time updates](/documentation/advanced/real-time-updates/)\n- [Using Redis or Valkey](/documentation/advanced/using-redis-or-valkey/)\n- [Using a reverse proxy](/documentation/advanced/exposing-through-reverse-proxy/)\n- [Send visits to Matomo](/documentation/advanced/send-visits-to-matomo/)\n- [Shlink architecture](/documentation/advanced/shlink-architecture/)\n\n\n\n\n", "documentId": "advanced", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/index.md" } ] }, { "id": "advanced/dynamic-rule-based-redirects-system/index.md", "kind": "page", "title": "Dynamic rule-based redirects system", "description": "Shlink 4.0.0 introduced a new system to dynamically redirect visitors to different long URLs based on runtime conditions.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/dynamic-rule-based-redirects-system/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/dynamic-rule-based-redirects-system/index.md", "file": "advanced/dynamic-rule-based-redirects-system/index.md", "searchText": "\n# Dynamic rule-based redirects system {#dynamic-rule-based-redirects-system}\n\n\nShlink 4.0.0 introduced a new system to dynamically redirect visitors to different long URLs based on runtime conditions.\n\nIt works by allowing you to define any number of rules for a short URL, which are checked sequentially based on their priority, until one matches.\n\nIf a rule matches, the visitor is redirected to that rule's long URL, and only if none match, they are redirected to the default long URL normally.\n\nEvery rule can be composed of any number of conditions, but all of them need to match in order to consider the rule a positive match.\n\n\n## Supported conditions {#supported-conditions}\n\n\nCurrently, Shlink supports the next condition types:\n\n- **Language**: Checks the `Accept-Language` header in order to see if one specific language is accepted.\n- **Query param**: Verifies if the query string contains a specific query param with a specific value.\n- **Any value query param** _(since v4.5.0)_ : Verifies if the query string contains a specific query param with any value or no value at all.\n- **Valueless query param** _(since v4.5.0)_ : Verifies if the query string contains a specific query param with no value at all.\n- **Device**: Tries to match the visitor's device based on the `User-Agent` header. It can match:\n - `Android`\n - `iOS`\n - `Mobile` _(since v4.5.0)_ (matches the two above all at once)\n - `Windows` _(since v4.5.0)_\n - `Linux` _(since v4.5.0)_\n - `MacOS` _(since v4.5.0)_\n - `ChromeOS` _(since v4.5.0)_\n - `Desktop` (matches the four above all at once)\n \n\n> [!IMPORTANT]\n> **Note**\n>\n> Device rules used to be handled separately, but they were migrated to the new rule system for consistency and\n> flexibility.\n\n\n- **IP address** _(since v4.2.0)_ : Allows to dynamically redirect based on the visitor's IP address, via exact match (`100.200.80.40`), CIDR block matching (`192.168.10.0/24`) or wildcard pattern matching (`11.22.*.*`).\n- **Geolocation: country code** _(since v4.3.0)_ : Checks the visitor's [ISO 3166-1 alpha-2 two-letter](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code resolved via geolocation.\n- **Geolocation: city name** _(since v4.3.0)_ : Checks the visitor's city name resolved via geolocation.\n \n\n> [!WARNING]\n> Geolocation-based rules are prone to false positives/negatives (specially by city name), since geolocating a visitor\n> based on their IP address is not perfect.\n\n\n\n\n## Handling redirect rules {#handling-redirect-rules}\n\n\nThere are mainly two ways to manage dynamic redirect rules for a specific short URL:\n\n- The REST API, via [POST /short-urls/[shortCode]/redirect-rules](/documentation/api/#operation-rest-v-version-short-urls-shortcode-redirect-rules-post) endpoint, which expects a body like this:\n ```json\n {\n \"redirectRules\": [\n {\n \"longUrl\": \"https://example.com/android-en-us\",\n \"conditions\": [\n {\n \"type\": \"device\",\n \"matchValue\": \"android\",\n \"matchKey\": null\n },\n {\n \"type\": \"language\",\n \"matchValue\": \"en-US\",\n \"matchKey\": null\n }\n ]\n },\n {\n \"longUrl\": \"https://example.com/fr\",\n \"conditions\": [\n {\n \"type\": \"language\",\n \"matchValue\": \"fr\",\n \"matchKey\": null\n }\n ]\n },\n {\n \"longUrl\": \"https://example.com/query-foo-bar-hello-world\",\n \"conditions\": [\n {\n \"type\": \"query-param\",\n \"matchKey\": \"foo\",\n \"matchValue\": \"bar\"\n },\n {\n \"type\": \"query-param\",\n \"matchKey\": \"hello\",\n \"matchValue\": \"world\"\n }\n ]\n }\n ]\n }\n ```\n- The command line interface, via `short-code:manage-rules` command:\n\n ```shell\n $ shlink short-url:manage-rules rmD8f\n ---------- ------------------- -----------------------------\n Priority Conditions Redirect to\n ---------- ------------------- -----------------------------\n 1 device is android https://example.com/android\n 2 device is desktop https://example.com\n ---------- ------------------- -----------------------------\n\n\n What do you want to do next? [Save and exit]:\n [0] Add new rule\n [1] Remove existing rule\n [2] Re-arrange rule\n [3] Save and exit\n [4] Discard changes\n >\n ```\n\n\n## FAQs {#faqs}\n\n\n- **Can I use the same type of condition more than once in the same rule?**\n\n Yes. Of course, this does not always make sense, like a visitor will never be using an `Android` and `iOS` device at the same time, but you could check for more than one query param, or if more than one language is accepted.\n\n- **Can I make a rule match as soon as some of its conditions match?**\n\n No. In order to match a rule, all its conditions need to positively match. There's no way to configure a partial match.\n\n However, this behavior can be easily mimicked by defining consecutive rules that redirect to the same long URL.\n\n For example, if you want to redirect to `https://example.com/foo` when visitors are (`Android` AND `?foo=bar`) OR (`iOS` AND `?hello=world`), create one rule for the first two conditions, and another rule for the other two, and point both of them to `https://example.com/foo`.\n\n- **How granular is the language condition?**\n\n The Language condition allows for a lot of flexibility, as you can match full locales (in the form of `en_US` or `en-US`) but also language codes.\n\n For example, if you define the rule with value `es-ES` and the header is sent like `Accept-Language: fr-FR, es-ES, en-UK`, it will match positively, however, it won't match `Accept-Language: es`.\n\n On the other hand, if the rule is defined as only `es`, it will match in both cases, as it means \"any Spanish\".\n\n There's one exception. If the `Accept-Language` header is sent with value `*`, it will be ignored and never match, as it would incorrectly match any language otherwise.\n\n Finally, it's worth mentioning language matches are case-insensitive.\n\n- **My geolocation conditions do not work. What is wrong?**\n\n Geolocation conditions will match based on the visitor's geolocation, so you need to make sure a [GeoLite2 license key](/documentation/geolite-license-key/) was provided, and [tracking is not disabled](/documentation/tracking-visits/#disable-tracking).\n\n Additionally, and even if geolocation is working properly, this is known to be error-prone. Sometimes IP addresses cannot be located, or they are located in the wrong city/country.\n\n One way to mitigate incorrect geolocations is to combine geolocation-based rules with language rules: You could configure a rule for users in `ES`, and add another rule for language `es-ES`. If the country didn't properly match as Spain but the visitor's language is Spanish from Spain, you could assume the visitor is in Spain and redirect to the same place.\n", "documentId": "advanced/dynamic-rule-based-redirects-system", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/dynamic-rule-based-redirects-system/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/dynamic-rule-based-redirects-system/index.md" } ] }, { "id": "advanced/special-redirects/index.md", "kind": "page", "title": "Special redirects", "description": "There are some cases in which Shlink can receive \"invalid\" requests. When this happens, the default behavior is to return a 404 status with a \"Not Found\" template.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/special-redirects/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/special-redirects/index.md", "file": "advanced/special-redirects/index.md", "searchText": "\n# Special redirects {#special-redirects}\n\n\nThere are some cases in which Shlink can receive \"invalid\" requests. When this happens, the default behavior is to return a 404 status with a \"Not Found\" template.\n\nHowever, it is possible to configure redirects for some special use cases, known as _special redirects_, _\"not found\" redirects_ or _orphan redirects_:\n\n- `base_url`: Requests to the base URL in which Shlink is being served. The base URL is composed by any of the domains that Shlink can respond to, followed by the base path config option.\n- `invalid_short_url`: Requests to a URL with the shape of a valid short URL, but with a short code or custom slug that doesn't resolve an enabled short URL.\n- `regular_404`: Requests to any other URL that Shlink cannot handle.\n\nEach one of these cases can be configured individually, so you can redirect to different URLs for each one of them, or even configure redirects for some of them and leave the 404 behavior for others.\n\nIn order to configure these redirects you can use [env vars](/documentation/environment-variables/#redirects), or the [installation tool](/documentation/command-line-interface/installation-tool/), which will ask you for those values.\n\n\n## Per-domain redirects {#per-domain-redirects}\n\n\nStarting with v2.8.0, Shlink allows configuring different _special redirects_ for every domain.\n\nIt can be done via CLI, by running the `domain:redirects` command, or using the [`PATCH /domains/redirects`](/documentation/api/#operation-rest-v-version-domains-redirects-patch) REST endpoint.\n\nIf a domain does not have a specific redirect configured for any of the values described above, it will fall back to the general configuration.\n\n\n## Placeholders {#placeholders}\n\n\nWith Shlink v2.9.0 and newer, you can include placeholders in the URLs to redirect to. The placeholders will be replaced with the appropriate values before the redirection occurs.\n\nCurrently, these are the supported placeholders:\n\n- `{DOMAIN}`: It will be replaced with the visited domain.\n- `{ORIGINAL_PATH}`: It will be replaced with the visited path.\n\nWith this, you can generate dynamic redirection URLs looking like this:\n\n- `https://example.com/{ORIGINAL_PATH}`\n- `https://example.com/?domain={DOMAIN}`\n- `https://example.com/?p={ORIGINAL_PATH}&d={DOMAIN}`\n- Etc...\n\n\n\n> [!IMPORTANT]\n> **Note**\n>\n> If you use any of the placeholders as query params (as in <b>https://example.com/?path={'{ORIGINAL_PATH}'}</b>),\n> Shlink will detect it and make sure they are URL-encoded.\n\n\n", "documentId": "advanced/special-redirects", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/special-redirects/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/special-redirects/index.md" } ] }, { "id": "advanced/multiple-domains/index.md", "kind": "page", "title": "Using multiple domains", "description": "While in many cases you will just have one short domain, and you'll want all your short URLs to be served from it, there are some cases in which you may want to have multiple short domains served from the same Shlink instance.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/multiple-domains/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/multiple-domains/index.md", "file": "advanced/multiple-domains/index.md", "searchText": "\n# Using multiple domains {#using-multiple-domains}\n\n\nWhile in many cases you will just have one short domain, and you'll want all your short URLs to be served from it, there are some cases in which you may want to have multiple short domains served from the same Shlink instance.\n\nIf that's the case, you need to understand how Shlink will behave when managing your short URLs or any of them is visited.\n\n\n\n> [!WARNING]\n> **Important!**\n>\n> In this page you will learn how a single Shlink instance behaves when served behind more than one domain.\n>\n> However, it's still <b>up to you</b> to properly configure the DNS and web server, so that all the domains point to\n> the proper \"place\", and the requests end up in Shlink. Shlink will never be able to do this on its own.\n>\n> If you want to learn more about this aspect, go to \n> [External configuration](/documentation/advanced/multiple-domains/#external-configuration).\n\n\n\n\n## Management {#management}\n\n\nWhen you create a short URL (either from the CLI or the REST API), it is possible to optionally provide a `domain` param. If you don't pass it, the short URL will be created for the default domain (the one provided during Shlink's installation or in the `DEFAULT_DOMAIN` env var).\n\nHowever, if you pass it, the short URL will be \"linked\" to that domain.\n\n> Note that, if the default domain is passed here, Shlink will ignore it and will behave as if no `domain` param was provided.\n\nThe main benefit of being able to pass the domain is that Shlink will allow the same custom slug to be used in multiple short URLs, as long as the domain is different (like `example.com/my-compaign`, `another.com/my-compaign` and `foo.com/my-compaign`).\n\nThen, each short URL will be tracked separately and you will be able to define specific tags and metadata for each one of them.\n\nHowever, this has a side effect. When you try to interact with an existing short URL (editing tags, editing meta, resolving it or deleting it), either from the REST API or the CLI, you will have to provide the domain appropriately.\n\nLet's imagine this situation. Shlink's default domain is `example.com`, and you have the next short URLs:\n\n- `https://example.com/abc123`: a regular short URL where no domain was provided.\n- `https://example.com/my-campaign`: a regular short URL where no domain was provided, but it has a custom slug.\n- `https://another.com/my-campaign`: a short URL where the `another.com` domain was provided, and it also has a custom slug.\n- `https://another.com/def456`: a short URL where the `another.com` domain was provided.\n\nThese are some of the results you will get when trying to interact with them, depending on the params you provide:\n\n- Providing just the `abc123` short code: the first URL will be matched.\n- Providing just the `my-campaign` short code: the second URL will be matched, since you did not specify a domain, therefor, Shlink looks for the one with the short code/slug `my-campaign` which is also linked to default domain (or not linked to any domain, to be more precise).\n- Providing the `my-campaign` short code and the `another.com` domain: The third one will be matched.\n- Providing just the `def456` short code: Shlink will fail/not find any short URL, since there's none with the short code `def456` linked to default domain.\n- Providing the `def456` short code and the `another.com` domain: The fourth short URL will be matched.\n- Providing any short code and the `foo.com` domain: Again, no short URL will be found, as there's none linked to `foo.com` domain.\n\n\n## Visits {#visits}\n\n\nBefore adding support for multiple domains, you could point as many domains as you wanted to Shlink, and they would have always worked for existing short codes/slugs.\n\nIn order to keep backwards compatibility, Shlink's behavior when a short URL is visited is slightly different, getting to fallback in some cases.\n\nLet's continue with previous example, and also consider we have three domains that will resolve to our Shlink instance, which are `example.com`, `another.com` and `foo.com`.\n\nWith that in mind, this is how Shlink will behave when the next short URLs are visited:\n\n- `https://another.com/abc123`: There was no short URL specifically defined for domain `another.com` and short code `abc123`, but it exists for default domain (`example.com`), so it will fall back to it and redirect to where `example.com/abc123` is configured to redirect.\n- `https://example.com/def456`: The fall back does not happen from default domain to specific ones, only the other way around (like in previous case). Because of that, this one will result in a not-found URL, even though the `def456` short code exists for `another.com` domain.\n- `https://foo.com/abc123`: This will also fall back to `example.com/abc123`, like in the first case.\n- `https://another.com/non-existing`: The combination of `another.com` domain with the `non-existing` slug does not exist, so Shlink will try to fall back to the same but for default domain (`example.com`). However, since that combination does not exist either, it will result in a not-found URL.\n- Any other short URL visited exactly as it was configured will, of course, resolve as expected.\n\n\n## Special redirects {#special-redirects}\n\n\nStarting with Shlink v2.8.0, it is possible to configure special redirects on a per-domain basis. [Read the docs](/documentation/advanced/special-redirects/#per-domain-redirects) to get more information.\n\n\n## External configuration {#external-configuration}\n\n\nNow that you know how Shlink behaves on a multi-domain context, you also need to perform a couple of extra steps outside Shlink itself.\n\nNot performing these steps will result in requests never reaching Shlink or miss important information.\n\n- **Configure the DNS**: You probably did this for the default domain, and it needs to be done for every extra domain you plan Shlink to handle.\n\n DNS management is different for every provider, but a good way to start is by searching for \"configure DNS\" followed by your DNS provider name on the search engine of your choice.\n\n- **Configure your server's virtual host**: If you are serving Shlink with a classic web server or behind a reverse proxy, you have probably configured you virtual hosts at some point.\n\n Those virtual hosts need to handle all the default and non-default domains. This is how it's done for the most used web servers here:\n\n - Nginx: Use the [`server_name`](https://nginx.org/en/docs/http/server_names.html) followed by all the domains, separated by spaces.\n\n ```\n server_name example.com another.com foo.com\n ```\n - Apache: Use the [`ServerName`](https://httpd.apache.org/docs/2.4/mod/core.html#servername) directive for the main domain, and then add as many [`ServerAlias`](https://httpd.apache.org/docs/2.4/mod/core.html#serveralias) as you need, until you completed all the domains.\n\n ```\n ServerName example.com\n ServerAlias another.com\n ServerAlias foo.com\n ```\n - Caddy: Use the [`bind`](https://caddyserver.com/docs/caddyfile/directives/bind) directive followed by all the domains, separated by spaces.\n\n ```\n bind example.com another.com foo.com\n ```\n\n- **Make sure the domain is passed when using a reverse proxy**: If you don't configure your reverse proxy to pass the domain down, Shlink won't be able what was the actual domain used when visiting a short URL, resulting in 404s or incorrect visits stats.\n\n Because fo that, follow the [Using a reverse proxy](/documentation/advanced/exposing-through-reverse-proxy/) documentation.\n\n In any case, these are the important instructions for the most used web servers:\n\n - Nginx: Use the `proxy_set_header` directive to pass the `Host` header, combined with the `$host` variable.\n\n ```\n proxy_set_header Host $host;\n ```\n - Apache: Set the `ProxyPreserveHost` option to `On`.\n\n ```\n ProxyPreserveHost On\n ```\n - Caddy: Use the `header_up` directive to pass the `Host` header, combined with the `{upstream_hostport}` placeholder.\n\n ```\n header_up Host {upstream_hostport}\n ```\n", "documentId": "advanced/multiple-domains", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/multiple-domains/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/multiple-domains/index.md" } ] }, { "id": "advanced/import-short-urls/index.md", "kind": "page", "title": "Import short URLs", "description": "Since it's quite possible that you are already using some other URL shortener, starting with v2.4.0, it is possible to import short URLs directly into Shlink.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/import-short-urls/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/import-short-urls/index.md", "file": "advanced/import-short-urls/index.md", "searchText": "\n# Import short URLs {#import-short-urls}\n\n\nSince it's quite possible that you are already using some other URL shortener, starting with v2.4.0, it is possible to import short URLs directly into Shlink.\n\nImport is performed from the command line, by running the `short-urls:import` command.\n\nThis command will guide you through the import process, asking you to provide the source from which you want to import, together with all required information for this process to succeed.\n\n```shell\n$ bin/cli short-url:import\n\n What is the source you want to import from:\n [0] bitly\n [1] yourls\n [2] csv\n [3] shlink\n [4] kutt\n >\n```\n\nThe import command can be run as many times as you want, as Shlink is smart enough to not import the same link from the same source more than once, ensuring data consistency.\n\nHowever, there's a couple considerations:\n\n- The process has been optimized as much as possible, trying to avoid memory leaks. However, it is recommended to [reserve at least 512Mb](https://www.php.net/manual/en/ini.core.php#ini.memory-limit) to PHP when running this process.\n- The import process is transactional and all-or-nothing. If there's an uncontrolled error, the import will be rolled-back.\n- In order to determine if a visit has already been imported, Shlink relies on their date, assuming you will usually import on top of an \"empty\" instance. If this is not the case, it could end up ignoring visits that are not actually imported yet, just because they are older than other existing visits.\n\n\n### Supported sources {#supported-sources}\n\n\nThese are the sources from which you can currently import:\n\n- [Bitly](/documentation/advanced/import-short-urls/#bitly) _(since Shlink v2.4.0)_\n- [YOURLS](/documentation/advanced/import-short-urls/#yourls) _(since Shlink v2.10.0)_\n- [Standard CSV](/documentation/advanced/import-short-urls/#standard-csv) _(since Shlink v2.6.0)_\n- [Shlink instance](/documentation/advanced/import-short-urls/#shlink-instance) _(since Shlink v2.7.0)_\n- [Kutt.it](/documentation/advanced/import-short-urls/#kuttit) _(since Shlink v3.1.0)_\n\n\n## Bitly {#bitly}\n\n\nBitly's importing is done through their API. That means that, depending on how many URLs you need to import, you could hit some API limit.\n\nHowever, they allow up to 150 requests per minute for free accounts, and the number is even higher for paid plans.\n\nOn every API call, 50 URLs are imported, which means you won't hit the limit if you have less than 7500 URLs.\n\nIf you hit the limit, shlink will print a \"continue token\" that can be used to skip already imported URLs, and therefore, avoid the limit to be hit again.\n\nWhen you have waited a couple of minutes for the limit to clear, you can run the import command again, but providing the \"continue token\" when requested.\n\nRunning the command will generate an output similar to this:\n\n```shell\n$ bin/cli short-url:import bitly\n\n What is your Bit.ly's API access token? (you can generate one here https://bitly.is/accesstoken):\n > ****************************\n\n Do you want to import short-codes/slugs as they are? Otherwise, new unique short-codes will be generated for every imported URL. (yes/no) [yes]:\n > y\n\n Do you want to import tags? (yes/no) [yes]:\n > y\n\n Do you want to import custom domains? (any domain other than bit.ly) (yes/no) [no]:\n > y\n\n Do you want to keep the original creation date? Otherwise, all imported URLs will have current date as its creation date (yes/no) [yes]:\n > n\n\n Do you want to ignore archived URLs? (yes/no) [no]:\n > n\n\n If you already run this command once and a warning was displayed, you might have been provided with a \"continue token\". If that's the case, paste it here. If this is the first time you run this command, ignore this:\n >\n\nhttps://shlink.io/documentation: Imported\nhttps://docs.mezzio.dev/: Skipped\nhttps://www.example.com/foo/bar: Imported\n```\n\n\n## YOURLS {#yourls}\n\n\nShlink allows importing short URLs, and optionally visits, from a YOURLS instance using its API.\n\nThere's a couple of limitations on imported data, as YOURLS does not store by default visitors IP address or geoloaction.\n\n\n\n> [!WARNING]\n> YOURLS' API does not expose enough actions for Shlink to fetch all data. Because of that, you first need to install\n> the <code class=\"indivisible\">yourls-shlink-import-plugin</code> in YOURLS itself. You can download it from \n> [its repository](https://slnk.to/yourls-import) and follow the instructions there.\n\n\n\nRunning the command will generate an output similar to this:\n\n```shell\n$ bin/cli short-url:import yourls -v\n\n What is your YOURLS instance base URL?:\n > https://s.test\n\n What is your YOURLS instance username?:\n > user\n\n What is your YOURLS instance password?:\n > pass\n\n Do you want to import each short URL's visits too? (yes/no) [yes]:\n > y\n\nhttps://shlink.io: Imported with 381 visits.\nhttps://example.com: Imported with 68 visits.\n```\n\n\n## Standard CSV {#standard-csv}\n\n\nIn order to simplify importing links from arbitrary sources, Shlink supports importing from a simple CSV file.\n\nThe only 2 required columns in the CSV file are `Long URL` and `Short code`, but it also accepts the optional `Title`, `Domain` and `Tags` columns.\n\nThe `Tags` one should contain a list of pipe-separated items, as in `foo|bar|baz`.\n\nThis is an example of a valid CSV file:\n\n```csv\nLong URL,Tags,Domain,Short code,Title\nhttps://shlink.io,foo|bar|baz,,123,\nhttps://example.com,,example.com,456,my title\n```\n\nRunning the command will generate an output similar to this:\n\n```shell\n$ bin/cli short-url:import csv\n\n What's the path for the CSV file you want to import:\n > ./my_links.csv\n\n What's the delimiter used to separate values? [Comma]:\n [,] Comma\n [;] Semicolon\n > ,\n\nhttps://shlink.io: Imported\nhttps://example.com: Imported\n```\n\n\n## Shlink instance {#shlink-instance}\n\n\nIf at some point you need to migrate your Shlink instance, or you want to change the database engine for any reason, this will help you import your short URLs from another Shlink instance.\n\nThe importing will be done by making use of Shlink's built-in REST API. It will import links, their tags and domains, and also their visits if you choose to.\n\nIn order for this to work, you need to keep your old Shlink instance publicly accessible, otherwise you will not be able to import.\n\nRunning the command will generate an output similar to this:\n\n```shell\n$ bin/cli short-url:import shlink\n\n What is your Shlink instance base URL?:\n > https://s.test\n\n What is your Shlink instance API key?:\n > 54d07c90-a45f-11eb-9d0d-0800200c9a66\n\n Do you want to import each short URL's visits too? (yes/no) [yes]:\n > y\n\nhttps://shlink.io: Imported with 381 visits.\nhttps://example.com: Imported with 68 visits.\n```\n\n\n\n> [!IMPORTANT]\n> **Note**\n>\n> Starting with v3.4.0, Shlink also allows to import orphan visits from the original Shlink instance.\n\n\n\n> This importing source is available since Shlink 2.7.0, but it can import from older Shlink versions.\n\n\n## Kutt.it {#kuttit}\n\n\nShlink allows importing short URLs, and optionally visits, from a self-hosted kutt instance, or the SaaS https://kutt.to, using its API.\n\n```shell\n$ bin/cli short-url:import kutt\n\n What is your Kutt.it instance base URL?:\n > https://kutt.to\n\n What is your Kutt.it instance API key?:\n > api_key\n\n Do you want to import URLs created anonymously? (yes/no) [no]:\n >\n\nhttps://shlink.io: Imported with 381 visits.\nhttps://example.com: Imported with 68 visits.\n```\n", "documentId": "advanced/import-short-urls", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/import-short-urls/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/import-short-urls/index.md" } ] }, { "id": "advanced/real-time-updates/index.md", "kind": "page", "title": "Real-time updates", "description": "Once your Shlink instance is set up, you may want to enable real-time updates to notify third parties when certain events occur.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/real-time-updates/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/real-time-updates/index.md", "file": "advanced/real-time-updates/index.md", "searchText": "\n# Real-time updates {#real-time-updates}\n\n\nOnce your Shlink instance is set up, you may want to enable real-time updates to notify third parties when certain events occur.\n\nCurrently, Shlink supports the next technologies to publish updates.\n\n- [Mercure hub](/documentation/advanced/real-time-updates/#mercure-hub-server): allows to subscribe to server-sent events. _(Since v2.2.0)_.\n- [RabbitMQ](/documentation/advanced/real-time-updates/#rabbitmq-server): to publish server-to-server updates _(Since v2.10.0)_.\n- [Redis pub/sub](/documentation/advanced/real-time-updates/#redis-pub-sub): to publish server-to-server updates _(Since v3.2.0)_.\n\n\n\n> [!WARNING]\n> Real-time updates only work with [RoadRunner](/documentation/supported-runtimes/serve-with-roadrunner/), which is the\n> case if you are using the [docker image](/documentation/install-docker-image/).\n\n\n\n\n## Topics and payloads {#topics-and-payloads}\n\n\nRegardless the technology used for publishing and subscribing to updates, the whole list of supported topics, together with their payloads can be found in Shlink's [Async API spec](https://api-spec.shlink.io/async-api) page.\n\n\n## Mercure hub server {#mercure-hub-server}\n\n\nThe best option if you want to get real-time updates on a client-side web app, is by taking advantage of the integration with a [mercure](https://mercure.rocks) hub server.\n\nMercure provides server-sent events, so that consumers can subscribe to topics and get automatically notified when Shlink publishes an update for any of them.\n\n\n### Configure the mercure hub server {#configure-the-mercure-hub-server}\n\n\nThe mercure hub server will act as an intermediary between Shlink, which will publish updates on it, and consumers, which will subscribe to those updates and get notified by the hub.\n\nThe first thing you need to do is [install the mercure hub](https://mercure.rocks/docs/hub/install) server. There's both a prebuilt dependency-less binary, and a docker image, which is the best option to use together with Shlink's docker image.\n\nThen you need to provide some config options to the mercure hub for the integration to properly work:\n\n\n#### For new mercure versions (since 0.11): {#for-new-mercure-versions-since-011}\n\n\n- `SERVER_NAME`: This env var should have the value `\":80\"`, in order to disable https. Just make sure you [serve mercure behind a reverse proxy](https://mercure.rocks/docs/hub/cookbooks#using-nginx-as-an-http-2-reverse-proxy-in-front-of-the-hub), and enable https there.\n- `MERCURE_PUBLISHER_JWT_KEY` and `MERCURE_SUBSCRIBER_JWT_KEY`: The same value provided to Shlink should be used for these two env vars, otherwise, the JWTs generated by Shlink will be rejected by mercure and neither publishing nor subscribing will be possible.\n- `MERCURE_EXTRA_DIRECTIVES`: if you want to consume updates from a browser web app (like shlink-web-client), this option should have the directive `cors_origins` followed by the domain/s from which you plan to consume mercure (for example `cors_origins https://app.shlink.io`), otherwise, it will reject the connection.\n\n\n#### For legacy mercure versions (before 0.11 or using _legacy_ prefix): {#for-legacy-mercure-versions-before-011-or-using-legacy-prefix}\n\n\n- `--jwt-key`|`JWT_KEY`: The same value provided to Shlink should be used here, otherwise, the JWTs generated by Shlink will be rejected by mercure and neither publishing nor subscribing will be possible.\n- `--cors-allowed-origins`|`CORS_ALLOWED_ORIGINS`: if you want to consume updates from a browser web app (like shlink-web-client), this option should have the domain/s from which you plan to consume mercure (for example `\"https://app.shlink.io\"`), otherwise, it will reject the connection.\n\n\n### Interaction between the parts {#interaction-between-the-parts}\n\n\nOnce installed, this is how Shlink, the mercure hub and consumers will interact:\n\n\n\n\n\n```mermaid\nsequenceDiagram\n Shlink->>Consumers: Get mercure URL and JWT\n Consumers-->>Mercure hub: Subscribe to topics\n Shlink->>Mercure hub: Publish updates\n Mercure hub-->>Consumers: Receive updates\n```\n\n\n\n\n\n- Shlink knows Mercure hub's public URL and the JWT secret key.\n- Shlink can generate JWTs for mercure, which only have permission for subscribing.\n- Shlink publishes updates to mercure when something needs to be notified to consumers.\n- Consumers get valid JWTs and the hub URL from Shlink's REST API, by calling the [mercure info endpoint](/documentation/api/#operation-rest-v-version-mercure-info-get).\n- Consumers subscribe to topics on the mercure hub using the JWT returned on previous request.\n- If the JWT expires, consumers can call the endpoint as many times as they need to get new JWTs.\n\nThis flow ensures the JWT key is never leaked by accident, and you need to have a valid Shlink API key in order to get valid JWTs for mercure.\n\nAlso, JWTs returned to consumers will only have permission to subscribe to updates. Only Shlink will be able to publish updates.\n\n\n\n> [!IMPORTANT]\n> **Note**\n>\n> If you use shlink-web-client to interact with your Shlink instance, it will work out of the box and consume updates\n> from mercure, updating the UI in real-time where applicable.\n\n\n\n\n## RabbitMQ server {#rabbitmq-server}\n\n\nStarting with v2.10.0, Shlink supports publishing updates in a [RabbitMQ](https://www.rabbitmq.com/) server, which is a widely used technology for publishing and subscribing to server-to-server updates.\n\n\n### Configure the RabbitMQ server {#configure-the-rabbitmq-server}\n\n\nThe RabbitMQ server will act as an intermediary between Shlink, which will publish updates on it, and consumers, which will subscribe to those updates and get notified in real-time.\n\nThere are several ways to install RabbitMQ. The best option is to follow the [official documentation](https://www.rabbitmq.com/download.html).\n\nOnce the server is configured, you can provide the integration config to Shlink via [installation tool](/documentation/command-line-interface/installation-tool/) or [env vars](/documentation/environment-variables/#rabbitmq-integration).\n\n\n### Exchanges and queues {#exchanges-and-queues}\n\n\nShlink will create an exchange with its corresponding queue, for every operation defined in Shlink's [Async API spec](https://api-spec.shlink.io/async-api/).\n\nThe exchanges and queues are created in a \"durable\" way, with \"direct\" publishing type.\n\n\n## Redis pub/sub {#redis-pubsub}\n\n\nSince Shlink v3.2.0, if you configured a redis server/cluster for caching, Shlink can also use that instance for real-time updates via redis pub/sub.\n\nWhen this happens, the redis server/cluster will act as an intermediary where Shlink publishes the updates, and others can subscribe to them.\n", "documentId": "advanced/real-time-updates", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/real-time-updates/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/real-time-updates/index.md" } ] }, { "id": "advanced/using-redis-or-valkey/index.md", "kind": "page", "title": "Using Redis or Valkey", "description": "Shlink can take advantage of a shared cache server like redis or valkey in multiple contexts.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/using-redis-or-valkey/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/using-redis-or-valkey/index.md", "file": "advanced/using-redis-or-valkey/index.md", "searchText": "\n# Using Redis or Valkey {#using-redis-or-valkey}\n\n\nShlink can take advantage of a shared cache server like [redis](https://redis.io/) or [valkey](https://valkey.io/) in multiple contexts.\n\n- For [caching purposes](#caching-purposes).\n- To store [shared locks](#shared-locks).\n- To publish [real-time updates](/documentation/advanced/real-time-updates/#redis-pubsub) via Pub/Sub.\n\n\n### Caching purposes {#caching-purposes}\n\n\nShlink can persist certain things in a faster storage for quick access.\n\nBy default, it uses APCu if available (when using a [classic web server](/documentation/supported-runtimes/classic-web-server/)) or in-memory (when using [Roadrunner](/documentation/supported-runtimes/serve-with-roadrunner/) as the runtimes), but it can be provided with some shared cache server access configuration.\n\nWhen doing so, Shlink will use it as the cache persistence.\n\n\n### Shared locks {#shared-locks}\n\n\n\n\n> [!IMPORTANT]\n> **Note**\n>\n> **Locks** are used to make sure certain tasks are not run more than once in parallel. For example, geolocating visits.\n\n\n\nIf you plan to run multiple Shlink instances, it's important to make sure the so-called \"locks\" are shared between all of them.\n\nA shared cache server is a good way to do so. If Shlink is provided with access configuration, it will use it to store shared locks.\n\n\n## Supported capabilities {#supported-capabilities}\n\n\nShlink supports multiple shared cache server capabilities. They can be enabled by providing different connection URIs:\n\n- **Single instance** ([Redis](https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack/) / [Valkey](https://valkey.io/topics/installation/)), when providing just one server (for example, `tcp://my_redis_server:6379`).\n- **Cluster** ([Redis](https://redis.io/docs/latest/operate/oss_and_stack/management/scaling/) / [Valkey](https://valkey.io/topics/cluster-tutorial/)), when providing multiple servers (for example, `tcp://one_redis_server:6379,tcp://another_redis_server:6379`).\n- **Sentinels** ([Redis](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/) / [Valkey](https://valkey.io/topics/sentinel/)), when providing multiple servers, together with a sentinel service name.\n- Database selection (since Shlink 4.2.1), by providing the database index in the URI path (for example, `tcp://my_redis_server:6379/5`).\n- Credentials, that can be provided as part of the server URIs (whether they are redis instances or sentinels):\n - ACL, with username and password ([Redis](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl/) / [Valkey](https://valkey.io/topics/acl/)): `tcp://the_username:the_password@my_redis_server:6379`\n - Legacy, with just password ([Redis](https://redis.io/docs/latest/operate/oss_and_stack/management/security/) / [Valkey](https://valkey.io/topics/security/)): `tcp://:the_password@my_redis_server:6379`.\n - Separately via config or env vars, when using sentinels and redis instances have their own auth.\n\n\n## Providing configuration {#providing-configuration}\n\n\nAs with any other configuration params, there are two main ways to provide shared cache server options:\n\n- [Environment variables](/documentation/environment-variables/#redis-integration), which allow you to enable the integration however you like.\n- The [installation tool](/documentation/command-line-interface/installation-tool/), which will, at some point, ask you if you want to integrate with redis, and request you to provide all the capabilities above if so.\n\n ```shell\n [...]\n\n INTEGRATIONS\n ============\n\n Do you want to use a redis instance, redis cluster or redis sentinels as a shared cache for Shlink? (recommended if you run a cluster of Shlink instances) (yes/no) [no]:\n > yes\n\n Provide a comma-separated list of URIs (redis servers/sentinel instances):\n > tcp://one_redis_server:6379,tcp://another_redis_server:6379\n\n Provide the name of the sentinel service (leave empty if not using redis sentinel):\n >\n\n Do you want Shlink to publish real-time updates in this Redis instance/cluster? (yes/no) [no]:\n > yes\n\n [...]\n ```\n", "documentId": "advanced/using-redis-or-valkey", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/using-redis-or-valkey/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/using-redis-or-valkey/index.md" } ] }, { "id": "advanced/exposing-through-reverse-proxy/index.md", "kind": "page", "title": "Exposing Shlink through a reverse proxy", "description": "When you are serving Shlink with RoadRunner or using the docker image, you'll probably want to put a reverse proxy in front of it.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/exposing-through-reverse-proxy/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/exposing-through-reverse-proxy/index.md", "file": "advanced/exposing-through-reverse-proxy/index.md", "searchText": "\n# Exposing Shlink through a reverse proxy {#exposing-shlink-through-a-reverse-proxy}\n\n\nWhen you are serving Shlink with RoadRunner or using the docker image, you'll probably want to put a reverse proxy in front of it.\n\nRoadRunner has some limitations, that can be solved by using a reverse proxy:\n\n- Using a standard HTTP port (80, 443), so that users don't have to explicitly set the port in the URL.\n- Using an `https` certificate to encrypt the connection, keeping your users' data safe.\n\nThe only consideration to ensure all Shlink capabilities work as expected, is that you make sure the consumer's IP address, and the request's domain, are forwarded from the proxy to Shlink.\n\n\n## Configure the proxy {#configure-the-proxy}\n\n\nHere you can find some docs on how to do it with the most used web servers:\n\n- Nginx: https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/\n- Apache: https://httpd.apache.org/docs/trunk/en/howto/reverse_proxy.html\n- Caddy: https://caddyserver.com/docs/quick-starts/reverse-proxy\n\nExample nginx configuration to use as a reverse proxy in front of RoadRunner, with SSL enabled:\n\n```nginx\n// default.conf\nserver {\n listen 443 ssl;\n ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;\n ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;\n\n server_name example.com another.com;\n charset utf-8;\n\n location / {\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n proxy_pass http://localhost:8080;\n proxy_read_timeout 90s;\n }\n}\n```\n", "documentId": "advanced/exposing-through-reverse-proxy", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/exposing-through-reverse-proxy/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/exposing-through-reverse-proxy/index.md" } ] }, { "id": "advanced/send-visits-to-matomo/index.md", "kind": "page", "title": "Send visits to Matomo", "description": "Starting with v3.7.0, Shlink can send every visit to a Matomo instance of your choice.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/send-visits-to-matomo/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/send-visits-to-matomo/index.md", "file": "advanced/send-visits-to-matomo/index.md", "searchText": "\n# Send visits to Matomo {#send-visits-to-matomo}\n\n\nStarting with v3.7.0, Shlink can send every visit to a [Matomo](https://matomo.org/) instance of your choice.\n\nMatomo is an open source Google Analytics alternative, which can be self-hosted or used in the cloud, with a philosophy very much in line with Shlink's.\n\nSending visits to Matomo will enable an alternative UI to check short URL visits, and take advantage of all its analytics capabilities.\n\n\n## Matomo integration FAQ {#matomo-integration-faq}\n\n\nThis is some general information and considerations when integrating Shlink with a Matomo instance:\n\n- When enabled, all visits are sent to Matomo, no matter the runtime used to serve Shlink. When using a runtime that supports background jobs (like [roadrunner](/documentation/supported-runtimes/serve-with-roadrunner/)), it will send the visits asynchronously, with no impact to end visitors. However, if you serve Shlink with a [classic web server](/documentation/supported-runtimes/classic-web-server/), visits will be sent to matomo before redirecting the visitor to the long URL.\n- In order to integrate a matomo instance, you need to provide three configuration options:\n - An instance public URL that can be reached by Shlink.\n - The Site ID (usually a number). You can see how to get this value in [their docs](https://matomo.org/faq/general/faq_19212/).\n - An API token. Their docs explain how to [generate one](https://matomo.org/faq/general/faq_114/).\n- While Matomo supports sending data via `GET` and `POST`, Shlink will always use the latter, making sure data is secure as long as your Matomo instance uses HTTPS.\n- Matomo [tracks unique visits](https://matomo.org/faq/general/faq_36/) in intervals of 30 minutes. Any new visit from the [same visitor](https://matomo.org/faq/general/faq_43) within this interval will be tracked as an action of the same visit. This could make visits tracked by Shlink and Matomo differ.\n- Shlink will send raw IP addresses to Matomo, to let it [geolocate](https://matomo.org/faq/how-to/setting-up-accurate-visitors-geolocation/) them in case something failed in Shlink side. Matomo has [its own mechanism](https://matomo.org/faq/general/configure-privacy-settings-in-matomo/) to anonymize visitor's IP addresses.\n\n\n## Configuring Matomo integration {#configuring-matomo-integration}\n\n\nAs with any other configuration params, there are two main ways to provide matomo integration options:\n\n- [Environment variables](/documentation/environment-variables/#matomo-integration), which allow you to enable the integration however you like.\n- The [installation tool](/documentation/command-line-interface/installation-tool/), which, at some point in the process, will ask you if you want to integrate with matomo, and request you to provide all required options.\n\n ```shell\n [...]\n\n INTEGRATIONS\n ============\n\n Do you want Shlink to send all visits to an external Matomo server? (yes/no) [no]:\n > yes\n\n Matomo server URL:\n > https://my-matomo-server.example.com\n\n Matomo site ID:\n > 3\n\n Matomo API token:\n > 15a010fec36a1f7d07f507ccd9ef1de5\n\n [...]\n ```\n\n\n## Sending existing visits {#sending-existing-visits}\n\n\nIf you have been using Shlink for a while and start using Matomo at a later point in time, you may find yourself with existing visits that do not show in Matomo.\n\nStarting with Shlink 4.1.0, Shlink provides a `integration:matomo:send-visits` command to send existing/old visits to your Matomo instance.\n\nFor example, if you started using Matomo on October 10th, 2023, you can send all visits which are older than that:\n\n```shell\n$ shlink integration:matomo:send-visits --until 2023-10-09\n```\n\n\n\n> [!WARNING]\n> Bear in mind that Shlink will not check if a specific visit already exists in Matomo. All visits matching provided\n> dates will be sent, which could cause duplications.\n\n\n", "documentId": "advanced/send-visits-to-matomo", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/send-visits-to-matomo/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/send-visits-to-matomo/index.md" } ] }, { "id": "advanced/shlink-architecture/index.md", "kind": "page", "title": "Shlink architecture", "description": "While building and evolving Shlink and its ecosystem, some architecture decisions have been made.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/shlink-architecture/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/shlink-architecture/index.md", "file": "advanced/shlink-architecture/index.md", "searchText": "\n# Shlink architecture {#shlink-architecture}\n\n\nWhile building and evolving Shlink and its ecosystem, some architecture decisions have been made.\n\nSome of those decisions are sometimes hard to understand, specially when coming from other services, like Bit.ly or YOURLS. This document explains their benefits and drawbacks.\n\nShlink has been built with **cloud-native environments** in mind, being an **API-first** service that simplifies its integration with other services, and treats any kind of user interface as an external consumer.\n\n\n## Architecture diagram {#architecture-diagram}\n\n\nThis could represent a typical architecture in which Shlink would be integrated.\n\n![Shlink architecture](/images/architecture/shlink-architecture.png)\n\n\n## Benefits {#benefits}\n\n\n- Shlink itself does not need to care about end-user permissions or roles. As an API it just provides capabilities, and you can keep its API unreachable from outside your private network.\n - Any potential end-user permission would be handled by a consumer with its own back-end.\n- Any user interface or consumer app (like [shlink-web-client](/documentation/shlink-web-client/)) can have its own independent release lifecycle.\n - If shlink-web-client covers your needs as a web UI, you can forget about maintaining your own instance and just use https://app.shlink.io\n- It simplifies building a docker image for Shlink, as it has a single responsibility and a single process to serve.\n- It plays nicely with how the different container-based infrastructures (like kubernetes) expect services to behave.\n- It allows to have multiple Shlink instances, if needed, that can be all handled from a centralized dashboard (shlink-web-client supports this out of the box).\n\n\n## Drawbacks {#drawbacks}\n\n\n- This approach might make it harder to deploy Shlink + shlink-web-client on a shared hosting, but that's never been the focus of the project anyway. There are alternatives if that's what you need.\n\n\n## FAQs {#faqs}\n\n\n\n### Why can't I serve Shlink and a UI (like shlink-web-client) from the same domain? {#why-cant-i-serve-shlink-and-a-ui-like-shlink-web-client-from-the-same-domain}\n\n\nAs mentioned above, Shlink itself does not provide a web UI, and it needs external services that provide this capability.\n\nThat means Shlink and the UI are two separated web apps, and therefore, serving them under the same domain is not that straightforward, but you have options:\n\n- Use a sub-path for one of them: Both Shlink and shlink-web-client support being served under a common subpath. You could use something like `/admin` for the web client, or a very short path with low impact (like `/s`) for Shlink.\n- Use subdomains: This is a pretty simple approach, and Shlink supports [CORS](/documentation/api-docs/#cors) out of the box.\n\n\n### Why is Shlink exposing both an API and the short URLs? {#why-is-shlink-exposing-both-an-api-and-the-short-urls}\n\n\nThat's the only grey area. Some time ago, there was [some investigation](https://github.com/shlinkio/shlink/issues/198) about actually splitting Shlink into a pure web service, and a separated app designed just to handle short URLs.\n\nThe idea was discarded, as it would introduce too much complexity for two components which are relatively coupled anyway. This is where the line was drawn.\n\n\n### How can I try Shlink without setting-up the whole pack? {#how-can-i-try-shlink-without-setting-up-the-whole-pack}\n\n\nFor quick tests, you can use the [CLI tool](/documentation/command-line-interface/entry-point/) which is included with Shlink. It provides most of the capabilities and will help you check if Shlink covers your needs and is worth installing anything else.\n", "documentId": "advanced/shlink-architecture", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/advanced/shlink-architecture/", "markdown": "https://sourcey-shlink.pages.dev/documentation/advanced/shlink-architecture/index.md" } ] }, { "id": "command-line-interface/index.md", "kind": "page", "title": "Command Line Interface", "description": "Due to the project's architecture, and the lack of an integrated GUI, Shlink provides a couple of command line tools that can be used to install or update Shlink instances, or even completely manage Shlink as a whole (create short URLs, see visits, manage domains, etc).", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/command-line-interface/", "markdown": "https://sourcey-shlink.pages.dev/documentation/command-line-interface/index.md", "file": "command-line-interface/index.md", "searchText": "\n# Command Line Interface {#command-line-interface}\n\n\nDue to the project's architecture, and the lack of an integrated GUI, Shlink provides a couple of command line tools that can be used to install or update Shlink instances, or even completely manage Shlink as a whole (create short URLs, see visits, manage domains, etc).\n\nTake a look to a more in-depth documentation for each command line tool:\n\n\n\n\n\n- [CLI entry point](/documentation/command-line-interface/entry-point/)\n- [Installation tool](/documentation/command-line-interface/installation-tool/)\n\n\n\n\n", "documentId": "command-line-interface", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/command-line-interface/", "markdown": "https://sourcey-shlink.pages.dev/documentation/command-line-interface/index.md" } ] }, { "id": "command-line-interface/entry-point/index.md", "kind": "page", "title": "CLI Entry point", "description": "Shlink provides a CLI entry point which exposes a set of commands to perform a variety of operations. From creating, updating or listing short URLs, to manage API keys or handle your domains.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/command-line-interface/entry-point/", "markdown": "https://sourcey-shlink.pages.dev/documentation/command-line-interface/entry-point/index.md", "file": "command-line-interface/entry-point/index.md", "searchText": "\n# CLI Entry point {#cli-entry-point}\n\n\nShlink provides a CLI entry point which exposes a set of commands to perform a variety of operations. From creating, updating or listing short URLs, to manage API keys or handle your domains.\n\nYou can treat it as an alternative interface to manage your Shlink instance, that will be available out of the box.\n\nThe entry point is the `bin/cli` script, and you will usually run it as `bin/cli [command] [arguments]`. It is recommended to symlink the `bin/cli` script to a global `shlink` script, so that you can run the CLI from anywhere with `shlink [command] [arguments]`.\n\n\n## Commands {#commands}\n\n\nCommands in Shlink's CLI entry point are contextually namespaced in `api-key`, `domain`, `short-url`, `tag` and `visit`.\n\nBy running the `bin/cli` script with no arguments, you will see the full list of commands with a description for each one of them.\n\nRunning any command with the `-h`/`--help` flag will display an extended help for that specific command, showing the list of arguments, and a descriptive explanation on how to use it.\n\nThis is the full list of commands exposed by Shlink's CLI entry point:\n\n```shell\nUsage:\n command [options] [arguments]\n\nOptions:\n -h, --help Display help for the given command. When no command is given display help for the list command\n --silent Do not output any message\n -q, --quiet Only errors are displayed. All other output is suppressed\n -V, --version Display this application version\n --ansi|--no-ansi Force (or disable --no-ansi) ANSI output\n -n, --no-interaction Do not ask any interactive question\n -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug\n\nAvailable commands:\n completion Dump the shell completion script\n help Display help for a command\n list List commands\n api-key\n api-key:delete Deletes an API key by name\n api-key:disable Disables an API key by name or plain-text key (providing a plain-text key is DEPRECATED)\n api-key:generate Generate a new valid API key.\n api-key:initial Tries to create initial API key\n api-key:list Lists all the available API keys.\n api-key:rename Renames an API key by name\n domain\n domain:list List all domains that have been ever used for some short URL\n domain:redirects Set specific \"not found\" redirects for individual domains.\n domain:visits Returns the list of visits for provided domain.\n integration\n integration:matomo:send-visits Send existing visits to the configured matomo instance\n short-url\n short-url:create Generates a short URL for provided long URL and returns it\n short-url:delete Deletes a short URL\n short-url:delete-expired Deletes all short URLs that are considered expired, because they have a validUntil date in the past\n short-url:edit Edit an existing short URL\n short-url:import Allows to import short URLs from third party sources\n short-url:list List all short URLs\n short-url:manage-rules Set redirect rules for a short URL\n short-url:parse Returns the long URL behind a short code\n short-url:visits Returns the detailed visits information for provided short code\n short-url:visits-delete Deletes visits from a short URL\n tag\n tag:delete Deletes one or more tags.\n tag:list Lists existing tags.\n tag:rename Renames one existing tag.\n tag:visits Returns the list of visits for provided tag.\n visit\n visit:download-db Checks if the GeoLite2 db file is too old or it does not exist, and tries to download an up-to-date copy if so.\n visit:locate Resolves visits origin locations. It implicitly downloads/updates the GeoLite2 db file if needed.\n visit:non-orphan Returns the list of non-orphan visits.\n visit:orphan Returns the list of orphan visits.\n visit:orphan-delete Deletes all orphan visits\n```\n", "documentId": "command-line-interface/entry-point", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/command-line-interface/entry-point/", "markdown": "https://sourcey-shlink.pages.dev/documentation/command-line-interface/entry-point/index.md" } ] }, { "id": "command-line-interface/installation-tool/index.md", "kind": "page", "title": "Installation tool", "description": "Shlink provides a helper CLI installation tool which comes in handy to configure your instance when you are not using Shlink's docker image, and you prefer not to use environment variables.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/command-line-interface/installation-tool/", "markdown": "https://sourcey-shlink.pages.dev/documentation/command-line-interface/installation-tool/index.md", "file": "command-line-interface/installation-tool/index.md", "searchText": "\n# Installation tool {#installation-tool}\n\n\nShlink provides a helper CLI installation tool which comes in handy to configure your instance when you are not using Shlink's docker image, and you prefer not to use [environment variables](/documentation/environment-variables/).\n\nThe tool is executed using the `vendor/bin/shlink-installer` script, and it provides a couple of commands that simplify installing/updating shlink instances, or editing some configuration options.\n\n\n\n> [!WARNING]\n> The installation tool expects to be executed on Shlink's root directory. Running it at a different level will result\n> in an error.\n\n\n\n\n## Commands {#commands}\n\n\nIn order to list all available commands from the installation tool, just run `vendor/bin/shlink-installer` with no arguments:\n\n```shell\nUsage:\n command [options] [arguments]\n\nOptions:\n -h, --help Display help for the given command. When no command is given display help for the list command\n -q, --quiet Do not output any message\n -V, --version Display this application version\n --ansi|--no-ansi Force (or disable --no-ansi) ANSI output\n -n, --no-interaction Do not ask any interactive question\n -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug\n\nAvailable commands:\n completion Dump the shell completion script\n help Display help for a command\n init Initializes external dependencies required for Shlink to properly work, like DB, cache warmup, initial GeoLite DB download, etc\n install Guides you through the installation process, to get Shlink up and running.\n list List commands\n set-option Allows you to set new values for any config option.\n update Helps you import Shlink's config from an older version to a new one.\n```\n\n\n## Main commands {#main-commands}\n\n\nThe installation tool is designed to make a couple of main actions: install Shlink, update an existing instance or update the value from a particular config option.\n\n\n### Install {#install}\n\n\nIn order to install Shlink, run `vendor/bin/shlink-installer install`.\n\nIt will trigger an interactive tool that will guide you through the installation process, asking you questions about all the aspects in Shlink that can be customized.\n\n```shell\nWelcome to Shlink!!\nThis tool will guide you through the installation process.\n\nDATABASE\n========\n\nSelect database type [MySQL]:\n [0] MySQL\n [1] MariaDB\n [2] PostgreSQL\n [3] MicrosoftSQL\n [4] SQLite\n>\n\n[...]\n```\n\nAt the end, it will generate a special config file which will later be consumed by Shlink.\n\n\n### Update {#update}\n\n\nIn order to update Shlink, run `vendor/bin/shlink-installer update`.\n\nThe update process is very similar to the \"install\" one, with the only difference that it will give you the opportunity to consume the config previously generated.\n\nThanks to that, the update tool will make sure to skip all \"questions\" for which it can already infer an answer from the previous config.\n\n```shell\nWelcome to Shlink!!\nThis tool will guide you through the installation process.\n\nDo you want to import configuration from previous installation? (You will still be asked for any new config option that did not exist in previous shlink versions) (yes/no) [yes]:\n> yes\n\nPrevious shlink installation path from which to import config:\n>\n\n[...]\n```\n\nSimilarly to what the \"install\" command did, you will end up with a newly generated config file that containing what was firt imported, plus everything you provided for the new questions.\n\n\n### Set option {#set-option}\n\n\nSometimes you need to change some specific config option, but you don't want to reinstall Shlink completely.\n\nMaybe the database password changed, maybe you want to change your default domain, or maybe you want to disable some tracking option.\n\nIn order to be able to do this, run `vendor/bin/shlink-installer set-option`.\n\nIt will display a list of all the possible options to customize, and you just have to select one and provide the new value.\n\n```shell\nWhat config option do you want to change:\n [1 ] Database > Name\n [2 ] Database > Host (or unix socket for PostgreSQL)\n [3 ] Database > Port\n [4 ] Database > User\n [5 ] Database > Password\n [...]\n [14] GeoLite2 license key\n [...]\n [20] Tracking > Disable tracking\n [21] Tracking > Disable IP address tracking\n [...]\n [28] QR codes > Default size\n [29] QR codes > Default margin\n [...]\n```\n\n> This command has a limitation. It can only be executed on a Shlink install where the `install` command has been successfully executed first.\n\n\n### Init {#init}\n\n\nThis command helps to automate Shlink installation, by \"initializing\" all the external dependencies it needs, like the database, cache warmup, download GeoLite db, etc.\n\nIt can be used both for new Shlink installations, but also to update the external environment on a Shlink instance which is being updated, as it also runs database migrations.\n\nThis command is internally used both by `install` and `update` commands, but comes in handy in case you want to provide Shlink config via [environment variables](/documentation/environment-variables/).\n\nThe official [docker image](/documentation/install-docker-image/) entry point also uses this command, but you don't need to worry in that case.\n\nIt allows a bit of customization via CLI flags, depending on your needs:\n\n```shell\nDescription:\n Initializes external dependencies required for Shlink to properly work, like DB, cache warmup, initial GeoLite DB download, etc\n\nUsage:\n init [options]\n\nOptions:\n --initial-api-key[=INITIAL-API-KEY] Create an initial admin API key. A random one will be generated and printed if no value is provided. [default: false]\n --skip-initialize-db Skip the initial empty database creation. It will make this command fail on a later stage if the database was not created manually.\n --clear-db-cache Clear the database metadata cache.\n --download-rr-binary Download a RoadRunner binary. Useful only if you plan to serve Shlink with Roadrunner.\n --skip-download-geolite Skip downloading the initial GeoLite DB file. Shlink will try to download it the first time it needs to geolocate visits.\n```\n\n- `--initial-api-key`: useful for new Shlink instances, so that it generates a first admin API key.\n- `--skip-initialize-db`: it can be passed when updating Shlink to skip a command which won't have any effect anyway.\n- `--clear-db-cache`: you want to provide this every time you update Shlink, but passing it on new installations won't have any side effect.\n- `--download-rr-binary`: If you are serving/want to [serve Shlink with RoadRunner](/documentation/supported-runtimes/serve-with-roadrunner/), this option will ensure the binary is downloaded.\n- `--skip-download-geolite`: If you are not passing a [GeoLite license key](/documentation/geolite-license-key/), you can pass this to skip a command which won't have any effect anyway.\n\n> This command is available since Shlink 3.6.0\n", "documentId": "command-line-interface/installation-tool", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/command-line-interface/installation-tool/", "markdown": "https://sourcey-shlink.pages.dev/documentation/command-line-interface/installation-tool/index.md" } ] }, { "id": "api-docs/index.md", "kind": "page", "title": "REST API", "description": "Shlink provides a REST API that can be used to integrate the short URLs management on any consuming system or application.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/api-docs/", "markdown": "https://sourcey-shlink.pages.dev/documentation/api-docs/index.md", "file": "api-docs/index.md", "searchText": "Shlink provides a REST API that can be used to integrate the short URLs management on any consuming system or application.\n\nThis document explains the behavior of some aspects and architectural decisions of the API.\n\n\n### Content negotiation {#content-negotiation}\n\n\nAll the requests return JSON-encoded responses by default, together with semantic status codes, so it should be easy to implement client apps that consume this API.\n\nHowever, if an unexpected error occurs, the system could end up returning HTML. To prevent this, always pass the header `Accept: application/json`.\n\n\n### CORS {#cors}\n\n\nThis API supports [**C**ross-**O**rigin **R**esource **S**haring](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) out of the box (aka cross domain).\n\nIt will automatically generate the required `Access-Control-*` headers and manage pre-flight (`OPTIONS`) requests, so it can be transparently consumed from web clients hosted on different domains.\n\nStarting with Shlink v2.5.2, the `Access-Control-Allow-Origin` header will be returned with value `*`. Previous versions used to return the value coming in the request's `Origin` header instead, but some browsers might not accept that value when it's an IP address, therefore the change.\n\n**Important:** notice that Shlink will not generate the CORS headers when the request does not include an `Origin` header, in which case it will consider the request a server-to-server one. Browsers will always send this header when consuming an API on a different domain, so it should work transparently.\n\n\n### Dates {#dates}\n\n\nThe API tries to be consistent on how dates are handled and exchanged, but these are some basic guidelines:\n\n- All returned dates will have the [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) format with offset from UTC (for example, `2020-01-23T05:16:00+02:00`).\n- Any endpoint accepting dates will also expect the same format, usually resulting in `400 Bad Request` response when this is not fulfilled.\n- Shlink also assumes all persisted dates (from visits, short URL creation, etc) belong to the timezone in which Shlink is configured.\n- Any input date will be converted to the timezone in which Shlink is configured, before using it to query data.\n - For example, if Shlink is configured in `America/Los_Angeles`, and the date `2020-01-23T05:16:00+02:00` is provided as part of the input for any endpoint, Shlink will first cast it to `2020-01-22T19:16:00-08:00`.\n\n\n### Request tracing {#request-tracing}\n\n\nShlink generates a request ID on every API request. This ID is returned inside the `X-Request-Id` response header, and can be used to identify all the logs generated by Shlink during that request, as they are all prefixed with this ID.\n\nIf you use Shlink as part of a collection of services and need to be able to trace the whole request flow, you can also send the same `X-Request-Id` header in the request, and Shlink will use that value instead of generating a new one.\n\n\n### Further information {#further-information}\n\n\nContinue reading the rest of the sections to understand more details of the API.\n\n\n\n\n\n- [Authentication](/documentation/api-docs/authentication/)\n- [Error management](/documentation/api-docs/error-management/)\n- [API key roles](/documentation/api-docs/api-key-roles/)\n\n\n\n\n", "documentId": "api-docs", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/api-docs/", "markdown": "https://sourcey-shlink.pages.dev/documentation/api-docs/index.md" } ] }, { "id": "api-docs/authentication/index.md", "kind": "page", "title": "Authentication", "description": "All endpoints require authentication. In order to do it, always provide a X-Api-Key: {api_key} header on every request.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/api-docs/authentication/", "markdown": "https://sourcey-shlink.pages.dev/documentation/api-docs/authentication/index.md", "file": "api-docs/authentication/index.md", "searchText": "\n# Authentication {#authentication}\n\n\nAll endpoints require authentication. In order to do it, always provide a `X-Api-Key: {api_key}` header on every request.\n\n\n## Managing API keys {#managing-api-keys}\n\n\nAPI keys are generated (and managed) from the command line. Run the `api-key:generate` command to get a new and valid API key.\n\n```shell\nshlink api-key:generate --name=my_api_key\n```\n\n\n\n> [!WARNING]\n> Starting with Shlink v4.3, API keys are hashed before being persisted, so it's very important you save them once generated, as you won't be able to get the value afterwards.\n>\n> Providing the name is also a good idea to uniquely identify generated API keys afterwards.\n\n\n\nThis command optionally accepts an expiration date through the `--expiration-date`|`-e` modifier:\n\n```shell\nshlink api-key:generate --expiration-date 2020-01-01\n```\n\nDisabling existing API keys is also possible, through the `api-key:disable` command:\n\n```shell\nshlink api-key:disable my_api_key --by-name\n\n# Disabling via the plain-text key is possible but deprecated\nshlink api-key:disable 1ae89449-f8d2-4b44-baf7-dd7eb0b05017\n```\n\nYou can also rename an existing API key, but remember names have to be unique.\n\n```shell\nshlink api-key:rename my_api_key the_key_for_my_client\n```\n\n\n## Listing API keys {#listing-api-keys}\n\n\nYou can see all existing APi keys by running `shlink api-key:list`.\n\nThe output will allow you to see which API keys are expired or disabled, and what are their names.\n\n```shell\nshlink api-key:list\n\n+--------------------------------------+------------+---------------------------+-------+\n| Name | Is enabled | Expiration date | Roles |\n+--------------------------------------+------------+---------------------------+-------+\n| Disabled | --- | - | Admin |\n+--------------------------------------+------------+---------------------------+-------+\n| my_api_key | +++ | - | Admin |\n+--------------------------------------+------------+---------------------------+-------+\n| d438df20-****-****-****-************ | +++ | 2024-12-05T00:00:00+00:00 | Admin |\n+--------------------------------------+------------+---------------------------+-------+\n```\n\n\n\n> [!IMPORTANT]\n> **Note**\n>\n> Starting with Shlink v4.3, all API keys that are created without a name will fall back to a redacted version of the\n> key.\n\n\n\n\n## API key roles {#api-key-roles}\n\n\nStarting with Shlink v2.5.0, API keys can have a set of roles that will limit the operations they can do. [Read the docs](/documentation/api-docs/api-key-roles/) to learn how.\n\n\n## Errors during authentication {#errors-during-authentication}\n\n\nWhen performing an API call, if no API key is provided, or it is invalid/disabled/expired, the server will return this response payload, with status 401.\n\n```json\n{\n \"type\": \"https://shlink.io/api/error/invalid-api-key\",\n \"detail\": \"Provided API key does not exist or is invalid\",\n \"title\": \"Invalid API key\",\n \"status\": 401\n}\n```\n", "documentId": "api-docs/authentication", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/api-docs/authentication/", "markdown": "https://sourcey-shlink.pages.dev/documentation/api-docs/authentication/index.md" } ] }, { "id": "api-docs/error-management/index.md", "kind": "page", "title": "Error management", "description": "Shlink's REST API implements the Problem Details standard for error management.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/api-docs/error-management/", "markdown": "https://sourcey-shlink.pages.dev/documentation/api-docs/error-management/index.md", "file": "api-docs/error-management/index.md", "searchText": "\n# Error management {#error-management}\n\n\nShlink's REST API implements the [Problem Details](https://tools.ietf.org/html/rfc7807) standard for error management.\n\nBecause of this, all error responses will have `Content-Type: application/problem+json`, and the payload will have at least these properties:\n\n- `type`: A unique error code identifying the error.\n- `detail`: A human-friendly description of the error.\n- `title`: A short unique error title.\n- `status`: The same value returned as the response status code.\n\n```json\n{\n \"type\": \"https://shlink.io/api/error/tag-not-found\",\n \"detail\": \"Tag with name \\\"foo\\\" could not be found\",\n \"title\": \"Tag not found\",\n \"status\": 404\n}\n```\n\nSome errors can have extra properties, depending on their nature.\n\n```json\n{\n \"type\": \"https://shlink.io/api/error/non-unique-slug\",\n \"detail\": \"Provided slug \\\"custom\\\" is already in use\",\n \"title\": \"Invalid custom slug\",\n \"status\": 400,\n \"customSlug\": \"custom\"\n}\n```\n\nError interpretation depends on the context and the endpoint. Every endpoint includes the documentation for its specific errors.\n\nFor more information, read the [API specification](/documentation/api/).\n", "documentId": "api-docs/error-management", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/api-docs/error-management/", "markdown": "https://sourcey-shlink.pages.dev/documentation/api-docs/error-management/index.md" } ] }, { "id": "api-docs/api-key-roles/index.md", "kind": "page", "title": "API key roles", "description": "Starting with v2.5.0, Shlink allows attaching certain roles to API keys, in order to limit the actions they can do.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/api-docs/api-key-roles/", "markdown": "https://sourcey-shlink.pages.dev/documentation/api-docs/api-key-roles/index.md", "file": "api-docs/api-key-roles/index.md", "searchText": "\n# API key roles {#api-key-roles}\n\n\nStarting with v2.5.0, Shlink allows attaching certain roles to API keys, in order to limit the actions they can do.\n\nFor backwards compatibility, all API keys without roles are considered admin API keys and can do everything.\n\n\n## Supported roles {#supported-roles}\n\n\nCurrently, API keys can have any combination of these roles:\n\n- `AUTHORED_SHORT_URLS`: The API key will only be able to interact with short URLs created with it.\n\n This includes not being able to fetch stats or tags that belong to short URLs created with other API keys.\n\n- `DOMAIN_SPECIFIC`: The API key will be able to create and interact with short URLs only under one specific domain.\n\n It will also cause short URLs from other domains to not be counted when fetching visit stats or tags.\n\n- `NO_ORPHAN_VISITS` _(since v3.7.0)_ : Shlink will behave as if orphan visits do not exist when accessed with an API key having this role.\n\n They will always get an empty list when fetching orphan visits, and when trying to delete orphan visits the result will always be `0` with no side effects.\n\n\n## Attaching roles {#attaching-roles}\n\n\nRoles are attached from the command line, while creating the API key with `api-key:generate` command.\n\nThis command accepts flags for every role, allowing to provide any of them at a time.\n\n- `AUTHORED_SHORT_URLS`: Provide the flag `--author-only` (`-a`), which does not accept a value.\n- `DOMAIN_SPECIFIC`: Provide the flag `--domain-only=example.com` (`-d example.com`). This will attach the role for the domain provided as value.\n- `NO_ORPHAN_VISITS`: Provide the flag `--no-orphan-visits` (`-o`), which does not accept a value.\n\n```bash\n$ bin/cli api-key:generate --author-only --domain-only=example.com --no-orphan-visits\n```\n\n\n\n> [!WARNING]\n> Editing roles on existing API keys is not allowed, as it could lead to behavior inconsistencies and security breaches.\n>\n> If you wish to restrict permissions, disable an existing API key and generate a new one.\n\n\n\n\n## Considerations {#considerations}\n\n\nThere are a couple of edge cases and considerations to have in mind when attaching roles to API keys:\n\n- Operations from CLI will always behave as admin. Among other things, this means that:\n - It will not be possible to apply any limitation while listing or interacting with any entity.\n - Created short URLs will not be attached to an API key, and therefore, will not be affected by `AUTHORED_SHORT_URLS` API keys.\n - Imported short URLs will not be attached to an API key either, having the same limitation as in previous point.\n- Custom slugs are globally unique. That means that a conflict error could occur when providing a custom slug that \"seems\" to be available, but it's actually in use by a short URL which is not visible by the API key in use.\n- When creating short URLs with a `DOMAIN_SPECIFIC` API key, they will all be created for that domain implicitly, regardless of the domain provided. Provided one will always be ignored.\n- The `DOMAIN_SPECIFIC` restriction cannot be used for the default domain.\n- For simplicity, editing and deleting tags will not be allowed for non-admin API keys, resulting on a 403 response. The intention is to improve this behavior in future versions.\n", "documentId": "api-docs/api-key-roles", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/api-docs/api-key-roles/", "markdown": "https://sourcey-shlink.pages.dev/documentation/api-docs/api-key-roles/index.md" } ] }, { "id": "shlink-web-client/index.md", "kind": "page", "title": "Shlink web client", "description": "Shlink web client (aka shlink-web-client) is the official Progressive Web Application for Shlink.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/shlink-web-client/", "markdown": "https://sourcey-shlink.pages.dev/documentation/shlink-web-client/index.md", "file": "shlink-web-client/index.md", "searchText": "\n# Shlink web client {#shlink-web-client}\n\n\nShlink web client (aka `shlink-web-client`) is the official Progressive Web Application for Shlink.\n\nIt provides a beautiful UI from which you can handle your short URLs, create new ones or see very detailed and customizable visits stats.\n\nIt is part of the same organization and usually supports all Shlink features, soon after they are released.\n\n\n\n\n\n**Shlink web client**\n\n\n\n**[video/webm](/videos/shlink-web-client.webm)**\n\n\n\n**[video/mp4](/videos/shlink-web-client.mp4)**\n\n\n\n\n\nHere you will find some docs on how to install, customize and use it.\n\n\n\n\n\n- [Installation](/documentation/shlink-web-client/installation/)\n- [Serve in sub path](/documentation/shlink-web-client/serve-in-sub-path/)\n- [Pre-configuring servers](/documentation/shlink-web-client/pre-configuring-servers/)\n\n\n\n\n", "documentId": "shlink-web-client", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/shlink-web-client/", "markdown": "https://sourcey-shlink.pages.dev/documentation/shlink-web-client/index.md" } ] }, { "id": "shlink-web-client/installation/index.md", "kind": "page", "title": "Installation", "description": "There are three ways in which you can use Shlink web client. The Free hosted one does not actually require installation.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/shlink-web-client/installation/", "markdown": "https://sourcey-shlink.pages.dev/documentation/shlink-web-client/installation/index.md", "file": "shlink-web-client/installation/index.md", "searchText": "\n# Installation {#installation}\n\n\nThere are three ways in which you can use Shlink web client. The [Free hosted](/documentation/shlink-web-client/installation/#free-hosted) one does not actually require installation.\n\n\n## Free hosted {#free-hosted}\n\n\nThe easiest way to use shlink-web-client is by just going to https://app.shlink.io/.\n\nThe application runs 100% in the browser, so you can safely access any Shlink server from there.\n\nThe main benefit of this approach is that you will always have the latest version, and you will not have to worry about updates.\n\n\n## Docker image {#docker-image}\n\n\nIf you want to deploy shlink-web-client in a container-based infrastructure (kubernetes, docker swarm, etc), just pick the [shlinkio/shlink-web-client](https://hub.docker.com/r/shlinkio/shlink-web-client/) image from Docker hub, or [ghcr.io/shlinkio/shlink-web-client](https://github.com/shlinkio/shlink-web-client/pkgs/container/shlink-web-client) from GitHub Container Registry.\n\nIt's a lightweight [nginx:alpine](https://hub.docker.com/r/library/nginx/)-based image serving the static app on port 8080.\n\n\n\n> [!IMPORTANT]\n> **Note**\n>\n> Before shlink-web-client 4.0.0, the docker image was serving the app on port 80.\n\n\n\n\n## Self-hosted {#self-hosted}\n\n\nIf you want to self-host it yourself, get the [latest release](https://github.com/shlinkio/shlink-web-client/releases/latest) and download the distributable zip file attached to it (it will like something like this `shlink-web-client_X.X.X_dist.zip`).\n\nThe package contains static files only, so just put it in a folder and serve it with the web server of your choice.\n\n---\n\n**Considerations**:\n\nThese apply for both docker image and self-hosted approaches.\n\n- Provided dist files and docker images are configured to be served from the root of your domain. If you need to serve shlink-web-client from a sub path, you will have to build it yourself by following [these steps](/documentation/shlink-web-client/serve-in-sub-path/).\n- The app has a client-side router that handles dynamic paths. Because of that, you need to configure your web server to fall-back to the `index.html` file when requested files do not exist.\n - If you use Apache, you are covered, since the project includes an `.htaccess` file which already does this.\n - If you use nginx, you can [see how it's done](https://github.com/shlinkio/shlink-web-client/blob/main/config/docker/nginx.conf) for the docker image and do the same.\n", "documentId": "shlink-web-client/installation", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/shlink-web-client/installation/", "markdown": "https://sourcey-shlink.pages.dev/documentation/shlink-web-client/installation/index.md" } ] }, { "id": "shlink-web-client/serve-in-sub-path/index.md", "kind": "page", "title": "Serve in sub path", "description": "Official distributable files and docker images have been built so that they are served from the root of a domain.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/shlink-web-client/serve-in-sub-path/", "markdown": "https://sourcey-shlink.pages.dev/documentation/shlink-web-client/serve-in-sub-path/index.md", "file": "shlink-web-client/serve-in-sub-path/index.md", "searchText": "\n# Serve in sub path {#serve-in-sub-path}\n\n\nOfficial distributable files and docker images have been built so that they are served from the root of a domain.\n\nIf you need to host shlink-web-client yourself and serve it from a subpath, follow these steps:\n\n- Download shlink-web-client source code for the version you want to build.\n - For example, if you want to build `v2.3.1`, use this link https://github.com/shlinkio/shlink-web-client/archive/v2.3.1.zip\n - Replace the `v2.3.1` part in the link with the one of the version you want to build.\n- Decompress the file and `cd` into the resulting folder.\n- Open the `package.json` file in the root of the project, locate the `homepage` property and replace the value (which should be an empty string) by the path from which you want to serve shlink-web-client.\n - For example: `\"homepage\": \"/my-projects/shlink-web-client\"`.\n- Build the project:\n - For classic hosting:\n - Download [node](https://nodejs.org/en/download/package-manager/) 16 or later.\n - Install project dependencies by running `npm install`.\n - Build the project by running `node --run build`.\n - Once the command finishes, you will have a `build` folder with all the static assets you need to run shlink-web-client. Just place them wherever you want them to be served from.\n - For docker image:\n - Download [docker](https://docs.docker.com/install/).\n - Build the docker image by running `docker build . -t shlink-web-client`.\n - Once the command finishes, you will have an image with the name `shlink-web-client`.\n", "documentId": "shlink-web-client/serve-in-sub-path", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/shlink-web-client/serve-in-sub-path/", "markdown": "https://sourcey-shlink.pages.dev/documentation/shlink-web-client/serve-in-sub-path/index.md" } ] }, { "id": "shlink-web-client/pre-configuring-servers/index.md", "kind": "page", "title": "Pre-configuring servers", "description": "The first time you access shlink-web-client from a browser, you will have to configure the list of shlink servers you want to manage, and they will be saved in the local storage.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/shlink-web-client/pre-configuring-servers/", "markdown": "https://sourcey-shlink.pages.dev/documentation/shlink-web-client/pre-configuring-servers/index.md", "file": "shlink-web-client/pre-configuring-servers/index.md", "searchText": "\n# Pre-configuring servers {#pre-configuring-servers}\n\n\n\n\n> [!WARNING]\n> **Be extremely careful when using this feature**\n>\n> Due to shlink-web-client's client-side nature, the file needs to be accessible from the browser.\n> <br />\n>\n> Because of that, make sure you use this only when you self-host shlink-web-client, and you know only trusted people\n> will have access to it.\n> <br />\n>\n> Failing to do this could cause your API keys to be exposed.\n\n\n\nThe first time you access shlink-web-client from a browser, you will have to configure the list of shlink servers you want to manage, and they will be saved in the local storage.\n\nThose servers can be exported and imported in other browsers, but if for some reason you need some servers to be there from the beginning, starting with shlink-web-client 2.1.0, you can provide a `servers.json` file in the project root folder (the same containing the `index.html`, `favicon.ico`, etc) with a structure like this:\n\n```json\n[\n {\n \"name\": \"Main server\",\n \"url\": \"https://s.test\",\n \"apiKey\": \"09c972b7-506b-49f1-a19a-d729e22e599c\",\n \"forwardCredentials\": true // Since v4.4.0\n },\n {\n \"name\": \"Local\",\n \"url\": \"http://localhost:8080\",\n \"apiKey\": \"580d0b42-4dea-419a-96bf-6c876b901451\"\n }\n]\n```\n\n> The list can contain as many servers as you need.\n\n\n\n> [!WARNING]\n> The `forwardCredentials` option will make cookies, TLS client certificates and authentication headers to be forwarded to the Shlink server.\n>\n> Setting it to `true` will make all requests fail if the server sets `Accept-Control-Allow-Origin: *`, which is the default behavior in Shlink older than 4.5.0.\n>\n> If you need this capability, you will need to configure a more restrictive value in your custom proxy, or use Shlink 4.5.0 or newer, which allows further customizations.\n\n\n\nWhen shlink-web-client is loaded, if it detects there are no servers configured yet in current device, it will try to load the `servers.json` file, and populate the local storage with the servers it finds there.\n\nOnce loaded, it will not try to load the file again, so making changes in that file will not have any effect on a device that already loaded the servers.\n\n\n## With the docker image {#with-the-docker-image}\n\n\nIf you are using the shlink-web-client docker image, you can also pre-configure servers in one of these ways:\n\n- Mount the `servers.json` file in a volume inside `/usr/share/nginx/html`, which is the app's document root inside the container.\n\n ```shell\n docker run --name shlink-web-client -p 8000:8080 -v ${PWD}/servers.json:/usr/share/nginx/html/servers.json shlinkio/shlink-web-client\n ```\n\n- Mount a `conf.d` directory, which in turn contains the `servers.json` file, in a volume inside `/usr/share/nginx/html`. _(since shlink-web-client 3.2.0)_.\n\n ```shell\n docker run --name shlink-web-client -p 8000:8080 -v ${PWD}/my-config/:/usr/share/nginx/html/conf.d/ shlinkio/shlink-web-client\n ```\n\n- Provide the config for a default server via env vars. When the container starts up, it will build the `servers.json` file dynamically based on them. _(since shlink-web-client 3.2.0)_.\n\n - `SHLINK_SERVER_URL`: The fully qualified URL for the Shlink server.\n - `SHLINK_SERVER_API_KEY`: The API key.\n - `SHLINK_SERVER_NAME`: The name to be displayed. Defaults to `Shlink` if not provided.\n - `SHLINK_SERVER_FORWARD_CREDENTIALS` _(v4.4.0)_ : Whether credentials should be forwarded (`true`) or not (`false`). Defaults to `false`.\n\n ```shell\n docker run \\\n --name shlink-web-client \\\n -p 8000:8080 \\\n -e SHLINK_SERVER_URL=https://s.test \\\n -e SHLINK_SERVER_API_KEY=6aeb82c6-e275-4538-a747-31f9abfba63c \\\n shlinkio/shlink-web-client\n ```\n", "documentId": "shlink-web-client/pre-configuring-servers", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/shlink-web-client/pre-configuring-servers/", "markdown": "https://sourcey-shlink.pages.dev/documentation/shlink-web-client/pre-configuring-servers/index.md" } ] }, { "id": "integrations/index.md", "kind": "page", "title": "Integrations", "description": "Since Shlink exposes a REST API, it is possible to use it to integrate it with third party services.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/integrations/", "markdown": "https://sourcey-shlink.pages.dev/documentation/integrations/index.md", "file": "integrations/index.md", "searchText": "\n# Integrations {#integrations}\n\n\nSince Shlink exposes a REST API, it is possible to use it to integrate it with third party services.\n\nHere you will find links to official SDKs, official documentation on how to integrate Shlink with some popular apps and links for third party integrations developed by users and Shlink fans.\n\n\n\n\n\n- [Short Menu for Mac](/documentation/integrations/short-menu-mac/)\n- [Short Menu for iOS](/documentation/integrations/short-menu-ios/)\n- [GNOME Shell extension](/documentation/integrations/gnome-shell-extension/)\n- [Microsoft PowerToys Run](/documentation/integrations/microsoft-power-toys-run/)\n- [Shlink iOS shortcut](/documentation/integrations/shlink-ios-shortcut/)\n\n\n\n\n\n> If you are already using Shlink with some service or app that's not listed here, feel free to [let me know](https://github.com/shlinkio/shlink.io/issues/new), and I will add it.\n", "documentId": "integrations", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/integrations/", "markdown": "https://sourcey-shlink.pages.dev/documentation/integrations/index.md" } ] }, { "id": "integrations/short-menu-mac/index.md", "kind": "page", "title": "Short Menu for Mac", "description": "You can download Short Menu for Mac from their official website.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/integrations/short-menu-mac/", "markdown": "https://sourcey-shlink.pages.dev/documentation/integrations/short-menu-mac/index.md", "file": "integrations/short-menu-mac/index.md", "searchText": "\n# Short Menu for Mac {#short-menu-for-mac}\n\n\nYou can download **Short Menu for Mac** from their [official website](https://shortmenu.com/mac/).\n\nIt supports several SaaS URL shorteners out of the box, but you can also configure custom services.\n\nIn order to integrate your Shlink instance with it, open Short Menu, and go to **Preferences**.\n\n![Short Menu for Mac popover](/images/integrations/short-menu-mac-popover.png)\n\nOnce there, you have to select **Custom Services**.\n\n![Short Menu for Mac custom services](/images/integrations/short-menu-mac-custom-services.png)\n\nClick on the **+** button, on the bottom-left corner, in order to configure a new custom service.\n\nOnce there, you have two options:\n\n- Use the regular `POST` endpoint, which supports providing all the configuration options listed in the [API spec](/documentation/api/#operation-rest-v-version-short-urls-post).\n\n![Short Menu for Mac POST shortening](/images/integrations/short-menu-mac-post-shortening.png)\n\n- Use the `GET` endpoint, where the only thing that can be provided is the long URL.\n\n![Short Menu for Mac GET shortening](/images/integrations/short-menu-mac-get-shortening.png)\n\nRegardless the option you choose, you need to replace `{SHORT_DOMAIN}` with the domain in which you are exposing your Shlink instance, and `{API_KEY}`, with your own API key.\n", "documentId": "integrations/short-menu-mac", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/integrations/short-menu-mac/", "markdown": "https://sourcey-shlink.pages.dev/documentation/integrations/short-menu-mac/index.md" } ] }, { "id": "integrations/short-menu-ios/index.md", "kind": "page", "title": "Short Menu for iOS", "description": "You can download Short Menu for iOS from the App Store.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/integrations/short-menu-ios/", "markdown": "https://sourcey-shlink.pages.dev/documentation/integrations/short-menu-ios/index.md", "file": "integrations/short-menu-ios/index.md", "searchText": "\n# Short Menu for iOS {#short-menu-for-ios}\n\n\nYou can download **Short Menu for iOS** from the [App Store](https://apps.apple.com/app/short-menu/id885851937).\n\nIt supports several SaaS URL shorteners out of the box, but you can also configure custom services.\n\nIn order to integrate your Shlink instance with it, open Short Menu, and go to **Settings**, by clicking on the \"gear\" icon, on the top-right corner of the app.\n\n![Short Menu for iOS settings](/images/integrations/short-menu-ios-settings.jpg)\n\nOnce there, you have to select **Custom Services**.\n\n![Short Menu for iOS custom services](/images/integrations/short-menu-ios-custom-services.jpg)\n\nTap on the **+** button, on the top-right corner, in order to configure a new custom service.\n\nOnce there, you have two options:\n\n- Use the regular `POST` endpoint, which supports providing all the configuration options listed in the [API spec](/documentation/api/#operation-rest-v-version-short-urls-post).\n\n![Short Menu for iOS POST shortening](/images/integrations/short-menu-ios-post-shortening.jpg)\n\n- Use the `GET` endpoint, where the only thing that can be provided is the long URL.\n\n![Short Menu for iOS GET shortening](/images/integrations/short-menu-ios-get-shortening.jpg)\n\nRegardless the option you choose, you need to replace `{DOMAIN}` with the domain in which you are exposing your Shlink instance, and `{API_KEY}`, with your own API key.\n\nOnce finished, tap on **Done**, on the top-right corner.\n", "documentId": "integrations/short-menu-ios", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/integrations/short-menu-ios/", "markdown": "https://sourcey-shlink.pages.dev/documentation/integrations/short-menu-ios/index.md" } ] }, { "id": "integrations/gnome-shell-extension/index.md", "kind": "page", "title": "GNOME Shell extension", "description": "You can install the GNOME extension for Shlink from extensions.gnome.org or any Software Center application that supports installing GNOME Shell extensions.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/integrations/gnome-shell-extension/", "markdown": "https://sourcey-shlink.pages.dev/documentation/integrations/gnome-shell-extension/index.md", "file": "integrations/gnome-shell-extension/index.md", "searchText": "\n# GNOME Shell extension {#gnome-shell-extension}\n\n\nYou can install the GNOME extension for Shlink from [extensions.gnome.org](https://extensions.gnome.org/extension/3282/shlink-url-shortener/)\nor any Software Center application that supports installing GNOME Shell extensions.\n\n![Extension Settings](/images/integrations/gnome-shell-extension-settings.png)\n\nUsage is pretty straightforward: Once you've set up your Shlink instance URL and API key in the extension settings,\nyou can copy a URL and press `Ctrl+Super+Q` (or your custom keyboard shortcut) to shorten the URL in clipboard.\nYour desktop will show a notification on success or error.\n", "documentId": "integrations/gnome-shell-extension", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/integrations/gnome-shell-extension/", "markdown": "https://sourcey-shlink.pages.dev/documentation/integrations/gnome-shell-extension/index.md" } ] }, { "id": "integrations/microsoft-power-toys-run/index.md", "kind": "page", "title": "Microsoft PowerToys run", "description": "As described in their website, Microsoft PowerToys run is a quick launcher for Windows power users.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/integrations/microsoft-power-toys-run/", "markdown": "https://sourcey-shlink.pages.dev/documentation/integrations/microsoft-power-toys-run/index.md", "file": "integrations/microsoft-power-toys-run/index.md", "searchText": "\n# Microsoft PowerToys run {#microsoft-powertoys-run}\n\n\nAs described in [their website](https://learn.microsoft.com/en-us/windows/powertoys/run), **Microsoft PowerToys run** is a quick launcher for Windows power users.\n\nYou can add this [third party plugin](https://github.com/inukiwi/PowerToysRun-Shlink) from [inukiwi](https://github.com/inukiwi) to generate short urls using your own Shlink instance.\n\n![Microsoft PowerToys run Shlink plugin](/images/integrations/shlink-power-toys-run.png)\n\nYou can find installation and usage instructions in their [README](https://github.com/inukiwi/PowerToysRun-Shlink?tab=readme-ov-file#powertoys-run-shlink-url-shortener).\n", "documentId": "integrations/microsoft-power-toys-run", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/integrations/microsoft-power-toys-run/", "markdown": "https://sourcey-shlink.pages.dev/documentation/integrations/microsoft-power-toys-run/index.md" } ] }, { "id": "integrations/shlink-ios-shortcut/index.md", "kind": "page", "title": "Shlink iOS shortcut", "description": "Create an iOS shortcut to generate short URLs with your Shlink instance, from ycy-0510.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/integrations/shlink-ios-shortcut/", "markdown": "https://sourcey-shlink.pages.dev/documentation/integrations/shlink-ios-shortcut/index.md", "file": "integrations/shlink-ios-shortcut/index.md", "searchText": "\n# Shlink iOS shortcut {#shlink-ios-shortcut}\n\n\nCreate an iOS shortcut to generate short URLs with your Shlink instance, from [ycy-0510](https://github.com/ycy-0510).\n\n\n## Installation {#installation}\n\n\n1. Using an iOS device, go to https://shlink-shortcut.ycydev.org/, and click on \"Get Shortcut\".\n2. Add the shortcut to your iPhone.\n ![Add shortcut](/images/integrations/ios-shortcut-add-shortcut.png)\n3. Configure your custom domain (make sure you **do not** include a trailing slash).\n ![Set domain](/images/integrations/ios-shortcut-set-domain.png)\n4. Generate an API key and paste it here.\n ![Set API key](/images/integrations/ios-shortcut-set-api-key.png)\n\n\n## Usage {#usage}\n\n\nShare any link from iOS, then tap Short URL in the Share Sheet.\n\n![Generate short URL](/images/integrations/ios-shortcut-generate-url.png)\n\nYou can optionally set a custom slug, or leave it empty to let Shlink generate a random one.\n\n![Custom slug](/images/integrations/ios-shortcut-custom-slug.png)\n\nOnce the short URL has been generated, it will be copied to the clipboard and show a notification.\n\nLong-pressing the notification will display a QR code for the new link.\n\n![QR code](/images/integrations/ios-shortcut-qr-code.png)\n", "documentId": "integrations/shlink-ios-shortcut", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/integrations/shlink-ios-shortcut/", "markdown": "https://sourcey-shlink.pages.dev/documentation/integrations/shlink-ios-shortcut/index.md" } ] }, { "id": "troubleshooting/index.md", "kind": "page", "title": "Troubleshooting", "description": "These are some common issues that people have reported when using Shlink, together with questions that people ask with a higher frequency.", "tab": "", "url": "https://sourcey-shlink.pages.dev/documentation/troubleshooting/", "markdown": "https://sourcey-shlink.pages.dev/documentation/troubleshooting/index.md", "file": "troubleshooting/index.md", "searchText": "\n# Troubleshooting {#troubleshooting}\n\n\nThese are some common issues that people have reported when using Shlink, together with questions that people ask with a higher frequency.\n\n\n## How do I change config options after installing Shlink. {#how-do-i-change-config-options-after-installing-shlink}\n\n\nWhen you install Shlink using the [installation tool](/documentation/command-line-interface/installation-tool/), you will be able to easily provide all the config options.\n\nHowever, sometimes you need to change some of those params later in time.\n\nIn order to do that, you can simply use the `vendor/bin/shlink-installer set-option` script to change the value for any config option.\n\nIf that script fails, it could mean you are using a too old Shlink version. In that case, follow these steps:\n\n- Make a backup of the generated config file (`config/params/generated_config.php`).\n- Open that same file, locate the config option you want to change, and set the new value.\n- Delete the config cache file (`data/cache/app_config.php`). If the file does not exist, skip this step.\n\nThe generated config file is in PHP format, but it's a relatively straightforward options \"map\".\n\nIf you are not sure which option should be changed, feel free to [open an issue](https://github.com/shlinkio/shlink/issues/new?labels=question&template=Question_Support.md) asking for help.\n\nIf Shlink does not work after changing the config, restore the backup you did in first step.\n\n\n## BadMethodCallException: Undefined method 'methodName' {#badmethodcallexception-undefined-method-methodname}\n\n\nIf you have recently updated Shlink, it could include some new code that is not picked due to in-memory caches.\n\nTry restarting `apache`/`nginx`/`php-fpm` services. It should solve the problem.\n\n\n## How to install Shlink on a shared hosting {#how-to-install-shlink-on-a-shared-hosting}\n\n\nFirst, shared hosting is not the main target env for Shlink. The goal of the project is to provide a cloud-native and cloud-friendly solution to self-host a URL shortener.\n\nThere are other projects which play better with shared hosting. Try googling \"self-hosted URL shortener\".\n\nThat said, there are ways to get Shlink working.\n\n- Some shared hosting services provide SSH access to the document root's parent folder. If that's the case, upload Shlink there, and then rename the `public` folder to whatever name your service provider is using for the document root.\n- If you only have access to the document root, upload the project there, and then copy everything inside the `public` folder to the project's root.\n Sadly, this makes all other folders accessible. It's highly recommended that you deny access to them if you shared hosting provider allows it, for example, using `.htaccess` files.\n\nIn any case, you will need to have some kind of shell access in order to run the [installation tool](/documentation/command-line-interface/installation-tool/).\n\n\n## I renamed Shlink's folder, and now nothing works {#i-renamed-shlinks-folder-and-now-nothing-works}\n\n\nShlink does not directly depend on the name of the folder, it's perfectly fine to rename it and continue working.\n\nHowever, Shlink generates a cached config file that resolves absolute paths. That makes file paths defined on it to still point to the old folder name, making Shlink unusable.\n\nThe solution is to just delete that file, `data/cache/app_config.php`. After that, Shlink will regenerate it with the new folder name where needed.\n\n\n## When trying to install or update Shlink, I see \"PHP Parse error: syntax error\" {#when-trying-to-install-or-update-shlink-i-see-php-parse-error-syntax-error}\n\n\nIt's relatively frequent that servers have many PHP versions coexisting, being one of them the default one.\n\nSometimes, you think you are using the latest version required by Shlink, because that's what you see with `phpinfo()` executed on a web request.\n\nHowever, when running the [install](/documentation/command-line-interface/installation-tool/#install) or [update](/documentation/command-line-interface/installation-tool/#update) scripts you see syntax errors.\n\nWhen this happens, it is because you are running an older PHP version from the CLI. Run `php -v` to see the actual version being used.\n\n\n## Shlink cannot be accessed from shlink-web-client or other web clients {#shlink-cannot-be-accessed-from-shlink-web-client-or-other-web-clients}\n\n\nSometimes, after setting up Shlink and verifying it works from the command line, and you can create and visit short URLs, you try to get it configured on a web client like shlink-web-client, only to realize it fails to connect, displaying an error page.\n\nIn most of the cases, this is due to one of these other two issues:\n\n- [Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present](/documentation/troubleshooting/#response-to-preflight-request-doesnt-pass-access-control-check-no-access-control-allow-origin-header-is-present)\n- [I see \"Mixed Content\" errors in the browser's console](/documentation/troubleshooting/#i-see-mixed-content-errors-in-the-browsers-console)\n\nIn order to find out which is the actual root cause, you will have to open the browser's developer console, which will most probably display one of the errors above.\n\nThese are the instructions to open it on the most popular web browsers:\n\n- [Google Chrome](https://developer.chrome.com/docs/devtools/open/#console)\n- [Mozilla Firefox](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools#the_javascript_console)\n- [Microsoft Edge](https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/open/?tabs=cmd-Windows#open-the-console-panel)\n\n\n## Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present {#response-to-preflight-request-doesnt-pass-access-control-check-no-access-control-allow-origin-header-is-present}\n\n\nShlink generates all the CORS headers required to consume it from a web app running on different domains, including `Access-Control-Allow-Origin`.\n\nIt also handles transparently the preflight (`OPTIONS`) requests (See [more info](/documentation/api-docs/#cors) on the topic).\n\nWhen the error above happens when consuming Shlink from shlink-web-client or any other web client running on a different URL, that's because some element in between is dropping the CORS headers or blocking the `OPTIONS` requests.\n\nThe most frequent candidate is some reversed proxy with strict security rules. You need to make sure any reverse proxy in front of your Shlink instance returns transparently all the headers generated by Shlink.\n\nAnother scenario in which this could happen is when accessing Shlink from a web client which was accessed through IP address instead of hostname. This scenario is fixed after Shlink 2.5.2, but could also be the cause when using previous versions.\n\n\n## I see \"Mixed Content\" errors in the browser's console {#i-see-mixed-content-errors-in-the-browsers-console}\n\n\nMany browsers (like Google Chrome on its latest versions) do not allow requests to `http` endpoints from web apps that were served with `https`.\n\nIf you are trying to access a Shlink instance which is served with `http` (no encryption) from the default shlink-web-client at https://app.shlink.io or any other web client which is served with `https`, you will see those errors.\n\nIt is highly recommended that you serve Shlink with `https` to solve this problem, but instead, you can make sure the web client is also served with `http`.\n\n\n## Short URLs work, but I can't consume Shlink from shlink-web-client {#short-urls-work-but-i-cant-consume-shlink-from-shlink-web-client}\n\n\n_See [Shlink cannot be accessed from shlink-web-client or other web clients](/documentation/troubleshooting/#shlink-cannot-be-accessed-from-shlink-web-client-or-other-web-clients)_\n\n\n## URLs on non-default domains result in 404 errors {#urls-on-non-default-domains-result-in-404-errors}\n\n\nIn order to properly resolve short URLs when they use a non-default domain, Shlink needs to know what's the host to which the request was made.\n\nIf you have a reverse proxy in front of Shlink, make sure to forward the hostname in the `Host` header.\n\nFor example when using nginx as a reverse proxy, use the `proxy_set_header Host $host;` instruction.\n\nYou can also get detailed info on how to [expose Shlink through a reverse proxy](/documentation/advanced/exposing-through-reverse-proxy/).\n\n\n## My visits location is always unknown {#my-visits-location-is-always-unknown}\n\n\nThere are two main reasons for the visits to never get located:\n\n- You are serving Shlink with a classic web server (like nginx or apache) and didn't [schedule the task](/documentation/long-running-tasks/#locate-visits) that processes the visits.\n- You didn't provide your own GeoLite2 license key.\n\nWhen the second happens, Shlink falls back to the default license key. The problem is that this key is used by too many people, and the daily download limit is always hit.\n\nUsing your own GeoLite2 license key is currently considered mandatory. Follow [the instructions](/documentation/geolite-license-key/) to get it.\n\n\n## Real-time updates never get triggered {#real-time-updates-never-get-triggered}\n\n\nFirst, real-time updates are only triggered when serving Shlink with RoadRunner (or when using the docker image, which uses RoadRunner internally), and they will never work if you serve it with a classic web server.\n\nSecond, real-time updates are triggered after a visit has been located. Because of this, the issue described in previous point can also result in the updates never getting triggered.\n\nFor example, if you do not provide your own GeoLite2 license key and the default one already reached the limit, you will never get your first GeoLite2 db file, never being able to locate visits, and finally, never getting the real-time updates triggered.\n\nFollow [the instructions](/documentation/geolite-license-key/) to provide your own GeoLite2 license key.\n\n\n## What are the minimum grants required for the database user when using MySQL/Mariadb {#what-are-the-minimum-grants-required-for-the-database-user-when-using-mysqlmariadb}\n\n\nThe database user you provide to Shlink will need to have at least these grants: `ALTER`, `CREATE`, `DROP`, `INDEX`, `LOCK TABLES`, `REFERENCES`, `SELECT`, `INSERT`, `DELETE` and `UPDATE`.\n\n\n## How to keep data on docker image between container recreations {#how-to-keep-data-on-docker-image-between-container-recreations}\n\n\nShlink's docker image comes with a SQLite database inside it. This database is intended just for testing and experimentation purposes.\n\nAs soon as you plan to use Shlink in production, you should always use an [external database](/documentation/install-docker-image/#use-an-external-db), as that's the only way to ensure you will not loose any data if the container gets killed.\n\nSome people have tried to mount the SQLite database file in a volume, but that is not possible [see this comment](https://github.com/shlinkio/shlink-docker-image/issues/40#issuecomment-491924262) to understand why.\n\n\n## Shlink's docker image does not listen to 443/https traffic {#shlinks-docker-image-does-not-listen-to-443https-traffic}\n\n\nYes, that's right. Handling the https certificate is out of Shlink's scope.\n\nThe recommendation is to put a reverse proxy that provides this capability in front of Shlink.\n\nFollow these instructions in order to know how to [expose Shlink through a reverse proxy](/documentation/advanced/exposing-through-reverse-proxy/).\n\n\n## Troubleshoot errors when booting-up the docker image {#troubleshoot-errors-when-booting-up-the-docker-image}\n\n\nSometimes, when running Shlink's docker image, the container may fail to boot-up, without a clear or obvious reason.\n\nA good way to troubleshoot this is by providing the env var `SHELL_VERBOSITY=3`, that will increase verbosity of the image's entry point.\n\n\n## Subscription from shlink-web-client to mercure fails with \"Response to preflight request doesn't pass access control check\" {#subscription-from-shlink-web-client-to-mercure-fails-with-response-to-preflight-request-doesnt-pass-access-control-check}\n\n\nIf you are serving your mercure instance on a host different from the one where you serve shlink-web-client (which is most probably the case), you need to ensure mercure allows the client's host.\n\nFor mercure older than v0.11, that's done via the `CORS_ALLOWED_ORIGINS` env var, which can have the `\"*\"` value, or the explicit domain of your web client.\n\nFor mercure v0.11 or newer, you need to pass the `MERCURE_EXTRA_DIRECTIVES` env var, with value `cors_origins https://my-web-client.com`. This versions no longer allows the `\"*\"` value.\n\n\n## Error writing to config/params/generated_config.php during installation {#error-writing-to-configparamsgenerated_configphp-during-installation}\n\n\nShlink's [installation tool](/documentation/command-line-interface/installation-tool/) does a couple of things. One of them is writing a config file with provided options.\n\nA common mistake is running the installation tool from the wrong directory, which results on the generated config file's path not being found, which triggers an error like this:\n\n`Error writing to \"config/params/generated_config.php\": file_put_contents(config/params/generated_config.php): Failed to open stream: No such file or directory`.\n\nIn order to solve this, make sure the working directory when running the installation tool, is always Shlink's root folder.\n", "documentId": "troubleshooting", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/troubleshooting/", "markdown": "https://sourcey-shlink.pages.dev/documentation/troubleshooting/index.md" } ] }, { "id": "api/index.md", "kind": "page", "title": "Shlink REST API", "description": "Shlink, the self-hosted URL shortener", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/index.md", "file": "api/index.md", "searchText": "info title Shlink REST API summary version 3.0 description Shlink, the self-hosted URL shortener termsOfService contact license logo servers 0 url {scheme}://{host} description variables scheme default https description enum 0 https 1 http host default s.test description enum tags 0 name Short URLs summary description Operations that can be performed on short URLs externalDocs 1 name Redirect rules summary description Handle dynamic rule-based redirects externalDocs 2 name Tags summary description Let you handle the list of available tags externalDocs 3 name Visits summary description Operations to manage visits on short URLs externalDocs 4 name Domains summary description Operations to manage domains used on short URLs externalDocs 5 name Integrations summary description Handle services with which shlink is integrated externalDocs 6 name Monitoring summary description Public endpoints designed to monitor the service externalDocs 7 name URL Shortener summary description Non-rest endpoints, used to be publicly exposed externalDocs securitySchemes ApiKey type apiKey name X-Api-Key description A valid shlink API key in header scheme bearerFormat flows openIdConnectUrl oauth2MetadataUrl deprecated ", "documentId": "introduction", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/index.md" } ] }, { "id": "api/operations/operation-rest-v-version-short-urls-get.md", "kind": "operation", "title": "List short URLs", "description": "Returns the list of short URLs.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-get.md", "file": "api/operations/operation-rest-v-version-short-urls-get.md", "searchText": "operationId listShortUrls summary List short URLs description Returns the list of short URLs. method get path /rest/v{version}/short-urls tags 0 Short URLs parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 1 name page in query description The page to be displayed. Defaults to 1 required deprecated style explode allowReserved schema name type integer format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 2 name itemsPerPage in query description The amount of items to return on every page. Defaults to 10 required deprecated style explode allowReserved schema name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 3 name searchTerm in query description A query used to filter results by searching for it on the longUrl and shortCode fields. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 4 name tags[] in query description A list of tags used to filter the result set. Only short URLs **with** these tags will be returned. required deprecated style explode allowReserved schema name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 5 name tagsMode in query description Tells how the filtering by `tags` should work, returning short URLs containing \"any\" of the tags, or \"all\" the tags. Defaults to \"any\".<br />It's ignored if `tags` is not provided. required deprecated style explode allowReserved schema name type string format title description default enum 0 any 1 all enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 6 name excludeTags[] in query description A list of tags used to filter the result set. Only short URLs **without** these tags will be returned. required deprecated style explode allowReserved schema name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 7 name excludeTagsMode in query description Tells how the filtering by `excludeTags` should work, returning short URLs not containing \"any\" of the tags, or not containing \"all\" the tags. Defaults to \"any\".<br />It's ignored if `excludeTags` is not provided. required deprecated style explode allowReserved schema name type string format title description default enum 0 any 1 all enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 8 name orderBy in query description The field from which you want to order the result. required deprecated style explode allowReserved schema name type string format title description default enum 0 longUrl-ASC 1 longUrl-DESC 2 shortCode-ASC 3 shortCode-DESC 4 dateCreated-ASC 5 dateCreated-DESC 6 title-ASC 7 title-DESC 8 visits-ASC 9 visits-DESC 10 nonBotVisits-ASC 11 nonBotVisits-DESC enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 9 name startDate in query description The date (in ISO-8601 format) from which we want to get short URLs. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 10 name endDate in query description The date (in ISO-8601 format) until which we want to get short URLs. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 11 name excludeMaxVisitsReached in query description If true, short URLs which already reached their maximum amount of visits will be excluded. required deprecated style explode allowReserved schema name type string format title description default enum 0 true 1 false enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 12 name excludePastValidUntil in query description If true, short URLs which validUntil date is on the past will be excluded. required deprecated style explode allowReserved schema name type string format title description default enum 0 true 1 false enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 13 name domain in query description Get short URLs for this particular domain only. Use **DEFAULT** keyword for default domain. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 14 name apiKeyName in query description Only get short URLs created with this API key.<br />This value is **ignored** if the request is performed with a non-admin API key that does not match this name. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description The list of short URLs content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties shortUrls name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties data name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties shortCode name type string format title description The short code for this short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName shortUrl name type string format title description The short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName longUrl name type string format title description The original long URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName dateCreated name type string format date-time title description The date in which the short URL was created in ISO format. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName visitsSummary name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties total name type integer format title description The total amount of visits. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName nonBots name type integer format title description The amount of visits which were not identified as bots. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName bots name type integer format title description The amount of visits that were identified as potential bots. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 total 1 nonBots 2 bots tags name type array format title description A list of tags applied to this short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName meta name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties validSince name type string format title description The date (in ISO-8601 format) from which this short code will be valid default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName validUntil name type string format title description The date (in ISO-8601 format) until which this short code will be valid default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName maxVisits name type number format title description The maximum number of allowed visits for this short code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 validSince 1 validUntil 2 maxVisits domain name type string format title description The domain in which the short URL was created. Null if it belongs to default domain. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A descriptive title of the short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName crawlable name type boolean format title description Tells if this URL will be included as 'Allow' in Shlink's robots.txt. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName forwardQuery name type boolean format title description Tells if this URL will forward the query params to the long URL when visited, as explained in [the docs](https://shlink.io/documentation/some-features/#query-params-forwarding). default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName hasRedirectRules name type boolean format title description Whether this short URL has redirect rules attached to it or not. Use [this endpoint](/documentation/api/#operation-rest-v-version-short-urls-shortcode-redirect-rules-get) to get the actual list of rules. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 shortCode 1 shortUrl 2 longUrl 3 dateCreated 4 visitsSummary 5 tags 6 meta 7 domain 8 title 9 crawlable 10 forwardQuery 11 hasRedirectRules pagination name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties currentPage name type integer format title description The number of current page. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName pagesCount name type integer format title description The total number of pages that can be obtained. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName itemsPerPage name type integer format title description The number of items for every page. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName itemsInCurrentPage name type integer format title description The number of items in current page (could be smaller than itemsPerPage). default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName totalItems name type integer format title description The total number of items among all pages. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example shortUrls data 0 shortCode 12C18 shortUrl https://s.test/12C18 longUrl https://store.steampowered.com dateCreated 2016-08-21T20:34:16+02:00 visitsSummary total 328 nonBots 328 bots 0 tags 0 games 1 tech meta validSince 2017-01-21T00:00:00+02:00 validUntil maxVisits 100 domain title Welcome to Steam crawlable forwardQuery hasRedirectRules 1 shortCode 12Kb3 shortUrl https://s.test/12Kb3 longUrl https://shlink.io dateCreated 2016-05-01T20:34:16+02:00 visitsSummary total 1029 nonBots 900 bots 129 tags 0 shlink meta validSince validUntil maxVisits domain title crawlable forwardQuery hasRedirectRules 2 shortCode 123bA shortUrl https://example.com/123bA longUrl https://www.google.com dateCreated 2015-10-01T20:34:16+02:00 visitsSummary total 25 nonBots 0 bots 25 tags meta validSince 2017-01-21T00:00:00+02:00 validUntil maxVisits domain example.com title crawlable forwardQuery hasRedirectRules pagination currentPage 5 pagesCount 12 itemsPerPage 10 itemsInCurrentPage 10 totalItems 115 examples encoding prefixEncoding itemEncoding headers links 1 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /rest/v{version}/short-urls", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-get.md" } ] }, { "id": "api/operations/operation-rest-v-version-short-urls-post.md", "kind": "operation", "title": "Create short URL", "description": "Creates a new short URL. Param findIfExists: This new param allows to force shlink to return existing short URLs when found based on provided params, instead of creating a new one. However, it might add complexity and have unexpected outputs.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-post", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-post.md", "file": "api/operations/operation-rest-v-version-short-urls-post.md", "searchText": "operationId createShortUrl summary Create short URL description Creates a new short URL.<br></br>**Param findIfExists**: This new param allows to force shlink to return existing short URLs when found based on provided params, instead of creating a new one. However, it might add complexity and have unexpected outputs.\n\nThese are the use cases:\n* Only the long URL is provided: It will return the newest match or create a new short URL if none is found.\n* Long url and custom slug are provided: It will return the short URL when both params match, return an error when the slug is in use for another long URL, or create a new short URL otherwise.\n* Any of the above but including other params (tags, validSince, validUntil, maxVisits): It will behave the same as the previous two cases, but it will try to exactly match existing results using all the params. If any of them does not match, it will try to create a new short URL. method post path /rest/v{version}/short-urls tags 0 Short URLs parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody description Request body. required content application/json schema name type format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName allOf 0 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties longUrl name type string format title description The long URL this short URL will redirect to default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName validSince name type string format title description The date (in ISO-8601 format) from which this short code will be valid default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName validUntil name type string format title description The date (in ISO-8601 format) until which this short code will be valid default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName maxVisits name type number format title description The maximum number of allowed visits for this short code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName tags name type array format title description The list of tags to set to the short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A descriptive title of the short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName crawlable name type boolean format title description Tells if this URL will be included as 'Allow' in Shlink's robots.txt. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName forwardQuery name type boolean format title description Tells if the query params should be forwarded from the short URL to the long one, as explained in [the docs](https://shlink.io/documentation/some-features/#query-params-forwarding). default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName 1 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties customSlug name type string format title description A unique custom slug to be used instead of the generated short code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName pathPrefix name type string format title description A prefix that will be prepended to provided custom slug or auto-generated short code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName findIfExists name type boolean format title description Will force existing matching URL to be returned if found, instead of creating a new one default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName domain name type string format title description The domain to which the short URL will be attached default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName shortCodeLength name type number format title description The length for generated short code. It has to be at least 4 and defaults to 5. It will be ignored when customSlug is provided default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 longUrl example examples encoding prefixEncoding itemEncoding responses 0 statusCode 200 summary description The result of parsing the long URL content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties shortCode name type string format title description The short code for this short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName shortUrl name type string format title description The short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName longUrl name type string format title description The original long URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName dateCreated name type string format date-time title description The date in which the short URL was created in ISO format. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName visitsSummary name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties total name type integer format title description The total amount of visits. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName nonBots name type integer format title description The amount of visits which were not identified as bots. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName bots name type integer format title description The amount of visits that were identified as potential bots. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 total 1 nonBots 2 bots tags name type array format title description A list of tags applied to this short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName meta name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties validSince name type string format title description The date (in ISO-8601 format) from which this short code will be valid default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName validUntil name type string format title description The date (in ISO-8601 format) until which this short code will be valid default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName maxVisits name type number format title description The maximum number of allowed visits for this short code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 validSince 1 validUntil 2 maxVisits domain name type string format title description The domain in which the short URL was created. Null if it belongs to default domain. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A descriptive title of the short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName crawlable name type boolean format title description Tells if this URL will be included as 'Allow' in Shlink's robots.txt. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName forwardQuery name type boolean format title description Tells if this URL will forward the query params to the long URL when visited, as explained in [the docs](https://shlink.io/documentation/some-features/#query-params-forwarding). default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName hasRedirectRules name type boolean format title description Whether this short URL has redirect rules attached to it or not. Use [this endpoint](/documentation/api/#operation-rest-v-version-short-urls-shortcode-redirect-rules-get) to get the actual list of rules. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 shortCode 1 shortUrl 2 longUrl 3 dateCreated 4 visitsSummary 5 tags 6 meta 7 domain 8 title 9 crawlable 10 forwardQuery 11 hasRedirectRules example shortCode 12C18 shortUrl https://s.test/12C18 longUrl https://store.steampowered.com dateCreated 2016-08-21T20:34:16+02:00 visitsSummary total 0 nonBots 0 bots 0 tags 0 games 1 tech meta validSince 2017-01-21T00:00:00+02:00 validUntil maxVisits 500 domain title crawlable forwardQuery hasRedirectRules examples encoding prefixEncoding itemEncoding headers links 1 statusCode 400 summary description Some of provided data is invalid. Check extra fields to know exactly what. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName allOf 0 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status 1 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties invalidElements name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type string format title description default enum 0 validSince 1 validUntil 2 customSlug 3 pathPrefix 4 maxVisits 5 findIfExists 6 domain enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName customSlug name type string format title description Provided custom slug when the error type is https://shlink.io/api/error/non-unique-slug default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName domain name type string format title description The domain for which you were trying to create the new short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example examples Invalid arguments summary description value title Invalid data type https://shlink.io/api/error/invalid-data detail Provided data is not valid status 400 invalidElements 0 maxVisits 1 validSince externalValue Non-unique slug summary description value title Invalid custom slug type https://shlink.io/api/error/non-unique-slug detail Provided slug \"my-slug\" is already in use. status 400 customSlug my-slug externalValue encoding prefixEncoding itemEncoding headers links 2 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "POST /rest/v{version}/short-urls", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-post", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-post.md" } ] }, { "id": "api/operations/operation-rest-v-version-short-urls-shorten-get.md", "kind": "operation", "title": "Create a short URL", "description": "[Deprecated] Use Create short URL instead", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-shorten-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-shorten-get.md", "file": "api/operations/operation-rest-v-version-short-urls-shorten-get.md", "searchText": "operationId shortenUrl summary Create a short URL description **[Deprecated]** Use [Create short URL](/documentation/api/#operation-rest-v-version-short-urls-post) instead method get path /rest/v{version}/short-urls/shorten tags 0 Short URLs parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 1 name apiKey in query description The API key used to authenticate the request required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 2 name longUrl in query description The URL to be shortened required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 3 name format in query description The format in which you want the response to be returned. You can also use the \"Accept\" header instead of this required deprecated style explode allowReserved schema name type string format title description default enum 0 txt 1 json enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description The list of short URLs content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties shortCode name type string format title description The short code for this short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName shortUrl name type string format title description The short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName longUrl name type string format title description The original long URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName dateCreated name type string format date-time title description The date in which the short URL was created in ISO format. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName visitsSummary name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties total name type integer format title description The total amount of visits. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName nonBots name type integer format title description The amount of visits which were not identified as bots. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName bots name type integer format title description The amount of visits that were identified as potential bots. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 total 1 nonBots 2 bots tags name type array format title description A list of tags applied to this short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName meta name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties validSince name type string format title description The date (in ISO-8601 format) from which this short code will be valid default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName validUntil name type string format title description The date (in ISO-8601 format) until which this short code will be valid default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName maxVisits name type number format title description The maximum number of allowed visits for this short code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 validSince 1 validUntil 2 maxVisits domain name type string format title description The domain in which the short URL was created. Null if it belongs to default domain. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A descriptive title of the short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName crawlable name type boolean format title description Tells if this URL will be included as 'Allow' in Shlink's robots.txt. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName forwardQuery name type boolean format title description Tells if this URL will forward the query params to the long URL when visited, as explained in [the docs](https://shlink.io/documentation/some-features/#query-params-forwarding). default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName hasRedirectRules name type boolean format title description Whether this short URL has redirect rules attached to it or not. Use [this endpoint](/documentation/api/#operation-rest-v-version-short-urls-shortcode-redirect-rules-get) to get the actual list of rules. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 shortCode 1 shortUrl 2 longUrl 3 dateCreated 4 visitsSummary 5 tags 6 meta 7 domain 8 title 9 crawlable 10 forwardQuery 11 hasRedirectRules example longUrl https://github.com/shlinkio/shlink shortUrl https://s.test/abc123 shortCode abc123 dateCreated 2016-08-21T20:34:16+02:00 visitsSummary total 0 nonBots 0 bots 0 tags 0 games 1 tech meta validSince 2017-01-21T00:00:00+02:00 validUntil maxVisits 100 domain title crawlable forwardQuery hasRedirectRules examples encoding prefixEncoding itemEncoding text/plain schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example https://s.test/abc123 examples encoding prefixEncoding itemEncoding headers links 1 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding text/plain schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example examples encoding prefixEncoding itemEncoding headers links security deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /rest/v{version}/short-urls/shorten", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-shorten-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-shorten-get.md" } ] }, { "id": "api/operations/operation-rest-v-version-short-urls-shortcode-get.md", "kind": "operation", "title": "Parse short code", "description": "Get the long URL behind a short URL's short code.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-shortcode-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-shortcode-get.md", "file": "api/operations/operation-rest-v-version-short-urls-shortcode-get.md", "searchText": "operationId getShortUrl summary Parse short code description Get the long URL behind a short URL's short code. method get path /rest/v{version}/short-urls/{shortCode} tags 0 Short URLs parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 1 name shortCode in path description The short code for the short URL. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 2 name domain in query description The domain in which the short code should be searched for. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description The URL info behind a short code. content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties shortCode name type string format title description The short code for this short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName shortUrl name type string format title description The short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName longUrl name type string format title description The original long URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName dateCreated name type string format date-time title description The date in which the short URL was created in ISO format. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName visitsSummary name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties total name type integer format title description The total amount of visits. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName nonBots name type integer format title description The amount of visits which were not identified as bots. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName bots name type integer format title description The amount of visits that were identified as potential bots. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 total 1 nonBots 2 bots tags name type array format title description A list of tags applied to this short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName meta name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties validSince name type string format title description The date (in ISO-8601 format) from which this short code will be valid default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName validUntil name type string format title description The date (in ISO-8601 format) until which this short code will be valid default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName maxVisits name type number format title description The maximum number of allowed visits for this short code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 validSince 1 validUntil 2 maxVisits domain name type string format title description The domain in which the short URL was created. Null if it belongs to default domain. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A descriptive title of the short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName crawlable name type boolean format title description Tells if this URL will be included as 'Allow' in Shlink's robots.txt. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName forwardQuery name type boolean format title description Tells if this URL will forward the query params to the long URL when visited, as explained in [the docs](https://shlink.io/documentation/some-features/#query-params-forwarding). default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName hasRedirectRules name type boolean format title description Whether this short URL has redirect rules attached to it or not. Use [this endpoint](/documentation/api/#operation-rest-v-version-short-urls-shortcode-redirect-rules-get) to get the actual list of rules. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 shortCode 1 shortUrl 2 longUrl 3 dateCreated 4 visitsSummary 5 tags 6 meta 7 domain 8 title 9 crawlable 10 forwardQuery 11 hasRedirectRules example shortCode 12Kb3 shortUrl https://s.test/12Kb3 longUrl https://shlink.io dateCreated 2016-05-01T20:34:16+02:00 visitsSummary total 1029 nonBots 820 bots 209 tags 0 shlink meta validSince 2017-01-21T00:00:00+02:00 validUntil maxVisits 100 domain title crawlable forwardQuery hasRedirectRules examples encoding prefixEncoding itemEncoding headers links 1 statusCode 404 summary description No URL was found for provided short code. content application/problem+json schema name type format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName allOf 0 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status 1 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties shortCode name type string format title description The short code with which we tried to find the short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName domain name type string format title description The domain with which we tried to find the short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 shortCode example examples Short URL not found summary description value detail No URL found with short code \"abc123\" title Short URL not found type https://shlink.io/api/error/short-url-not-found status 404 shortCode abc123 externalValue encoding prefixEncoding itemEncoding headers links 2 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /rest/v{version}/short-urls/{shortCode}", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-shortcode-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-shortcode-get.md" } ] }, { "id": "api/operations/operation-rest-v-version-short-urls-shortcode-delete.md", "kind": "operation", "title": "Delete short URL", "description": "Deletes the short URL for provided short code.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-shortcode-delete", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-shortcode-delete.md", "file": "api/operations/operation-rest-v-version-short-urls-shortcode-delete.md", "searchText": "operationId deleteShortUrl summary Delete short URL description Deletes the short URL for provided short code. method delete path /rest/v{version}/short-urls/{shortCode} tags 0 Short URLs parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 1 name shortCode in path description The short code for the short URL. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 2 name domain in query description The domain in which the short code should be searched for. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 204 summary description The short URL has been properly deleted. content headers links 1 statusCode 404 summary description No URL was found for provided short code. content application/problem+json schema name type format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName allOf 0 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status 1 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties shortCode name type string format title description The short code with which we tried to find the short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName domain name type string format title description The domain with which we tried to find the short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 shortCode example examples Short URL not found summary description value detail No URL found with short code \"abc123\" title Short URL not found type https://shlink.io/api/error/short-url-not-found status 404 shortCode abc123 externalValue encoding prefixEncoding itemEncoding headers links 2 statusCode 422 summary description The visits threshold in shlink does not allow this short URL to be deleted. content application/problem+json schema name type format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName allOf 0 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status 1 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties shortCode name type string format title description The short code with which we tried to find the short URL to delete default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName domain name type string format title description The domain with which we tried to find the short URL to delete default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName threshold name type number format title description The amount of visits currently configured as threshold to allow deleting short URLs or not default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 shortCode 1 threshold example examples API v3 and newer summary description value title Cannot delete short URL type https://shlink.io/api/error/invalid-short-url-deletion detail Impossible to delete short URL with short code \"abc123\", since it has more than \"15\" visits. status 422 shortCode abc123 threshold 15 externalValue Previous to API v3 summary description value title Cannot delete short URL type INVALID_SHORT_URL_DELETION detail Impossible to delete short URL with short code \"abc123\", since it has more than \"15\" visits. status 422 shortCode abc123 threshold 15 externalValue encoding prefixEncoding itemEncoding headers links 3 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "DELETE /rest/v{version}/short-urls/{shortCode}", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-shortcode-delete", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-shortcode-delete.md" } ] }, { "id": "api/operations/operation-rest-v-version-short-urls-shortcode-patch.md", "kind": "operation", "title": "Edit short URL", "description": "Update certain meta arguments from an existing short URL.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-shortcode-patch", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-shortcode-patch.md", "file": "api/operations/operation-rest-v-version-short-urls-shortcode-patch.md", "searchText": "operationId editShortUrl summary Edit short URL description Update certain meta arguments from an existing short URL. method patch path /rest/v{version}/short-urls/{shortCode} tags 0 Short URLs parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 1 name shortCode in path description The short code for the short URL. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 2 name domain in query description The domain in which the short code should be searched for. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody description Request body. required content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties longUrl name type string format title description The long URL this short URL will redirect to default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName validSince name type string format title description The date (in ISO-8601 format) from which this short code will be valid default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName validUntil name type string format title description The date (in ISO-8601 format) until which this short code will be valid default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName maxVisits name type number format title description The maximum number of allowed visits for this short code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName tags name type array format title description The list of tags to set to the short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A descriptive title of the short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName crawlable name type boolean format title description Tells if this URL will be included as 'Allow' in Shlink's robots.txt. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName forwardQuery name type boolean format title description Tells if the query params should be forwarded from the short URL to the long one, as explained in [the docs](https://shlink.io/documentation/some-features/#query-params-forwarding). default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example examples encoding prefixEncoding itemEncoding responses 0 statusCode 200 summary description The short URL has been properly updated. content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties shortCode name type string format title description The short code for this short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName shortUrl name type string format title description The short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName longUrl name type string format title description The original long URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName dateCreated name type string format date-time title description The date in which the short URL was created in ISO format. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName visitsSummary name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties total name type integer format title description The total amount of visits. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName nonBots name type integer format title description The amount of visits which were not identified as bots. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName bots name type integer format title description The amount of visits that were identified as potential bots. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 total 1 nonBots 2 bots tags name type array format title description A list of tags applied to this short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName meta name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties validSince name type string format title description The date (in ISO-8601 format) from which this short code will be valid default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName validUntil name type string format title description The date (in ISO-8601 format) until which this short code will be valid default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName maxVisits name type number format title description The maximum number of allowed visits for this short code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 validSince 1 validUntil 2 maxVisits domain name type string format title description The domain in which the short URL was created. Null if it belongs to default domain. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A descriptive title of the short URL. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName crawlable name type boolean format title description Tells if this URL will be included as 'Allow' in Shlink's robots.txt. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName forwardQuery name type boolean format title description Tells if this URL will forward the query params to the long URL when visited, as explained in [the docs](https://shlink.io/documentation/some-features/#query-params-forwarding). default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName hasRedirectRules name type boolean format title description Whether this short URL has redirect rules attached to it or not. Use [this endpoint](/documentation/api/#operation-rest-v-version-short-urls-shortcode-redirect-rules-get) to get the actual list of rules. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 shortCode 1 shortUrl 2 longUrl 3 dateCreated 4 visitsSummary 5 tags 6 meta 7 domain 8 title 9 crawlable 10 forwardQuery 11 hasRedirectRules example shortCode 12Kb3 shortUrl https://s.test/12Kb3 longUrl https://shlink.io dateCreated 2016-05-01T20:34:16+02:00 visitsSummary total 1029 nonBots 900 bots 129 tags 0 shlink meta validSince 2017-01-21T00:00:00+02:00 validUntil maxVisits 100 domain title Shlink - The URL shortener crawlable forwardQuery hasRedirectRules examples encoding prefixEncoding itemEncoding headers links 1 statusCode 400 summary description Provided meta arguments are invalid. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName allOf 0 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status 1 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties invalidElements name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type string format title description default enum 0 longUrl 1 validSince 2 validUntil 3 maxVisits enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 invalidElements example examples Invalid arguments summary description value title Invalid data type https://shlink.io/api/error/invalid-data detail Provided data is not valid status 400 invalidElements 0 maxVisits 1 validSince externalValue encoding prefixEncoding itemEncoding headers links 2 statusCode 404 summary description No URL was found for provided short code. content application/problem+json schema name type format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName allOf 0 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status 1 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties shortCode name type string format title description The short code with which we tried to find the short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName domain name type string format title description The domain with which we tried to find the short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 shortCode example examples Short URL not found summary description value detail No URL found with short code \"abc123\" title Short URL not found type https://shlink.io/api/error/short-url-not-found status 404 shortCode abc123 externalValue encoding prefixEncoding itemEncoding headers links 3 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "PATCH /rest/v{version}/short-urls/{shortCode}", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-shortcode-patch", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-shortcode-patch.md" } ] }, { "id": "api/operations/operation-rest-v-version-short-urls-shortcode-redirect-rules-get.md", "kind": "operation", "title": "List short URL redirect rules", "description": "Returns the list of redirect rules for a short URL.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-shortcode-redirect-rules-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-shortcode-redirect-rules-get.md", "file": "api/operations/operation-rest-v-version-short-urls-shortcode-redirect-rules-get.md", "searchText": "operationId listShortUrlRedirectRules summary List short URL redirect rules description Returns the list of redirect rules for a short URL. method get path /rest/v{version}/short-urls/{shortCode}/redirect-rules tags 0 Redirect rules parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 1 name shortCode in path description The short code for the short URL. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 2 name domain in query description The domain in which the short code should be searched for. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description The list of rules content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties defaultLongUrl name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName redirectRules name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties priority name type number format title description Order in which attempting to match the rule. Lower goes first default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 priority allOf 0 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties longUrl name type string format title description Long URL to redirect to when this condition matches default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName conditions name type array format title description List of conditions that need to match in order to consider this rule matches default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description The type of the condition, which will determine the logic used to match it default enum 0 device 1 language 2 query-param 3 any-value-query-param 4 valueless-query-param 5 ip-address 6 geolocation-country-code 7 geolocation-city-name 8 before-date 9 after-date 10 browser enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName matchKey name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName matchValue name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 matchKey 2 matchValue required 0 longUrl 1 conditions required 0 defaultLongUrl 1 redirectRules example defaultLongUrl https://example.com redirectRules 0 longUrl https://example.com/android-en-us priority 1 conditions 0 type device matchValue android matchKey 1 type language matchValue en-US matchKey 1 longUrl https://example.com/fr priority 2 conditions 0 type language matchValue fr matchKey 2 longUrl https://example.com/query-foo-bar-hello-world priority 3 conditions 0 type query-param matchKey foo matchValue bar 1 type query-param matchKey hello matchValue world examples encoding prefixEncoding itemEncoding headers links 1 statusCode 404 summary description No URL was found for provided short code. content application/problem+json schema name type format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName allOf 0 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status 1 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties shortCode name type string format title description The short code with which we tried to find the short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName domain name type string format title description The domain with which we tried to find the short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 shortCode example examples Short URL not found summary description value detail No URL found with short code \"abc123\" title Short URL not found type https://shlink.io/api/error/short-url-not-found status 404 shortCode abc123 externalValue encoding prefixEncoding itemEncoding headers links 2 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /rest/v{version}/short-urls/{shortCode}/redirect-rules", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-shortcode-redirect-rules-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-shortcode-redirect-rules-get.md" } ] }, { "id": "api/operations/operation-rest-v-version-short-urls-shortcode-redirect-rules-post.md", "kind": "operation", "title": "Set short URL redirect rules", "description": "Sets redirect rules for a short URL, with priorities matching the order in which they are provided.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-shortcode-redirect-rules-post", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-shortcode-redirect-rules-post.md", "file": "api/operations/operation-rest-v-version-short-urls-shortcode-redirect-rules-post.md", "searchText": "operationId setShortUrlRedirectRules summary Set short URL redirect rules description Sets redirect rules for a short URL, with priorities matching the order in which they are provided. method post path /rest/v{version}/short-urls/{shortCode}/redirect-rules tags 0 Redirect rules parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 1 name shortCode in path description The short code for the short URL. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 2 name domain in query description The domain in which the short code should be searched for. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody description Request body. required content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties redirectRules name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties longUrl name type string format title description Long URL to redirect to when this condition matches default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName conditions name type array format title description List of conditions that need to match in order to consider this rule matches default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description The type of the condition, which will determine the logic used to match it default enum 0 device 1 language 2 query-param 3 any-value-query-param 4 valueless-query-param 5 ip-address 6 geolocation-country-code 7 geolocation-city-name 8 before-date 9 after-date 10 browser enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName matchKey name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName matchValue name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 matchKey 2 matchValue required 0 longUrl 1 conditions example redirectRules 0 longUrl https://example.com/android-en-us conditions 0 type device matchValue android matchKey 1 type language matchValue en-US matchKey 1 longUrl https://example.com/fr conditions 0 type language matchValue fr matchKey 2 longUrl https://example.com/query-foo-bar-hello-world conditions 0 type query-param matchKey foo matchValue bar 1 type query-param matchKey hello matchValue world examples encoding prefixEncoding itemEncoding responses 0 statusCode 200 summary description The list of rules content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties defaultLongUrl name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName redirectRules name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties priority name type number format title description Order in which attempting to match the rule. Lower goes first default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 priority allOf 0 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties longUrl name type string format title description Long URL to redirect to when this condition matches default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName conditions name type array format title description List of conditions that need to match in order to consider this rule matches default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description The type of the condition, which will determine the logic used to match it default enum 0 device 1 language 2 query-param 3 any-value-query-param 4 valueless-query-param 5 ip-address 6 geolocation-country-code 7 geolocation-city-name 8 before-date 9 after-date 10 browser enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName matchKey name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName matchValue name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 matchKey 2 matchValue required 0 longUrl 1 conditions required 0 defaultLongUrl 1 redirectRules example defaultLongUrl https://example.com redirectRules 0 longUrl https://example.com/android-en-us priority 1 conditions 0 type device matchValue android matchKey 1 type language matchValue en-US matchKey 1 longUrl https://example.com/fr priority 2 conditions 0 type language matchValue fr matchKey 2 longUrl https://example.com/query-foo-bar-hello-world priority 3 conditions 0 type query-param matchKey foo matchValue bar 1 type query-param matchKey hello matchValue world examples encoding prefixEncoding itemEncoding headers links 1 statusCode 404 summary description No URL was found for provided short code. content application/problem+json schema name type format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName allOf 0 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status 1 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties shortCode name type string format title description The short code with which we tried to find the short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName domain name type string format title description The domain with which we tried to find the short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 shortCode example examples Short URL not found summary description value detail No URL found with short code \"abc123\" title Short URL not found type https://shlink.io/api/error/short-url-not-found status 404 shortCode abc123 externalValue encoding prefixEncoding itemEncoding headers links 2 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "POST /rest/v{version}/short-urls/{shortCode}/redirect-rules", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-shortcode-redirect-rules-post", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-shortcode-redirect-rules-post.md" } ] }, { "id": "api/operations/operation-rest-v-version-tags-get.md", "kind": "operation", "title": "List existing tags", "description": "Returns the list of all tags used in any short URL", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-tags-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-tags-get.md", "file": "api/operations/operation-rest-v-version-tags-get.md", "searchText": "operationId listTags summary List existing tags description Returns the list of all tags used in any short URL method get path /rest/v{version}/tags tags 0 Tags parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 1 name page in query description The page to display. Defaults to 1 required deprecated style explode allowReserved schema name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 2 name itemsPerPage in query description The amount of items to return on every page. Defaults to all the items required deprecated style explode allowReserved schema name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 3 name searchTerm in query description A query used to filter results by searching for it on the tag name. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 4 name orderBy in query description To determine how to order the results. required deprecated style explode allowReserved schema name type string format title description default enum 0 tag-ASC 1 tag-DESC enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description The list of tags content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties tags name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties data name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName pagination name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties currentPage name type integer format title description The number of current page. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName pagesCount name type integer format title description The total number of pages that can be obtained. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName itemsPerPage name type integer format title description The number of items for every page. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName itemsInCurrentPage name type integer format title description The number of items in current page (could be smaller than itemsPerPage). default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName totalItems name type integer format title description The total number of items among all pages. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 data example tags data 0 games 1 php 2 shlink 3 tech pagination currentPage 5 pagesCount 10 itemsPerPage 4 itemsInCurrentPage 4 totalItems 38 examples encoding prefixEncoding itemEncoding headers links 1 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /rest/v{version}/tags", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-tags-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-tags-get.md" } ] }, { "id": "api/operations/operation-rest-v-version-tags-put.md", "kind": "operation", "title": "Rename tag", "description": "Renames one existing tag", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-tags-put", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-tags-put.md", "file": "api/operations/operation-rest-v-version-tags-put.md", "searchText": "operationId renameTag summary Rename tag description Renames one existing tag method put path /rest/v{version}/tags tags 0 Tags parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody description Request body. required content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties oldName name type string format title description Current name of the tag default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName newName name type string format title description New name of the tag default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 oldName 1 newName example examples encoding prefixEncoding itemEncoding responses 0 statusCode 204 summary description The tag has been properly renamed content headers links 1 statusCode 400 summary description You have not provided either the oldName or the newName params. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples API v3 and newer summary description value title Invalid data type https://shlink.io/api/error/invalid-data detail Provided data is not valid status 400 invalidElements 0 oldName 1 newName externalValue Previous to API v3 summary description value title Invalid data type INVALID_ARGUMENT detail Provided data is not valid status 400 invalidElements 0 oldName 1 newName externalValue encoding prefixEncoding itemEncoding headers links 2 statusCode 403 summary description The API key you used does not have permissions to rename tags. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples API v3 and newer summary description value detail You are not allowed to rename tags title Forbidden tag operation type https://shlink.io/api/error/forbidden-tag-operation status 403 externalValue Previous to API v3 summary description value detail You are not allowed to rename tags title Forbidden tag operation type FORBIDDEN_OPERATION status 403 externalValue encoding prefixEncoding itemEncoding headers links 3 statusCode 404 summary description There's no tag found with the name provided in oldName param. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples API v3 and newer summary description value detail Tag with name \"foo\" could not be found title Tag not found type https://shlink.io/api/error/tag-not-found status 404 tag foo externalValue encoding prefixEncoding itemEncoding headers links 4 statusCode 409 summary description The name provided in newName param is already in use for another tag. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples API v3 and newer summary description value detail You cannot rename tag foo, because it already exists title Tag conflict type https://shlink.io/api/error/tag-conflict status 409 oldName bar newName foo externalValue Previous to API v3 summary description value detail You cannot rename tag foo, because it already exists title Tag conflict type TAG_CONFLICT status 409 oldName bar newName foo externalValue encoding prefixEncoding itemEncoding headers links 5 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "PUT /rest/v{version}/tags", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-tags-put", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-tags-put.md" } ] }, { "id": "api/operations/operation-rest-v-version-tags-delete.md", "kind": "operation", "title": "Delete tags", "description": "Deletes provided list of tags", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-tags-delete", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-tags-delete.md", "file": "api/operations/operation-rest-v-version-tags-delete.md", "searchText": "operationId deleteTags summary Delete tags description Deletes provided list of tags method delete path /rest/v{version}/tags tags 0 Tags parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 1 name tags[] in query description The names of the tags to delete required deprecated style explode allowReserved schema name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 204 summary description Tags properly deleted content headers links 1 statusCode 403 summary description The API key you used does not have permissions to delete tags. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples API v3 and newer summary description value detail You are not allowed to delete tags title Forbidden tag operation type https://shlink.io/api/error/forbidden-tag-operation status 403 externalValue Previous to API v3 summary description value detail You are not allowed to delete tags title Forbidden tag operation type FORBIDDEN_OPERATION status 403 externalValue encoding prefixEncoding itemEncoding headers links 2 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "DELETE /rest/v{version}/tags", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-tags-delete", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-tags-delete.md" } ] }, { "id": "api/operations/operation-rest-v-version-tags-stats-get.md", "kind": "operation", "title": "Get tags with stats", "description": "Returns the list of all tags used in any short URL, together with the amount of short URLs and visits for it", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-tags-stats-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-tags-stats-get.md", "file": "api/operations/operation-rest-v-version-tags-stats-get.md", "searchText": "operationId tagsWithStats summary Get tags with stats description Returns the list of all tags used in any short URL, together with the amount of short URLs and visits for it method get path /rest/v{version}/tags/stats tags 0 Tags parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 1 name page in query description The page to display. Defaults to 1 required deprecated style explode allowReserved schema name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 2 name itemsPerPage in query description The amount of items to return on every page. Defaults to all the items required deprecated style explode allowReserved schema name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 3 name searchTerm in query description A query used to filter results by searching for it on the tag name. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 4 name orderBy in query description To determine how to order the results.<br /><br />**Important!** Ordering by `shortUrlsCount`, `visits` or `nonBotVisits` has a [known performance issue](https://github.com/shlinkio/shlink/issues/1346) which makes loading a subset of the list take as much as loading the whole list.<br />If you plan to order by any of these fields, it's worth loading the whole list with no pagination. required deprecated style explode allowReserved schema name type string format title description default enum 0 tag-ASC 1 tag-DESC 2 shortUrlsCount-ASC 3 shortUrlsCount-DESC 4 visits-ASC 5 visits-DESC 6 nonBotVisits-ASC 7 nonBotVisits-DESC enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description The list of tags content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties tags name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties data name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties tag name type string format title description The unique tag name default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName shortUrlsCount name type number format title description The amount of short URLs using this tag default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName visitsSummary name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties total name type integer format title description The total amount of visits. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName nonBots name type integer format title description The amount of visits which were not identified as bots. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName bots name type integer format title description The amount of visits that were identified as potential bots. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 total 1 nonBots 2 bots required 0 tag 1 shortUrlsCount 2 visitsSummary pagination name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties currentPage name type integer format title description The number of current page. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName pagesCount name type integer format title description The total number of pages that can be obtained. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName itemsPerPage name type integer format title description The number of items for every page. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName itemsInCurrentPage name type integer format title description The number of items in current page (could be smaller than itemsPerPage). default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName totalItems name type integer format title description The total number of items among all pages. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 data example tags data 0 tag games shortUrlsCount 10 visitsSummary total 521 nonBots 521 bots 0 1 tag shlink shortUrlsCount 7 visitsSummary total 1087 nonBots 1000 bots 87 pagination currentPage 5 pagesCount 5 itemsPerPage 10 itemsInCurrentPage 2 totalItems 42 examples encoding prefixEncoding itemEncoding headers links 1 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /rest/v{version}/tags/stats", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-tags-stats-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-tags-stats-get.md" } ] }, { "id": "api/operations/operation-rest-v-version-visits-get.md", "kind": "operation", "title": "Get general visits stats", "description": "Get general visits stats not linked to one specific short URL.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-visits-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-visits-get.md", "file": "api/operations/operation-rest-v-version-visits-get.md", "searchText": "operationId getGlobalVisits summary Get general visits stats description Get general visits stats not linked to one specific short URL. method get path /rest/v{version}/visits tags 0 Visits parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description Visits stats. content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties visits name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties nonOrphanVisits name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties total name type integer format title description The total amount of visits. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName nonBots name type integer format title description The amount of visits which were not identified as bots. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName bots name type integer format title description The amount of visits that were identified as potential bots. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 total 1 nonBots 2 bots orphanVisits name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties total name type integer format title description The total amount of visits. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName nonBots name type integer format title description The amount of visits which were not identified as bots. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName bots name type integer format title description The amount of visits that were identified as potential bots. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 total 1 nonBots 2 bots required 0 nonOrphanVisits 1 orphanVisits example visits nonOrphanVisits total 64994 nonBots 64986 bots 8 orphanVisits total 37 nonBots 34 bots 3 examples encoding prefixEncoding itemEncoding headers links 1 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /rest/v{version}/visits", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-visits-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-visits-get.md" } ] }, { "id": "api/operations/operation-rest-v-version-short-urls-shortcode-visits-get.md", "kind": "operation", "title": "List visits for short URL", "description": "Get the list of visits on the short URL behind provided short code.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-shortcode-visits-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-shortcode-visits-get.md", "file": "api/operations/operation-rest-v-version-short-urls-shortcode-visits-get.md", "searchText": "operationId getShortUrlVisits summary List visits for short URL description Get the list of visits on the short URL behind provided short code. method get path /rest/v{version}/short-urls/{shortCode}/visits tags 0 Visits parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 1 name shortCode in path description The short code for the short URL. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 2 name domain in query description The domain in which the short code should be searched for. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 3 name startDate in query description The date (in ISO-8601 format) from which we want to get visits. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 4 name endDate in query description The date (in ISO-8601 format) until which we want to get visits. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 5 name page in query description The page to display. Defaults to 1 required deprecated style explode allowReserved schema name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 6 name itemsPerPage in query description The amount of items to return on every page. Defaults to all the items required deprecated style explode allowReserved schema name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 7 name excludeBots in query description Tells if visits from potential bots should be excluded from the result set required deprecated style explode allowReserved schema name type string format title description default enum 0 true enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description List of visits. content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties visits name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties data name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties referer name type string format title description The origin from which the visit was performed default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName date name type string format date-time title description The date in which the visit was performed default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName userAgent name type string format title description The user agent from which the visit was performed default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName visitLocation name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties cityName name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName countryCode name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName countryName name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName latitude name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName longitude name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName regionName name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName timezone name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName potentialBot name type boolean format title description Tells if Shlink thinks this visit comes potentially from a bot or crawler default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName visitedUrl name type string format title description The originally visited URL that triggered the tracking of this visit default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName redirectUrl name type string format title description The URL to which the visitor was redirected, or null if a redirect did not occur, like for 404 requests or pixel tracking default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 referer 1 date 2 userAgent 3 visitLocation 4 potentialBot 5 visitedUrl pagination name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties currentPage name type integer format title description The number of current page. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName pagesCount name type integer format title description The total number of pages that can be obtained. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName itemsPerPage name type integer format title description The number of items for every page. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName itemsInCurrentPage name type integer format title description The number of items in current page (could be smaller than itemsPerPage). default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName totalItems name type integer format title description The total number of items among all pages. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example visits data 0 referer https://twitter.com date 2015-08-20T05:05:03+04:00 userAgent Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0 visitLocation potentialBot visitedUrl https://s.test 1 referer https://t.co date 2015-08-20T05:05:03+04:00 userAgent Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36 visitLocation cityName Cupertino countryCode US countryName United States latitude 37.3042 longitude -122.0946 regionName California timezone America/Los_Angeles potentialBot visitedUrl https://s.test 2 referer date 2015-08-20T05:05:03+04:00 userAgent some_web_crawler/1.4 visitLocation potentialBot visitedUrl https://s.test pagination currentPage 5 pagesCount 12 itemsPerPage 10 itemsInCurrentPage 10 totalItems 115 examples encoding prefixEncoding itemEncoding headers links 1 statusCode 404 summary description The short code does not belong to any short URL. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples Short URL not found summary description value detail No URL found with short code \"abc123\" title Short URL not found type https://shlink.io/api/error/short-url-not-found status 404 shortCode abc123 externalValue encoding prefixEncoding itemEncoding headers links 2 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /rest/v{version}/short-urls/{shortCode}/visits", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-shortcode-visits-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-shortcode-visits-get.md" } ] }, { "id": "api/operations/operation-rest-v-version-short-urls-shortcode-visits-delete.md", "kind": "operation", "title": "Delete visits for short URL", "description": "Delete all existing visits on the short URL behind provided short code.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-shortcode-visits-delete", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-shortcode-visits-delete.md", "file": "api/operations/operation-rest-v-version-short-urls-shortcode-visits-delete.md", "searchText": "operationId deleteShortUrlVisits summary Delete visits for short URL description Delete all existing visits on the short URL behind provided short code. method delete path /rest/v{version}/short-urls/{shortCode}/visits tags 0 Visits parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 1 name shortCode in path description The short code for the short URL. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 2 name domain in query description The domain in which the short code should be searched for. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description Deleted visits content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties deletedVisits name type number format title description Amount of affected visits default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example deletedVisits 536 examples encoding prefixEncoding itemEncoding headers links 1 statusCode 404 summary description The short code does not belong to any short URL. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples Short URL not found summary description value detail No URL found with short code \"abc123\" title Short URL not found type https://shlink.io/api/error/short-url-not-found status 404 shortCode abc123 externalValue encoding prefixEncoding itemEncoding headers links 2 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "DELETE /rest/v{version}/short-urls/{shortCode}/visits", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-short-urls-shortcode-visits-delete", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-short-urls-shortcode-visits-delete.md" } ] }, { "id": "api/operations/operation-rest-v-version-tags-tag-visits-get.md", "kind": "operation", "title": "List visits for tag", "description": "Get the list of visits on any short URL which is tagged with provided tag.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-tags-tag-visits-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-tags-tag-visits-get.md", "file": "api/operations/operation-rest-v-version-tags-tag-visits-get.md", "searchText": "operationId getTagVisits summary List visits for tag description Get the list of visits on any short URL which is tagged with provided tag. method get path /rest/v{version}/tags/{tag}/visits tags 0 Visits parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 1 name tag in path description The tag from which we want to get the visits. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 2 name startDate in query description The date (in ISO-8601 format) from which we want to get visits. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 3 name endDate in query description The date (in ISO-8601 format) until which we want to get visits. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 4 name page in query description The page to display. Defaults to 1 required deprecated style explode allowReserved schema name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 5 name itemsPerPage in query description The amount of items to return on every page. Defaults to all the items required deprecated style explode allowReserved schema name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 6 name excludeBots in query description Tells if visits from potential bots should be excluded from the result set required deprecated style explode allowReserved schema name type string format title description default enum 0 true enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 7 name domain in query description The domain in which the short code should be searched for. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description List of visits. content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties visits name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties data name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties referer name type string format title description The origin from which the visit was performed default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName date name type string format date-time title description The date in which the visit was performed default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName userAgent name type string format title description The user agent from which the visit was performed default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName visitLocation name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties cityName name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName countryCode name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName countryName name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName latitude name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName longitude name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName regionName name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName timezone name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName potentialBot name type boolean format title description Tells if Shlink thinks this visit comes potentially from a bot or crawler default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName visitedUrl name type string format title description The originally visited URL that triggered the tracking of this visit default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName redirectUrl name type string format title description The URL to which the visitor was redirected, or null if a redirect did not occur, like for 404 requests or pixel tracking default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 referer 1 date 2 userAgent 3 visitLocation 4 potentialBot 5 visitedUrl pagination name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties currentPage name type integer format title description The number of current page. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName pagesCount name type integer format title description The total number of pages that can be obtained. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName itemsPerPage name type integer format title description The number of items for every page. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName itemsInCurrentPage name type integer format title description The number of items in current page (could be smaller than itemsPerPage). default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName totalItems name type integer format title description The total number of items among all pages. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example visits data 0 referer https://twitter.com date 2015-08-20T05:05:03+04:00 userAgent Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0 visitLocation potentialBot visitedUrl https://s.test 1 referer https://t.co date 2015-08-20T05:05:03+04:00 userAgent Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36 visitLocation cityName Cupertino countryCode US countryName United States latitude 37.3042 longitude -122.0946 regionName California timezone America/Los_Angeles potentialBot visitedUrl https://s.test 2 referer date 2015-08-20T05:05:03+04:00 userAgent some_web_crawler/1.4 visitLocation potentialBot visitedUrl https://s.test pagination currentPage 5 pagesCount 12 itemsPerPage 10 itemsInCurrentPage 10 totalItems 115 examples encoding prefixEncoding itemEncoding headers links 1 statusCode 404 summary description The tag does not exist. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples Tag not found summary description value detail Tag with name \"foo\" could not be found title Tag not found type https://shlink.io/api/error/tag-not-found status 404 tag foo externalValue encoding prefixEncoding itemEncoding headers links 2 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /rest/v{version}/tags/{tag}/visits", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-tags-tag-visits-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-tags-tag-visits-get.md" } ] }, { "id": "api/operations/operation-rest-v-version-domains-domain-visits-get.md", "kind": "operation", "title": "List visits for domain", "description": "Get the list of visits on any short URL which belongs to provided domain.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-domains-domain-visits-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-domains-domain-visits-get.md", "file": "api/operations/operation-rest-v-version-domains-domain-visits-get.md", "searchText": "operationId getDomainVisits summary List visits for domain description Get the list of visits on any short URL which belongs to provided domain. method get path /rest/v{version}/domains/{domain}/visits tags 0 Visits parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 1 name domain in path description The domain from which we want to get the visits, or **DEFAULT** keyword for default domain. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 2 name startDate in query description The date (in ISO-8601 format) from which we want to get visits. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 3 name endDate in query description The date (in ISO-8601 format) until which we want to get visits. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 4 name page in query description The page to display. Defaults to 1 required deprecated style explode allowReserved schema name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 5 name itemsPerPage in query description The amount of items to return on every page. Defaults to all the items required deprecated style explode allowReserved schema name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 6 name excludeBots in query description Tells if visits from potential bots should be excluded from the result set required deprecated style explode allowReserved schema name type string format title description default enum 0 true enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description List of visits. content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties visits name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties data name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties referer name type string format title description The origin from which the visit was performed default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName date name type string format date-time title description The date in which the visit was performed default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName userAgent name type string format title description The user agent from which the visit was performed default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName visitLocation name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties cityName name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName countryCode name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName countryName name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName latitude name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName longitude name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName regionName name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName timezone name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName potentialBot name type boolean format title description Tells if Shlink thinks this visit comes potentially from a bot or crawler default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName visitedUrl name type string format title description The originally visited URL that triggered the tracking of this visit default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName redirectUrl name type string format title description The URL to which the visitor was redirected, or null if a redirect did not occur, like for 404 requests or pixel tracking default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 referer 1 date 2 userAgent 3 visitLocation 4 potentialBot 5 visitedUrl pagination name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties currentPage name type integer format title description The number of current page. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName pagesCount name type integer format title description The total number of pages that can be obtained. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName itemsPerPage name type integer format title description The number of items for every page. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName itemsInCurrentPage name type integer format title description The number of items in current page (could be smaller than itemsPerPage). default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName totalItems name type integer format title description The total number of items among all pages. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example visits data 0 referer https://twitter.com date 2015-08-20T05:05:03+04:00 userAgent Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0 visitLocation potentialBot visitedUrl https://s.test 1 referer https://t.co date 2015-08-20T05:05:03+04:00 userAgent Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36 visitLocation cityName Cupertino countryCode US countryName United States latitude 37.3042 longitude -122.0946 regionName California timezone America/Los_Angeles potentialBot visitedUrl https://s.test 2 referer date 2015-08-20T05:05:03+04:00 userAgent some_web_crawler/1.4 visitLocation potentialBot visitedUrl https://s.test pagination currentPage 5 pagesCount 12 itemsPerPage 10 itemsInCurrentPage 10 totalItems 115 examples encoding prefixEncoding itemEncoding headers links 1 statusCode 404 summary description The domain does not exist. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples API v3 and newer summary description value detail Domain with authority \"example.com\" could not be found title Domain not found type https://shlink.io/api/error/domain-not-found status 404 authority example.com externalValue Previous to API v3 summary description value detail Domain with authority \"example.com\" could not be found title Domain not found type DOMAIN_NOT_FOUND status 404 authority example.com externalValue encoding prefixEncoding itemEncoding headers links 2 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /rest/v{version}/domains/{domain}/visits", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-domains-domain-visits-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-domains-domain-visits-get.md" } ] }, { "id": "api/operations/operation-rest-v-version-visits-orphan-get.md", "kind": "operation", "title": "List orphan visits", "description": "Get the list of visits to invalid short URLs, the base URL or any other 404.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-visits-orphan-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-visits-orphan-get.md", "file": "api/operations/operation-rest-v-version-visits-orphan-get.md", "searchText": "operationId getOrphanVisits summary List orphan visits description Get the list of visits to invalid short URLs, the base URL or any other 404. method get path /rest/v{version}/visits/orphan tags 0 Visits parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 1 name startDate in query description The date (in ISO-8601 format) from which we want to get visits. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 2 name endDate in query description The date (in ISO-8601 format) until which we want to get visits. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 3 name page in query description The page to display. Defaults to 1 required deprecated style explode allowReserved schema name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 4 name itemsPerPage in query description The amount of items to return on every page. Defaults to all the items required deprecated style explode allowReserved schema name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 5 name excludeBots in query description Tells if visits from potential bots should be excluded from the result set required deprecated style explode allowReserved schema name type string format title description default enum 0 true enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 6 name type in query description The type of visits to return. All visits are returned when not provided. required deprecated style explode allowReserved schema name type string format title description default enum 0 invalid_short_url 1 base_url 2 regular_404 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 7 name domain in query description The domain in which the short code should be searched for. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description List of visits. content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties visits name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties data name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description Tells the type of orphan visit default enum 0 invalid_short_url 1 base_url 2 regular_404 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type allOf 0 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties referer name type string format title description The origin from which the visit was performed default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName date name type string format date-time title description The date in which the visit was performed default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName userAgent name type string format title description The user agent from which the visit was performed default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName visitLocation name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties cityName name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName countryCode name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName countryName name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName latitude name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName longitude name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName regionName name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName timezone name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName potentialBot name type boolean format title description Tells if Shlink thinks this visit comes potentially from a bot or crawler default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName visitedUrl name type string format title description The originally visited URL that triggered the tracking of this visit default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName redirectUrl name type string format title description The URL to which the visitor was redirected, or null if a redirect did not occur, like for 404 requests or pixel tracking default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 referer 1 date 2 userAgent 3 visitLocation 4 potentialBot 5 visitedUrl pagination name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties currentPage name type integer format title description The number of current page. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName pagesCount name type integer format title description The total number of pages that can be obtained. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName itemsPerPage name type integer format title description The number of items for every page. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName itemsInCurrentPage name type integer format title description The number of items in current page (could be smaller than itemsPerPage). default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName totalItems name type integer format title description The total number of items among all pages. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example visits data 0 referer https://twitter.com date 2015-08-20T05:05:03+04:00 userAgent Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0 visitLocation potentialBot visitedUrl https://s.test type base_url 1 referer https://t.co date 2015-08-20T05:05:03+04:00 userAgent Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36 visitLocation cityName Cupertino countryCode US countryName United States latitude 37.3042 longitude -122.0946 regionName California timezone America/Los_Angeles potentialBot visitedUrl https://s.test/foo type invalid_short_url 2 referer date 2015-08-20T05:05:03+04:00 userAgent some_web_crawler/1.4 visitLocation potentialBot visitedUrl https://s.test/foo/bar/baz type regular_404 pagination currentPage 5 pagesCount 12 itemsPerPage 10 itemsInCurrentPage 10 totalItems 115 examples encoding prefixEncoding itemEncoding headers links 1 statusCode 400 summary description Provided query arguments are invalid. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName allOf 0 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status 1 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties invalidElements name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type string format title description default enum 0 type enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 invalidElements example examples API v3 and newer summary description value title Invalid data type https://shlink.io/api/error/invalid-data detail Provided data is not valid status 400 invalidElements 0 type externalValue Previous to API v3 summary description value title Invalid data type INVALID_ARGUMENT detail Provided data is not valid status 400 invalidElements 0 type externalValue encoding prefixEncoding itemEncoding headers links 2 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /rest/v{version}/visits/orphan", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-visits-orphan-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-visits-orphan-get.md" } ] }, { "id": "api/operations/operation-rest-v-version-visits-orphan-delete.md", "kind": "operation", "title": "Delete orphan visits", "description": "Delete all visits to invalid short URLs, the base URL or any other 404.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-visits-orphan-delete", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-visits-orphan-delete.md", "file": "api/operations/operation-rest-v-version-visits-orphan-delete.md", "searchText": "operationId deleteOrphanVisits summary Delete orphan visits description Delete all visits to invalid short URLs, the base URL or any other 404. method delete path /rest/v{version}/visits/orphan tags 0 Visits parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description Deleted visits content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties deletedVisits name type number format title description Amount of affected visits default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example deletedVisits 536 examples encoding prefixEncoding itemEncoding headers links 1 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "DELETE /rest/v{version}/visits/orphan", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-visits-orphan-delete", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-visits-orphan-delete.md" } ] }, { "id": "api/operations/operation-rest-v-version-visits-non-orphan-get.md", "kind": "operation", "title": "List non-orphan visits", "description": "Get the list of visits to any short URL.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-visits-non-orphan-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-visits-non-orphan-get.md", "file": "api/operations/operation-rest-v-version-visits-non-orphan-get.md", "searchText": "operationId getNonOrphanVisits summary List non-orphan visits description Get the list of visits to any short URL. method get path /rest/v{version}/visits/non-orphan tags 0 Visits parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 1 name startDate in query description The date (in ISO-8601 format) from which we want to get visits. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 2 name endDate in query description The date (in ISO-8601 format) until which we want to get visits. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 3 name page in query description The page to display. Defaults to 1 required deprecated style explode allowReserved schema name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 4 name itemsPerPage in query description The amount of items to return on every page. Defaults to all the items required deprecated style explode allowReserved schema name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 5 name excludeBots in query description Tells if visits from potential bots should be excluded from the result set required deprecated style explode allowReserved schema name type string format title description default enum 0 true enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples 6 name domain in query description The domain in which the short code should be searched for. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description List of visits. content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties visits name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties data name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties referer name type string format title description The origin from which the visit was performed default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName date name type string format date-time title description The date in which the visit was performed default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName userAgent name type string format title description The user agent from which the visit was performed default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName visitLocation name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties cityName name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName countryCode name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName countryName name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName latitude name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName longitude name type number format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName regionName name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName timezone name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName potentialBot name type boolean format title description Tells if Shlink thinks this visit comes potentially from a bot or crawler default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName visitedUrl name type string format title description The originally visited URL that triggered the tracking of this visit default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName redirectUrl name type string format title description The URL to which the visitor was redirected, or null if a redirect did not occur, like for 404 requests or pixel tracking default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 referer 1 date 2 userAgent 3 visitLocation 4 potentialBot 5 visitedUrl pagination name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties currentPage name type integer format title description The number of current page. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName pagesCount name type integer format title description The total number of pages that can be obtained. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName itemsPerPage name type integer format title description The number of items for every page. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName itemsInCurrentPage name type integer format title description The number of items in current page (could be smaller than itemsPerPage). default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName totalItems name type integer format title description The total number of items among all pages. default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example visits data 0 referer https://twitter.com date 2015-08-20T05:05:03+04:00 userAgent Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0 visitLocation potentialBot visitedUrl https://s.test 1 referer https://t.co date 2015-08-20T05:05:03+04:00 userAgent Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36 visitLocation cityName Cupertino countryCode US countryName United States latitude 37.3042 longitude -122.0946 regionName California timezone America/Los_Angeles potentialBot visitedUrl https://s.test 2 referer date 2015-08-20T05:05:03+04:00 userAgent some_web_crawler/1.4 visitLocation potentialBot visitedUrl https://s.test pagination currentPage 5 pagesCount 12 itemsPerPage 10 itemsInCurrentPage 10 totalItems 115 examples encoding prefixEncoding itemEncoding headers links 1 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /rest/v{version}/visits/non-orphan", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-visits-non-orphan-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-visits-non-orphan-get.md" } ] }, { "id": "api/operations/operation-rest-v-version-domains-get.md", "kind": "operation", "title": "List configured domains", "description": "Returns the list of all domains that have been either used for some short URL, or have explicitly configured redirects. It also includes the domain redirects, plus the default redirects that will be used for any non-explicitly-configured one.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-domains-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-domains-get.md", "file": "api/operations/operation-rest-v-version-domains-get.md", "searchText": "operationId listDomains summary List configured domains description Returns the list of all domains that have been either used for some short URL, or have explicitly configured redirects.<br/>It also includes the domain redirects, plus the default redirects that will be used for any non-explicitly-configured one. method get path /rest/v{version}/domains tags 0 Domains parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description The list of domains content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties domains name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties data name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties domain name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName isDefault name type boolean format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName redirects name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties baseUrlRedirect name type string format title description URL to redirect to when a user hits the domain's base URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName regular404Redirect name type string format title description URL to redirect to when a user hits a not found URL other than an invalid short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName invalidShortUrlRedirect name type string format title description URL to redirect to when a user hits an invalid short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 domain 1 isDefault 2 redirects defaultRedirects name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties baseUrlRedirect name type string format title description URL to redirect to when a user hits the domain's base URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName regular404Redirect name type string format title description URL to redirect to when a user hits a not found URL other than an invalid short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName invalidShortUrlRedirect name type string format title description URL to redirect to when a user hits an invalid short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 data required 0 domains example domains data 0 domain example.com isDefault redirects baseUrlRedirect https://example.com/my-landing-page regular404Redirect invalidShortUrlRedirect https://example.com/invalid-url 1 domain aaa.com isDefault redirects baseUrlRedirect regular404Redirect invalidShortUrlRedirect 2 domain bbb.com isDefault redirects baseUrlRedirect regular404Redirect invalidShortUrlRedirect https://example.com/invalid-url defaultRedirects baseUrlRedirect https://somewhere.com regular404Redirect invalidShortUrlRedirect examples encoding prefixEncoding itemEncoding headers links 1 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /rest/v{version}/domains", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-domains-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-domains-get.md" } ] }, { "id": "api/operations/operation-rest-v-version-domains-redirects-patch.md", "kind": "operation", "title": "Sets domain \"not found\" redirects", "description": "Sets the URLs that you want a visitor to get redirected to for \"not found\" URLs for a specific domain", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-domains-redirects-patch", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-domains-redirects-patch.md", "file": "api/operations/operation-rest-v-version-domains-redirects-patch.md", "searchText": "operationId setDomainRedirects summary Sets domain \"not found\" redirects description Sets the URLs that you want a visitor to get redirected to for \"not found\" URLs for a specific domain method patch path /rest/v{version}/domains/redirects tags 0 Domains parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody description Request body. required content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName allOf 0 name type format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties domain name type string format title description The domain's authority for which you want to set redirects default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 domain 1 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties baseUrlRedirect name type string format title description URL to redirect to when a user hits the domain's base URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName regular404Redirect name type string format title description URL to redirect to when a user hits a not found URL other than an invalid short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName invalidShortUrlRedirect name type string format title description URL to redirect to when a user hits an invalid short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example examples encoding prefixEncoding itemEncoding responses 0 statusCode 200 summary description The domain's redirects after the update, when existing redirects have been merged with provided ones. content application/json schema name type format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName allOf 0 name type format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 baseUrlRedirect 1 regular404Redirect 2 invalidShortUrlRedirect 1 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties baseUrlRedirect name type string format title description URL to redirect to when a user hits the domain's base URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName regular404Redirect name type string format title description URL to redirect to when a user hits a not found URL other than an invalid short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName invalidShortUrlRedirect name type string format title description URL to redirect to when a user hits an invalid short URL default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example baseUrlRedirect https://example.com/my-landing-page regular404Redirect invalidShortUrlRedirect https://example.com/invalid-url examples encoding prefixEncoding itemEncoding headers links 1 statusCode 400 summary description Provided data is invalid. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName allOf 0 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status 1 name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties invalidElements name type array format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName items name type string format title description default enum 0 domain 1 baseUrlRedirect 2 regular404Redirect 3 invalidShortUrlRedirect enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 invalidElements example examples API v3 and newer summary description value title Invalid data type https://shlink.io/api/error/invalid-data detail Provided data is not valid status 400 invalidElements 0 domain 1 invalidShortUrlRedirect externalValue Previous to API v3 summary description value title Invalid data type INVALID_ARGUMENT detail Provided data is not valid status 400 invalidElements 0 domain 1 invalidShortUrlRedirect externalValue encoding prefixEncoding itemEncoding headers links 2 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "PATCH /rest/v{version}/domains/redirects", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-domains-redirects-patch", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-domains-redirects-patch.md" } ] }, { "id": "api/operations/operation-rest-v-version-mercure-info-get.md", "kind": "operation", "title": "Get mercure integration info", "description": "Returns information to consume updates published by Shlink on a mercure hub. https://mercure.rocks/", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-mercure-info-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-mercure-info-get.md", "file": "api/operations/operation-rest-v-version-mercure-info-get.md", "searchText": "operationId mercureInfo summary Get mercure integration info description Returns information to consume updates published by Shlink on a mercure hub. https://mercure.rocks/ method get path /rest/v{version}/mercure-info tags 0 Integrations parameters 0 name version in path description The API version to be consumed required deprecated style explode allowReserved schema name type string format title description default enum 0 3 1 2 2 1 enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description The mercure integration info content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties mercureHubUrl name type string format title description The public URL of the mercure hub that can be used to get real-time updates published by Shlink default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName jwt name type string format title description A JWT with subscribe permissions which is valid with the mercure hub default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName jwtExpiration name type string format title description The date (in ISO-8601 format) in which the JWT will expire default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 mercureHubUrl 1 jwt 2 jwtExpiration example mercureHubUrl https://example.com/.well-known/mercure jwt eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJTaGxpbmsiLCJpYXQiOjE1ODY2ODY3MzIsImV4cCI6MTU4Njk0NTkzMiwibWVyY3VyZSI6eyJzdWJzY3JpYmUiOltdfX0.P-519lgU7dFz0bbNlRG1CXyqugGbaHon4kw6fu4QBdQ jwtExpiration 2020-04-15T12:18:52+02:00 examples encoding prefixEncoding itemEncoding headers links 1 statusCode 501 summary description This Shlink instance is not integrated with a mercure hub content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples API v3 and newer summary description value title Mercure integration not configured type https://shlink.io/api/error/mercure-not-configured detail This Shlink instance is not integrated with a mercure hub. status 501 externalValue Previous to API v3 summary description value title Mercure integration not configured type MERCURE_NOT_CONFIGURED detail This Shlink instance is not integrated with a mercure hub. status 501 externalValue encoding prefixEncoding itemEncoding headers links 2 statusCode default summary description Unexpected error. content application/problem+json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security 0 ApiKey deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /rest/v{version}/mercure-info", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-v-version-mercure-info-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-v-version-mercure-info-get.md" } ] }, { "id": "api/operations/operation-rest-health-get.md", "kind": "operation", "title": "Check healthiness", "description": "Checks the healthiness of the service, making sure it can access required resources.", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-health-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-health-get.md", "file": "api/operations/operation-rest-health-get.md", "searchText": "operationId health summary Check healthiness description Checks the healthiness of the service, making sure it can access required resources. method get path /rest/health tags 0 Monitoring parameters requestBody responses 0 statusCode 200 summary description The passing health status content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties status name type string format title description The status of the service default enum 0 pass 1 fail enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName version name type string format title description Shlink version default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName links name type object format title description A list of links default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties about name type string format title description About shlink default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName project name type string format title description Shlink project repository default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example status pass version 2.10.0 links about https://shlink.io project https://github.com/shlinkio/shlink examples encoding prefixEncoding itemEncoding headers links 1 statusCode 503 summary description The failing health status content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties status name type string format title description The status of the service default enum 0 pass 1 fail enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName version name type string format title description Shlink version default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName links name type object format title description A list of links default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties about name type string format title description About shlink default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName project name type string format title description Shlink project repository default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example status fail version 2.10.0 links about https://shlink.io project https://github.com/shlinkio/shlink examples encoding prefixEncoding itemEncoding headers links 2 statusCode default summary description Unexpected error. content application/json schema name type object format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName properties type name type string format title description A machine unique code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName title name type string format title description A unique title default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName detail name type string format title description A human-friendly error description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName status name type number format title description HTTP response status code default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName required 0 type 1 title 2 detail 3 status example examples encoding prefixEncoding itemEncoding headers links security deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /rest/health", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-rest-health-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-rest-health-get.md" } ] }, { "id": "api/operations/operation-shortcode-get.md", "kind": "operation", "title": "Short URL", "description": "Represents a short URL. Tracks the visit and redirects tio the corresponding long URL", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-shortcode-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-shortcode-get.md", "file": "api/operations/operation-shortcode-get.md", "searchText": "operationId shortUrl summary Short URL description Represents a short URL. Tracks the visit and redirects tio the corresponding long URL method get path /{shortCode} tags 0 URL Shortener parameters 0 name shortCode in path description The short code for the short URL. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 302 summary description Visit properly tracked and redirected content headers links security deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /{shortCode}", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-shortcode-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-shortcode-get.md" } ] }, { "id": "api/operations/operation-shortcode-track-get.md", "kind": "operation", "title": "Short URL tracking pixel", "description": "Generates a 1px transparent image which can be used to track emails with a short URL", "tab": "api", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-shortcode-track-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-shortcode-track-get.md", "file": "api/operations/operation-shortcode-track-get.md", "searchText": "operationId trackShortUrl summary Short URL tracking pixel description Generates a 1px transparent image which can be used to track emails with a short URL method get path /{shortCode}/track tags 0 URL Shortener parameters 0 name shortCode in path description The short code for the short URL. required deprecated style explode allowReserved schema name type string format title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName content example examples requestBody responses 0 statusCode 200 summary description Image in GIF format content image/gif schema name type string format binary title description default enum enumNames enumDescriptions const nullable readOnly writeOnly deprecated example examples refName example examples encoding prefixEncoding itemEncoding headers links security deprecated servers externalDocs callbacks hidden codeSamples ", "documentId": "GET /{shortCode}/track", "locale": "en", "contentLocale": "en", "contentVersion": "v5", "versionScope": "tab:api", "alternates": [ { "locale": "en", "contentVersion": "v5", "url": "https://sourcey-shlink.pages.dev/documentation/api/#operation-shortcode-track-get", "markdown": "https://sourcey-shlink.pages.dev/documentation/api/operations/operation-shortcode-track-get.md" } ] }, { "id": "about-this-preview/index.md", "kind": "page", "title": "About this preview", "description": "An unofficial rebuild of the Shlink documentation with Sourcey, and how it measures against the current site.", "tab": "@pages", "url": "https://sourcey-shlink.pages.dev/documentation/about-this-preview/", "markdown": "https://sourcey-shlink.pages.dev/documentation/about-this-preview/index.md", "file": "about-this-preview/index.md", "searchText": "\n# About this preview {#about-this-preview}\n\n\nThis is an unofficial preview of the Shlink documentation, rebuilt with [Sourcey](https://sourcey.com), an open-source docs engine licensed under AGPL-3.0. It is not run by the Shlink project. Search engines are asked not to index it, and it comes down on request, or after 30 days.\n\n\n## What it is built from {#what-it-is-built-from}\n\n\n- The website repository, [shlinkio/shlink.io](https://github.com/shlinkio/shlink.io) at `705517f`, converted with `sourcey migrate`: all 46 pages at their addresses under `/documentation`, with every heading link still landing, in one sidebar sectioned as the site sections it.\n- The [REST API reference](/documentation/api/) from `shlink-open-api-specs`, for 5.1.7, 4.6.0 and 3.7.4, with a release picker and each release on one page. Every link from the documentation to the specification site lands on its operation, including the removed QR code endpoint on 4.6.0's.\n\n\n## Measured beside the current site {#measured-beside-the-current-site}\n\n\nBoth sites were built from their own sources and served side by side on one machine, compressed as hosts serve them. Each page was opened in a fresh browser at 1440 by 1000 pixels and measured once the network settled, on 21 October 2026 with Sourcey 3.8.3.\n\n| Page | Current site: requests, download, JavaScript heap | This preview |\n| --- | --- | --- |\n| `/documentation/` | 16, 250.8 KB, 3.9 MB | 10, 69.0 KB, 0.8 MB |\n| `/documentation/supported-runtimes/` | 17, 256.5 KB, 3.9 MB | 11, 74.0 KB, 0.8 MB |\n| `/documentation/advanced/dynamic-rule-based-redirects-system/` | 18, 257.5 KB, 3.9 MB | 10, 70.5 KB, 0.8 MB |\n| `/documentation/api/` (5.1.7) | on a separate site | 11, 98.5 KB, 0.5 MB |\n\nSearch runs from static files the build writes: typing \"redirect\" downloads 39.9 KB the first time, and nothing after that, with no hosted service to apply for or keep. The current site's search downloads 11.6 KB for each query from its hosted service.\n\nThe preview builds in 4.7 s from cold with the three API references, peaking at 1.16 GB of memory; the current site builds in 2.3 s, peaking at 1.32 GB. It writes 25.8 MB, of which 22.3 MB is what readers load (the current site writes 22.4 MB), most of it the site's own media.\n\n\n## For agents {#for-agents}\n\n\nEvery page and operation is also published as Markdown, with an [llms.txt](/documentation/llms.txt), a [documents index](/documentation/documents.json), each release's [OpenAPI bundle](/documentation/api/openapi.json), and [ARD](/documentation/ard.json) and [API catalog](/documentation/api-catalog.json) discovery files.\n\n\n## A link on the current site that misses its section {#a-link-on-the-current-site-that-misses-its-section}\n\n\n| Page | Link | Should be |\n| --- | --- | --- |\n| [advanced/real-time-updates](https://shlink.io/documentation/advanced/real-time-updates/) | `#redis-pub-sub` | `#redis-pubsub` |\n", "documentId": "about-this-preview", "locale": "en", "contentLocale": "en", "contentVersion": "current", "versionScope": "site", "alternates": [ { "locale": "en", "contentVersion": "current", "url": "https://sourcey-shlink.pages.dev/documentation/about-this-preview/", "markdown": "https://sourcey-shlink.pages.dev/documentation/about-this-preview/index.md" } ] } ] }