Shlink REST API

v3.0

Base URL

{scheme}://{host}

scheme: default https; one of https, http
host: default s.test

Shlink, the self-hosted URL shortener

Find more info on how to start using this API here

Authentication

ApiKeyapiKey

A valid shlink API key

API Key: X-Api-Key in header

Short URLs

Operations that can be performed on short URLs

List short URLs

GET

https://s.test/rest/v{version}/short-urls

Returns the list of short URLs.

List short URLs

curl -X GET 'https://s.test/rest/v3/short-urls' \
  -H 'X-Api-Key: YOUR_TOKEN'

const response = await fetch('https://s.test/rest/v3/short-urls', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://s.test/rest/v3/short-urls',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "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
    }
  }
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

pageintegerquery

The page to be displayed. Defaults to 1

itemsPerPagenumberquery

The amount of items to return on every page. Defaults to 10

searchTermstringquery

A query used to filter results by searching for it on the longUrl and shortCode fields.

tags[]Array<string>query

A list of tags used to filter the result set. Only short URLs with these tags will be returned.

tagsModestringanyallquery

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.

excludeTags[]Array<string>query

A list of tags used to filter the result set. Only short URLs without these tags will be returned.

excludeTagsModestringanyallquery

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.

orderBystringlongUrl-ASClongUrl-DESCshortCode-ASCshortCode-DESCdateCreated-ASCdateCreated-DESCtitle-ASCtitle-DESCvisits-ASCvisits-DESCnonBotVisits-ASCnonBotVisits-DESCquery

The field from which you want to order the result.

startDatestringquery

The date (in ISO-8601 format) from which we want to get short URLs.

endDatestringquery

The date (in ISO-8601 format) until which we want to get short URLs.

excludeMaxVisitsReachedstringtruefalsequery

If true, short URLs which already reached their maximum amount of visits will be excluded.

excludePastValidUntilstringtruefalsequery

If true, short URLs which validUntil date is on the past will be excluded.

domainstringquery

Get short URLs for this particular domain only. Use DEFAULT keyword for default domain.

apiKeyNamestringquery

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.

Response

200OKobject

The list of short URLs

Response fields application/json

shortUrlsobject

Show child attributes

dataArray<object>

Show child attributes

shortCodestringrequired

The short code for this short URL.

shortUrlstringrequired

The short URL.

longUrlstringrequired

The original long URL.

dateCreatedstring<date-time>required

The date in which the short URL was created in ISO format.

visitsSummaryobjectrequired

Show child attributes

totalintegerrequired

The total amount of visits.

nonBotsintegerrequired

The amount of visits which were not identified as bots.

botsintegerrequired

The amount of visits that were identified as potential bots.

tagsArray<string>required

A list of tags applied to this short URL

metaobjectrequired

Show child attributes

validSincestring | nullrequired

The date (in ISO-8601 format) from which this short code will be valid

validUntilstring | nullrequired

The date (in ISO-8601 format) until which this short code will be valid

maxVisitsnumber | nullrequired

The maximum number of allowed visits for this short code

domainstring | nullrequired

The domain in which the short URL was created. Null if it belongs to default domain.

titlestring | nullrequired

A descriptive title of the short URL.

crawlablebooleanrequired

Tells if this URL will be included as ‘Allow’ in Shlink’s robots.txt.

forwardQuerybooleanrequired

Tells if this URL will forward the query params to the long URL when visited, as explained in the docs.

hasRedirectRulesbooleanrequired

Whether this short URL has redirect rules attached to it or not. Use this endpoint to get the actual list of rules.

paginationobject

Show child attributes

currentPageinteger

The number of current page.

pagesCountinteger

The total number of pages that can be obtained.

itemsPerPageinteger

The number of items for every page.

itemsInCurrentPageinteger

The number of items in current page (could be smaller than itemsPerPage).

totalItemsinteger

The total number of items among all pages.

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

Create short URL

POST

https://s.test/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.

Create short URL

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
}'

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();

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)

Request 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
}

{
  "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
}

{
  "title": "Invalid data",
  "type": "https://shlink.io/api/error/invalid-data",
  "detail": "Provided data is not valid",
  "status": 400,
  "invalidElements": [
    "maxVisits",
    "validSince"
  ]
}

