# Shlink REST API Shlink, the self-hosted URL shortener Version: 3.0 Authentication: - ApiKey: apiKey, header X-Api-Key. A valid shlink API key ## List short URLs `GET /rest/v{version}/short-urls` Returns the list of short URLs. Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] - `page` (query, integer, optional) - The page to be displayed. Defaults to 1 Type: integer - `itemsPerPage` (query, number, optional) - The amount of items to return on every page. Defaults to 10 Type: number - `searchTerm` (query, string, optional) - A query used to filter results by searching for it on the longUrl and shortCode fields. Type: string - `tags[]` (query, array, optional) - A list of tags used to filter the result set. Only short URLs **with** these tags will be returned. Type: array Items: Type: string - `tagsMode` (query, string, optional) - Tells how the filtering by `tags` should work, returning short URLs containing "any" of the tags, or "all" the tags. Defaults to "any".
It's ignored if `tags` is not provided. Type: string enum: ["any","all"] - `excludeTags[]` (query, array, optional) - A list of tags used to filter the result set. Only short URLs **without** these tags will be returned. Type: array Items: Type: string - `excludeTagsMode` (query, string, optional) - 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".
It's ignored if `excludeTags` is not provided. Type: string enum: ["any","all"] - `orderBy` (query, string, optional) - The field from which you want to order the result. Type: string enum: ["longUrl-ASC","longUrl-DESC","shortCode-ASC","shortCode-DESC","dateCreated-ASC","dateCreated-DESC","title-ASC","title-DESC","visits-ASC","visits-DESC","nonBotVisits-ASC","nonBotVisits-DESC"] - `startDate` (query, string, optional) - The date (in ISO-8601 format) from which we want to get short URLs. Type: string - `endDate` (query, string, optional) - The date (in ISO-8601 format) until which we want to get short URLs. Type: string - `excludeMaxVisitsReached` (query, string, optional) - If true, short URLs which already reached their maximum amount of visits will be excluded. Type: string enum: ["true","false"] - `excludePastValidUntil` (query, string, optional) - If true, short URLs which validUntil date is on the past will be excluded. Type: string enum: ["true","false"] - `domain` (query, string, optional) - Get short URLs for this particular domain only. Use **DEFAULT** keyword for default domain. Type: string - `apiKeyName` (query, string, optional) - Only get short URLs created with this API key.
This value is **ignored** if the request is performed with a non-admin API key that does not match this name. Type: string Responses: - 200: The list of short URLs Content type: application/json Type: object - `shortUrls` (optional) Type: object - `data` (optional) Type: array Items: Type: object - `shortCode` (required) Type: string The short code for this short URL. - `shortUrl` (required) Type: string The short URL. - `longUrl` (required) Type: string The original long URL. - `dateCreated` (required) Type: string, date-time The date in which the short URL was created in ISO format. - `visitsSummary` (required) Type: object - `total` (required) Type: integer The total amount of visits. - `nonBots` (required) Type: integer The amount of visits which were not identified as bots. - `bots` (required) Type: integer The amount of visits that were identified as potential bots. - `tags` (required) Type: array A list of tags applied to this short URL Items: Type: string - `meta` (required) Type: object - `validSince` (required) Type: string; nullable The date (in ISO-8601 format) from which this short code will be valid - `validUntil` (required) Type: string; nullable The date (in ISO-8601 format) until which this short code will be valid - `maxVisits` (required) Type: number; nullable The maximum number of allowed visits for this short code - `domain` (required) Type: string; nullable The domain in which the short URL was created. Null if it belongs to default domain. - `title` (required) Type: string; nullable A descriptive title of the short URL. - `crawlable` (required) Type: boolean Tells if this URL will be included as 'Allow' in Shlink's robots.txt. - `forwardQuery` (required) Type: boolean 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). - `hasRedirectRules` (required) Type: boolean Whether this short URL has redirect rules attached to it or not. Use [this endpoint](https://sourcey-shlink.pages.dev/documentation/api/index.md#operation-rest-v-version-short-urls-shortcode-redirect-rules-get) to get the actual list of rules. - `pagination` (optional) Type: object - `currentPage` (optional) Type: integer The number of current page. - `pagesCount` (optional) Type: integer The total number of pages that can be obtained. - `itemsPerPage` (optional) Type: integer The number of items for every page. - `itemsInCurrentPage` (optional) Type: integer The number of items in current page (could be smaller than itemsPerPage). - `totalItems` (optional) Type: integer The total number of items among all pages. ```json { "shortUrls": { "data": [ { "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": [ "games", "tech" ], "meta": { "validSince": "2017-01-21T00:00:00+02:00", "validUntil": null, "maxVisits": 100 }, "domain": null, "title": "Welcome to Steam", "crawlable": false, "forwardQuery": true, "hasRedirectRules": true }, { "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": [ "shlink" ], "meta": { "validSince": null, "validUntil": null, "maxVisits": null }, "domain": null, "title": null, "crawlable": false, "forwardQuery": true, "hasRedirectRules": false }, { "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": null, "maxVisits": null }, "domain": "example.com", "title": null, "crawlable": false, "forwardQuery": false, "hasRedirectRules": true } ], "pagination": { "currentPage": 5, "pagesCount": 12, "itemsPerPage": 10, "itemsInCurrentPage": 10, "totalItems": 115 } } } ``` - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X GET 'https://s.test/rest/v3/short-urls' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/short-urls', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'https://s.test/rest/v3/short-urls', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Create short URL `POST /rest/v{version}/short-urls` 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. These are the use cases: * Only the long URL is provided: It will return the newest match or create a new short URL if none is found. * 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. * 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. Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] Request body: application/json (required) Request body. Type: unknown allOf: Type: object - `longUrl` (optional) Type: string The long URL this short URL will redirect to - `validSince` (optional) Type: string; nullable The date (in ISO-8601 format) from which this short code will be valid - `validUntil` (optional) Type: string; nullable The date (in ISO-8601 format) until which this short code will be valid - `maxVisits` (optional) Type: number; nullable The maximum number of allowed visits for this short code - `tags` (optional) Type: array The list of tags to set to the short URL. Items: Type: string - `title` (optional) Type: string; nullable A descriptive title of the short URL. - `crawlable` (optional) Type: boolean Tells if this URL will be included as 'Allow' in Shlink's robots.txt. - `forwardQuery` (optional) Type: boolean 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). Type: object - `customSlug` (optional) Type: string A unique custom slug to be used instead of the generated short code - `pathPrefix` (optional) Type: string A prefix that will be prepended to provided custom slug or auto-generated short code - `findIfExists` (optional) Type: boolean Will force existing matching URL to be returned if found, instead of creating a new one - `domain` (optional) Type: string The domain to which the short URL will be attached - `shortCodeLength` (optional) Type: number 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 Responses: - 200: The result of parsing the long URL Content type: application/json Type: object - `shortCode` (required) Type: string The short code for this short URL. - `shortUrl` (required) Type: string The short URL. - `longUrl` (required) Type: string The original long URL. - `dateCreated` (required) Type: string, date-time The date in which the short URL was created in ISO format. - `visitsSummary` (required) Type: object - `total` (required) Type: integer The total amount of visits. - `nonBots` (required) Type: integer The amount of visits which were not identified as bots. - `bots` (required) Type: integer The amount of visits that were identified as potential bots. - `tags` (required) Type: array A list of tags applied to this short URL Items: Type: string - `meta` (required) Type: object - `validSince` (required) Type: string; nullable The date (in ISO-8601 format) from which this short code will be valid - `validUntil` (required) Type: string; nullable The date (in ISO-8601 format) until which this short code will be valid - `maxVisits` (required) Type: number; nullable The maximum number of allowed visits for this short code - `domain` (required) Type: string; nullable The domain in which the short URL was created. Null if it belongs to default domain. - `title` (required) Type: string; nullable A descriptive title of the short URL. - `crawlable` (required) Type: boolean Tells if this URL will be included as 'Allow' in Shlink's robots.txt. - `forwardQuery` (required) Type: boolean 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). - `hasRedirectRules` (required) Type: boolean Whether this short URL has redirect rules attached to it or not. Use [this endpoint](https://sourcey-shlink.pages.dev/documentation/api/index.md#operation-rest-v-version-short-urls-shortcode-redirect-rules-get) to get the actual list of rules. ```json { "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": [ "games", "tech" ], "meta": { "validSince": "2017-01-21T00:00:00+02:00", "validUntil": null, "maxVisits": 500 }, "domain": null, "title": null, "crawlable": false, "forwardQuery": true, "hasRedirectRules": false } ``` - 400: Some of provided data is invalid. Check extra fields to know exactly what. Content type: application/problem+json Type: object allOf: Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code Type: object - `invalidElements` (optional) Type: array Items: Type: string enum: ["validSince","validUntil","customSlug","pathPrefix","maxVisits","findIfExists","domain"] - `customSlug` (optional) Type: string Provided custom slug when the error type is https://shlink.io/api/error/non-unique-slug - `domain` (optional) Type: string The domain for which you were trying to create the new short URL - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X POST 'https://s.test/rest/v3/short-urls' \ -H 'X-Api-Key: YOUR_TOKEN' \ -H 'Content-Type: application/json' \ --data-raw '{ "longUrl": "string", "validSince": "string", "validUntil": "string", "maxVisits": 0, "tags": [ "string" ], "title": "string", "crawlable": true, "forwardQuery": true, "customSlug": "string", "pathPrefix": "string", "findIfExists": true, "domain": "string", "shortCodeLength": 0 }' ``` ### JavaScript ```javascript const body = `{ "longUrl": "string", "validSince": "string", "validUntil": "string", "maxVisits": 0, "tags": [ "string" ], "title": "string", "crawlable": true, "forwardQuery": true, "customSlug": "string", "pathPrefix": "string", "findIfExists": true, "domain": "string", "shortCodeLength": 0 }`; const response = await fetch('https://s.test/rest/v3/short-urls', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "longUrl": "string", "validSince": "string", "validUntil": "string", "maxVisits": 0, "tags": [ "string" ], "title": "string", "crawlable": true, "forwardQuery": true, "customSlug": "string", "pathPrefix": "string", "findIfExists": true, "domain": "string", "shortCodeLength": 0 }''' response = requests.post( 'https://s.test/rest/v3/short-urls', data=body.encode('utf-8'), headers={ 'X-Api-Key': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Create a short URL `GET /rest/v{version}/short-urls/shorten` **[Deprecated]** Use [Create short URL](https://sourcey-shlink.pages.dev/documentation/api/index.md#operation-rest-v-version-short-urls-post) instead Deprecated. Authentication: no security requirement declared for this operation. Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] - `apiKey` (query, string, required) - The API key used to authenticate the request Type: string - `longUrl` (query, string, required) - The URL to be shortened Type: string - `format` (query, string, optional) - The format in which you want the response to be returned. You can also use the "Accept" header instead of this Type: string enum: ["txt","json"] Responses: - 200: The list of short URLs Content type: application/json Type: object - `shortCode` (required) Type: string The short code for this short URL. - `shortUrl` (required) Type: string The short URL. - `longUrl` (required) Type: string The original long URL. - `dateCreated` (required) Type: string, date-time The date in which the short URL was created in ISO format. - `visitsSummary` (required) Type: object - `total` (required) Type: integer The total amount of visits. - `nonBots` (required) Type: integer The amount of visits which were not identified as bots. - `bots` (required) Type: integer The amount of visits that were identified as potential bots. - `tags` (required) Type: array A list of tags applied to this short URL Items: Type: string - `meta` (required) Type: object - `validSince` (required) Type: string; nullable The date (in ISO-8601 format) from which this short code will be valid - `validUntil` (required) Type: string; nullable The date (in ISO-8601 format) until which this short code will be valid - `maxVisits` (required) Type: number; nullable The maximum number of allowed visits for this short code - `domain` (required) Type: string; nullable The domain in which the short URL was created. Null if it belongs to default domain. - `title` (required) Type: string; nullable A descriptive title of the short URL. - `crawlable` (required) Type: boolean Tells if this URL will be included as 'Allow' in Shlink's robots.txt. - `forwardQuery` (required) Type: boolean 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). - `hasRedirectRules` (required) Type: boolean Whether this short URL has redirect rules attached to it or not. Use [this endpoint](https://sourcey-shlink.pages.dev/documentation/api/index.md#operation-rest-v-version-short-urls-shortcode-redirect-rules-get) to get the actual list of rules. ```json { "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": [ "games", "tech" ], "meta": { "validSince": "2017-01-21T00:00:00+02:00", "validUntil": null, "maxVisits": 100 }, "domain": null, "title": null, "crawlable": false, "forwardQuery": true, "hasRedirectRules": false } ``` Content type: text/plain Type: string ```json "https://s.test/abc123" ``` - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code Content type: text/plain Type: string ## Examples ### cURL ```bash curl -X GET 'https://s.test/rest/v3/short-urls/shorten?apiKey=string&longUrl=string' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/short-urls/shorten?apiKey=string&longUrl=string', { method: 'GET', }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get('https://s.test/rest/v3/short-urls/shorten?apiKey=string&longUrl=string') print(response.text) ``` ## Parse short code `GET /rest/v{version}/short-urls/{shortCode}` Get the long URL behind a short URL's short code. Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] - `shortCode` (path, string, required) - The short code for the short URL. Type: string - `domain` (query, string, optional) - The domain in which the short code should be searched for. Type: string Responses: - 200: The URL info behind a short code. Content type: application/json Type: object - `shortCode` (required) Type: string The short code for this short URL. - `shortUrl` (required) Type: string The short URL. - `longUrl` (required) Type: string The original long URL. - `dateCreated` (required) Type: string, date-time The date in which the short URL was created in ISO format. - `visitsSummary` (required) Type: object - `total` (required) Type: integer The total amount of visits. - `nonBots` (required) Type: integer The amount of visits which were not identified as bots. - `bots` (required) Type: integer The amount of visits that were identified as potential bots. - `tags` (required) Type: array A list of tags applied to this short URL Items: Type: string - `meta` (required) Type: object - `validSince` (required) Type: string; nullable The date (in ISO-8601 format) from which this short code will be valid - `validUntil` (required) Type: string; nullable The date (in ISO-8601 format) until which this short code will be valid - `maxVisits` (required) Type: number; nullable The maximum number of allowed visits for this short code - `domain` (required) Type: string; nullable The domain in which the short URL was created. Null if it belongs to default domain. - `title` (required) Type: string; nullable A descriptive title of the short URL. - `crawlable` (required) Type: boolean Tells if this URL will be included as 'Allow' in Shlink's robots.txt. - `forwardQuery` (required) Type: boolean 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). - `hasRedirectRules` (required) Type: boolean Whether this short URL has redirect rules attached to it or not. Use [this endpoint](https://sourcey-shlink.pages.dev/documentation/api/index.md#operation-rest-v-version-short-urls-shortcode-redirect-rules-get) to get the actual list of rules. ```json { "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": [ "shlink" ], "meta": { "validSince": "2017-01-21T00:00:00+02:00", "validUntil": null, "maxVisits": 100 }, "domain": null, "title": null, "crawlable": false, "forwardQuery": true, "hasRedirectRules": true } ``` - 404: No URL was found for provided short code. Content type: application/problem+json Type: unknown allOf: Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code Type: object - `shortCode` (required) Type: string The short code with which we tried to find the short URL - `domain` (optional) Type: string The domain with which we tried to find the short URL - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X GET 'https://s.test/rest/v3/short-urls/string' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/short-urls/string', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'https://s.test/rest/v3/short-urls/string', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Delete short URL `DELETE /rest/v{version}/short-urls/{shortCode}` Deletes the short URL for provided short code. Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] - `shortCode` (path, string, required) - The short code for the short URL. Type: string - `domain` (query, string, optional) - The domain in which the short code should be searched for. Type: string Responses: - 204: The short URL has been properly deleted. - 404: No URL was found for provided short code. Content type: application/problem+json Type: unknown allOf: Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code Type: object - `shortCode` (required) Type: string The short code with which we tried to find the short URL - `domain` (optional) Type: string The domain with which we tried to find the short URL - 422: The visits threshold in shlink does not allow this short URL to be deleted. Content type: application/problem+json Type: unknown allOf: Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code Type: object - `shortCode` (required) Type: string The short code with which we tried to find the short URL to delete - `domain` (optional) Type: string The domain with which we tried to find the short URL to delete - `threshold` (required) Type: number The amount of visits currently configured as threshold to allow deleting short URLs or not - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X DELETE 'https://s.test/rest/v3/short-urls/string' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/short-urls/string', { method: 'DELETE', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.delete( 'https://s.test/rest/v3/short-urls/string', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Edit short URL `PATCH /rest/v{version}/short-urls/{shortCode}` Update certain meta arguments from an existing short URL. Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] - `shortCode` (path, string, required) - The short code for the short URL. Type: string - `domain` (query, string, optional) - The domain in which the short code should be searched for. Type: string Request body: application/json (required) Request body. Type: object - `longUrl` (optional) Type: string The long URL this short URL will redirect to - `validSince` (optional) Type: string; nullable The date (in ISO-8601 format) from which this short code will be valid - `validUntil` (optional) Type: string; nullable The date (in ISO-8601 format) until which this short code will be valid - `maxVisits` (optional) Type: number; nullable The maximum number of allowed visits for this short code - `tags` (optional) Type: array The list of tags to set to the short URL. Items: Type: string - `title` (optional) Type: string; nullable A descriptive title of the short URL. - `crawlable` (optional) Type: boolean Tells if this URL will be included as 'Allow' in Shlink's robots.txt. - `forwardQuery` (optional) Type: boolean 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). Responses: - 200: The short URL has been properly updated. Content type: application/json Type: object - `shortCode` (required) Type: string The short code for this short URL. - `shortUrl` (required) Type: string The short URL. - `longUrl` (required) Type: string The original long URL. - `dateCreated` (required) Type: string, date-time The date in which the short URL was created in ISO format. - `visitsSummary` (required) Type: object - `total` (required) Type: integer The total amount of visits. - `nonBots` (required) Type: integer The amount of visits which were not identified as bots. - `bots` (required) Type: integer The amount of visits that were identified as potential bots. - `tags` (required) Type: array A list of tags applied to this short URL Items: Type: string - `meta` (required) Type: object - `validSince` (required) Type: string; nullable The date (in ISO-8601 format) from which this short code will be valid - `validUntil` (required) Type: string; nullable The date (in ISO-8601 format) until which this short code will be valid - `maxVisits` (required) Type: number; nullable The maximum number of allowed visits for this short code - `domain` (required) Type: string; nullable The domain in which the short URL was created. Null if it belongs to default domain. - `title` (required) Type: string; nullable A descriptive title of the short URL. - `crawlable` (required) Type: boolean Tells if this URL will be included as 'Allow' in Shlink's robots.txt. - `forwardQuery` (required) Type: boolean 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). - `hasRedirectRules` (required) Type: boolean Whether this short URL has redirect rules attached to it or not. Use [this endpoint](https://sourcey-shlink.pages.dev/documentation/api/index.md#operation-rest-v-version-short-urls-shortcode-redirect-rules-get) to get the actual list of rules. ```json { "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": [ "shlink" ], "meta": { "validSince": "2017-01-21T00:00:00+02:00", "validUntil": null, "maxVisits": 100 }, "domain": null, "title": "Shlink - The URL shortener", "crawlable": false, "forwardQuery": false, "hasRedirectRules": true } ``` - 400: Provided meta arguments are invalid. Content type: application/problem+json Type: object allOf: Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code Type: object - `invalidElements` (required) Type: array Items: Type: string enum: ["longUrl","validSince","validUntil","maxVisits"] - 404: No URL was found for provided short code. Content type: application/problem+json Type: unknown allOf: Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code Type: object - `shortCode` (required) Type: string The short code with which we tried to find the short URL - `domain` (optional) Type: string The domain with which we tried to find the short URL - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X PATCH 'https://s.test/rest/v3/short-urls/string' \ -H 'X-Api-Key: YOUR_TOKEN' \ -H 'Content-Type: application/json' \ --data-raw '{ "longUrl": "string", "validSince": "string", "validUntil": "string", "maxVisits": 0, "tags": [ "string" ], "title": "string", "crawlable": true, "forwardQuery": true }' ``` ### JavaScript ```javascript const body = `{ "longUrl": "string", "validSince": "string", "validUntil": "string", "maxVisits": 0, "tags": [ "string" ], "title": "string", "crawlable": true, "forwardQuery": true }`; const response = await fetch('https://s.test/rest/v3/short-urls/string', { method: 'PATCH', headers: { 'X-Api-Key': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "longUrl": "string", "validSince": "string", "validUntil": "string", "maxVisits": 0, "tags": [ "string" ], "title": "string", "crawlable": true, "forwardQuery": true }''' response = requests.patch( 'https://s.test/rest/v3/short-urls/string', data=body.encode('utf-8'), headers={ 'X-Api-Key': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## List short URL redirect rules `GET /rest/v{version}/short-urls/{shortCode}/redirect-rules` Returns the list of redirect rules for a short URL. Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] - `shortCode` (path, string, required) - The short code for the short URL. Type: string - `domain` (query, string, optional) - The domain in which the short code should be searched for. Type: string Responses: - 200: The list of rules Content type: application/json Type: object - `defaultLongUrl` (required) Type: string - `redirectRules` (required) Type: array Items: Type: object - `priority` (required) Type: number Order in which attempting to match the rule. Lower goes first allOf: Type: object - `longUrl` (required) Type: string Long URL to redirect to when this condition matches - `conditions` (required) Type: array List of conditions that need to match in order to consider this rule matches Items: Type: object - `type` (required) Type: string The type of the condition, which will determine the logic used to match it enum: ["device","language","query-param","any-value-query-param","valueless-query-param","ip-address","geolocation-country-code","geolocation-city-name","before-date","after-date","browser"] - `matchKey` (required) Type: string; nullable - `matchValue` (required) Type: string; nullable ```json { "defaultLongUrl": "https://example.com", "redirectRules": [ { "longUrl": "https://example.com/android-en-us", "priority": 1, "conditions": [ { "type": "device", "matchValue": "android", "matchKey": null }, { "type": "language", "matchValue": "en-US", "matchKey": null } ] }, { "longUrl": "https://example.com/fr", "priority": 2, "conditions": [ { "type": "language", "matchValue": "fr", "matchKey": null } ] }, { "longUrl": "https://example.com/query-foo-bar-hello-world", "priority": 3, "conditions": [ { "type": "query-param", "matchKey": "foo", "matchValue": "bar" }, { "type": "query-param", "matchKey": "hello", "matchValue": "world" } ] } ] } ``` - 404: No URL was found for provided short code. Content type: application/problem+json Type: unknown allOf: Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code Type: object - `shortCode` (required) Type: string The short code with which we tried to find the short URL - `domain` (optional) Type: string The domain with which we tried to find the short URL - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X GET 'https://s.test/rest/v3/short-urls/string/redirect-rules' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/short-urls/string/redirect-rules', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'https://s.test/rest/v3/short-urls/string/redirect-rules', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Set short URL redirect rules `POST /rest/v{version}/short-urls/{shortCode}/redirect-rules` Sets redirect rules for a short URL, with priorities matching the order in which they are provided. Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] - `shortCode` (path, string, required) - The short code for the short URL. Type: string - `domain` (query, string, optional) - The domain in which the short code should be searched for. Type: string Request body: application/json (required) Request body. Type: object - `redirectRules` (optional) Type: array Items: Type: object - `longUrl` (required) Type: string Long URL to redirect to when this condition matches - `conditions` (required) Type: array List of conditions that need to match in order to consider this rule matches Items: Type: object - `type` (required) Type: string The type of the condition, which will determine the logic used to match it enum: ["device","language","query-param","any-value-query-param","valueless-query-param","ip-address","geolocation-country-code","geolocation-city-name","before-date","after-date","browser"] - `matchKey` (required) Type: string; nullable - `matchValue` (required) Type: string; nullable ```json { "redirectRules": [ { "longUrl": "https://example.com/android-en-us", "conditions": [ { "type": "device", "matchValue": "android", "matchKey": null }, { "type": "language", "matchValue": "en-US", "matchKey": null } ] }, { "longUrl": "https://example.com/fr", "conditions": [ { "type": "language", "matchValue": "fr", "matchKey": null } ] }, { "longUrl": "https://example.com/query-foo-bar-hello-world", "conditions": [ { "type": "query-param", "matchKey": "foo", "matchValue": "bar" }, { "type": "query-param", "matchKey": "hello", "matchValue": "world" } ] } ] } ``` Responses: - 200: The list of rules Content type: application/json Type: object - `defaultLongUrl` (required) Type: string - `redirectRules` (required) Type: array Items: Type: object - `priority` (required) Type: number Order in which attempting to match the rule. Lower goes first allOf: Type: object - `longUrl` (required) Type: string Long URL to redirect to when this condition matches - `conditions` (required) Type: array List of conditions that need to match in order to consider this rule matches Items: Type: object - `type` (required) Type: string The type of the condition, which will determine the logic used to match it enum: ["device","language","query-param","any-value-query-param","valueless-query-param","ip-address","geolocation-country-code","geolocation-city-name","before-date","after-date","browser"] - `matchKey` (required) Type: string; nullable - `matchValue` (required) Type: string; nullable ```json { "defaultLongUrl": "https://example.com", "redirectRules": [ { "longUrl": "https://example.com/android-en-us", "priority": 1, "conditions": [ { "type": "device", "matchValue": "android", "matchKey": null }, { "type": "language", "matchValue": "en-US", "matchKey": null } ] }, { "longUrl": "https://example.com/fr", "priority": 2, "conditions": [ { "type": "language", "matchValue": "fr", "matchKey": null } ] }, { "longUrl": "https://example.com/query-foo-bar-hello-world", "priority": 3, "conditions": [ { "type": "query-param", "matchKey": "foo", "matchValue": "bar" }, { "type": "query-param", "matchKey": "hello", "matchValue": "world" } ] } ] } ``` - 404: No URL was found for provided short code. Content type: application/problem+json Type: unknown allOf: Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code Type: object - `shortCode` (required) Type: string The short code with which we tried to find the short URL - `domain` (optional) Type: string The domain with which we tried to find the short URL - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X POST 'https://s.test/rest/v3/short-urls/string/redirect-rules' \ -H 'X-Api-Key: YOUR_TOKEN' \ -H 'Content-Type: application/json' \ --data-raw '{ "redirectRules": [ { "longUrl": "https://example.com/android-en-us", "conditions": [ { "type": "device", "matchValue": "android", "matchKey": null }, { "type": "language", "matchValue": "en-US", "matchKey": null } ] }, { "longUrl": "https://example.com/fr", "conditions": [ { "type": "language", "matchValue": "fr", "matchKey": null } ] }, { "longUrl": "https://example.com/query-foo-bar-hello-world", "conditions": [ { "type": "query-param", "matchKey": "foo", "matchValue": "bar" }, { "type": "query-param", "matchKey": "hello", "matchValue": "world" } ] } ] }' ``` ### JavaScript ```javascript const body = `{ "redirectRules": [ { "longUrl": "https://example.com/android-en-us", "conditions": [ { "type": "device", "matchValue": "android", "matchKey": null }, { "type": "language", "matchValue": "en-US", "matchKey": null } ] }, { "longUrl": "https://example.com/fr", "conditions": [ { "type": "language", "matchValue": "fr", "matchKey": null } ] }, { "longUrl": "https://example.com/query-foo-bar-hello-world", "conditions": [ { "type": "query-param", "matchKey": "foo", "matchValue": "bar" }, { "type": "query-param", "matchKey": "hello", "matchValue": "world" } ] } ] }`; const response = await fetch('https://s.test/rest/v3/short-urls/string/redirect-rules', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "redirectRules": [ { "longUrl": "https://example.com/android-en-us", "conditions": [ { "type": "device", "matchValue": "android", "matchKey": null }, { "type": "language", "matchValue": "en-US", "matchKey": null } ] }, { "longUrl": "https://example.com/fr", "conditions": [ { "type": "language", "matchValue": "fr", "matchKey": null } ] }, { "longUrl": "https://example.com/query-foo-bar-hello-world", "conditions": [ { "type": "query-param", "matchKey": "foo", "matchValue": "bar" }, { "type": "query-param", "matchKey": "hello", "matchValue": "world" } ] } ] }''' response = requests.post( 'https://s.test/rest/v3/short-urls/string/redirect-rules', data=body.encode('utf-8'), headers={ 'X-Api-Key': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## List existing tags `GET /rest/v{version}/tags` Returns the list of all tags used in any short URL Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] - `page` (query, number, optional) - The page to display. Defaults to 1 Type: number - `itemsPerPage` (query, number, optional) - The amount of items to return on every page. Defaults to all the items Type: number - `searchTerm` (query, string, optional) - A query used to filter results by searching for it on the tag name. Type: string - `orderBy` (query, string, optional) - To determine how to order the results. Type: string enum: ["tag-ASC","tag-DESC"] Responses: - 200: The list of tags Content type: application/json Type: object - `tags` (optional) Type: object - `data` (required) Type: array Items: Type: string - `pagination` (optional) Type: object - `currentPage` (optional) Type: integer The number of current page. - `pagesCount` (optional) Type: integer The total number of pages that can be obtained. - `itemsPerPage` (optional) Type: integer The number of items for every page. - `itemsInCurrentPage` (optional) Type: integer The number of items in current page (could be smaller than itemsPerPage). - `totalItems` (optional) Type: integer The total number of items among all pages. ```json { "tags": { "data": [ "games", "php", "shlink", "tech" ], "pagination": { "currentPage": 5, "pagesCount": 10, "itemsPerPage": 4, "itemsInCurrentPage": 4, "totalItems": 38 } } } ``` - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X GET 'https://s.test/rest/v3/tags' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/tags', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'https://s.test/rest/v3/tags', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Rename tag `PUT /rest/v{version}/tags` Renames one existing tag Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] Request body: application/json (required) Request body. Type: object - `oldName` (required) Type: string Current name of the tag - `newName` (required) Type: string New name of the tag Responses: - 204: The tag has been properly renamed - 400: You have not provided either the oldName or the newName params. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code - 403: The API key you used does not have permissions to rename tags. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code - 404: There's no tag found with the name provided in oldName param. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code - 409: The name provided in newName param is already in use for another tag. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X PUT 'https://s.test/rest/v3/tags' \ -H 'X-Api-Key: YOUR_TOKEN' \ -H 'Content-Type: application/json' \ --data-raw '{ "oldName": "string", "newName": "string" }' ``` ### JavaScript ```javascript const body = `{ "oldName": "string", "newName": "string" }`; const response = await fetch('https://s.test/rest/v3/tags', { method: 'PUT', headers: { 'X-Api-Key': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "oldName": "string", "newName": "string" }''' response = requests.put( 'https://s.test/rest/v3/tags', data=body.encode('utf-8'), headers={ 'X-Api-Key': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Delete tags `DELETE /rest/v{version}/tags` Deletes provided list of tags Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] - `tags[]` (query, array, required) - The names of the tags to delete Type: array Items: Type: string Responses: - 204: Tags properly deleted - 403: The API key you used does not have permissions to delete tags. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X DELETE 'https://s.test/rest/v3/tags?tags%5B%5D=string' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/tags?tags%5B%5D=string', { method: 'DELETE', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.delete( 'https://s.test/rest/v3/tags?tags%5B%5D=string', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Get tags with stats `GET /rest/v{version}/tags/stats` Returns the list of all tags used in any short URL, together with the amount of short URLs and visits for it Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] - `page` (query, number, optional) - The page to display. Defaults to 1 Type: number - `itemsPerPage` (query, number, optional) - The amount of items to return on every page. Defaults to all the items Type: number - `searchTerm` (query, string, optional) - A query used to filter results by searching for it on the tag name. Type: string - `orderBy` (query, string, optional) - To determine how to order the results.

