Regular API
API Documentation.
The API is available only to registered users API key can be generate in account edit page. The parameter userDomain for using branded domains is available only to registered users with any paid subscription plan.
Link shortening
URL Shortener
To shorten the link, open the file https://cutt.ly/api/api.php
remotely (eg via the php file_get_contents
), and in the parameters: short enter the address to be shortened (it should be encoded so any special characters will be interpreted correctly), name specify the preferred shortening of the link, userDomain specify if you want to use your own domain, to do so send 1.
Possible parameters
key |
Your API key. Required |
short |
URL you want to shorten. Required |
name |
Your desired short link - alias - if not already taken |
userDomain |
If set to 1, it will use the domain from the user account that is approved and has the status: active. Check subscription plans for more details - available from Single plan |
noTitle |
noTitle=1 Faster API response time This parameter disables getting the page title from the source page meta tag which results in faster API response time Available for Team Enterprise plan |
public |
public=1 Settings public click stats for shortened link via API Available from Single plan |
UTM tags, parameters etc.
The entered link should go through the built-in urlencode()
function, then the link parameters will be sent, including UTM tags etc.
Examples
As a reply, json string will be sent, containing following data
url => status: 1 |
the shortened link comes from the domain that shortens the link, i.e. the link has already been shortened |
url => status: 2 |
the entered link is not a link |
url => status: 3 |
the preferred link name is already taken |
url => status: 4 |
Invalid API key |
url => status: 5 |
the link has not passed the validation. Includes invalid characters |
url => status: 6 |
The link provided is from a blocked domain |
url => status: 7 |
OK - the link has been shortened |
url => status: 8 |
You have reached your monthly link limit. You can upgrade your subscription plan to add more links. |
If the status is equal to 7, then
url => date |
date of shortening the link |
url => shortLink |
shortened link |
url => fullLink |
original link |
url => title |
website title |
Errors
401 Unauthorized | Your API key is incorrect and a json with parameter auth:false has been returned |
Subscription has expired or you've reached your shortening limit | You should consider upgrading your subscription plan |
You do not own provided domain | It occurs when you do not own the provided domain |
You do not own any domain | It occurs when you specified that you want to shorten using your own domain, but you do not own any |
Link editing
Editing short links | from Single plan
In order to edit short link, open the file https://cutt.ly/api/api.php
remotely (eg via the php file_get_contents
), with the following parameters
key |
Your API key. Required |
edit |
edit=[SHORT_LINK] Your shortened link to be edited. Required |
userDomain |
If set to 1, then it will use account's user domain. Check subscription plans for more details - available from Single plan. |
tag |
tag=[TAG] The TAG you want to add for shortened link. Optional |
name |
name=[NEW_ALIAS] New alias / name, if not already taken. Optional |
delete |
delete=1 It will delete your shortened link. Optional |
source |
source=[FULL LINK] It will change the source url of shortened link. You can change source URL depending at your subscription plan. [FULL LINK] should be passed through urlencode(); Optional |
mobile |
Sets up alternative redirects depending on the operating system on mobile devices. Parameter mobile is case sensitive.redirect | alternative all other devicesandroid | Androidios | iOswindowsMobile | Windows MobileOptional |
destination |
An encoded url to be assigned in the mobile option. If the parameter is omitted (only mobile parameter is posted) then the destination from mobile option will be removed.Optional |
unique |
Sets a unique stat count for a short link.unique=0 | It removes counting unique clicks.unique=1 | for Single subscription plan. The time of uniqueness is 15 minutes.unique=15-1440 | for Team subscription plans. Time to count unique clicks ranging from 15 minutes to 1440 minutes (24h).Optional |
title |
title=[LINK TITLE] It will change the title of url of shortened link. You can change the short link title depending at your subscription plan. Optional |
Status for editing short links
status => 1 | OK |
status => 2 | Could not save in database |
status => 3 | The url does not exist or you do not own it |
status => 4 (for source and for destination only) | URL didn't pass the validation |
Errors
Insufficient subscription level | When using parameters without the required subscription. |
Unique time must be between 15 - 1440 minutes | Time to count unique clicks must be from 15 minutes to 1440 minutes (24h). |
Provided alias is unavailable | This alias is already in use and cannot be used. |
Link analytics
Analytics
In order to access URL statistics, open the file https://cutt.ly/api/api.php
remotely (eg via the php file_get_contents
), with the following parameters
key |
Your API key. Required |
stats |
The shortened URL you want to check statistics of. Required |
date_from |
It returns the number of clicks from a given period, both total and for social media. The correct format of the given dates: YYYY-MM-DD, e.g. 2021-03-02 Can be used with the second parameter date_to or separatelyAvailable from Team subscription plan. Optional |
date_to |
It returns the number of clicks from a given period, both total and for social media. The correct format of the given dates: YYYY-MM-DD, e.g. 2021-03-02 Can be used with the second parameter date_from or separatelyAvailable from Team subscription plan. Optional |
Examples
If status is equal to 1
In order to access URL statistics, open the file https://cutt.ly/api/api.php remotely (eg via the php file_get_contents), with the following parameters
stats=>date | Date of shortening the link |
stats=>clicks | Total number of clicks |
stats=>title | Title of the shortened link |
stats=>fullLink | Original link |
stats=>shortLink | Shortened link |
stats=>facebook | The number of clicks from Facebook |
stats=>twitter | The number of clicks from twitter |
stats=>linkedin | The number of clicks from linkedin |
stats=>rest | Other clicks |
stats=>bots | The number of clicks from bots |
In order to display subsequent data, it should take place in a loop. (E.g. for
, while
, foreach
loop)
Let $i
to be the next variable in the array.
stats=>refs=>ref=>$i=>link | displaying the domain from which you clicked on the link |
stats=>refs=>ref=>$i=>clicks | displaying the number of clicks from that domain |
stats=>devices=>geo=>$i=>tag | displaying the abbreviation of the country from which the link was clicked |
stats=>devices=>geo=>$i=>clicks | displaying the number of clicks from this country |
stats=>devices=>dev=>$i=>tag | displaying the type of device from which the link was clicked |
stats=>devices=>dev=>$i=>clicks | displaying the number of clicks from this device |
stats=>devices=>sys=>$i=>tag | displaying the operating system of the device from which the link was clicked |
stats=>devices=>sys=>$i=>clicks | displaying the number of clicks from this system |
stats=>devices=>bro=>$i=>tag | displaying the browser from which the link was clicked |
stats=>devices=>bro=>$i=>clicks | displaying the number of clicks from this browser |
stats=>devices=>brand=>$i=>tag | displaying the brand from which the link was clicked |
stats=>devices=>brand=>$i=>clicks | displaying the number of clicks from this brand |
stats=>devices=>lang=>$i=>tag | displaying the language set on the device from which the link was clicked |
stats=>devices=>lang=>$i=>clicks | displaying the number of clicks from this language |
stats=>bots=>bots=>$i=>name | displaying the bot from which the link was clicked |
stats=>bots=>bots=>$i=>clicks | displaying the number of clicks from this bot |
Errors
Incorrect date format | In case the date format is incorrect. The correct format of the given dates: YYYY-MM-DD, e.g. 2021-03-02 |
Insufficient subscription level | When using parameters without the required subscription plan. |
API limits
API limits per account depending on subscription plan | ||||
Free | Single | Team | Team Enterprise | |
3 requests / 60 sec. | 60 requests / 60 sec. | 180 requests / 60 sec. | 360 requests / 60 sec. more on request after individual calculation - additionally payable |