{
  "title": "Invalid custom slug",
  "type": "https://shlink.io/api/error/non-unique-slug",
  "detail": "Provided slug \"my-slug\" is already in use.",
  "status": 400,
  "customSlug": "my-slug"
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Body

application/json

Request body.

longUrlstring

The long URL this short URL will redirect to

validSincestring | null

The date (in ISO-8601 format) from which this short code will be valid

validUntilstring | null

The date (in ISO-8601 format) until which this short code will be valid

maxVisitsnumber | null

The maximum number of allowed visits for this short code

tagsArray<string>

The list of tags to set to the short URL.

titlestring | null

A descriptive title of the short URL.

crawlableboolean

Tells if this URL will be included as ‘Allow’ in Shlink’s robots.txt.

forwardQueryboolean

Tells if the query params should be forwarded from the short URL to the long one, as explained in the docs.

customSlugstring

A unique custom slug to be used instead of the generated short code

pathPrefixstring

A prefix that will be prepended to provided custom slug or auto-generated short code

findIfExistsboolean

Will force existing matching URL to be returned if found, instead of creating a new one

domainstring

The domain to which the short URL will be attached

shortCodeLengthnumber

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

Parameters

versionstring321requiredpath

The API version to be consumed

Response

200OKobject

The result of parsing the long URL

Response fields application/json

shortCodestringrequired

The short code for this short URL.

shortUrlstringrequired

The short URL.

longUrlstringrequired

The original long URL.

dateCreatedstring<date-time>required

The date in which the short URL was created in ISO format.

visitsSummaryobjectrequired

Show child attributes

totalintegerrequired

The total amount of visits.

nonBotsintegerrequired

The amount of visits which were not identified as bots.

botsintegerrequired

The amount of visits that were identified as potential bots.

tagsArray<string>required

A list of tags applied to this short URL

metaobjectrequired

Show child attributes

validSincestring | nullrequired

The date (in ISO-8601 format) from which this short code will be valid

validUntilstring | nullrequired

The date (in ISO-8601 format) until which this short code will be valid

maxVisitsnumber | nullrequired

The maximum number of allowed visits for this short code

domainstring | nullrequired

The domain in which the short URL was created. Null if it belongs to default domain.

titlestring | nullrequired

A descriptive title of the short URL.

crawlablebooleanrequired

Tells if this URL will be included as ‘Allow’ in Shlink’s robots.txt.

forwardQuerybooleanrequired

Tells if this URL will forward the query params to the long URL when visited, as explained in the docs.

hasRedirectRulesbooleanrequired

Whether this short URL has redirect rules attached to it or not. Use this endpoint to get the actual list of rules.

400Bad Requestobject

Some of provided data is invalid. Check extra fields to know exactly what.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

invalidElementsArray<string>validSincevalidUntilcustomSlugpathPrefixmaxVisitsfindIfExistsdomain

customSlugstring

Provided custom slug when the error type is https://shlink.io/api/error/non-unique-slug

domainstring

The domain for which you were trying to create the new short URL

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

Create a short URL

deprecated

GET

https://s.test/rest/v{version}/short-urls/shorten

[Deprecated] Use Create short URL instead

Create a short URL

curl -X GET 'https://s.test/rest/v3/short-urls/shorten?apiKey=string&longUrl=string'

const response = await fetch('https://s.test/rest/v3/short-urls/shorten?apiKey=string&longUrl=string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://s.test/rest/v3/short-urls/shorten?apiKey=string&longUrl=string')
print(response.text)

{
  "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
}

https://s.test/abc123

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

string

Parameters

versionstring321requiredpath

The API version to be consumed

apiKeystringrequiredquery

The API key used to authenticate the request

longUrlstringrequiredquery

The URL to be shortened

formatstringtxtjsonquery

The format in which you want the response to be returned. You can also use the “Accept” header instead of this

Response

200OKobject

The list of short URLs

Response fields application/json

shortCodestringrequired

The short code for this short URL.

shortUrlstringrequired

The short URL.

longUrlstringrequired

The original long URL.

dateCreatedstring<date-time>required

The date in which the short URL was created in ISO format.

visitsSummaryobjectrequired

Show child attributes

totalintegerrequired

The total amount of visits.

nonBotsintegerrequired

The amount of visits which were not identified as bots.

botsintegerrequired

The amount of visits that were identified as potential bots.

tagsArray<string>required

A list of tags applied to this short URL

metaobjectrequired

Show child attributes

validSincestring | nullrequired

The date (in ISO-8601 format) from which this short code will be valid

validUntilstring | nullrequired

The date (in ISO-8601 format) until which this short code will be valid

maxVisitsnumber | nullrequired

The maximum number of allowed visits for this short code

domainstring | nullrequired

The domain in which the short URL was created. Null if it belongs to default domain.

titlestring | nullrequired

A descriptive title of the short URL.

crawlablebooleanrequired

Tells if this URL will be included as ‘Allow’ in Shlink’s robots.txt.

forwardQuerybooleanrequired

Tells if this URL will forward the query params to the long URL when visited, as explained in the docs.

hasRedirectRulesbooleanrequired

Whether this short URL has redirect rules attached to it or not. Use this endpoint to get the actual list of rules.

Response fields text/plain

string

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Response fields text/plain

string

Parse short code

GET

https://s.test/rest/v{version}/short-urls/{shortCode}

Get the long URL behind a short URL’s short code.

Parse short code

curl -X GET 'https://s.test/rest/v3/short-urls/string' \
  -H 'X-Api-Key: YOUR_TOKEN'

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();

import requests

response = requests.get(
    'https://s.test/rest/v3/short-urls/string',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "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
}

{
  "detail": "No URL found with short code \"abc123\"",
  "title": "Short URL not found",
  "type": "https://shlink.io/api/error/short-url-not-found",
  "status": 404,
  "shortCode": "abc123"
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

shortCodestringrequiredpath

The short code for the short URL.

domainstringquery

The domain in which the short code should be searched for.

Response

200OKobject

The URL info behind a short code.

Response fields application/json

shortCodestringrequired

The short code for this short URL.

shortUrlstringrequired

The short URL.

longUrlstringrequired

The original long URL.

dateCreatedstring<date-time>required

The date in which the short URL was created in ISO format.

visitsSummaryobjectrequired

Show child attributes

totalintegerrequired

The total amount of visits.

nonBotsintegerrequired

The amount of visits which were not identified as bots.

botsintegerrequired

The amount of visits that were identified as potential bots.

tagsArray<string>required

A list of tags applied to this short URL

metaobjectrequired

Show child attributes

validSincestring | nullrequired

The date (in ISO-8601 format) from which this short code will be valid

validUntilstring | nullrequired

The date (in ISO-8601 format) until which this short code will be valid

maxVisitsnumber | nullrequired

The maximum number of allowed visits for this short code

domainstring | nullrequired

The domain in which the short URL was created. Null if it belongs to default domain.

titlestring | nullrequired

A descriptive title of the short URL.

crawlablebooleanrequired

Tells if this URL will be included as ‘Allow’ in Shlink’s robots.txt.

forwardQuerybooleanrequired

Tells if this URL will forward the query params to the long URL when visited, as explained in the docs.

hasRedirectRulesbooleanrequired

Whether this short URL has redirect rules attached to it or not. Use this endpoint to get the actual list of rules.

404Not Foundobject

No URL was found for provided short code.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

shortCodestringrequired

The short code with which we tried to find the short URL

domainstring

The domain with which we tried to find the short URL

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

Delete short URL

DELETE

https://s.test/rest/v{version}/short-urls/{shortCode}

Deletes the short URL for provided short code.

Delete short URL

curl -X DELETE 'https://s.test/rest/v3/short-urls/string' \
  -H 'X-Api-Key: YOUR_TOKEN'

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();

import requests

response = requests.delete(
    'https://s.test/rest/v3/short-urls/string',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "detail": "No URL found with short code \"abc123\"",
  "title": "Short URL not found",
  "type": "https://shlink.io/api/error/short-url-not-found",
  "status": 404,
  "shortCode": "abc123"
}

{
  "title": "Cannot delete short URL",
  "type": "https://shlink.io/api/error/invalid-short-url-deletion",
  "detail": "Impossible to delete short URL with short code \"abc123\", since it has more than \"15\" visits.",
  "status": 422,
  "shortCode": "abc123",
  "threshold": 15
}

{
  "title": "Cannot delete short URL",
  "type": "INVALID_SHORT_URL_DELETION",
  "detail": "Impossible to delete short URL with short code \"abc123\", since it has more than \"15\" visits.",
  "status": 422,
  "shortCode": "abc123",
  "threshold": 15
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

shortCodestringrequiredpath

The short code for the short URL.

domainstringquery

The domain in which the short code should be searched for.

Response

204No Content

The short URL has been properly deleted.

404Not Foundobject

No URL was found for provided short code.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

shortCodestringrequired

The short code with which we tried to find the short URL

domainstring

The domain with which we tried to find the short URL

422Unprocessable Entityobject

The visits threshold in shlink does not allow this short URL to be deleted.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

shortCodestringrequired

The short code with which we tried to find the short URL to delete

domainstring

The domain with which we tried to find the short URL to delete

thresholdnumberrequired

The amount of visits currently configured as threshold to allow deleting short URLs or not

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

Edit short URL

PATCH

https://s.test/rest/v{version}/short-urls/{shortCode}

Update certain meta arguments from an existing short URL.

Edit short URL

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
}'

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();

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)

Request Body

{
  "longUrl": "string",
  "validSince": "string",
  "validUntil": "string",
  "maxVisits": 0,
  "tags": [
    "string"
  ],
  "title": "string",
  "crawlable": true,
  "forwardQuery": 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": "2017-01-21T00:00:00+02:00",
    "validUntil": null,
    "maxVisits": 100
  },
  "domain": null,
  "title": "Shlink - The URL shortener",
  "crawlable": false,
  "forwardQuery": false,
  "hasRedirectRules": true
}

