Short links
Every route for short links, each with a request example and the response returned. A link is referred to by its id or by its custom address (slug).
- GET
/v1/linksList short links - POST
/v1/linksShorten an address - GET
/v1/links/{id}Read a short link - PATCH
/v1/links/{id}Edit a short link - DELETE
/v1/links/{id}Delete a short link
List short links
GET/v1/links
The environment's short links, newest first. Read scope.
?search=— searches the destination, the custom address and the id?tag=— a tag id: only the links that carry it?page=and?per_page=— pagination, 50 per page by default, 100 at most
curl "https://api.tinylink.fr/v1/links?search=promo" \
-H "Authorization: Bearer tl_your_token"const response = await fetch('https://api.tinylink.fr/v1/links?search=promo', {
headers: { Authorization: 'Bearer tl_your_token' },
});
const data = await response.json();$ch = curl_init('https://api.tinylink.fr/v1/links?search=promo');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer tl_your_token'],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);import requests
response = requests.get(
'https://api.tinylink.fr/v1/links?search=promo',
headers={'Authorization': 'Bearer tl_your_token'},
)
data = response.json()Possible responses
{
"data": [
{
"id": "6ac401093831b",
"type": "link",
"target_url": "https://example.com/promo",
"slug": "promo",
"url": "https://tnlnk.fr/promo",
"status": "active",
"password_protected": false,
"restricted": false,
"tags": [],
"qr_code": null,
"created_at": "2026-10-05T21:56:57+02:00",
"edit_url": "https://app.tinylink.fr/shortener-edit?id=6ac401093831b"
}
],
"pagination": {
"page": 1,
"per_page": 50,
"total": 1,
"total_pages": 1
}
}No token in the request
{
"error": {
"code": "missing_token",
"message": "Send your token in the header: Authorization: Bearer tl_…"
}
}Unknown or revoked token
{
"error": {
"code": "invalid_token",
"message": "This token does not exist or has been revoked."
}
}The owner's plan does not include the API
{
"error": {
"code": "plan_required",
"message": "The TinyLink API is included in the Pro and Business plans. Upgrade the plan of this environment's owner to use it."
}
}The token does not carry the Read scope
{
"error": {
"code": "insufficient_scope",
"message": "This token does not have the \"read\" scope.",
"details": {
"required_scope": "read"
}
}
}More than 120 requests within the minute
{
"error": {
"code": "rate_limited",
"message": "Too many requests: 120 per minute per token."
}
}Shorten an address
POST/v1/links
url is required: a web address, an e-mail or a phone number. The response is the link created; in it, url is the short address and target_url the destination. Write scope.
url— the destination, 500 characters at mostslug— the custom address: letters, digits,-,_and., 40 characters at mostpassword— protects the link with a passwordtags— a list of tag ids from the environmentqr_code—truefor the classic QR code,"none"without a logo, or a template id
curl -X POST https://api.tinylink.fr/v1/links \
-H "Authorization: Bearer tl_your_token" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/promo",
"slug": "promo",
"qr_code": "none"
}'const response = await fetch('https://api.tinylink.fr/v1/links', {
method: 'POST',
headers: {
Authorization: 'Bearer tl_your_token',
'Content-Type': 'application/json',
},
body: JSON.stringify({
url: 'https://example.com/promo',
slug: 'promo',
qr_code: 'none',
}),
});
const data = await response.json();$ch = curl_init('https://api.tinylink.fr/v1/links');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer tl_your_token', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://example.com/promo',
'slug' => 'promo',
'qr_code' => 'none',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);import requests
response = requests.post(
'https://api.tinylink.fr/v1/links',
headers={'Authorization': 'Bearer tl_your_token'},
json={
'url': 'https://example.com/promo',
'slug': 'promo',
'qr_code': 'none',
},
)
data = response.json()Possible responses
{
"id": "6ac401093831b",
"type": "link",
"target_url": "https://example.com/promo",
"slug": "promo",
"url": "https://tnlnk.fr/promo",
"status": "active",
"password_protected": false,
"restricted": false,
"tags": [],
"qr_code": {
"png": "https://content.tinylink.fr/QR_Code/QRCode_6ac4011f7a12f.png",
"svg": "https://content.tinylink.fr/QR_Code/QRCode_6ac4011f7a12f.svg",
"template": "none",
"shape": "square",
"encoded_url": "https://tnlnk.fr/6ac401093831b&qr"
},
"created_at": "2026-10-05T21:56:57+02:00",
"edit_url": "https://app.tinylink.fr/shortener-edit?id=6ac401093831b"
}The body is not a JSON object
{
"error": {
"code": "invalid_json",
"message": "The request body must be a JSON object."
}
}No token in the request
{
"error": {
"code": "missing_token",
"message": "Send your token in the header: Authorization: Bearer tl_…"
}
}Unknown or revoked token
{
"error": {
"code": "invalid_token",
"message": "This token does not exist or has been revoked."
}
}The plan's number of short links is reached
{
"error": {
"code": "plan_limit_reached",
"message": "The link limit of the plan has been reached."
}
}The owner's plan does not include the API
{
"error": {
"code": "plan_required",
"message": "The TinyLink API is included in the Pro and Business plans. Upgrade the plan of this environment's owner to use it."
}
}The token does not carry the Write scope
{
"error": {
"code": "insufficient_scope",
"message": "This token does not have the \"write\" scope.",
"details": {
"required_scope": "write"
}
}
}Custom address already used by a page or a link
{
"error": {
"code": "slug_taken",
"message": "This slug is already taken.",
"details": {
"field": "slug"
}
}
}Required field missing or empty
{
"error": {
"code": "validation_failed",
"message": "The \"url\" field is required (a string).",
"details": {
"field": "url"
}
}
}Neither a web address, nor an e-mail, nor a phone number
{
"error": {
"code": "invalid_url",
"message": "This is not a valid web address, e-mail address or phone number.",
"details": {
"field": "url"
}
}
}Domain flagged as suspicious
{
"error": {
"code": "suspicious_url",
"message": "This address is on our list of suspicious domains and cannot be used.",
"details": {
"field": "url"
}
}
}More than 120 requests within the minute
{
"error": {
"code": "rate_limited",
"message": "Too many requests: 120 per minute per token."
}
}Read a short link
GET/v1/links/{id}
status is active, pending_review (being checked, the link does not redirect yet) or blocked. Read scope.
curl https://api.tinylink.fr/v1/links/promo \
-H "Authorization: Bearer tl_your_token"const response = await fetch('https://api.tinylink.fr/v1/links/promo', {
headers: { Authorization: 'Bearer tl_your_token' },
});
const data = await response.json();$ch = curl_init('https://api.tinylink.fr/v1/links/promo');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer tl_your_token'],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);import requests
response = requests.get(
'https://api.tinylink.fr/v1/links/promo',
headers={'Authorization': 'Bearer tl_your_token'},
)
data = response.json()Possible responses
{
"id": "6ac401093831b",
"type": "link",
"target_url": "https://example.com/promo",
"slug": "promo",
"url": "https://tnlnk.fr/promo",
"status": "active",
"password_protected": false,
"restricted": false,
"tags": [],
"qr_code": {
"png": "https://content.tinylink.fr/QR_Code/QRCode_6ac4011f7a12f.png",
"svg": "https://content.tinylink.fr/QR_Code/QRCode_6ac4011f7a12f.svg",
"template": "none",
"shape": "square",
"encoded_url": "https://tnlnk.fr/6ac401093831b&qr"
},
"created_at": "2026-10-05T21:56:57+02:00",
"edit_url": "https://app.tinylink.fr/shortener-edit?id=6ac401093831b"
}No token in the request
{
"error": {
"code": "missing_token",
"message": "Send your token in the header: Authorization: Bearer tl_…"
}
}Unknown or revoked token
{
"error": {
"code": "invalid_token",
"message": "This token does not exist or has been revoked."
}
}The owner's plan does not include the API
{
"error": {
"code": "plan_required",
"message": "The TinyLink API is included in the Pro and Business plans. Upgrade the plan of this environment's owner to use it."
}
}The token does not carry the Read scope
{
"error": {
"code": "insufficient_scope",
"message": "This token does not have the \"read\" scope.",
"details": {
"required_scope": "read"
}
}
}No short link with this id or slug in the environment
{
"error": {
"code": "not_found",
"message": "Link not found in this environment."
}
}More than 120 requests within the minute
{
"error": {
"code": "rate_limited",
"message": "Too many requests: 120 per minute per token."
}
}Edit a short link
PATCH/v1/links/{id}
Only send the fields to change: url (the destination), slug, password. null removes the custom address or the password. Changing the destination does not change the short address. Write scope.
curl -X PATCH https://api.tinylink.fr/v1/links/6ac401093831b \
-H "Authorization: Bearer tl_your_token" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/sale"}'const response = await fetch('https://api.tinylink.fr/v1/links/6ac401093831b', {
method: 'PATCH',
headers: {
Authorization: 'Bearer tl_your_token',
'Content-Type': 'application/json',
},
body: JSON.stringify({ url: 'https://example.com/sale' }),
});
const data = await response.json();$ch = curl_init('https://api.tinylink.fr/v1/links/6ac401093831b');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer tl_your_token', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['url' => 'https://example.com/sale']),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);import requests
response = requests.patch(
'https://api.tinylink.fr/v1/links/6ac401093831b',
headers={'Authorization': 'Bearer tl_your_token'},
json={'url': 'https://example.com/sale'},
)
data = response.json()Possible responses
{
"id": "6ac401093831b",
"type": "link",
"target_url": "https://example.com/sale",
"slug": "promo",
"url": "https://tnlnk.fr/promo",
"status": "active",
"password_protected": false,
"restricted": false,
"tags": [],
"qr_code": {
"png": "https://content.tinylink.fr/QR_Code/QRCode_6ac4011f7a12f.png",
"svg": "https://content.tinylink.fr/QR_Code/QRCode_6ac4011f7a12f.svg",
"template": "none",
"shape": "square",
"encoded_url": "https://tnlnk.fr/6ac401093831b&qr"
},
"created_at": "2026-10-05T21:56:57+02:00",
"edit_url": "https://app.tinylink.fr/shortener-edit?id=6ac401093831b"
}The body is not a JSON object
{
"error": {
"code": "invalid_json",
"message": "The request body must be a JSON object."
}
}No token in the request
{
"error": {
"code": "missing_token",
"message": "Send your token in the header: Authorization: Bearer tl_…"
}
}Unknown or revoked token
{
"error": {
"code": "invalid_token",
"message": "This token does not exist or has been revoked."
}
}The owner's plan does not include the API
{
"error": {
"code": "plan_required",
"message": "The TinyLink API is included in the Pro and Business plans. Upgrade the plan of this environment's owner to use it."
}
}The token does not carry the Write scope
{
"error": {
"code": "insufficient_scope",
"message": "This token does not have the \"write\" scope.",
"details": {
"required_scope": "write"
}
}
}No short link with this id or slug in the environment
{
"error": {
"code": "not_found",
"message": "Link not found in this environment."
}
}Custom address already used by a page or a link
{
"error": {
"code": "slug_taken",
"message": "This slug is already taken.",
"details": {
"field": "slug"
}
}
}No editable field in the body
{
"error": {
"code": "validation_failed",
"message": "Nothing to update. Accepted fields: url, slug, password."
}
}Neither a web address, nor an e-mail, nor a phone number
{
"error": {
"code": "invalid_url",
"message": "This is not a valid web address, e-mail address or phone number.",
"details": {
"field": "url"
}
}
}Element blocked by moderation
{
"error": {
"code": "element_blocked",
"message": "This element is blocked by moderation and can no longer be modified."
}
}More than 120 requests within the minute
{
"error": {
"code": "rate_limited",
"message": "Too many requests: 120 per minute per token."
}
}Delete a short link
DELETE/v1/links/{id}
Deletes the link, its QR code and its statistics: the short address stops redirecting. This cannot be undone. Delete scope.
curl -X DELETE https://api.tinylink.fr/v1/links/6ac401093831b \
-H "Authorization: Bearer tl_your_token"const response = await fetch('https://api.tinylink.fr/v1/links/6ac401093831b', {
method: 'DELETE',
headers: { Authorization: 'Bearer tl_your_token' },
});
console.log(response.status); // 204$ch = curl_init('https://api.tinylink.fr/v1/links/6ac401093831b');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer tl_your_token'],
]);
curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); // 204
curl_close($ch);import requests
response = requests.delete(
'https://api.tinylink.fr/v1/links/6ac401093831b',
headers={'Authorization': 'Bearer tl_your_token'},
)
print(response.status_code) # 204Possible responses
No content
No token in the request
{
"error": {
"code": "missing_token",
"message": "Send your token in the header: Authorization: Bearer tl_…"
}
}Unknown or revoked token
{
"error": {
"code": "invalid_token",
"message": "This token does not exist or has been revoked."
}
}The owner's plan does not include the API
{
"error": {
"code": "plan_required",
"message": "The TinyLink API is included in the Pro and Business plans. Upgrade the plan of this environment's owner to use it."
}
}The token does not carry the Delete scope
{
"error": {
"code": "insufficient_scope",
"message": "This token does not have the \"delete\" scope.",
"details": {
"required_scope": "delete"
}
}
}No short link with this id or slug in the environment
{
"error": {
"code": "not_found",
"message": "Link not found in this environment."
}
}More than 120 requests within the minute
{
"error": {
"code": "rate_limited",
"message": "Too many requests: 120 per minute per token."
}
}