Links API
Create, list, read, change and delete short links with the siz.la REST API, with cURL, JavaScript, Python and PHP examples.
Links are the heart of the API. Each one has an id, a short address and a destination. Ids are numbers. The short address ends in a code, either one you pick or a random one.
Reading needs a key. Making, changing and deleting links need a key with write access, which the plan table on (https://siz.la/docs/errors) shows for each plan.
Plan limits that apply here
Your plan sets how many links you can make a month, how short a hand-picked ending can be, and which options are open. A request that asks for something the plan does not include gets a 400 that says so, before anything is saved.
| Feature | Free | Pro | Team | Business | Organization |
|---|---|---|---|---|---|
| Password on a link | Yes | Yes | Yes | Yes | Yes |
| Expiry date | Yes | Yes | Yes | Yes | Yes |
| Click limit | Yes | Yes | Yes | Yes | Yes |
| Targeting by country, device and language | Yes | Yes | Yes | Yes | Yes |
| App deep links | Yes | Yes | Yes | Yes | Yes |
| Campaigns | No | Yes | Yes | Yes | Yes |
| Conversions | No | Yes | Yes | Yes | Yes |
| Webhooks | No | Yes | Yes | Yes | Yes |
| Raw click export | No | Yes | Yes | Yes | Yes |
Messages over the page
A link can show one of your call-to-action messages over the page it opens: a line of text and a button, with an optional picture. You make the messages on siz.la under Call to action, then send the message's id as cta when you make or change a link. On update, send 0 to take it off. Sending the id of someone else's message gets a 400. The number of messages you can keep depends on your plan.
Splash pages
A link can show one of your splash pages for a few seconds before the page opens. Make the page under (https://siz.la/docs/splash) or in the members area, then send its id as splash when you make or change a link. On update, send 0 to take it off. A link shows a splash page or a call to action, not both.
Opening apps on a phone
When a link leads to the web address of a well-known app, such as YouTube, Instagram, Spotify, Amazon or WhatsApp, a person on a phone gets the app if it is installed, and the web page if it is not. This is on for every link on every plan. Send openinapp as false to always open the web page. If you set your own app addresses with deeplink, those are used first. Computers, search engines and link previews always get the web page. The link's details show the app that was recognized under app.
Link previews
When someone shares a short link in a chat app or on a social site, the app asks the short address for a title, a description and a picture. Set them with metatitle, metadescription and metaimage and the app shows that card. People who open the link are sent on as usual. A link with none of the three set shows the address as before. A picture can also be uploaded in the link editor.
List links
GET/api/urls
Your links, newest first, with the number of clicks on each.
Needs: API key.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
limit | Query | integer | How many links to return on a page. 1 to 100. Default 15. |
page | Query | integer | Which page to return. At least 1. Default 1. |
order | Query | string | Newest first (date) or most clicked first (click). One of date, click. Default date. |
short | Query | string | Find one link by its ending or its full short address. |
q | Query | string | Text to look for in the destination, the ending and the title. |
Example request
curl "https://siz.la/api/urls?limit=10&page=1" \
-H "Authorization: Bearer $SIZLA_API_KEY"const response = await fetch("https://siz.la/api/urls?limit=10&page=1", {
headers: {
Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
},
});
const data = await response.json();
console.log(data);import os
import requests
response = requests.get(
"https://siz.la/api/urls",
headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
params={
"limit": 10,
"page": 1,
},
)
print(response.json())$ch = curl_init('https://siz.la/api/urls?limit=10&page=1');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);Example answer, status 200
{
"error": "0",
"data": {
"result": 1,
"perpage": 10,
"currentpage": 1,
"nextpage": null,
"maxpage": 1,
"urls": [
{
"id": 1042,
"alias": "lunch-menu",
"shorturl": "https://siz.la/lunch-menu",
"longurl": "https://example.com/a/long/address",
"clicks": 37,
"title": "",
"description": "",
"date": "2026-11-14 09:30:00"
}
]
}
}Notes
erroris the text"0"on this endpoint and the number0on the others. Compare it loosely or convert it first.resultis the total number of links that match, not the number on this page.
Get a link
GET/api/url/{id}
One link with its settings and a summary of its clicks.
Needs: API key.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) | Path | integer | The link's id, from the list or from the answer when it was made. At least 1. |
Example request
curl "https://siz.la/api/url/1042" \
-H "Authorization: Bearer $SIZLA_API_KEY"const response = await fetch("https://siz.la/api/url/1042", {
headers: {
Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
},
});
const data = await response.json();
console.log(data);import os
import requests
response = requests.get(
"https://siz.la/api/url/1042",
headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())$ch = curl_init('https://siz.la/api/url/1042');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);Example answer, status 200
{
"error": 0,
"id": 1042,
"details": {
"id": 1042,
"shorturl": "https://siz.la/lunch-menu",
"longurl": "https://example.com/a/long/address",
"title": "",
"description": "",
"metaimage": "",
"location": {},
"device": {},
"expiry": null,
"splash": null,
"openinapp": true,
"blockbots": false,
"openinbrowser": false,
"app": null,
"date": "2026-11-14 09:30:00"
},
"data": {
"clicks": 37,
"uniqueClicks": 31,
"topCountries": {
"US": 20,
"GB": 7
},
"topReferrers": {
"t.co": 9
},
"topBrowsers": {
"Chrome": 22
},
"topOs": {
"iOS": 14
},
"socialCount": {
"facebook": 0,
"twitter": 9,
"google": 0
}
}
}Errors specific to this call
404: The link does not exist or belongs to someone else.
Notes
- A list in
data(topCountriesand the others) is the number0when there are no clicks to count.
Shorten a link
POST/api/url/add
Make a short link. The address is checked first, and your plan's monthly link limit applies.
Needs: API key with write access.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
url (required) | Body | string | The full web address to shorten. It must start with http:// or https://. |
custom | Body | string | The ending you want, such as lunch-menu. Letters, numbers, dashes and underscores. Leave it out to get a random one. The shortest ending allowed on siz.la depends on the plan. |
domain | Body | string | One of your connected custom domains, as the host name (go.example.com) or its id. Leave it out to use siz.la. |
password | Body | string | A password visitors must enter before they are sent on. On update, send an empty string to remove it. |
expiry | Body | string | When the link stops working, as a date and time in the future such as 2026-12-31 18:00. On update, send an empty string to remove it. |
campaign | Body | string | A campaign to put the link in, by id or by name. A name that does not exist yet makes a new campaign. Needs Pro and the plans above it. |
cta | Body | integer | One of your call-to-action messages, by id, to show over the page the link opens. On update, send 0 to remove it. |
pixels | Body | array | The ids of your ad pixels to fire on each click, from the pixels list. On update, an empty list removes them all and leaving it out keeps them. |
channel | Body | string | A channel to put the link in, by id or by name. On update, send an empty string to take it out. |
splash | Body | integer | One of your splash pages, by id, to show for a few seconds before the page opens. A link shows a splash page or a call to action, not both. On update, send 0 to remove it. |
openinapp | Body | boolean | Open the app on a phone when the address belongs to a known app, such as YouTube or Spotify, and the app is installed. On by default for every plan; send false to always open the web page. An app address you set with deeplink is used first. Default 1. |
blockbots | Body | boolean | Answer crawlers and scripts with a plain "not found" page instead of the redirect. Their visits are not counted. Chat apps that fetch a card still get it when the link has a preview. Leave it out on update to keep what the link has. Default ``. |
openinbrowser | Body | boolean | Show people inside the Instagram, TikTok or Facebook app a page that helps them open the link in their own browser. The visit is counted when they do. Leave it out on update to keep what the link has. Default ``. |
metatitle | Body | string | The title shown when the link is shared in a chat app or on a social site. Send an empty string to remove it. Up to 191 characters. |
metadescription | Body | string | The description shown when the link is shared. Send an empty string to remove it. Up to 500 characters. |
metaimage | Body | string | The address of the picture shown when the link is shared. It must start with https:// or http://. Send an empty string to remove it. Up to 191 characters. |
description | Body | string | A private note. Only you see it. |
geotarget | Body | array | Send visitors from some countries somewhere else: a list of objects with location (a country name or two-letter code) and link (the address). |
devicetarget | Body | array | Send some devices somewhere else: a list of objects with device (ios, android, windows, macos or linux) and link. |
languagetarget | Body | array | Send some browser languages somewhere else: a list of objects with language (a two-letter code) and link. |
deeplink | Body | object | Send phones to an app or store address of your own instead of the web address: an object with apple and google addresses. Links to well-known apps open the app without this; see openinapp. |
type | Body | string | Only direct is available. Any other value is refused. One of direct. |
Example request
curl -X POST "https://siz.la/api/url/add" \
-H "Authorization: Bearer $SIZLA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/a/long/address","custom":"lunch-menu"}'const response = await fetch("https://siz.la/api/url/add", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"url": "https://example.com/a/long/address",
"custom": "lunch-menu"
}),
});
const data = await response.json();
console.log(data);import os
import requests
response = requests.post(
"https://siz.la/api/url/add",
headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
json={
"url": "https://example.com/a/long/address",
"custom": "lunch-menu",
},
)
print(response.json())$ch = curl_init('https://siz.la/api/url/add');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://example.com/a/long/address',
'custom' => 'lunch-menu',
]),
]);
$data = json_decode(curl_exec($ch), true);Example answer, status 200
{
"error": 0,
"id": 1042,
"shorturl": "https://siz.la/lunch-menu"
}Errors specific to this call
400: The address is not allowed, the ending is taken or not allowed, an option needs a different plan, or the monthly link limit is used up.messagesays which.
Notes
pixelsandchannelmust be yours. The ids come from the pixels and channels lists.
Update a link
PUT/api/url/{id}/update
Change a link. Only the fields you send change.
Needs: API key with write access.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) | Path | integer | The link's id. At least 1. |
url | Body | string | The new full web address the link leads to. |
custom | Body | string | The ending you want, such as lunch-menu. Letters, numbers, dashes and underscores. Leave it out to get a random one. The shortest ending allowed on siz.la depends on the plan. |
domain | Body | string | One of your connected custom domains, as the host name (go.example.com) or its id. Leave it out to use siz.la. |
password | Body | string | A password visitors must enter before they are sent on. On update, send an empty string to remove it. |
expiry | Body | string | When the link stops working, as a date and time in the future such as 2026-12-31 18:00. On update, send an empty string to remove it. |
campaign | Body | string | A campaign to put the link in, by id or by name. A name that does not exist yet makes a new campaign. Needs Pro and the plans above it. |
cta | Body | integer | One of your call-to-action messages, by id, to show over the page the link opens. On update, send 0 to remove it. |
pixels | Body | array | The ids of your ad pixels to fire on each click, from the pixels list. On update, an empty list removes them all and leaving it out keeps them. |
channel | Body | string | A channel to put the link in, by id or by name. On update, send an empty string to take it out. |
splash | Body | integer | One of your splash pages, by id, to show for a few seconds before the page opens. A link shows a splash page or a call to action, not both. On update, send 0 to remove it. |
openinapp | Body | boolean | Open the app on a phone when the address belongs to a known app, such as YouTube or Spotify, and the app is installed. On by default for every plan; send false to always open the web page. An app address you set with deeplink is used first. Default 1. |
blockbots | Body | boolean | Answer crawlers and scripts with a plain "not found" page instead of the redirect. Their visits are not counted. Chat apps that fetch a card still get it when the link has a preview. Leave it out on update to keep what the link has. Default ``. |
openinbrowser | Body | boolean | Show people inside the Instagram, TikTok or Facebook app a page that helps them open the link in their own browser. The visit is counted when they do. Leave it out on update to keep what the link has. Default ``. |
metatitle | Body | string | The title shown when the link is shared in a chat app or on a social site. Send an empty string to remove it. Up to 191 characters. |
metadescription | Body | string | The description shown when the link is shared. Send an empty string to remove it. Up to 500 characters. |
metaimage | Body | string | The address of the picture shown when the link is shared. It must start with https:// or http://. Send an empty string to remove it. Up to 191 characters. |
description | Body | string | A private note. Only you see it. |
geotarget | Body | array | Send visitors from some countries somewhere else: a list of objects with location (a country name or two-letter code) and link (the address). |
devicetarget | Body | array | Send some devices somewhere else: a list of objects with device (ios, android, windows, macos or linux) and link. |
languagetarget | Body | array | Send some browser languages somewhere else: a list of objects with language (a two-letter code) and link. |
deeplink | Body | object | Send phones to an app or store address of your own instead of the web address: an object with apple and google addresses. Links to well-known apps open the app without this; see openinapp. |
type | Body | string | Only direct is available. Any other value is refused. One of direct. |
Example request
curl -X PUT "https://siz.la/api/url/1042/update" \
-H "Authorization: Bearer $SIZLA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/new-address"}'const response = await fetch("https://siz.la/api/url/1042/update", {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"url": "https://example.com/new-address"
}),
});
const data = await response.json();
console.log(data);import os
import requests
response = requests.put(
"https://siz.la/api/url/1042/update",
headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
json={
"url": "https://example.com/new-address",
},
)
print(response.json())$ch = curl_init('https://siz.la/api/url/1042/update');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://example.com/new-address',
]),
]);
$data = json_decode(curl_exec($ch), true);Example answer, status 200
{
"error": 0,
"id": 1042,
"short": "https://siz.la/lunch-menu"
}Errors specific to this call
404: The link does not exist or belongs to someone else.400: A value is not allowed.messagesays which.
Notes
- The short address in the answer is under
shorthere, and undershorturlwhen a link is made.
Delete a link
DELETE/api/url/{id}/delete
Delete a link and its click history for good. The short address stops working and cannot be used again.
Needs: API key with write access.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) | Path | integer | The link's id. At least 1. |
Example request
curl -X DELETE "https://siz.la/api/url/1042/delete" \
-H "Authorization: Bearer $SIZLA_API_KEY"const response = await fetch("https://siz.la/api/url/1042/delete", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
},
});
const data = await response.json();
console.log(data);import os
import requests
response = requests.delete(
"https://siz.la/api/url/1042/delete",
headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())$ch = curl_init('https://siz.la/api/url/1042/delete');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);Example answer, status 200
{
"error": 0,
"message": "Link has been deleted successfully"
}Errors specific to this call
404: The link does not exist or belongs to someone else.