{
  "title": "Invalid data",
  "type": "https://shlink.io/api/error/invalid-data",
  "detail": "Provided data is not valid",
  "status": 400,
  "invalidElements": [
    "maxVisits",
    "validSince"
  ]
}

{
  "detail": "No URL found with short code \"abc123\"",
  "title": "Short URL not found",
  "type": "https://shlink.io/api/error/short-url-not-found",
  "status": 404,
  "shortCode": "abc123"
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Body

application/json

Request body.

longUrlstring

The long URL this short URL will redirect to

validSincestring | null

The date (in ISO-8601 format) from which this short code will be valid

validUntilstring | null

The date (in ISO-8601 format) until which this short code will be valid

maxVisitsnumber | null

The maximum number of allowed visits for this short code

tagsArray<string>

The list of tags to set to the short URL.

titlestring | null

A descriptive title of the short URL.

crawlableboolean

Tells if this URL will be included as ‘Allow’ in Shlink’s robots.txt.

forwardQueryboolean

Tells if the query params should be forwarded from the short URL to the long one, as explained in the docs.

Parameters

versionstring321requiredpath

The API version to be consumed

shortCodestringrequiredpath

The short code for the short URL.

domainstringquery

The domain in which the short code should be searched for.

Response

200OKobject

The short URL has been properly updated.

Response fields application/json

shortCodestringrequired

The short code for this short URL.

shortUrlstringrequired

The short URL.

longUrlstringrequired

The original long URL.

dateCreatedstring<date-time>required

The date in which the short URL was created in ISO format.

visitsSummaryobjectrequired

Show child attributes

totalintegerrequired

The total amount of visits.

nonBotsintegerrequired

The amount of visits which were not identified as bots.

botsintegerrequired

The amount of visits that were identified as potential bots.

tagsArray<string>required

A list of tags applied to this short URL

metaobjectrequired

Show child attributes

validSincestring | nullrequired

The date (in ISO-8601 format) from which this short code will be valid

validUntilstring | nullrequired

The date (in ISO-8601 format) until which this short code will be valid

maxVisitsnumber | nullrequired

The maximum number of allowed visits for this short code

domainstring | nullrequired

The domain in which the short URL was created. Null if it belongs to default domain.

titlestring | nullrequired

A descriptive title of the short URL.

crawlablebooleanrequired

Tells if this URL will be included as ‘Allow’ in Shlink’s robots.txt.

forwardQuerybooleanrequired

Tells if this URL will forward the query params to the long URL when visited, as explained in the docs.

hasRedirectRulesbooleanrequired

Whether this short URL has redirect rules attached to it or not. Use this endpoint to get the actual list of rules.

400Bad Requestobject

Provided meta arguments are invalid.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

invalidElementsArray<string>longUrlvalidSincevalidUntilmaxVisitsrequired

404Not Foundobject

No URL was found for provided short code.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

shortCodestringrequired

The short code with which we tried to find the short URL

domainstring

The domain with which we tried to find the short URL

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

Redirect rules

Handle dynamic rule-based redirects

List short URL redirect rules

GET

https://s.test/rest/v{version}/short-urls/{shortCode}/redirect-rules

Returns the list of redirect rules for a short URL.

List short URL redirect rules

curl -X GET 'https://s.test/rest/v3/short-urls/string/redirect-rules' \
  -H 'X-Api-Key: YOUR_TOKEN'

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();

import requests

response = requests.get(
    'https://s.test/rest/v3/short-urls/string/redirect-rules',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "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"
        }
      ]
    }
  ]
}

{
  "detail": "No URL found with short code \"abc123\"",
  "title": "Short URL not found",
  "type": "https://shlink.io/api/error/short-url-not-found",
  "status": 404,
  "shortCode": "abc123"
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

shortCodestringrequiredpath

The short code for the short URL.

domainstringquery

The domain in which the short code should be searched for.

Response

200OKobject

The list of rules

Response fields application/json

defaultLongUrlstringrequired

redirectRulesArray<object>required

Show child attributes

prioritynumberrequired

Order in which attempting to match the rule. Lower goes first

longUrlstringrequired

Long URL to redirect to when this condition matches

conditionsArray<object>required

List of conditions that need to match in order to consider this rule matches

Show child attributes

typestringdevicelanguagequery-paramany-value-query-paramvalueless-query-paramip-addressgeolocation-country-codegeolocation-city-namerequired

The type of the condition, which will determine the logic used to match it

matchKeystring | nullrequired

matchValuestring | nullrequired

404Not Foundobject

No URL was found for provided short code.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

shortCodestringrequired

The short code with which we tried to find the short URL

domainstring

The domain with which we tried to find the short URL

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

Set short URL redirect rules

POST

https://s.test/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.

Set short URL redirect rules

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"
        }
      ]
    }
  ]
}'

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();

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)