**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.
If you plan to order by any of these fields, it's worth loading the whole list with no pagination. Type: string enum: ["tag-ASC","tag-DESC","shortUrlsCount-ASC","shortUrlsCount-DESC","visits-ASC","visits-DESC","nonBotVisits-ASC","nonBotVisits-DESC"] Responses: - 200: The list of tags Content type: application/json Type: object - `tags` (optional) Type: object - `data` (required) Type: array Items: Type: object - `tag` (required) Type: string The unique tag name - `shortUrlsCount` (required) Type: number The amount of short URLs using this tag - `visitsSummary` (required) Type: object - `total` (required) Type: integer The total amount of visits. - `nonBots` (required) Type: integer The amount of visits which were not identified as bots. - `bots` (required) Type: integer The amount of visits that were identified as potential bots. - `pagination` (optional) Type: object - `currentPage` (optional) Type: integer The number of current page. - `pagesCount` (optional) Type: integer The total number of pages that can be obtained. - `itemsPerPage` (optional) Type: integer The number of items for every page. - `itemsInCurrentPage` (optional) Type: integer The number of items in current page (could be smaller than itemsPerPage). - `totalItems` (optional) Type: integer The total number of items among all pages. ```json { "tags": { "data": [ { "tag": "games", "shortUrlsCount": 10, "visitsSummary": { "total": 521, "nonBots": 521, "bots": 0 } }, { "tag": "shlink", "shortUrlsCount": 7, "visitsSummary": { "total": 1087, "nonBots": 1000, "bots": 87 } } ], "pagination": { "currentPage": 5, "pagesCount": 5, "itemsPerPage": 10, "itemsInCurrentPage": 2, "totalItems": 42 } } } ``` - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X GET 'https://s.test/rest/v3/tags/stats' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/tags/stats', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'https://s.test/rest/v3/tags/stats', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Get general visits stats `GET /rest/v{version}/visits` Get general visits stats not linked to one specific short URL. Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] Responses: - 200: Visits stats. Content type: application/json Type: object - `visits` (optional) Type: object - `nonOrphanVisits` (required) Type: object - `total` (required) Type: integer The total amount of visits. - `nonBots` (required) Type: integer The amount of visits which were not identified as bots. - `bots` (required) Type: integer The amount of visits that were identified as potential bots. - `orphanVisits` (required) Type: object - `total` (required) Type: integer The total amount of visits. - `nonBots` (required) Type: integer The amount of visits which were not identified as bots. - `bots` (required) Type: integer The amount of visits that were identified as potential bots. ```json { "visits": { "nonOrphanVisits": { "total": 64994, "nonBots": 64986, "bots": 8 }, "orphanVisits": { "total": 37, "nonBots": 34, "bots": 3 } } } ``` - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X GET 'https://s.test/rest/v3/visits' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/visits', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'https://s.test/rest/v3/visits', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## List visits for short URL `GET /rest/v{version}/short-urls/{shortCode}/visits` Get the list of visits on the short URL behind provided short code. Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] - `shortCode` (path, string, required) - The short code for the short URL. Type: string - `domain` (query, string, optional) - The domain in which the short code should be searched for. Type: string - `startDate` (query, string, optional) - The date (in ISO-8601 format) from which we want to get visits. Type: string - `endDate` (query, string, optional) - The date (in ISO-8601 format) until which we want to get visits. Type: string - `page` (query, number, optional) - The page to display. Defaults to 1 Type: number - `itemsPerPage` (query, number, optional) - The amount of items to return on every page. Defaults to all the items Type: number - `excludeBots` (query, string, optional) - Tells if visits from potential bots should be excluded from the result set Type: string enum: ["true"] Responses: - 200: List of visits. Content type: application/json Type: object - `visits` (optional) Type: object - `data` (optional) Type: array Items: Type: object - `referer` (required) Type: string The origin from which the visit was performed - `date` (required) Type: string, date-time The date in which the visit was performed - `userAgent` (required) Type: string The user agent from which the visit was performed - `visitLocation` (required) Type: object - `cityName` (optional) Type: string - `countryCode` (optional) Type: string - `countryName` (optional) Type: string - `latitude` (optional) Type: number - `longitude` (optional) Type: number - `regionName` (optional) Type: string - `timezone` (optional) Type: string - `potentialBot` (required) Type: boolean Tells if Shlink thinks this visit comes potentially from a bot or crawler - `visitedUrl` (required) Type: string; nullable The originally visited URL that triggered the tracking of this visit - `redirectUrl` (optional) Type: string; nullable The URL to which the visitor was redirected, or null if a redirect did not occur, like for 404 requests or pixel tracking - `pagination` (optional) Type: object - `currentPage` (optional) Type: integer The number of current page. - `pagesCount` (optional) Type: integer The total number of pages that can be obtained. - `itemsPerPage` (optional) Type: integer The number of items for every page. - `itemsInCurrentPage` (optional) Type: integer The number of items in current page (could be smaller than itemsPerPage). - `totalItems` (optional) Type: integer The total number of items among all pages. ```json { "visits": { "data": [ { "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": null, "potentialBot": false, "visitedUrl": "https://s.test" }, { "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": false, "visitedUrl": "https://s.test" }, { "referer": null, "date": "2015-08-20T05:05:03+04:00", "userAgent": "some_web_crawler/1.4", "visitLocation": null, "potentialBot": true, "visitedUrl": "https://s.test" } ], "pagination": { "currentPage": 5, "pagesCount": 12, "itemsPerPage": 10, "itemsInCurrentPage": 10, "totalItems": 115 } } } ``` - 404: The short code does not belong to any short URL. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X GET 'https://s.test/rest/v3/short-urls/string/visits' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/short-urls/string/visits', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'https://s.test/rest/v3/short-urls/string/visits', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Delete visits for short URL `DELETE /rest/v{version}/short-urls/{shortCode}/visits` Delete all existing visits on the short URL behind provided short code. Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] - `shortCode` (path, string, required) - The short code for the short URL. Type: string - `domain` (query, string, optional) - The domain in which the short code should be searched for. Type: string Responses: - 200: Deleted visits Content type: application/json Type: object - `deletedVisits` (optional) Type: number Amount of affected visits ```json { "deletedVisits": 536 } ``` - 404: The short code does not belong to any short URL. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X DELETE 'https://s.test/rest/v3/short-urls/string/visits' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/short-urls/string/visits', { method: 'DELETE', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.delete( 'https://s.test/rest/v3/short-urls/string/visits', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## List visits for tag `GET /rest/v{version}/tags/{tag}/visits` Get the list of visits on any short URL which is tagged with provided tag. Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] - `tag` (path, string, required) - The tag from which we want to get the visits. Type: string - `startDate` (query, string, optional) - The date (in ISO-8601 format) from which we want to get visits. Type: string - `endDate` (query, string, optional) - The date (in ISO-8601 format) until which we want to get visits. Type: string - `page` (query, number, optional) - The page to display. Defaults to 1 Type: number - `itemsPerPage` (query, number, optional) - The amount of items to return on every page. Defaults to all the items Type: number - `excludeBots` (query, string, optional) - Tells if visits from potential bots should be excluded from the result set Type: string enum: ["true"] - `domain` (query, string, optional) - The domain in which the short code should be searched for. Type: string Responses: - 200: List of visits. Content type: application/json Type: object - `visits` (optional) Type: object - `data` (optional) Type: array Items: Type: object - `referer` (required) Type: string The origin from which the visit was performed - `date` (required) Type: string, date-time The date in which the visit was performed - `userAgent` (required) Type: string The user agent from which the visit was performed - `visitLocation` (required) Type: object - `cityName` (optional) Type: string - `countryCode` (optional) Type: string - `countryName` (optional) Type: string - `latitude` (optional) Type: number - `longitude` (optional) Type: number - `regionName` (optional) Type: string - `timezone` (optional) Type: string - `potentialBot` (required) Type: boolean Tells if Shlink thinks this visit comes potentially from a bot or crawler - `visitedUrl` (required) Type: string; nullable The originally visited URL that triggered the tracking of this visit - `redirectUrl` (optional) Type: string; nullable The URL to which the visitor was redirected, or null if a redirect did not occur, like for 404 requests or pixel tracking - `pagination` (optional) Type: object - `currentPage` (optional) Type: integer The number of current page. - `pagesCount` (optional) Type: integer The total number of pages that can be obtained. - `itemsPerPage` (optional) Type: integer The number of items for every page. - `itemsInCurrentPage` (optional) Type: integer The number of items in current page (could be smaller than itemsPerPage). - `totalItems` (optional) Type: integer The total number of items among all pages. ```json { "visits": { "data": [ { "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": null, "potentialBot": false, "visitedUrl": "https://s.test" }, { "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": false, "visitedUrl": "https://s.test" }, { "referer": null, "date": "2015-08-20T05:05:03+04:00", "userAgent": "some_web_crawler/1.4", "visitLocation": null, "potentialBot": true, "visitedUrl": "https://s.test" } ], "pagination": { "currentPage": 5, "pagesCount": 12, "itemsPerPage": 10, "itemsInCurrentPage": 10, "totalItems": 115 } } } ``` - 404: The tag does not exist. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X GET 'https://s.test/rest/v3/tags/string/visits' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/tags/string/visits', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'https://s.test/rest/v3/tags/string/visits', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## List visits for domain `GET /rest/v{version}/domains/{domain}/visits` Get the list of visits on any short URL which belongs to provided domain. Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] - `domain` (path, string, required) - The domain from which we want to get the visits, or **DEFAULT** keyword for default domain. Type: string - `startDate` (query, string, optional) - The date (in ISO-8601 format) from which we want to get visits. Type: string - `endDate` (query, string, optional) - The date (in ISO-8601 format) until which we want to get visits. Type: string - `page` (query, number, optional) - The page to display. Defaults to 1 Type: number - `itemsPerPage` (query, number, optional) - The amount of items to return on every page. Defaults to all the items Type: number - `excludeBots` (query, string, optional) - Tells if visits from potential bots should be excluded from the result set Type: string enum: ["true"] Responses: - 200: List of visits. Content type: application/json Type: object - `visits` (optional) Type: object - `data` (optional) Type: array Items: Type: object - `referer` (required) Type: string The origin from which the visit was performed - `date` (required) Type: string, date-time The date in which the visit was performed - `userAgent` (required) Type: string The user agent from which the visit was performed - `visitLocation` (required) Type: object - `cityName` (optional) Type: string - `countryCode` (optional) Type: string - `countryName` (optional) Type: string - `latitude` (optional) Type: number - `longitude` (optional) Type: number - `regionName` (optional) Type: string - `timezone` (optional) Type: string - `potentialBot` (required) Type: boolean Tells if Shlink thinks this visit comes potentially from a bot or crawler - `visitedUrl` (required) Type: string; nullable The originally visited URL that triggered the tracking of this visit - `redirectUrl` (optional) Type: string; nullable The URL to which the visitor was redirected, or null if a redirect did not occur, like for 404 requests or pixel tracking - `pagination` (optional) Type: object - `currentPage` (optional) Type: integer The number of current page. - `pagesCount` (optional) Type: integer The total number of pages that can be obtained. - `itemsPerPage` (optional) Type: integer The number of items for every page. - `itemsInCurrentPage` (optional) Type: integer The number of items in current page (could be smaller than itemsPerPage). - `totalItems` (optional) Type: integer The total number of items among all pages. ```json { "visits": { "data": [ { "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": null, "potentialBot": false, "visitedUrl": "https://s.test" }, { "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": false, "visitedUrl": "https://s.test" }, { "referer": null, "date": "2015-08-20T05:05:03+04:00", "userAgent": "some_web_crawler/1.4", "visitLocation": null, "potentialBot": true, "visitedUrl": "https://s.test" } ], "pagination": { "currentPage": 5, "pagesCount": 12, "itemsPerPage": 10, "itemsInCurrentPage": 10, "totalItems": 115 } } } ``` - 404: The domain does not exist. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X GET 'https://s.test/rest/v3/domains/string/visits' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/domains/string/visits', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'https://s.test/rest/v3/domains/string/visits', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## List orphan visits `GET /rest/v{version}/visits/orphan` Get the list of visits to invalid short URLs, the base URL or any other 404. Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] - `startDate` (query, string, optional) - The date (in ISO-8601 format) from which we want to get visits. Type: string - `endDate` (query, string, optional) - The date (in ISO-8601 format) until which we want to get visits. Type: string - `page` (query, number, optional) - The page to display. Defaults to 1 Type: number - `itemsPerPage` (query, number, optional) - The amount of items to return on every page. Defaults to all the items Type: number - `excludeBots` (query, string, optional) - Tells if visits from potential bots should be excluded from the result set Type: string enum: ["true"] - `type` (query, string, optional) - The type of visits to return. All visits are returned when not provided. Type: string enum: ["invalid_short_url","base_url","regular_404"] - `domain` (query, string, optional) - The domain in which the short code should be searched for. Type: string Responses: - 200: List of visits. Content type: application/json Type: object - `visits` (optional) Type: object - `data` (optional) Type: array Items: Type: object - `type` (required) Type: string Tells the type of orphan visit enum: ["invalid_short_url","base_url","regular_404"] allOf: Type: object - `referer` (required) Type: string The origin from which the visit was performed - `date` (required) Type: string, date-time The date in which the visit was performed - `userAgent` (required) Type: string The user agent from which the visit was performed - `visitLocation` (required) Type: object - `cityName` (optional) Type: string - `countryCode` (optional) Type: string - `countryName` (optional) Type: string - `latitude` (optional) Type: number - `longitude` (optional) Type: number - `regionName` (optional) Type: string - `timezone` (optional) Type: string - `potentialBot` (required) Type: boolean Tells if Shlink thinks this visit comes potentially from a bot or crawler - `visitedUrl` (required) Type: string; nullable The originally visited URL that triggered the tracking of this visit - `redirectUrl` (optional) Type: string; nullable The URL to which the visitor was redirected, or null if a redirect did not occur, like for 404 requests or pixel tracking - `pagination` (optional) Type: object - `currentPage` (optional) Type: integer The number of current page. - `pagesCount` (optional) Type: integer The total number of pages that can be obtained. - `itemsPerPage` (optional) Type: integer The number of items for every page. - `itemsInCurrentPage` (optional) Type: integer The number of items in current page (could be smaller than itemsPerPage). - `totalItems` (optional) Type: integer The total number of items among all pages. ```json { "visits": { "data": [ { "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": null, "potentialBot": false, "visitedUrl": "https://s.test", "type": "base_url" }, { "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": false, "visitedUrl": "https://s.test/foo", "type": "invalid_short_url" }, { "referer": null, "date": "2015-08-20T05:05:03+04:00", "userAgent": "some_web_crawler/1.4", "visitLocation": null, "potentialBot": true, "visitedUrl": "https://s.test/foo/bar/baz", "type": "regular_404" } ], "pagination": { "currentPage": 5, "pagesCount": 12, "itemsPerPage": 10, "itemsInCurrentPage": 10, "totalItems": 115 } } } ``` - 400: Provided query arguments are invalid. Content type: application/problem+json Type: object allOf: Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code Type: object - `invalidElements` (required) Type: array Items: Type: string enum: ["type"] - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X GET 'https://s.test/rest/v3/visits/orphan' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/visits/orphan', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'https://s.test/rest/v3/visits/orphan', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Delete orphan visits `DELETE /rest/v{version}/visits/orphan` Delete all visits to invalid short URLs, the base URL or any other 404. Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] Responses: - 200: Deleted visits Content type: application/json Type: object - `deletedVisits` (optional) Type: number Amount of affected visits ```json { "deletedVisits": 536 } ``` - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X DELETE 'https://s.test/rest/v3/visits/orphan' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/visits/orphan', { method: 'DELETE', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.delete( 'https://s.test/rest/v3/visits/orphan', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## List non-orphan visits `GET /rest/v{version}/visits/non-orphan` Get the list of visits to any short URL. Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] - `startDate` (query, string, optional) - The date (in ISO-8601 format) from which we want to get visits. Type: string - `endDate` (query, string, optional) - The date (in ISO-8601 format) until which we want to get visits. Type: string - `page` (query, number, optional) - The page to display. Defaults to 1 Type: number - `itemsPerPage` (query, number, optional) - The amount of items to return on every page. Defaults to all the items Type: number - `excludeBots` (query, string, optional) - Tells if visits from potential bots should be excluded from the result set Type: string enum: ["true"] - `domain` (query, string, optional) - The domain in which the short code should be searched for. Type: string Responses: - 200: List of visits. Content type: application/json Type: object - `visits` (optional) Type: object - `data` (optional) Type: array Items: Type: object - `referer` (required) Type: string The origin from which the visit was performed - `date` (required) Type: string, date-time The date in which the visit was performed - `userAgent` (required) Type: string The user agent from which the visit was performed - `visitLocation` (required) Type: object - `cityName` (optional) Type: string - `countryCode` (optional) Type: string - `countryName` (optional) Type: string - `latitude` (optional) Type: number - `longitude` (optional) Type: number - `regionName` (optional) Type: string - `timezone` (optional) Type: string - `potentialBot` (required) Type: boolean Tells if Shlink thinks this visit comes potentially from a bot or crawler - `visitedUrl` (required) Type: string; nullable The originally visited URL that triggered the tracking of this visit - `redirectUrl` (optional) Type: string; nullable The URL to which the visitor was redirected, or null if a redirect did not occur, like for 404 requests or pixel tracking - `pagination` (optional) Type: object - `currentPage` (optional) Type: integer The number of current page. - `pagesCount` (optional) Type: integer The total number of pages that can be obtained. - `itemsPerPage` (optional) Type: integer The number of items for every page. - `itemsInCurrentPage` (optional) Type: integer The number of items in current page (could be smaller than itemsPerPage). - `totalItems` (optional) Type: integer The total number of items among all pages. ```json { "visits": { "data": [ { "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": null, "potentialBot": false, "visitedUrl": "https://s.test" }, { "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": false, "visitedUrl": "https://s.test" }, { "referer": null, "date": "2015-08-20T05:05:03+04:00", "userAgent": "some_web_crawler/1.4", "visitLocation": null, "potentialBot": true, "visitedUrl": "https://s.test" } ], "pagination": { "currentPage": 5, "pagesCount": 12, "itemsPerPage": 10, "itemsInCurrentPage": 10, "totalItems": 115 } } } ``` - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X GET 'https://s.test/rest/v3/visits/non-orphan' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/visits/non-orphan', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'https://s.test/rest/v3/visits/non-orphan', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## List configured domains `GET /rest/v{version}/domains` 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. Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] Responses: - 200: The list of domains Content type: application/json Type: object - `domains` (required) Type: object - `data` (required) Type: array Items: Type: object - `domain` (required) Type: string - `isDefault` (required) Type: boolean - `redirects` (required) Type: object - `baseUrlRedirect` (optional) Type: string; nullable URL to redirect to when a user hits the domain's base URL - `regular404Redirect` (optional) Type: string; nullable URL to redirect to when a user hits a not found URL other than an invalid short URL - `invalidShortUrlRedirect` (optional) Type: string; nullable URL to redirect to when a user hits an invalid short URL - `defaultRedirects` (optional) Type: object - `baseUrlRedirect` (optional) Type: string; nullable URL to redirect to when a user hits the domain's base URL - `regular404Redirect` (optional) Type: string; nullable URL to redirect to when a user hits a not found URL other than an invalid short URL - `invalidShortUrlRedirect` (optional) Type: string; nullable URL to redirect to when a user hits an invalid short URL ```json { "domains": { "data": [ { "domain": "example.com", "isDefault": true, "redirects": { "baseUrlRedirect": "https://example.com/my-landing-page", "regular404Redirect": null, "invalidShortUrlRedirect": "https://example.com/invalid-url" } }, { "domain": "aaa.com", "isDefault": false, "redirects": { "baseUrlRedirect": null, "regular404Redirect": null, "invalidShortUrlRedirect": null } }, { "domain": "bbb.com", "isDefault": false, "redirects": { "baseUrlRedirect": null, "regular404Redirect": null, "invalidShortUrlRedirect": "https://example.com/invalid-url" } } ], "defaultRedirects": { "baseUrlRedirect": "https://somewhere.com", "regular404Redirect": null, "invalidShortUrlRedirect": null } } } ``` - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X GET 'https://s.test/rest/v3/domains' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/domains', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'https://s.test/rest/v3/domains', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Sets domain "not found" redirects `PATCH /rest/v{version}/domains/redirects` Sets the URLs that you want a visitor to get redirected to for "not found" URLs for a specific domain Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] Request body: application/json (required) Request body. Type: object allOf: Type: object - `domain` (required) Type: string The domain's authority for which you want to set redirects Type: object - `baseUrlRedirect` (optional) Type: string; nullable URL to redirect to when a user hits the domain's base URL - `regular404Redirect` (optional) Type: string; nullable URL to redirect to when a user hits a not found URL other than an invalid short URL - `invalidShortUrlRedirect` (optional) Type: string; nullable URL to redirect to when a user hits an invalid short URL Responses: - 200: The domain's redirects after the update, when existing redirects have been merged with provided ones. Content type: application/json Type: unknown allOf: Type: unknown Type: object - `baseUrlRedirect` (optional) Type: string; nullable URL to redirect to when a user hits the domain's base URL - `regular404Redirect` (optional) Type: string; nullable URL to redirect to when a user hits a not found URL other than an invalid short URL - `invalidShortUrlRedirect` (optional) Type: string; nullable URL to redirect to when a user hits an invalid short URL ```json { "baseUrlRedirect": "https://example.com/my-landing-page", "regular404Redirect": null, "invalidShortUrlRedirect": "https://example.com/invalid-url" } ``` - 400: Provided data is invalid. Content type: application/problem+json Type: object allOf: Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code Type: object - `invalidElements` (required) Type: array Items: Type: string enum: ["domain","baseUrlRedirect","regular404Redirect","invalidShortUrlRedirect"] - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X PATCH 'https://s.test/rest/v3/domains/redirects' \ -H 'X-Api-Key: YOUR_TOKEN' \ -H 'Content-Type: application/json' \ --data-raw '{ "domain": "string", "baseUrlRedirect": "string", "regular404Redirect": "string", "invalidShortUrlRedirect": "string" }' ``` ### JavaScript ```javascript const body = `{ "domain": "string", "baseUrlRedirect": "string", "regular404Redirect": "string", "invalidShortUrlRedirect": "string" }`; const response = await fetch('https://s.test/rest/v3/domains/redirects', { method: 'PATCH', headers: { 'X-Api-Key': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, body, }); const data = await response.text(); ``` ### Python ```python import requests body = '''{ "domain": "string", "baseUrlRedirect": "string", "regular404Redirect": "string", "invalidShortUrlRedirect": "string" }''' response = requests.patch( 'https://s.test/rest/v3/domains/redirects', data=body.encode('utf-8'), headers={ 'X-Api-Key': 'YOUR_TOKEN', 'Content-Type': 'application/json', }, ) print(response.text) ``` ## Get mercure integration info `GET /rest/v{version}/mercure-info` Returns information to consume updates published by Shlink on a mercure hub. https://mercure.rocks/ Authentication (security requirement alternatives): ```json [ { "ApiKey": [] } ] ``` - ApiKey: apiKey, header X-Api-Key. A valid shlink API key Parameters: - `version` (path, string, required) - The API version to be consumed Type: string enum: ["3","2","1"] Responses: - 200: The mercure integration info Content type: application/json Type: object - `mercureHubUrl` (required) Type: string The public URL of the mercure hub that can be used to get real-time updates published by Shlink - `jwt` (required) Type: string A JWT with subscribe permissions which is valid with the mercure hub - `jwtExpiration` (required) Type: string The date (in ISO-8601 format) in which the JWT will expire ```json { "mercureHubUrl": "https://example.com/.well-known/mercure", "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJTaGxpbmsiLCJpYXQiOjE1ODY2ODY3MzIsImV4cCI6MTU4Njk0NTkzMiwibWVyY3VyZSI6eyJzdWJzY3JpYmUiOltdfX0.P-519lgU7dFz0bbNlRG1CXyqugGbaHon4kw6fu4QBdQ", "jwtExpiration": "2020-04-15T12:18:52+02:00" } ``` - 501: This Shlink instance is not integrated with a mercure hub Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code - default: Unexpected error. Content type: application/problem+json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X GET 'https://s.test/rest/v3/mercure-info' \ -H 'X-Api-Key: YOUR_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/v3/mercure-info', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_TOKEN', }, }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get( 'https://s.test/rest/v3/mercure-info', headers={ 'X-Api-Key': 'YOUR_TOKEN', }, ) print(response.text) ``` ## Check healthiness `GET /rest/health` Checks the healthiness of the service, making sure it can access required resources. Authentication: no security requirement declared for this operation. Responses: - 200: The passing health status Content type: application/json Type: object - `status` (optional) Type: string The status of the service enum: ["pass","fail"] - `version` (optional) Type: string Shlink version - `links` (optional) Type: object A list of links - `about` (optional) Type: string About shlink - `project` (optional) Type: string Shlink project repository ```json { "status": "pass", "version": "2.10.0", "links": { "about": "https://shlink.io", "project": "https://github.com/shlinkio/shlink" } } ``` - 503: The failing health status Content type: application/json Type: object - `status` (optional) Type: string The status of the service enum: ["pass","fail"] - `version` (optional) Type: string Shlink version - `links` (optional) Type: object A list of links - `about` (optional) Type: string About shlink - `project` (optional) Type: string Shlink project repository ```json { "status": "fail", "version": "2.10.0", "links": { "about": "https://shlink.io", "project": "https://github.com/shlinkio/shlink" } } ``` - default: Unexpected error. Content type: application/json Type: object - `type` (required) Type: string A machine unique code - `title` (required) Type: string A unique title - `detail` (required) Type: string A human-friendly error description - `status` (required) Type: number HTTP response status code ## Examples ### cURL ```bash curl -X GET 'https://s.test/rest/health' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/rest/health', { method: 'GET', }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get('https://s.test/rest/health') print(response.text) ``` ## Short URL `GET /{shortCode}` Represents a short URL. Tracks the visit and redirects tio the corresponding long URL Authentication: no security requirement declared for this operation. Parameters: - `shortCode` (path, string, required) - The short code for the short URL. Type: string Responses: - 302: Visit properly tracked and redirected ## Examples ### cURL ```bash curl -X GET 'https://s.test/string' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/string', { method: 'GET', }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get('https://s.test/string') print(response.text) ``` ## Short URL tracking pixel `GET /{shortCode}/track` Generates a 1px transparent image which can be used to track emails with a short URL Authentication: no security requirement declared for this operation. Parameters: - `shortCode` (path, string, required) - The short code for the short URL. Type: string Responses: - 200: Image in GIF format Content type: image/gif Type: string, binary ## Examples ### cURL ```bash curl -X GET 'https://s.test/string/track' ``` ### JavaScript ```javascript const response = await fetch('https://s.test/string/track', { method: 'GET', }); const data = await response.text(); ``` ### Python ```python import requests response = requests.get('https://s.test/string/track') print(response.text) ```