Tags

Every route for tags: managing them, then setting them on a page or a short link. A tag is referred to by its numeric id.

GET/v1/tagsList tags
POST/v1/tagsCreate a tag
GET/v1/tags/{id}Read a tag
PATCH/v1/tags/{id}Edit a tag
DELETE/v1/tags/{id}Delete a tag
GET/v1/tags/{id}/elementsList a tag's elements
GET/v1/pages/{id}/tagsRead an element's tags
GET/v1/links/{id}/tagsRead an element's tags
PUT/v1/pages/{id}/tags/{tag}Set a tag
PUT/v1/links/{id}/tags/{tag}Set a tag
DELETE/v1/pages/{id}/tags/{tag}Remove a tag
DELETE/v1/links/{id}/tags/{tag}Remove a tag

List tags

GET/v1/tags

The environment's tags, in alphabetical order. elements_count counts the pages and links that carry the tag. Read scope.

curl https://api.tinylink.fr/v1/tags \
  -H "Authorization: Bearer tl_your_token"

const response = await fetch('https://api.tinylink.fr/v1/tags', {
  headers: { Authorization: 'Bearer tl_your_token' },
});
const data = await response.json();

$ch = curl_init('https://api.tinylink.fr/v1/tags');
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/tags',
    headers={'Authorization': 'Bearer tl_your_token'},
)
data = response.json()

Possible responses

{
  "data": [
    {
      "id": 46,
      "name": "Campaign",
      "color": "#1E90FF",
      "elements_count": 1,
      "created_at": "2026-10-05T21:57:18+02:00"
    }
  ]
}

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

Create a tag

POST/v1/tags

name is required (50 characters at most). color is a hexadecimal colour, #1E90FF or #19F; without it the tag is black. Write scope.

curl -X POST https://api.tinylink.fr/v1/tags \
  -H "Authorization: Bearer tl_your_token" \
  -H "Content-Type: application/json" \
  -d '{"name":"Campaign","color":"#1E90FF"}'

const response = await fetch('https://api.tinylink.fr/v1/tags', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer tl_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Campaign', color: '#1E90FF' }),
});
const data = await response.json();

$ch = curl_init('https://api.tinylink.fr/v1/tags');
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(['name' => 'Campaign', 'color' => '#1E90FF']),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

import requests

response = requests.post(
    'https://api.tinylink.fr/v1/tags',
    headers={'Authorization': 'Bearer tl_your_token'},
    json={'name': 'Campaign', 'color': '#1E90FF'},
)
data = response.json()

Possible responses

{
  "id": 46,
  "name": "Campaign",
  "color": "#1E90FF",
  "elements_count": 0,
  "created_at": "2026-10-05T21:57:18+02:00"
}

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

Required field missing or empty

{
  "error": {
    "code": "validation_failed",
    "message": "The \"name\" field is required.",
    "details": {
      "field": "name"
    }
  }
}

Colour that is not hexadecimal

{
  "error": {
    "code": "validation_failed",
    "message": "The \"color\" field must be a hexadecimal colour such as #1E90FF.",
    "details": {
      "field": "color"
    }
  }
}

More than 120 requests within the minute

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests: 120 per minute per token."
  }
}

Read a tag

GET/v1/tags/{id}

Read scope.

curl https://api.tinylink.fr/v1/tags/46 \
  -H "Authorization: Bearer tl_your_token"

const response = await fetch('https://api.tinylink.fr/v1/tags/46', {
  headers: { Authorization: 'Bearer tl_your_token' },
});
const data = await response.json();

$ch = curl_init('https://api.tinylink.fr/v1/tags/46');
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/tags/46',
    headers={'Authorization': 'Bearer tl_your_token'},
)
data = response.json()

Possible responses

{
  "id": 46,
  "name": "Campaign",
  "color": "#1E90FF",
  "elements_count": 1,
  "created_at": "2026-10-05T21:57:18+02:00"
}

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 tag with this id in the environment

{
  "error": {
    "code": "not_found",
    "message": "Tag 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 tag

PATCH/v1/tags/{id}

name, color, or both. Write scope.

curl -X PATCH https://api.tinylink.fr/v1/tags/46 \
  -H "Authorization: Bearer tl_your_token" \
  -H "Content-Type: application/json" \
  -d '{"name":"Summer campaign"}'

const response = await fetch('https://api.tinylink.fr/v1/tags/46', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer tl_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Summer campaign' }),
});
const data = await response.json();

$ch = curl_init('https://api.tinylink.fr/v1/tags/46');
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(['name' => 'Summer campaign']),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

import requests

response = requests.patch(
    'https://api.tinylink.fr/v1/tags/46',
    headers={'Authorization': 'Bearer tl_your_token'},
    json={'name': 'Summer campaign'},
)
data = response.json()

Possible responses

{
  "id": 46,
  "name": "Summer campaign",
  "color": "#1E90FF",
  "elements_count": 1,
  "created_at": "2026-10-05T21:57:18+02:00"
}

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 tag with this id in the environment

{
  "error": {
    "code": "not_found",
    "message": "Tag not found in this environment."
  }
}

No editable field in the body

{
  "error": {
    "code": "validation_failed",
    "message": "Nothing to update. Accepted fields: name, color."
  }
}

Colour that is not hexadecimal

{
  "error": {
    "code": "validation_failed",
    "message": "The \"color\" field must be a hexadecimal colour such as #1E90FF.",
    "details": {
      "field": "color"
    }
  }
}

More than 120 requests within the minute

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests: 120 per minute per token."
  }
}