Request 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"
        }
      ]
    }
  ]
}

{
  "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"
        }
      ]
    }
  ]
}

{
  "detail": "No URL found with short code \"abc123\"",
  "title": "Short URL not found",
  "type": "https://shlink.io/api/error/short-url-not-found",
  "status": 404,
  "shortCode": "abc123"
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Body

application/json

Request body.

redirectRulesArray<object>

Show child attributes

longUrlstringrequired

Long URL to redirect to when this condition matches

conditionsArray<object>required

List of conditions that need to match in order to consider this rule matches

Show child attributes

typestringdevicelanguagequery-paramany-value-query-paramvalueless-query-paramip-addressgeolocation-country-codegeolocation-city-namerequired

The type of the condition, which will determine the logic used to match it

matchKeystring | nullrequired

matchValuestring | nullrequired

Parameters

versionstring321requiredpath

The API version to be consumed

shortCodestringrequiredpath

The short code for the short URL.

domainstringquery

The domain in which the short code should be searched for.

Response

200OKobject

The list of rules

Response fields application/json

defaultLongUrlstringrequired

redirectRulesArray<object>required

Show child attributes

prioritynumberrequired

Order in which attempting to match the rule. Lower goes first

longUrlstringrequired

Long URL to redirect to when this condition matches

conditionsArray<object>required

List of conditions that need to match in order to consider this rule matches

Show child attributes

typestringdevicelanguagequery-paramany-value-query-paramvalueless-query-paramip-addressgeolocation-country-codegeolocation-city-namerequired

The type of the condition, which will determine the logic used to match it

matchKeystring | nullrequired

matchValuestring | nullrequired

404Not Foundobject

No URL was found for provided short code.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

shortCodestringrequired

The short code with which we tried to find the short URL

domainstring

The domain with which we tried to find the short URL

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

List existing tags

GET

https://s.test/rest/v{version}/tags

Returns the list of all tags used in any short URL

List existing tags

curl -X GET 'https://s.test/rest/v3/tags' \
  -H 'X-Api-Key: YOUR_TOKEN'

const response = await fetch('https://s.test/rest/v3/tags', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://s.test/rest/v3/tags',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "tags": {
    "data": [
      "games",
      "php",
      "shlink",
      "tech"
    ],
    "pagination": {
      "currentPage": 5,
      "pagesCount": 10,
      "itemsPerPage": 4,
      "itemsInCurrentPage": 4,
      "totalItems": 38
    }
  }
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

pagenumberquery

The page to display. Defaults to 1

itemsPerPagenumberquery

The amount of items to return on every page. Defaults to all the items

searchTermstringquery

A query used to filter results by searching for it on the tag name.

orderBystringtag-ASCtag-DESCquery

To determine how to order the results.

Response

200OKobject

The list of tags

Response fields application/json

tagsobject

Show child attributes

dataArray<string>required

paginationobject

Show child attributes

currentPageinteger

The number of current page.

pagesCountinteger

The total number of pages that can be obtained.

itemsPerPageinteger

The number of items for every page.

itemsInCurrentPageinteger

The number of items in current page (could be smaller than itemsPerPage).

totalItemsinteger

The total number of items among all pages.

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

Rename tag

PUT

https://s.test/rest/v{version}/tags

Renames one existing tag

Rename tag

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"
}'

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();

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)

Request Body

{
  "oldName": "string",
  "newName": "string"
}

{
  "title": "Invalid data",
  "type": "https://shlink.io/api/error/invalid-data",
  "detail": "Provided data is not valid",
  "status": 400,
  "invalidElements": [
    "oldName",
    "newName"
  ]
}

{
  "title": "Invalid data",
  "type": "INVALID_ARGUMENT",
  "detail": "Provided data is not valid",
  "status": 400,
  "invalidElements": [
    "oldName",
    "newName"
  ]
}

{
  "detail": "You are not allowed to rename tags",
  "title": "Forbidden tag operation",
  "type": "https://shlink.io/api/error/forbidden-tag-operation",
  "status": 403
}

{
  "detail": "You are not allowed to rename tags",
  "title": "Forbidden tag operation",
  "type": "FORBIDDEN_OPERATION",
  "status": 403
}

{
  "detail": "Tag with name \"foo\" could not be found",
  "title": "Tag not found",
  "type": "https://shlink.io/api/error/tag-not-found",
  "status": 404,
  "tag": "foo"
}

{
  "detail": "You cannot rename tag foo, because it already exists",
  "title": "Tag conflict",
  "type": "https://shlink.io/api/error/tag-conflict",
  "status": 409,
  "oldName": "bar",
  "newName": "foo"
}

