Docs menu

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.

FeatureFreeProTeamBusinessOrganization
Password on a linkYesYesYesYesYes
Expiry dateYesYesYesYesYes
Click limitYesYesYesYesYes
Targeting by country, device and languageYesYesYesYesYes
App deep linksYesYesYesYesYes
CampaignsNoYesYesYesYes
ConversionsNoYesYesYesYes
WebhooksNoYesYesYesYes
Raw click exportNoYesYesYesYes

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.

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.

GET/api/urls

Your links, newest first, with the number of clicks on each.

Needs: API key.

Parameters

NameInTypeDescription
limitQueryintegerHow many links to return on a page. 1 to 100. Default 15.
pageQueryintegerWhich page to return. At least 1. Default 1.
orderQuerystringNewest first (date) or most clicked first (click). One of date, click. Default date.
shortQuerystringFind one link by its ending or its full short address.
qQuerystringText to look for in the destination, the ending and the title.

Example request

Shell
curl "https://siz.la/api/urls?limit=10&page=1" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
JavaScript
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);
Python
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())
PHP
$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

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

  • error is the text "0" on this endpoint and the number 0 on the others. Compare it loosely or convert it first.
  • result is the total number of links that match, not the number on this page.

GET/api/url/{id}

One link with its settings and a summary of its clicks.

Needs: API key.

Parameters

NameInTypeDescription
id (required)PathintegerThe link's id, from the list or from the answer when it was made. At least 1.

Example request

Shell
curl "https://siz.la/api/url/1042" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
JavaScript
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);
Python
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())
PHP
$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

JSON
{
    "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 (topCountries and the others) is the number 0 when there are no clicks to count.

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

NameInTypeDescription
url (required)BodystringThe full web address to shorten. It must start with http:// or https://.
customBodystringThe 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.
domainBodystringOne of your connected custom domains, as the host name (go.example.com) or its id. Leave it out to use siz.la.
passwordBodystringA password visitors must enter before they are sent on. On update, send an empty string to remove it.
expiryBodystringWhen 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.
campaignBodystringA 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.
ctaBodyintegerOne of your call-to-action messages, by id, to show over the page the link opens. On update, send 0 to remove it.
pixelsBodyarrayThe 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.
channelBodystringA channel to put the link in, by id or by name. On update, send an empty string to take it out.
splashBodyintegerOne 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.
openinappBodybooleanOpen 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.
blockbotsBodybooleanAnswer 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 ``.
openinbrowserBodybooleanShow 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 ``.
metatitleBodystringThe 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.
metadescriptionBodystringThe description shown when the link is shared. Send an empty string to remove it. Up to 500 characters.
metaimageBodystringThe 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.
descriptionBodystringA private note. Only you see it.
geotargetBodyarraySend visitors from some countries somewhere else: a list of objects with location (a country name or two-letter code) and link (the address).
devicetargetBodyarraySend some devices somewhere else: a list of objects with device (ios, android, windows, macos or linux) and link.
languagetargetBodyarraySend some browser languages somewhere else: a list of objects with language (a two-letter code) and link.
deeplinkBodyobjectSend 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.
typeBodystringOnly direct is available. Any other value is refused. One of direct.

Example request

Shell
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"}'
JavaScript
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);
Python
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())
PHP
$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

JSON
{
    "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. message says which.

Notes

  • pixels and channel must be yours. The ids come from the pixels and channels lists.

PUT/api/url/{id}/update

Change a link. Only the fields you send change.

Needs: API key with write access.

Parameters

NameInTypeDescription
id (required)PathintegerThe link's id. At least 1.
urlBodystringThe new full web address the link leads to.
customBodystringThe 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.
domainBodystringOne of your connected custom domains, as the host name (go.example.com) or its id. Leave it out to use siz.la.
passwordBodystringA password visitors must enter before they are sent on. On update, send an empty string to remove it.
expiryBodystringWhen 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.
campaignBodystringA 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.
ctaBodyintegerOne of your call-to-action messages, by id, to show over the page the link opens. On update, send 0 to remove it.
pixelsBodyarrayThe 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.
channelBodystringA channel to put the link in, by id or by name. On update, send an empty string to take it out.
splashBodyintegerOne 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.
openinappBodybooleanOpen 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.
blockbotsBodybooleanAnswer 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 ``.
openinbrowserBodybooleanShow 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 ``.
metatitleBodystringThe 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.
metadescriptionBodystringThe description shown when the link is shared. Send an empty string to remove it. Up to 500 characters.
metaimageBodystringThe 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.
descriptionBodystringA private note. Only you see it.
geotargetBodyarraySend visitors from some countries somewhere else: a list of objects with location (a country name or two-letter code) and link (the address).
devicetargetBodyarraySend some devices somewhere else: a list of objects with device (ios, android, windows, macos or linux) and link.
languagetargetBodyarraySend some browser languages somewhere else: a list of objects with language (a two-letter code) and link.
deeplinkBodyobjectSend 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.
typeBodystringOnly direct is available. Any other value is refused. One of direct.

Example request

Shell
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"}'
JavaScript
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);
Python
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())
PHP
$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

JSON
{
    "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. message says which.

Notes

  • The short address in the answer is under short here, and under shorturl when a link is made.

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

NameInTypeDescription
id (required)PathintegerThe link's id. At least 1.

Example request

Shell
curl -X DELETE "https://siz.la/api/url/1042/delete" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
JavaScript
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);
Python
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())
PHP
$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

JSON
{
    "error": 0,
    "message": "Link has been deleted successfully"
}

Errors specific to this call

  • 404: The link does not exist or belongs to someone else.