# 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. (Since v1.3.0)
Type: string
- `tags[]` (query, array, optional) - A list of tags used to filter the result set. Only short URLs tagged with at least one of the provided tags will be returned. (Since v1.3.0)
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. It's ignored if no tags are provided, and defaults to "any" if 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"]
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.
- `deviceLongUrls` (required)
Type: object
allOf:
Type: object
- `android` (optional)
Type: ; nullable
- `ios` (optional)
Type: ; nullable
- `desktop` (optional)
Type: ; nullable
allOf:
Type: object
- `android` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a device running Android
- `ios` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a device running iOS
- `desktop` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a desktop browser
- `dateCreated` (required)
Type: string, date-time
The date in which the short URL was created in ISO format.
- `visitsCount` (required)
Type: integer
**[DEPRECATED]** Use `visitsSummary.total` instead.
deprecated: true
- `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).
- `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",
"deviceLongUrls": {
"android": null,
"ios": null,
"desktop": null
},
"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
},
{
"shortCode": "12Kb3",
"shortUrl": "https://s.test/12Kb3",
"longUrl": "https://shlink.io",
"deviceLongUrls": {
"android": null,
"ios": "https://shlink.io/ios",
"desktop": null
},
"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
},
{
"shortCode": "123bA",
"shortUrl": "https://example.com/123bA",
"longUrl": "https://www.google.com",
"deviceLongUrls": {
"android": null,
"ios": null,
"desktop": null
},
"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
}
],
"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
- `deviceLongUrls` (optional)
Type: object
- `android` (optional)
Type: ; nullable
- `ios` (optional)
Type: ; nullable
- `desktop` (optional)
Type: ; nullable
allOf:
Type: object
- `android` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a device running Android
- `ios` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a device running iOS
- `desktop` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a desktop browser
- `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
- `validateUrl` (optional)
Type: boolean
**[DEPRECATED]** Tells if the long URL should or should not be validated as a reachable URL. Defaults to `false`
deprecated: true
- `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
- `deviceLongUrls` (optional)
Type: object
- `android` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a device running Android
- `ios` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a device running iOS
- `desktop` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a desktop browser
- `customSlug` (optional)
Type: string
A unique custom slug to be used instead of the 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.
- `deviceLongUrls` (required)
Type: object
allOf:
Type: object
- `android` (optional)
Type: ; nullable
- `ios` (optional)
Type: ; nullable
- `desktop` (optional)
Type: ; nullable
allOf:
Type: object
- `android` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a device running Android
- `ios` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a device running iOS
- `desktop` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a desktop browser
- `dateCreated` (required)
Type: string, date-time
The date in which the short URL was created in ISO format.
- `visitsCount` (required)
Type: integer
**[DEPRECATED]** Use `visitsSummary.total` instead.
deprecated: true
- `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).
```json
{
"shortCode": "12C18",
"shortUrl": "https://s.test/12C18",
"longUrl": "https://store.steampowered.com",
"deviceLongUrls": {
"android": null,
"ios": null,
"desktop": null
},
"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
}
```
- 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","maxVisits","findIfExists","domain"]
- `url` (optional)
Type: string
A URL that could not be verified, if the error type is https://shlink.io/api/error/invalid-url
- `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",
"deviceLongUrls": {
"android": "string",
"ios": "string",
"desktop": "string"
},
"validSince": "string",
"validUntil": "string",
"maxVisits": 0,
"validateUrl": true,
"tags": [
"string"
],
"title": "string",
"crawlable": true,
"forwardQuery": true,
"customSlug": "string",
"findIfExists": true,
"domain": "string",
"shortCodeLength": 0
}'
```
### JavaScript
```javascript
const body = `{
"longUrl": "string",
"deviceLongUrls": {
"android": "string",
"ios": "string",
"desktop": "string"
},
"validSince": "string",
"validUntil": "string",
"maxVisits": 0,
"validateUrl": true,
"tags": [
"string"
],
"title": "string",
"crawlable": true,
"forwardQuery": true,
"customSlug": "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",
"deviceLongUrls": {
"android": "string",
"ios": "string",
"desktop": "string"
},
"validSince": "string",
"validUntil": "string",
"maxVisits": 0,
"validateUrl": true,
"tags": [
"string"
],
"title": "string",
"crawlable": true,
"forwardQuery": true,
"customSlug": "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/v3/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.
- `deviceLongUrls` (required)
Type: object
allOf:
Type: object
- `android` (optional)
Type: ; nullable
- `ios` (optional)
Type: ; nullable
- `desktop` (optional)
Type: ; nullable
allOf:
Type: object
- `android` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a device running Android
- `ios` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a device running iOS
- `desktop` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a desktop browser
- `dateCreated` (required)
Type: string, date-time
The date in which the short URL was created in ISO format.
- `visitsCount` (required)
Type: integer
**[DEPRECATED]** Use `visitsSummary.total` instead.
deprecated: true
- `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).
```json
{
"longUrl": "https://github.com/shlinkio/shlink",
"deviceLongUrls": {
"android": null,
"ios": null,
"desktop": null
},
"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
}
```
Content type: text/plain
Type: string
```json
"https://s.test/abc123"
```
- 400: The long URL was not provided or is invalid.
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
- 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.
- `deviceLongUrls` (required)
Type: object
allOf:
Type: object
- `android` (optional)
Type: ; nullable
- `ios` (optional)
Type: ; nullable
- `desktop` (optional)
Type: ; nullable
allOf:
Type: object
- `android` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a device running Android
- `ios` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a device running iOS
- `desktop` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a desktop browser
- `dateCreated` (required)
Type: string, date-time
The date in which the short URL was created in ISO format.
- `visitsCount` (required)
Type: integer
**[DEPRECATED]** Use `visitsSummary.total` instead.
deprecated: true
- `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).
```json
{
"shortCode": "12Kb3",
"shortUrl": "https://s.test/12Kb3",
"longUrl": "https://shlink.io",
"deviceLongUrls": {
"android": null,
"ios": null,
"desktop": null
},
"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
}
```
- 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
- `deviceLongUrls` (optional)
Type: object
- `android` (optional)
Type: ; nullable
- `ios` (optional)
Type: ; nullable
- `desktop` (optional)
Type: ; nullable
allOf:
Type: object
- `android` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a device running Android
- `ios` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a device running iOS
- `desktop` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a desktop browser
- `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
- `validateUrl` (optional)
Type: boolean
**[DEPRECATED]** Tells if the long URL should or should not be validated as a reachable URL. Defaults to `false`
deprecated: true
- `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.
- `deviceLongUrls` (required)
Type: object
allOf:
Type: object
- `android` (optional)
Type: ; nullable
- `ios` (optional)
Type: ; nullable
- `desktop` (optional)
Type: ; nullable
allOf:
Type: object
- `android` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a device running Android
- `ios` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a device running iOS
- `desktop` (optional)
Type: string
The long URL to redirect to when the short URL is visited from a desktop browser
- `dateCreated` (required)
Type: string, date-time
The date in which the short URL was created in ISO format.
- `visitsCount` (required)
Type: integer
**[DEPRECATED]** Use `visitsSummary.total` instead.
deprecated: true
- `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).
```json
{
"shortCode": "12Kb3",
"shortUrl": "https://s.test/12Kb3",
"longUrl": "https://shlink.io",
"deviceLongUrls": {
"android": "https://shlink.io/android",
"ios": null,
"desktop": null
},
"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
}
```
- 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",
"deviceLongUrls": {
"android": "string",
"ios": "string",
"desktop": "string"
},
"validSince": "string",
"validUntil": "string",
"maxVisits": 0,
"validateUrl": true,
"tags": [
"string"
],
"title": "string",
"crawlable": true,
"forwardQuery": true
}'
```
### JavaScript
```javascript
const body = `{
"longUrl": "string",
"deviceLongUrls": {
"android": "string",
"ios": "string",
"desktop": "string"
},
"validSince": "string",
"validUntil": "string",
"maxVisits": 0,
"validateUrl": true,
"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",
"deviceLongUrls": {
"android": "string",
"ios": "string",
"desktop": "string"
},
"validSince": "string",
"validUntil": "string",
"maxVisits": 0,
"validateUrl": true,
"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 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"]
- `withStats` (query, string, optional) - **[Deprecated]** Use [GET /tags/stats](https://sourcey-shlink.pages.dev/documentation/api/v3/index.md#operation-rest-v-version-tags-stats-get) endpoint to get tags with their stats.
Type: string
enum: ["true","false"]
- `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
- `stats` (optional)
Type: array
The tag stats will be returned only if the withStats param was provided with value 'true'
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.
- `visitsCount` (required)
Type: number
**[DEPRECATED]** Use visitsSummary.total instead
deprecated: true
- `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.
- `visitsCount` (required)
Type: number
**[DEPRECATED]** Use visitsSummary.total instead
deprecated: true
- `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.
- `visitsCount` (required)
Type: number
**[DEPRECATED]** Use nonOrphanVisits.total instead
deprecated: true
- `orphanVisitsCount` (required)
Type: number
**[DEPRECATED]** Use orphanVisits.total instead
deprecated: true
```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` (optional)
Type: boolean
Tells if Shlink thinks this visit comes potentially from a bot or crawler
- `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
},
{
"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
},
{
"referer": null,
"date": "2015-08-20T05:05:03+04:00",
"userAgent": "some_web_crawler/1.4",
"visitLocation": null,
"potentialBot": true
}
],
"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"]
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` (optional)
Type: boolean
Tells if Shlink thinks this visit comes potentially from a bot or crawler
- `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
},
{
"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
},
{
"referer": null,
"date": "2015-08-20T05:05:03+04:00",
"userAgent": "some_web_crawler/1.4",
"visitLocation": null,
"potentialBot": true
}
],
"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` (optional)
Type: boolean
Tells if Shlink thinks this visit comes potentially from a bot or crawler
- `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
},
{
"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
},
{
"referer": null,
"date": "2015-08-20T05:05:03+04:00",
"userAgent": "some_web_crawler/1.4",
"visitLocation": null,
"potentialBot": true
}
],
"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"]
Responses:
- 200: List of visits.
Content type: application/json
Type: object
- `visits` (optional)
Type: object
- `data` (optional)
Type: array
Items:
Type: object
- `visitedUrl` (required)
Type: string; nullable
The originally visited URL that triggered the tracking of this visit
- `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` (optional)
Type: boolean
Tells if Shlink thinks this visit comes potentially from a bot or crawler
- `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
}
}
}
```
- 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"]
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` (optional)
Type: boolean
Tells if Shlink thinks this visit comes potentially from a bot or crawler
- `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
},
{
"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
},
{
"referer": null,
"date": "2015-08-20T05:05:03+04:00",
"userAgent": "some_web_crawler/1.4",
"visitLocation": null,
"potentialBot": 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/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)
```
## Short URL QR code
`GET /{shortCode}/qr-code`
Generates a QR code image pointing to a short URL.
Since this is not an API endpoint but an image one, when an invalid value is provided for any of the query params, they will fall to their default values instead of throwing an error.
Authentication: no security requirement declared for this operation.
Parameters:
- `shortCode` (path, string, required) - The short code for the short URL.
Type: string
- `size` (query, integer, optional) - The size of the image to be returned.
Type: integer
default: 300
minimum: 50
maximum: 1000
- `format` (query, string, optional) - The format for the QR code image, being valid values png and svg. Not providing the param or providing any other value will fall back to png.
Type: string
default: "png"
enum: ["png","svg"]
- `margin` (query, integer, optional) - The margin around the QR code image.
Type: integer
default: 0
minimum: 0
- `errorCorrection` (query, string, optional) - The error correction level to apply to the QR code: **[L]**ow, **[M]**edium, **[Q]**uartile or **[H]**igh. See [docs](https://www.qrcode.com/en/about/error_correction.html).
Type: string
default: "L"
enum: ["L","M","Q","H"]
- `roundBlockSize` (query, string, optional) - Allows to disable block size rounding, which might reduce the readability of the QR code, but ensures no extra margin is added.
Type: string
default: "false"
enum: ["true","false"]
Responses:
- 200: QR code in PNG format
Content type: image/png
Type: string, binary
Content type: image/svg+xml
Type: string, binary
## Examples
### cURL
```bash
curl -X GET 'https://s.test/string/qr-code?size=300&format=png&margin=0&errorCorrection=L&roundBlockSize=false'
```
### JavaScript
```javascript
const response = await fetch('https://s.test/string/qr-code?size=300&format=png&margin=0&errorCorrection=L&roundBlockSize=false', {
method: 'GET',
});
const data = await response.text();
```
### Python
```python
import requests
response = requests.get('https://s.test/string/qr-code?size=300&format=png&margin=0&errorCorrection=L&roundBlockSize=false')
print(response.text)
```