{
  "detail": "You cannot rename tag foo, because it already exists",
  "title": "Tag conflict",
  "type": "TAG_CONFLICT",
  "status": 409,
  "oldName": "bar",
  "newName": "foo"
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Body

application/json

Request body.

oldNamestringrequired

Current name of the tag

newNamestringrequired

New name of the tag

Parameters

versionstring321requiredpath

The API version to be consumed

Response

204No Content

The tag has been properly renamed

400Bad Requestobject

You have not provided either the oldName or the newName params.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

403Forbiddenobject

The API key you used does not have permissions to rename tags.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

404Not Foundobject

There’s no tag found with the name provided in oldName param.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

409Conflictobject

The name provided in newName param is already in use for another tag.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

Delete tags

DELETE

https://s.test/rest/v{version}/tags

Deletes provided list of tags

Delete tags

curl -X DELETE 'https://s.test/rest/v3/tags?tags%5B%5D=string' \
  -H 'X-Api-Key: YOUR_TOKEN'

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();

import requests

response = requests.delete(
    'https://s.test/rest/v3/tags?tags%5B%5D=string',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "detail": "You are not allowed to delete tags",
  "title": "Forbidden tag operation",
  "type": "https://shlink.io/api/error/forbidden-tag-operation",
  "status": 403
}

{
  "detail": "You are not allowed to delete tags",
  "title": "Forbidden tag operation",
  "type": "FORBIDDEN_OPERATION",
  "status": 403
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

tags[]Array<string>requiredquery

The names of the tags to delete

Response

204No Content

Tags properly deleted

403Forbiddenobject

The API key you used does not have permissions to delete tags.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

Get tags with stats

GET

https://s.test/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

Get tags with stats

curl -X GET 'https://s.test/rest/v3/tags/stats' \
  -H 'X-Api-Key: YOUR_TOKEN'

const response = await fetch('https://s.test/rest/v3/tags/stats', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://s.test/rest/v3/tags/stats',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "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
    }
  }
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

pagenumberquery

The page to display. Defaults to 1

itemsPerPagenumberquery

The amount of items to return on every page. Defaults to all the items

searchTermstringquery

A query used to filter results by searching for it on the tag name.

orderBystringtag-ASCtag-DESCshortUrlsCount-ASCshortUrlsCount-DESCvisits-ASCvisits-DESCnonBotVisits-ASCnonBotVisits-DESCquery

To determine how to order the results.

Important! Ordering by shortUrlsCount, visits or nonBotVisits has a known performance issue 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.

Response

200OKobject

The list of tags

Response fields application/json

tagsobject

Show child attributes

dataArray<object>required

Show child attributes

tagstringrequired

The unique tag name

shortUrlsCountnumberrequired

The amount of short URLs using this tag

visitsSummaryobjectrequired

Show child attributes

totalintegerrequired

The total amount of visits.

nonBotsintegerrequired

The amount of visits which were not identified as bots.

botsintegerrequired

The amount of visits that were identified as potential bots.

paginationobject

Show child attributes

currentPageinteger

The number of current page.

pagesCountinteger

The total number of pages that can be obtained.

itemsPerPageinteger

The number of items for every page.

itemsInCurrentPageinteger

The number of items in current page (could be smaller than itemsPerPage).

totalItemsinteger

The total number of items among all pages.

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

Visits

Operations to manage visits on short URLs

Get general visits stats

GET

https://s.test/rest/v{version}/visits

Get general visits stats not linked to one specific short URL.

Get general visits stats

curl -X GET 'https://s.test/rest/v3/visits' \
  -H 'X-Api-Key: YOUR_TOKEN'

const response = await fetch('https://s.test/rest/v3/visits', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://s.test/rest/v3/visits',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "visits": {
    "nonOrphanVisits": {
      "total": 64994,
      "nonBots": 64986,
      "bots": 8
    },
    "orphanVisits": {
      "total": 37,
      "nonBots": 34,
      "bots": 3
    }
  }
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

Response

200OKobject

Visits stats.

Response fields application/json

visitsobject

Show child attributes

nonOrphanVisitsobjectrequired

Show child attributes

totalintegerrequired

The total amount of visits.

nonBotsintegerrequired

The amount of visits which were not identified as bots.

botsintegerrequired

The amount of visits that were identified as potential bots.

orphanVisitsobjectrequired

Show child attributes

totalintegerrequired

The total amount of visits.

nonBotsintegerrequired

The amount of visits which were not identified as bots.

botsintegerrequired

The amount of visits that were identified as potential bots.

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

List visits for short URL

GET

https://s.test/rest/v{version}/short-urls/{shortCode}/visits

Get the list of visits on the short URL behind provided short code.

List visits for short URL

curl -X GET 'https://s.test/rest/v3/short-urls/string/visits' \
  -H 'X-Api-Key: YOUR_TOKEN'

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();

import requests

response = requests.get(
    'https://s.test/rest/v3/short-urls/string/visits',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "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
    }
  }
}

{
  "detail": "No URL found with short code \"abc123\"",
  "title": "Short URL not found",
  "type": "https://shlink.io/api/error/short-url-not-found",
  "status": 404,
  "shortCode": "abc123"
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

shortCodestringrequiredpath

The short code for the short URL.

domainstringquery

The domain in which the short code should be searched for.

startDatestringquery

The date (in ISO-8601 format) from which we want to get visits.

endDatestringquery

The date (in ISO-8601 format) until which we want to get visits.

pagenumberquery

The page to display. Defaults to 1

itemsPerPagenumberquery

The amount of items to return on every page. Defaults to all the items

excludeBotsstringtruequery

Tells if visits from potential bots should be excluded from the result set

Response

200OKobject

List of visits.

Response fields application/json

visitsobject

Show child attributes

dataArray<object>

Show child attributes

refererstringrequired

The origin from which the visit was performed

datestring<date-time>required

The date in which the visit was performed

userAgentstringrequired

The user agent from which the visit was performed

visitLocationobjectrequired

Show child attributes

cityNamestring

countryCodestring

countryNamestring

latitudenumber

longitudenumber

regionNamestring

timezonestring

potentialBotbooleanrequired

Tells if Shlink thinks this visit comes potentially from a bot or crawler

visitedUrlstring | nullrequired

The originally visited URL that triggered the tracking of this visit

redirectUrlstring | null

The URL to which the visitor was redirected, or null if a redirect did not occur, like for 404 requests or pixel tracking

paginationobject

Show child attributes

currentPageinteger

The number of current page.

pagesCountinteger

The total number of pages that can be obtained.

itemsPerPageinteger

The number of items for every page.

itemsInCurrentPageinteger

The number of items in current page (could be smaller than itemsPerPage).

totalItemsinteger

The total number of items among all pages.

404Not Foundobject

The short code does not belong to any short URL.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

Delete visits for short URL

DELETE

https://s.test/rest/v{version}/short-urls/{shortCode}/visits

Delete all existing visits on the short URL behind provided short code.

Delete visits for short URL

curl -X DELETE 'https://s.test/rest/v3/short-urls/string/visits' \
  -H 'X-Api-Key: YOUR_TOKEN'

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();

import requests

response = requests.delete(
    'https://s.test/rest/v3/short-urls/string/visits',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "deletedVisits": 536
}

{
  "detail": "No URL found with short code \"abc123\"",
  "title": "Short URL not found",
  "type": "https://shlink.io/api/error/short-url-not-found",
  "status": 404,
  "shortCode": "abc123"
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

shortCodestringrequiredpath

The short code for the short URL.

domainstringquery

The domain in which the short code should be searched for.

Response

200OKobject

Deleted visits

Response fields application/json

deletedVisitsnumber

Amount of affected visits

404Not Foundobject

The short code does not belong to any short URL.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

List visits for tag

GET

https://s.test/rest/v{version}/tags/{tag}/visits

Get the list of visits on any short URL which is tagged with provided tag.

List visits for tag

curl -X GET 'https://s.test/rest/v3/tags/string/visits' \
  -H 'X-Api-Key: YOUR_TOKEN'

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();

import requests

response = requests.get(
    'https://s.test/rest/v3/tags/string/visits',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "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
    }
  }
}