Delete a tag

DELETE/v1/tags/{id}

Deletes the tag and removes it from every element that carried it; the pages and links themselves are untouched. Delete scope.

curl -X DELETE https://api.tinylink.fr/v1/tags/46 \
  -H "Authorization: Bearer tl_your_token"

const response = await fetch('https://api.tinylink.fr/v1/tags/46', {
  method: 'DELETE',
  headers: { Authorization: 'Bearer tl_your_token' },
});
console.log(response.status); // 204

$ch = curl_init('https://api.tinylink.fr/v1/tags/46');
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/tags/46',
    headers={'Authorization': 'Bearer tl_your_token'},
)
print(response.status_code)  # 204

Possible 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 tag with this id in the environment

{
  "error": {
    "code": "not_found",
    "message": "Tag 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."
  }
}

List a tag's elements

GET/v1/tags/{id}/elements

The pages and short links that carry the tag, paginated like the other lists (?page=, ?per_page=). type tells page from link. Read scope.

curl https://api.tinylink.fr/v1/tags/46/elements \
  -H "Authorization: Bearer tl_your_token"

const response = await fetch('https://api.tinylink.fr/v1/tags/46/elements', {
  headers: { Authorization: 'Bearer tl_your_token' },
});
const data = await response.json();

$ch = curl_init('https://api.tinylink.fr/v1/tags/46/elements');
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/tags/46/elements',
    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": [
        {
          "id": 46,
          "name": "Campaign",
          "color": "#1E90FF"
        }
      ],
      "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"
    }
  }
}

No tag with this id in the environment

{
  "error": {
    "code": "not_found",
    "message": "Tag 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."
  }
}

Read an element's tags

GET/v1/pages/{id}/tags

GET/v1/links/{id}/tags

The tags set on a page or on a short link. Read scope.

curl https://api.tinylink.fr/v1/links/6ac401093831b/tags \
  -H "Authorization: Bearer tl_your_token"

const response = await fetch('https://api.tinylink.fr/v1/links/6ac401093831b/tags', {
  headers: { Authorization: 'Bearer tl_your_token' },
});
const data = await response.json();

$ch = curl_init('https://api.tinylink.fr/v1/links/6ac401093831b/tags');
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/6ac401093831b/tags',
    headers={'Authorization': 'Bearer tl_your_token'},
)
data = response.json()

Possible responses

{
  "data": [
    {
      "id": 46,
      "name": "Campaign",
      "color": "#1E90FF"
    }
  ]
}

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 page with this id or slug in the environment

{
  "error": {
    "code": "not_found",
    "message": "Page not found in this environment."
  }
}

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

Set a tag

PUT/v1/pages/{id}/tags/{tag}

PUT/v1/links/{id}/tags/{tag}

Sets the tag on the page or the short link; no request body. The response gives the element's tags after the operation. Write scope.

curl -X PUT https://api.tinylink.fr/v1/links/6ac401093831b/tags/46 \
  -H "Authorization: Bearer tl_your_token"

const response = await fetch('https://api.tinylink.fr/v1/links/6ac401093831b/tags/46', {
  method: 'PUT',
  headers: { Authorization: 'Bearer tl_your_token' },
});
const data = await response.json();

$ch = curl_init('https://api.tinylink.fr/v1/links/6ac401093831b/tags/46');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer tl_your_token'],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

import requests

response = requests.put(
    'https://api.tinylink.fr/v1/links/6ac401093831b/tags/46',
    headers={'Authorization': 'Bearer tl_your_token'},
)
data = response.json()

Possible responses

{
  "data": [
    {
      "id": 46,
      "name": "Campaign",
      "color": "#1E90FF"
    }
  ]
}

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 page with this id or slug in the environment

{
  "error": {
    "code": "not_found",
    "message": "Page not found in this environment."
  }
}

No short link with this id or slug in the environment

{
  "error": {
    "code": "not_found",
    "message": "Link not found in this environment."
  }
}

No tag with this id in the environment

{
  "error": {
    "code": "not_found",
    "message": "Tag 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."
  }
}

Remove a tag

DELETE/v1/pages/{id}/tags/{tag}

DELETE/v1/links/{id}/tags/{tag}

Removes the tag from the element without deleting anything: the Write scope is enough. The response gives the remaining tags.

curl -X DELETE https://api.tinylink.fr/v1/links/6ac401093831b/tags/46 \
  -H "Authorization: Bearer tl_your_token"

const response = await fetch('https://api.tinylink.fr/v1/links/6ac401093831b/tags/46', {
  method: 'DELETE',
  headers: { Authorization: 'Bearer tl_your_token' },
});
const data = await response.json();

$ch = curl_init('https://api.tinylink.fr/v1/links/6ac401093831b/tags/46');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer tl_your_token'],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

import requests

response = requests.delete(
    'https://api.tinylink.fr/v1/links/6ac401093831b/tags/46',
    headers={'Authorization': 'Bearer tl_your_token'},
)
data = response.json()

Possible responses

{
  "data": []
}

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 page with this id or slug in the environment

{
  "error": {
    "code": "not_found",
    "message": "Page not found in this environment."
  }
}

No short link with this id or slug in the environment

{
  "error": {
    "code": "not_found",
    "message": "Link not found in this environment."
  }
}

No tag with this id in the environment

{
  "error": {
    "code": "not_found",
    "message": "Tag 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."
  }
}

List tags

Create a tag

Read a tag

Edit a tag

Delete a tag

List a tag's elements

Read an element's tags

Set a tag

Remove a tag

Still stuck?