{
  "detail": "Tag with name \"foo\" could not be found",
  "title": "Tag not found",
  "type": "https://shlink.io/api/error/tag-not-found",
  "status": 404,
  "tag": "foo"
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

tagstringrequiredpath

The tag from which we want to get the visits.

startDatestringquery

The date (in ISO-8601 format) from which we want to get visits.

endDatestringquery

The date (in ISO-8601 format) until which we want to get visits.

pagenumberquery

The page to display. Defaults to 1

itemsPerPagenumberquery

The amount of items to return on every page. Defaults to all the items

excludeBotsstringtruequery

Tells if visits from potential bots should be excluded from the result set

domainstringquery

The domain in which the short code should be searched for.

Response

200OKobject

List of visits.

Response fields application/json

visitsobject

Show child attributes

dataArray<object>

Show child attributes

refererstringrequired

The origin from which the visit was performed

datestring<date-time>required

The date in which the visit was performed

userAgentstringrequired

The user agent from which the visit was performed

visitLocationobjectrequired

Show child attributes

cityNamestring

countryCodestring

countryNamestring

latitudenumber

longitudenumber

regionNamestring

timezonestring

potentialBotbooleanrequired

Tells if Shlink thinks this visit comes potentially from a bot or crawler

visitedUrlstring | nullrequired

The originally visited URL that triggered the tracking of this visit

redirectUrlstring | null

The URL to which the visitor was redirected, or null if a redirect did not occur, like for 404 requests or pixel tracking

paginationobject

Show child attributes

currentPageinteger

The number of current page.

pagesCountinteger

The total number of pages that can be obtained.

itemsPerPageinteger

The number of items for every page.

itemsInCurrentPageinteger

The number of items in current page (could be smaller than itemsPerPage).

totalItemsinteger

The total number of items among all pages.

404Not Foundobject

The tag does not exist.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

List visits for domain

GET

https://s.test/rest/v{version}/domains/{domain}/visits

Get the list of visits on any short URL which belongs to provided domain.

List visits for domain

curl -X GET 'https://s.test/rest/v3/domains/string/visits' \
  -H 'X-Api-Key: YOUR_TOKEN'

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();

import requests

response = requests.get(
    'https://s.test/rest/v3/domains/string/visits',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "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
    }
  }
}

{
  "detail": "Domain with authority \"example.com\" could not be found",
  "title": "Domain not found",
  "type": "https://shlink.io/api/error/domain-not-found",
  "status": 404,
  "authority": "example.com"
}

{
  "detail": "Domain with authority \"example.com\" could not be found",
  "title": "Domain not found",
  "type": "DOMAIN_NOT_FOUND",
  "status": 404,
  "authority": "example.com"
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

domainstringrequiredpath

The domain from which we want to get the visits, or DEFAULT keyword for default domain.

startDatestringquery

The date (in ISO-8601 format) from which we want to get visits.

endDatestringquery

The date (in ISO-8601 format) until which we want to get visits.

pagenumberquery

The page to display. Defaults to 1

itemsPerPagenumberquery

The amount of items to return on every page. Defaults to all the items

excludeBotsstringtruequery

Tells if visits from potential bots should be excluded from the result set

Response

200OKobject

List of visits.

Response fields application/json

visitsobject

Show child attributes

dataArray<object>

Show child attributes

refererstringrequired

The origin from which the visit was performed

datestring<date-time>required

The date in which the visit was performed

userAgentstringrequired

The user agent from which the visit was performed

visitLocationobjectrequired

Show child attributes

cityNamestring

countryCodestring

countryNamestring

latitudenumber

longitudenumber

regionNamestring

timezonestring

potentialBotbooleanrequired

Tells if Shlink thinks this visit comes potentially from a bot or crawler

visitedUrlstring | nullrequired

The originally visited URL that triggered the tracking of this visit

redirectUrlstring | null

The URL to which the visitor was redirected, or null if a redirect did not occur, like for 404 requests or pixel tracking

paginationobject

Show child attributes

currentPageinteger

The number of current page.

pagesCountinteger

The total number of pages that can be obtained.

itemsPerPageinteger

The number of items for every page.

itemsInCurrentPageinteger

The number of items in current page (could be smaller than itemsPerPage).

totalItemsinteger

The total number of items among all pages.

404Not Foundobject

The domain does not exist.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

List orphan visits

GET

https://s.test/rest/v{version}/visits/orphan

Get the list of visits to invalid short URLs, the base URL or any other 404.

List orphan visits

curl -X GET 'https://s.test/rest/v3/visits/orphan' \
  -H 'X-Api-Key: YOUR_TOKEN'

const response = await fetch('https://s.test/rest/v3/visits/orphan', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://s.test/rest/v3/visits/orphan',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "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
    }
  }
}

{
  "title": "Invalid data",
  "type": "https://shlink.io/api/error/invalid-data",
  "detail": "Provided data is not valid",
  "status": 400,
  "invalidElements": [
    "type"
  ]
}

{
  "title": "Invalid data",
  "type": "INVALID_ARGUMENT",
  "detail": "Provided data is not valid",
  "status": 400,
  "invalidElements": [
    "type"
  ]
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

startDatestringquery

The date (in ISO-8601 format) from which we want to get visits.

endDatestringquery

The date (in ISO-8601 format) until which we want to get visits.

pagenumberquery

The page to display. Defaults to 1

itemsPerPagenumberquery

The amount of items to return on every page. Defaults to all the items

excludeBotsstringtruequery

Tells if visits from potential bots should be excluded from the result set

typestringinvalid_short_urlbase_urlregular_404query

The type of visits to return. All visits are returned when not provided.

domainstringquery

The domain in which the short code should be searched for.

Response

200OKobject

List of visits.

Response fields application/json

visitsobject

Show child attributes

dataArray<object>

Show child attributes

typestringinvalid_short_urlbase_urlregular_404required

Tells the type of orphan visit

refererstringrequired

The origin from which the visit was performed

datestring<date-time>required

The date in which the visit was performed

userAgentstringrequired

The user agent from which the visit was performed

visitLocationobjectrequired

Show child attributes

cityNamestring

countryCodestring

countryNamestring

latitudenumber

longitudenumber

regionNamestring

timezonestring

potentialBotbooleanrequired

Tells if Shlink thinks this visit comes potentially from a bot or crawler

visitedUrlstring | nullrequired

The originally visited URL that triggered the tracking of this visit

redirectUrlstring | null

The URL to which the visitor was redirected, or null if a redirect did not occur, like for 404 requests or pixel tracking

paginationobject

Show child attributes

currentPageinteger

The number of current page.

pagesCountinteger

The total number of pages that can be obtained.

itemsPerPageinteger

The number of items for every page.

itemsInCurrentPageinteger

The number of items in current page (could be smaller than itemsPerPage).

totalItemsinteger

The total number of items among all pages.

400Bad Requestobject

Provided query arguments are invalid.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

invalidElementsArray<string>typerequired

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

Delete orphan visits

DELETE

https://s.test/rest/v{version}/visits/orphan

Delete all visits to invalid short URLs, the base URL or any other 404.

Delete orphan visits

curl -X DELETE 'https://s.test/rest/v3/visits/orphan' \
  -H 'X-Api-Key: YOUR_TOKEN'

const response = await fetch('https://s.test/rest/v3/visits/orphan', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'https://s.test/rest/v3/visits/orphan',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "deletedVisits": 536
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

Response

200OKobject

Deleted visits

Response fields application/json

deletedVisitsnumber

Amount of affected visits

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

List non-orphan visits

GET

https://s.test/rest/v{version}/visits/non-orphan

Get the list of visits to any short URL.

List non-orphan visits

curl -X GET 'https://s.test/rest/v3/visits/non-orphan' \
  -H 'X-Api-Key: YOUR_TOKEN'

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();

import requests

response = requests.get(
    'https://s.test/rest/v3/visits/non-orphan',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "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
    }
  }
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

startDatestringquery

The date (in ISO-8601 format) from which we want to get visits.

endDatestringquery

The date (in ISO-8601 format) until which we want to get visits.

pagenumberquery

The page to display. Defaults to 1

itemsPerPagenumberquery

The amount of items to return on every page. Defaults to all the items

excludeBotsstringtruequery

Tells if visits from potential bots should be excluded from the result set

domainstringquery

The domain in which the short code should be searched for.

Response

200OKobject

List of visits.

Response fields application/json

visitsobject

Show child attributes

dataArray<object>

Show child attributes

refererstringrequired

The origin from which the visit was performed

datestring<date-time>required

The date in which the visit was performed

userAgentstringrequired

The user agent from which the visit was performed

visitLocationobjectrequired

Show child attributes

cityNamestring

countryCodestring

countryNamestring

latitudenumber

longitudenumber

regionNamestring

timezonestring

potentialBotbooleanrequired

Tells if Shlink thinks this visit comes potentially from a bot or crawler

visitedUrlstring | nullrequired

The originally visited URL that triggered the tracking of this visit

redirectUrlstring | null

The URL to which the visitor was redirected, or null if a redirect did not occur, like for 404 requests or pixel tracking

paginationobject

Show child attributes

currentPageinteger

The number of current page.

pagesCountinteger

The total number of pages that can be obtained.

itemsPerPageinteger

The number of items for every page.

itemsInCurrentPageinteger

The number of items in current page (could be smaller than itemsPerPage).

totalItemsinteger

The total number of items among all pages.

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

Domains

Operations to manage domains used on short URLs

List configured domains

GET

https://s.test/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.

List configured domains

curl -X GET 'https://s.test/rest/v3/domains' \
  -H 'X-Api-Key: YOUR_TOKEN'

const response = await fetch('https://s.test/rest/v3/domains', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://s.test/rest/v3/domains',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "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
    }
  }
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

Response

200OKobject

The list of domains

Response fields application/json

domainsobjectrequired

Show child attributes

dataArray<object>required

Show child attributes

domainstringrequired

isDefaultbooleanrequired

redirectsobjectrequired

Show child attributes

baseUrlRedirectstring | null

URL to redirect to when a user hits the domain’s base URL

regular404Redirectstring | null

URL to redirect to when a user hits a not found URL other than an invalid short URL

invalidShortUrlRedirectstring | null

URL to redirect to when a user hits an invalid short URL

defaultRedirectsobject

Show child attributes

baseUrlRedirectstring | null

URL to redirect to when a user hits the domain’s base URL

regular404Redirectstring | null

URL to redirect to when a user hits a not found URL other than an invalid short URL

invalidShortUrlRedirectstring | null

URL to redirect to when a user hits an invalid short URL

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

Sets domain “not found” redirects

PATCH

https://s.test/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

Sets domain "not found" redirects

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"
}'

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();

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)

Request Body

{
  "domain": "string",
  "baseUrlRedirect": "string",
  "regular404Redirect": "string",
  "invalidShortUrlRedirect": "string"
}

{
  "baseUrlRedirect": "https://example.com/my-landing-page",
  "regular404Redirect": null,
  "invalidShortUrlRedirect": "https://example.com/invalid-url"
}

{
  "title": "Invalid data",
  "type": "https://shlink.io/api/error/invalid-data",
  "detail": "Provided data is not valid",
  "status": 400,
  "invalidElements": [
    "domain",
    "invalidShortUrlRedirect"
  ]
}

{
  "title": "Invalid data",
  "type": "INVALID_ARGUMENT",
  "detail": "Provided data is not valid",
  "status": 400,
  "invalidElements": [
    "domain",
    "invalidShortUrlRedirect"
  ]
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Body

application/json

Request body.

domainstringrequired

The domain’s authority for which you want to set redirects

baseUrlRedirectstring | null

URL to redirect to when a user hits the domain’s base URL

regular404Redirectstring | null

URL to redirect to when a user hits a not found URL other than an invalid short URL

invalidShortUrlRedirectstring | null

URL to redirect to when a user hits an invalid short URL

Parameters

versionstring321requiredpath

The API version to be consumed

Response

200OKany & object

The domain’s redirects after the update, when existing redirects have been merged with provided ones.

Response fields application/json

baseUrlRedirectstring | null

URL to redirect to when a user hits the domain’s base URL

regular404Redirectstring | null

URL to redirect to when a user hits a not found URL other than an invalid short URL

invalidShortUrlRedirectstring | null

URL to redirect to when a user hits an invalid short URL

any

400Bad Requestobject

Provided data is invalid.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

invalidElementsArray<string>domainbaseUrlRedirectregular404RedirectinvalidShortUrlRedirectrequired

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

Integrations

Handle services with which shlink is integrated

Get mercure integration info

GET

https://s.test/rest/v{version}/mercure-info

Returns information to consume updates published by Shlink on a mercure hub. https://mercure.rocks/

Get mercure integration info

curl -X GET 'https://s.test/rest/v3/mercure-info' \
  -H 'X-Api-Key: YOUR_TOKEN'

const response = await fetch('https://s.test/rest/v3/mercure-info', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://s.test/rest/v3/mercure-info',
    headers={
        'X-Api-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

{
  "mercureHubUrl": "https://example.com/.well-known/mercure",
  "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJTaGxpbmsiLCJpYXQiOjE1ODY2ODY3MzIsImV4cCI6MTU4Njk0NTkzMiwibWVyY3VyZSI6eyJzdWJzY3JpYmUiOltdfX0.P-519lgU7dFz0bbNlRG1CXyqugGbaHon4kw6fu4QBdQ",
  "jwtExpiration": "2020-04-15T12:18:52+02:00"
}

{
  "title": "Mercure integration not configured",
  "type": "https://shlink.io/api/error/mercure-not-configured",
  "detail": "This Shlink instance is not integrated with a mercure hub.",
  "status": 501
}

{
  "title": "Mercure integration not configured",
  "type": "MERCURE_NOT_CONFIGURED",
  "detail": "This Shlink instance is not integrated with a mercure hub.",
  "status": 501
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Parameters

versionstring321requiredpath

The API version to be consumed

Response

200OKobject

The mercure integration info

Response fields application/json

mercureHubUrlstringrequired

The public URL of the mercure hub that can be used to get real-time updates published by Shlink

jwtstringrequired

A JWT with subscribe permissions which is valid with the mercure hub

jwtExpirationstringrequired

The date (in ISO-8601 format) in which the JWT will expire

501Not Implementedobject

This Shlink instance is not integrated with a mercure hub

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

defaultobject

Unexpected error.

Response fields application/problem+json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

Authorization

ApiKeyapiKey in header

A valid shlink API key

Monitoring

Public endpoints designed to monitor the service

Check healthiness

GET

https://s.test/rest/health

Checks the healthiness of the service, making sure it can access required resources.

Check healthiness

curl -X GET 'https://s.test/rest/health'

const response = await fetch('https://s.test/rest/health', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://s.test/rest/health')
print(response.text)

{
  "status": "pass",
  "version": "2.10.0",
  "links": {
    "about": "https://shlink.io",
    "project": "https://github.com/shlinkio/shlink"
  }
}

{
  "status": "fail",
  "version": "2.10.0",
  "links": {
    "about": "https://shlink.io",
    "project": "https://github.com/shlinkio/shlink"
  }
}

{
  "type": "string",
  "title": "string",
  "detail": "string",
  "status": 0
}

Response

200OKobject

The passing health status

Response fields application/json

statusstringpassfail

The status of the service

versionstring

Shlink version

linksobject

A list of links

Show child attributes

aboutstring

About shlink

projectstring

Shlink project repository

503Service Unavailableobject

The failing health status

Response fields application/json

statusstringpassfail

The status of the service

versionstring

Shlink version

linksobject

A list of links

Show child attributes

aboutstring

About shlink

projectstring

Shlink project repository

defaultobject

Unexpected error.

Response fields application/json

typestringrequired

A machine unique code

titlestringrequired

A unique title

detailstringrequired

A human-friendly error description

statusnumberrequired

HTTP response status code

URL Shortener

Non-rest endpoints, used to be publicly exposed

Short URL

GET

https://s.test/{shortCode}

Represents a short URL. Tracks the visit and redirects tio the corresponding long URL

Short URL

curl -X GET 'https://s.test/string'

const response = await fetch('https://s.test/string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://s.test/string')
print(response.text)

Parameters

shortCodestringrequiredpath

The short code for the short URL.

Response

302Found

Visit properly tracked and redirected

Short URL tracking pixel

GET

https://s.test/{shortCode}/track

Generates a 1px transparent image which can be used to track emails with a short URL

Short URL tracking pixel

curl -X GET 'https://s.test/string/track'

const response = await fetch('https://s.test/string/track', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://s.test/string/track')
print(response.text)

200

"<binary>"

Parameters

shortCodestringrequiredpath

The short code for the short URL.

Response

200OKstring<binary>

Image in GIF format

Response fields image/gif

string<binary>

[Deprecated] Short URL QR code

deprecated

GET

https://s.test/{shortCode}/qr-code

[Deprecated] Use an external mechanism to generate QR codes. Shlink dashboard and shlink-web-client provide their own.

[Deprecated] Short URL QR code

curl -X GET 'https://s.test/string/qr-code?size=300&format=png&margin=0&errorCorrection=L&roundBlockSize=false&color=%23000000&bgColor=%23ffffff'

const response = await fetch('https://s.test/string/qr-code?size=300&format=png&margin=0&errorCorrection=L&roundBlockSize=false&color=%23000000&bgColor=%23ffffff', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://s.test/string/qr-code?size=300&format=png&margin=0&errorCorrection=L&roundBlockSize=false&color=%23000000&bgColor=%23ffffff')
print(response.text)

200

"<binary>"

<binary>

Parameters

shortCodestringrequiredpath

The short code for the short URL.

sizeinteger[50, 1000]300query

The size of the image to be returned.

formatstringpngsvgpngquery

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.

margininteger>= 00query

The margin around the QR code image.

errorCorrectionstringLMQHLquery

The error correction level to apply to the QR code: **[L]**ow, **[M]**edium, **[Q]**uartile or **[H]**igh. See docs.

roundBlockSizestringtruefalsefalsequery

Allows to disable block size rounding, which might reduce the readability of the QR code, but ensures no extra margin is added.

colorstring#000000query

The QR code foreground color. It should be an hex representation of a color, in 3 or 6 characters, optionally preceded by the “#” character.

bgColorstring#ffffffquery

The QR code background color. It should be an hex representation of a color, in 3 or 6 characters, optionally preceded by the “#” character.

logostringdisablequery

Currently used to disable the logo that was set via configuration options. It may be used in future to dynamically choose from multiple logos.

Response

200OKstring<binary>

QR code in PNG format

Response fields image/png

string<binary>

Response fields image/svg+xml

string<binary>