# siz.la developer docs

# siz.la developer docs

siz.la makes short links, QR codes and link-in-bio pages, and counts every click. Whatever you can do in the members area you can do from your own code with the REST API, hear about it as it happens with webhooks, or ask an AI assistant to do it with the connector.

## Your first short link

You need a siz.la account and an API key. Make the key under Settings, then [Developers](https://siz.la/user/developers). It is shown once, so copy it and keep it in an environment variable called `SIZLA_API_KEY`.

Every call goes to one base address, over HTTPS:

```text
https://siz.la/api
```

First check that the key works. This returns the account it belongs to:


**cURL**

```bash
curl "https://siz.la/api/account" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/account", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/account",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/account');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
```



Then shorten a link:


**cURL**

```bash
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**

```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**

```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**

```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);
```



The answer has the short address and the link's id:

```json
{
  "error": 0,
  "id": 1042,
  "shorturl": "https://siz.la/lunch-menu"
}
```

Open the short address and you are sent to the long one. The click is counted. Read the link back with its id to see how it is doing:


**cURL**

```bash
curl "https://siz.la/api/url/1042" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```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**

```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**

```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);
```



## How it works

- Requests and answers are JSON. Send `Content-Type: application/json` with a body.
- Every answer has `error`: `0` when it worked, `1` with a `message` when it did not. See (https://siz.la/docs/errors).
- Each plan allows a number of requests a minute. See (https://siz.la/docs/errors).
- A key acts as the account it belongs to. It can see and change that account's links and nothing else.

## Machine-readable description

The whole API is described in an OpenAPI 3.1 file at [https://siz.la/openapi.json](https://siz.la/openapi.json). Import it into Postman, Insomnia or a code generator. The same file, the examples and these pages are kept in the public repository at [https://github.com/NeoReader/sizla-docs](https://github.com/NeoReader/sizla-docs).

## Where to go next


- [Quick start](quick-start.md): Shorten links, read stats and record conversions from your own code with the siz.la REST API, webhooks and an MCP connector for AI assistants.
- [Authentication](authentication.md): How to make an API key, send it with each request and keep it safe.
- [Links](links.md): Create, list, read, change and delete short links with the siz.la REST API, with cURL, JavaScript, Python and PHP examples.
- [Campaigns](campaigns.md): Make, list, change and delete campaigns, put links in them and read the clicks of a whole campaign with the siz.la REST API.
- [Domains](domains.md): Add your own domain, read the DNS records to set, check it and set where the bare domain leads with the siz.la REST API.
- [Pixels](pixels.md): Add, list, change and delete Meta, Google, TikTok, LinkedIn, Pinterest, X, Snapchat, Microsoft, Reddit and Quora pixels, then fire them on links, with the siz.la REST API.
- [QR codes](qr-codes.md): Make, list, change and delete QR codes for links, contact cards, Wi-Fi and more, and read their scans, with the siz.la REST API.
- [Overlays](overlays.md): List the call-to-action messages on your account so you can show one over the page a link opens.
- [Channels](channels.md): Make, list, change and delete channels, and put links, QR codes and bio pages in them, with the siz.la REST API.
- [Splash pages](splash.md): Make, list, change and delete splash pages, then show one for a few seconds before a short link opens, with the siz.la REST API.
- [Account](account.md): Read the account behind an API key and change its email or password.
- [Click export](clicks.md): Download every click on your links, with country, device, referrer and UTM fields, as CSV or JSON lines.
- [Conversions](conversions.md): Count sign-ups and sales against the click that brought the visitor, from your server or with the sz.js browser snippet.
- [Webhooks](webhooks.md): Get a signed message at your own address when a link is made, changed or clicked and when a conversion comes in.
- [Integrations](integrations.md): Start automations from clicks, QR code scans, new links and email sign-ups, make links from Zapier, Make or n8n, and send sign-ups to Mailchimp or Slack.
- [AI assistant connector](connector.md): Connect Claude, ChatGPT, Cursor, VS Code or any MCP client to siz.la to make links and QR codes and read stats by asking.
- [Errors and rate limits](errors.md): The error format, every status the API sends, and how many requests each plan can make a minute.


# Authentication

The API uses bearer keys. A key belongs to one account and carries that account's plan limits.

## Make a key

1. Sign in and open Settings, then [Developers](https://siz.la/user/developers).
2. Choose Make a key.
3. Copy the key. It is shown once, and only the last four characters are kept on screen afterward.

An account has one key at a time. Making a new key stops the old one working at once, so update your code first or have both steps ready.

## Send it with every request

Put the key in the `Authorization` header:

```text
Authorization: Bearer YOUR_API_KEY
```


**cURL**

```bash
curl "https://siz.la/api/account" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/account", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/account",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/account');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
```



A missing, wrong or revoked key gets status `401` and this answer:

```json
{
  "error": 1,
  "message": "A valid API key is required."
}
```

Accounts that have been closed get the same answer.

## Keep it safe

- Keep the key on your server or in a secret store. Do not put it in a web page, a mobile app or a public repository.
- Read it from an environment variable, as the examples do.
- If it leaks, make a new key. The old one stops working at once.
- Changing the email address or the password through the API also needs the account's current password, so a leaked key alone cannot take an account over.
- Use HTTPS. Requests over plain HTTP are not served.

## Keys and the browser

The only call that works without a key is the browser conversion call, which is proved by a click id instead. See (https://siz.la/docs/conversions). Every other call needs a key, so do not call the API from code that runs in a visitor's browser.

## AI assistants do not use keys

The assistant connector signs in with OAuth and never sees your key. See (https://siz.la/docs/connector).


# Links API

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**

```bash
curl "https://siz.la/api/urls?limit=10&page=1" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```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**

```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**

```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 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**

```bash
curl "https://siz.la/api/url/1042" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```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**

```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**

```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.

## 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**

```bash
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**

```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**

```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**

```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.

## 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**

```bash
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**

```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**

```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**

```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 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**

```bash
curl -X DELETE "https://siz.la/api/url/1042/delete" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```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**

```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**

```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.


# Campaigns API

A campaign groups links so you can read their clicks together and give them the same UTM values. Campaigns are part of the paid plans. Reading needs a key; making, changing, deleting and filling a campaign need a key with write access, like the link calls.

A link joins a campaign in one of three ways: the `campaign` option when it is made or changed (see (https://siz.la/docs/links)), the assign call below, or a bulk upload in the members area. The campaign's UTM values are added to the link's address, and anything set on the link itself wins.


## List campaigns

`GET /api/campaigns`

Your campaigns by name, with how many links each holds and its clicks over the last 30 days.

**Needs:** API key. Needs Pro and the plans above it.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `limit` | Query | integer | How many campaigns to return on a page. 1 to 100. Default `15`. |
| `page` | Query | integer | Which page to return. At least 1. Default `1`. |
| `q` | Query | string | Text to look for in the name. |

**Example request**

**cURL**

```bash
curl "https://siz.la/api/campaigns?limit=10&page=1" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/campaigns?limit=10&page=1", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/campaigns",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    params={
        "limit": 10,
        "page": 1,
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/campaigns?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,
        "campaigns": [
            {
                "id": 12,
                "name": "Summer menu",
                "color": "ember",
                "utm_source": "newsletter",
                "utm_medium": "email",
                "utm_campaign": "summer-menu",
                "links": 8,
                "clicks": 412
            }
        ]
    }
}
```

**Errors specific to this call**

- `403`: The plan does not include campaigns.

**Notes**

- `error` is the text `"0"` on this endpoint and the number `0` on the others.

## Get a campaign

`GET /api/campaign/{id}`

One campaign with its settings, its clicks and where they came from.

**Needs:** API key. Needs Pro and the plans above it.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The campaign's id. At least 1. |
| `days` | Query | integer | How many days back to report. The plan may keep less history than that. One of `7`, `30`, `90`. Default `30`. |

**Example request**

**cURL**

```bash
curl "https://siz.la/api/campaign/12?days=30" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/campaign/12?days=30", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/campaign/12",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    params={
        "days": 30,
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/campaign/12?days=30');
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": 12,
    "details": {
        "id": 12,
        "name": "Summer menu",
        "color": "ember",
        "utm_source": "newsletter",
        "utm_medium": "email",
        "utm_campaign": "summer-menu",
        "links": 8,
        "date": "2026-11-10 08:00:00"
    },
    "data": {
        "days": 30,
        "clicks": 412,
        "uniqueClicks": 355,
        "topCountries": {
            "US": 240,
            "GB": 61
        },
        "topReferrers": {
            "t.co": 90
        },
        "topDevices": {
            "mobile": 301,
            "desktop": 111
        },
        "topLinks": [
            {
                "id": 1042,
                "shorturl": "https://siz.la/lunch-menu",
                "clicks": 37
            }
        ]
    }
}
```

**Errors specific to this call**

- `403`: The plan does not include campaigns.
- `404`: The campaign does not exist or belongs to someone else.

**Notes**

- A list in `data` is the number `0` when there are no clicks to count.

## Make a campaign

`POST /api/campaign/add`

Make a campaign. Put links in it with the `campaign` option on a link or with the assign call.

**Needs:** API key with write access. Needs Pro and the plans above it.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `name` (required) | Body | string | The campaign's name. It must be different from your other campaigns. Up to 80 characters. |
| `color` | Body | string | The color of the campaign's dot in the members area. The default is `ink`. One of `ink`, `ember`, `sky`, `mint`, `lilac`, `butter`, `blush`, `slate`. |
| `utm_source` | Body | string | Added to the address of every link in the campaign as `utm_source`. Send an empty string to remove it. Up to 100 characters. |
| `utm_medium` | Body | string | Added as `utm_medium`. Up to 100 characters. |
| `utm_campaign` | Body | string | Added as `utm_campaign`. Up to 100 characters. |

**Example request**

**cURL**

```bash
curl -X POST "https://siz.la/api/campaign/add" \
  -H "Authorization: Bearer $SIZLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Summer menu","utm_source":"newsletter","utm_medium":"email"}'
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/campaign/add", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Summer menu",
    "utm_source": "newsletter",
    "utm_medium": "email"
  }),
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://siz.la/api/campaign/add",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    json={
        "name": "Summer menu",
        "utm_source": "newsletter",
        "utm_medium": "email",
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/campaign/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([
        'name' => 'Summer menu',
        'utm_source' => 'newsletter',
        'utm_medium' => 'email',
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status 200**

```json
{
    "error": 0,
    "id": 12,
    "name": "Summer menu"
}
```

**Errors specific to this call**

- `400`: The name is missing or already used, a value is not allowed, or the account has the most campaigns it can keep.
- `403`: The plan does not include campaigns.

## Update a campaign

`PUT /api/campaign/{id}/update`

Change a campaign. Only the fields you send change. New UTM values reach a link the next time it is saved or added to the campaign.

**Needs:** API key with write access. Needs Pro and the plans above it.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The campaign's id. At least 1. |
| `name` | Body | string | The campaign's name. It must be different from your other campaigns. Up to 80 characters. |
| `color` | Body | string | The color of the campaign's dot in the members area. The default is `ink`. One of `ink`, `ember`, `sky`, `mint`, `lilac`, `butter`, `blush`, `slate`. |
| `utm_source` | Body | string | Added to the address of every link in the campaign as `utm_source`. Send an empty string to remove it. Up to 100 characters. |
| `utm_medium` | Body | string | Added as `utm_medium`. Up to 100 characters. |
| `utm_campaign` | Body | string | Added as `utm_campaign`. Up to 100 characters. |

**Example request**

**cURL**

```bash
curl -X PUT "https://siz.la/api/campaign/12/update" \
  -H "Authorization: Bearer $SIZLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"utm_campaign":"summer-menu-2026"}'
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/campaign/12/update", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "utm_campaign": "summer-menu-2026"
  }),
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.put(
    "https://siz.la/api/campaign/12/update",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    json={
        "utm_campaign": "summer-menu-2026",
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/campaign/12/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([
        'utm_campaign' => 'summer-menu-2026',
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status 200**

```json
{
    "error": 0,
    "id": 12,
    "name": "Summer menu"
}
```

**Errors specific to this call**

- `400`: A value is not allowed. `message` says which.
- `403`: The plan does not include campaigns.
- `404`: The campaign does not exist or belongs to someone else.

## Delete a campaign

`DELETE /api/campaign/{id}/delete`

Delete a campaign. Its links keep working and leave the campaign.

**Needs:** API key with write access. Needs Pro and the plans above it.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The campaign's id. At least 1. |

**Example request**

**cURL**

```bash
curl -X DELETE "https://siz.la/api/campaign/12/delete" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/campaign/12/delete", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.delete(
    "https://siz.la/api/campaign/12/delete",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/campaign/12/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": "Campaign has been deleted successfully"
}
```

**Errors specific to this call**

- `403`: The plan does not include campaigns.
- `404`: The campaign does not exist or belongs to someone else.

## Put a link in a campaign

`POST /api/campaign/{id}/assign/{link}`

Move one of your links into a campaign. The campaign's UTM values are added to the link's address.

**Needs:** API key with write access. Needs Pro and the plans above it.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The campaign's id. At least 1. |
| `link` (required) | Path | integer | The link's id. At least 1. |

**Example request**

**cURL**

```bash
curl -X POST "https://siz.la/api/campaign/12/assign/1042" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/campaign/12/assign/1042", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://siz.la/api/campaign/12/assign/1042",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/campaign/12/assign/1042');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    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 assigned to the campaign."
}
```

**Errors specific to this call**

- `403`: The plan does not include campaigns.
- `404`: The campaign or the link does not exist or belongs to someone else.

**Notes**

- To take a link out of a campaign, update the link with an empty `campaign`.


# Domains API

Custom domains let you make short links on an address of your own, such as `go.example.com`, instead of siz.la. Reading needs a key. Adding, changing, checking and deleting a domain need a key with write access, like the link calls.

A new domain is `pending`. Add the two DNS records the answer lists, a CNAME that points the domain here and a TXT record that proves you own it, then call the check endpoint. The domain is also checked on its own every few minutes. Once it is `active`, send its host name or id as `domain` when you make or change a link (see (https://siz.la/docs/links)). A domain that is not active cannot be used on a link.

How many domains an account can keep depends on the plan.


## List domains

`GET /api/domains`

Your custom domains by name, with where the bare domain and unknown endings send people.

**Needs:** API key.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `limit` | Query | integer | How many domains to return on a page. 1 to 100. Default `15`. |
| `page` | Query | integer | Which page to return. At least 1. Default `1`. |

**Example request**

**cURL**

```bash
curl "https://siz.la/api/domains?limit=10&page=1" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/domains?limit=10&page=1", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/domains",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    params={
        "limit": 10,
        "page": 1,
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/domains?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,
        "domains": [
            {
                "id": 31,
                "domain": "go.example.com",
                "redirectroot": "https://example.com",
                "redirect404": "https://example.com/not-found",
                "status": "active"
            }
        ]
    }
}
```

**Notes**

- `status` is `pending` until the DNS records are in place, `active` while links work on the domain and `failed` when the records stop pointing here. Only an `active` domain can be used on a link.
- `error` is the text `"0"` on this endpoint and the number `0` on the others.

## Add a domain

`POST /api/domain/add`

Add a domain or subdomain you own. The answer lists the two DNS records to add where its DNS is managed. Then call the check endpoint, or wait: domains are checked on their own every few minutes.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `domain` (required) | Body | string | The domain, such as `go.example.com`. A scheme, path or port is dropped. |
| `redirectroot` | Body | string | Where the bare domain sends visitors. It must start with `http://` or `https://`. |
| `redirect404` | Body | string | Where an ending that does not exist sends visitors. |

**Example request**

**cURL**

```bash
curl -X POST "https://siz.la/api/domain/add" \
  -H "Authorization: Bearer $SIZLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"go.example.com","redirectroot":"https://example.com"}'
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/domain/add", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "domain": "go.example.com",
    "redirectroot": "https://example.com"
  }),
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://siz.la/api/domain/add",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    json={
        "domain": "go.example.com",
        "redirectroot": "https://example.com",
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/domain/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([
        'domain' => 'go.example.com',
        'redirectroot' => 'https://example.com',
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status pending**

```json
{
    "error": 0,
    "id": 31,
    "domain": "go.example.com",
    "status": "pending",
    "records": {
        "cname": {
            "type": "CNAME",
            "name": "go.example.com",
            "value": "connect.siz.la"
        },
        "txt": {
            "type": "TXT",
            "name": "_sizla.go.example.com",
            "value": "sizla-verify=0123456789abcdef0123456789abcdef"
        }
    }
}
```

**Errors specific to this call**

- `400`: The domain is not a valid name, is siz.la itself, belongs to another account, or the account has the most domains its plan allows. `message` says which.

**Notes**

- The number of domains depends on the plan.

## Update a domain

`PUT /api/domain/{id}/update`

Change where the bare domain and unknown endings lead. Only the fields you send change.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The domain's id. At least 1. |
| `redirectroot` | Body | string | Where the bare domain sends visitors. Send an empty string to remove it. |
| `redirect404` | Body | string | Where an ending that does not exist sends visitors. Send an empty string to remove it. |

**Example request**

**cURL**

```bash
curl -X PUT "https://siz.la/api/domain/31/update" \
  -H "Authorization: Bearer $SIZLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"redirect404":"https://example.com/not-found"}'
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/domain/31/update", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "redirect404": "https://example.com/not-found"
  }),
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.put(
    "https://siz.la/api/domain/31/update",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    json={
        "redirect404": "https://example.com/not-found",
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/domain/31/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([
        'redirect404' => 'https://example.com/not-found',
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status 200**

```json
{
    "error": 0,
    "message": "Domain has been updated successfully"
}
```

**Errors specific to this call**

- `404`: The domain does not exist or belongs to someone else.
- `400`: An address is not allowed. `message` says which.

## Check a domain

`POST /api/domain/{id}/check`

Look for the DNS records now and turn the domain on when they are right. `problem` says what is still missing.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The domain's id. At least 1. |

**Example request**

**cURL**

```bash
curl -X POST "https://siz.la/api/domain/31/check" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/domain/31/check", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://siz.la/api/domain/31/check",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/domain/31/check');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status active**

```json
{
    "error": 0,
    "id": 31,
    "status": "active",
    "problem": null,
    "records": {
        "cname": {
            "type": "CNAME",
            "name": "go.example.com",
            "value": "connect.siz.la"
        },
        "txt": {
            "type": "TXT",
            "name": "_sizla.go.example.com",
            "value": "sizla-verify=0123456789abcdef0123456789abcdef"
        }
    }
}
```

**Errors specific to this call**

- `404`: The domain does not exist or belongs to someone else.

**Notes**

- DNS changes can take a few minutes to an hour to show.

## Delete a domain

`DELETE /api/domain/{id}/delete`

Remove a domain. A domain that still has links is refused: move them to another domain or delete them first.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The domain's id. At least 1. |

**Example request**

**cURL**

```bash
curl -X DELETE "https://siz.la/api/domain/31/delete" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/domain/31/delete", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.delete(
    "https://siz.la/api/domain/31/delete",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/domain/31/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": "Domain has been deleted successfully"
}
```

**Errors specific to this call**

- `404`: The domain does not exist or belongs to someone else.
- `400`: The domain still has links.


# Pixels API

A pixel is an ad or analytics id, such as a Meta pixel or a Google Analytics measurement id, that fires when someone clicks a link, before the visitor moves on. Reading needs a key. Adding, changing and deleting pixels need a key with write access.

To use a pixel, send its id in the `pixels` list when you make or change a link (see (https://siz.la/docs/links)). A link can fire a limited number of pixels at once. Deleting a pixel takes it off every link that used it.


## List pixels

`GET /api/pixels`

Your pixels by name. Send their ids as `pixels` when you make or change a link.

**Needs:** API key.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `limit` | Query | integer | How many pixels to return on a page. 1 to 100. Default `15`. |
| `page` | Query | integer | Which page to return. At least 1. Default `1`. |

**Example request**

**cURL**

```bash
curl "https://siz.la/api/pixels?limit=10&page=1" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/pixels?limit=10&page=1", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/pixels",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    params={
        "limit": 10,
        "page": 1,
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/pixels?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,
        "pixels": [
            {
                "id": 9,
                "type": "meta",
                "name": "Spring campaign",
                "tag": "123456789012345",
                "date": "2026-11-12 08:20:00"
            }
        ]
    }
}
```

**Errors specific to this call**

- `403`: The plan does not include pixels.

**Notes**

- `error` is the text `"0"` on this endpoint and the number `0` on the others.

## Add a pixel

`POST /api/pixel/add`

Add a pixel. The id is checked against the format of the type you pick.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `type` (required) | Body | string | Where the pixel reports to. One of `meta`, `google_ads`, `ga4`, `tiktok`, `linkedin`, `pinterest`, `x`, `snapchat`, `microsoft`, `reddit`, `quora`. |
| `name` (required) | Body | string | A name for you. Only you see it. Up to 80 characters. |
| `tag` (required) | Body | string | The pixel id from the provider. It must fit the format of the type. Up to 60 characters. |

**Example request**

**cURL**

```bash
curl -X POST "https://siz.la/api/pixel/add" \
  -H "Authorization: Bearer $SIZLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"meta","name":"Spring campaign","tag":"123456789012345"}'
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/pixel/add", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "type": "meta",
    "name": "Spring campaign",
    "tag": "123456789012345"
  }),
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://siz.la/api/pixel/add",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    json={
        "type": "meta",
        "name": "Spring campaign",
        "tag": "123456789012345",
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/pixel/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([
        'type' => 'meta',
        'name' => 'Spring campaign',
        'tag' => '123456789012345',
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status 200**

```json
{
    "error": 0,
    "id": 9
}
```

**Errors specific to this call**

- `400`: The type or id is not valid, you already have that pixel, or the account has the most pixels it can keep. `message` says which.
- `403`: The plan does not include pixels.

**Notes**

- Ids by type: `meta` is the pixel id, all digits, from Events Manager; `google_ads` is the conversion id that starts with AW-; `ga4` is the measurement id that starts with G-; `tiktok` is the pixel id from TikTok Events Manager; `linkedin` is the Insight Tag partner id, all digits; `pinterest` is the tag id, all digits, from Pinterest Ads; `x` is the pixel id from X Ads events manager; `snapchat` is the pixel id from Snapchat Ads Manager, with its dashes; `microsoft` is the UET tag id, all digits; `reddit` is the pixel id from Reddit Ads, starting with t2_ or a2_; `quora` is the pixel id from Quora Ads Manager, 32 letters and digits.

## Update a pixel

`PUT /api/pixel/{id}/update`

Change a pixel. Only the fields you send change. Links that use it fire the new id from then on.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The pixel's id. At least 1. |
| `type` | Body | string | Where the pixel reports to. One of `meta`, `google_ads`, `ga4`, `tiktok`, `linkedin`, `pinterest`, `x`, `snapchat`, `microsoft`, `reddit`, `quora`. |
| `name` | Body | string | A name for you. Only you see it. Up to 80 characters. |
| `tag` | Body | string | The pixel id from the provider. It must fit the format of the type. Up to 60 characters. |

**Example request**

**cURL**

```bash
curl -X PUT "https://siz.la/api/pixel/9/update" \
  -H "Authorization: Bearer $SIZLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Spring campaign 2026"}'
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/pixel/9/update", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Spring campaign 2026"
  }),
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.put(
    "https://siz.la/api/pixel/9/update",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    json={
        "name": "Spring campaign 2026",
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/pixel/9/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([
        'name' => 'Spring campaign 2026',
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status 200**

```json
{
    "error": 0,
    "message": "Pixel has been updated successfully"
}
```

**Errors specific to this call**

- `400`: A value is not valid. `message` says which.
- `403`: The plan does not include pixels.
- `404`: The pixel does not exist or belongs to someone else.

## Delete a pixel

`DELETE /api/pixel/{id}/delete`

Delete a pixel. Every link that used it stops firing it.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The pixel's id. At least 1. |

**Example request**

**cURL**

```bash
curl -X DELETE "https://siz.la/api/pixel/9/delete" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/pixel/9/delete", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.delete(
    "https://siz.la/api/pixel/9/delete",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/pixel/9/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": "Pixel has been deleted successfully"
}
```

**Errors specific to this call**

- `403`: The plan does not include pixels.
- `404`: The pixel does not exist or belongs to someone else.


# QR codes API

A QR code holds a web address, a contact card, a Wi-Fi login or another kind of content. Reading needs a key. Making, changing and deleting codes need a key with write access, like the link calls.

Some types are dynamic. A dynamic code holds a short link, so you can change where it leads after it is printed, and every scan is counted. Static codes hold their content directly, so they cannot change and cannot be counted. Your plan sets how many codes you can make a month.

The members area has a designer for shapes, frames and gradients. Through the API you set the colors and a logo, and a code made in the designer keeps its look when you change its content.


## List QR codes

`GET /api/qr`

Your QR codes, newest first, with how many times each was scanned.

**Needs:** API key.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `limit` | Query | integer | How many codes to return on a page. 1 to 100. Default `15`. |
| `page` | Query | integer | Which page to return. At least 1. Default `1`. |

**Example request**

**cURL**

```bash
curl "https://siz.la/api/qr?limit=10&page=1" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/qr?limit=10&page=1", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/qr",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    params={
        "limit": 10,
        "page": 1,
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/qr?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,
        "qrs": [
            {
                "id": 77,
                "link": "https://siz.la/menu-qr",
                "scans": 58,
                "name": "Table cards",
                "date": "2026-11-13 12:00:00",
                "type": "link"
            }
        ]
    }
}
```

**Notes**

- `link` is the short address a dynamic code points through. It is an empty string for a static code, which holds its content directly, and `scans` is `null` for it because a static code cannot be counted.
- `error` is the text `"0"` on this endpoint and the number `0` on the others.

## Get a QR code

`GET /api/qr/{id}`

One QR code with its content and colors, and a summary of the visits through its link.

**Needs:** API key.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The code's id. At least 1. |

**Example request**

**cURL**

```bash
curl "https://siz.la/api/qr/77" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/qr/77", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/qr/77",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/qr/77');
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,
    "details": {
        "id": 77,
        "link": "https://siz.la/menu-qr",
        "scans": 58,
        "name": "Table cards",
        "date": "2026-11-13 12:00:00",
        "type": "link",
        "foreground": "#17171a",
        "background": "#ffffff",
        "fields": {
            "url": "https://example.com/menu"
        }
    },
    "data": {
        "clicks": 58,
        "uniqueClicks": 49,
        "topCountries": {
            "US": 31,
            "GB": 12
        },
        "topReferrers": 0,
        "topBrowsers": {
            "Safari": 40
        },
        "topOs": {
            "iOS": 38
        },
        "socialCount": {
            "facebook": 0,
            "twitter": 0,
            "instagram": 4
        }
    }
}
```

**Errors specific to this call**

- `404`: The code does not exist or belongs to someone else.

**Notes**

- A list in `data` is the number `0` when there is nothing to count. A static code has no link behind it, so all of `data` is `0`.

## Make a QR code

`POST /api/qr/add`

Make a QR code. Dynamic types make a short link behind the code, so the destination can change later and scans are counted. Your plan's monthly QR code limit applies.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `data` (required) | Body | string | What the code holds. Send text to fill the main field of the type, such as the web address for `link`, or an object with the type's own fields. |
| `type` | Body | string | What the code does when scanned. It cannot be changed afterwards. One of `text`, `sms`, `wifi`, `vcard`, `event`, `link`, `email`, `phone`, `whatsapp`, `app`, `crypto`. Default `link`. |
| `name` | Body | string | A name for you. It defaults to the start of the content. Up to 120 characters. |
| `foreground` | Body | string | The color of the code, such as `#17171a`. It must contrast enough with the background for a phone to read it. |
| `background` | Body | string | The background color, such as `#ffffff`. |
| `logo` | Body | string | A PNG, JPG or WebP picture of up to 500 KB, sent as base64 text or a data address, drawn in the middle of the code. Send an empty string to remove it. |

**Example request**

**cURL**

```bash
curl -X POST "https://siz.la/api/qr/add" \
  -H "Authorization: Bearer $SIZLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"link","data":"https://example.com/menu","name":"Table cards","foreground":"#17171a"}'
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/qr/add", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "type": "link",
    "data": "https://example.com/menu",
    "name": "Table cards",
    "foreground": "#17171a"
  }),
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://siz.la/api/qr/add",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    json={
        "type": "link",
        "data": "https://example.com/menu",
        "name": "Table cards",
        "foreground": "#17171a",
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/qr/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([
        'type' => 'link',
        'data' => 'https://example.com/menu',
        'name' => 'Table cards',
        'foreground' => '#17171a',
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status 200**

```json
{
    "error": 0,
    "id": 77,
    "link": "https://siz.la/menu-qr"
}
```

**Errors specific to this call**

- `400`: The type or content is not valid, the colors are too close for a phone to read, the content is too long for one code, or the monthly limit is used up. `message` says which.

**Notes**

- Types and their fields: `text` takes `text` (the main one); `sms` takes `phone` (the main one), `message`; `wifi` takes `ssid` (the main one), `security`, `password`, `hidden`; `vcard` takes `first_name` (the main one), `last_name`, `organization`, `job_title`, `phone`, `email`, `website`, `address`; `event` takes `title` (the main one), `starts_at`, `ends_at`, `location`, `description`; `link` takes `url` (the main one); `email` takes `to` (the main one), `subject`, `body`; `phone` takes `phone` (the main one); `whatsapp` takes `phone` (the main one), `message`; `app` takes `ios` (the main one), `android`, `fallback`; `crypto` takes `coin`, `address` (the main one), `amount`.
- The answer's `link` is an empty string for a static code.

## Update a QR code

`PUT /api/qr/{id}/update`

Change a QR code. Only the fields you send change. The type of a code cannot change. A dynamic code keeps its printed picture and sends scans to the new destination.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The code's id. At least 1. |
| `data` | Body | string | The new content: text for the main field of the type, or an object with the fields to change. |
| `name` | Body | string | A name for you. It defaults to the start of the content. Up to 120 characters. |
| `foreground` | Body | string | The color of the code, such as `#17171a`. It must contrast enough with the background for a phone to read it. |
| `background` | Body | string | The background color, such as `#ffffff`. |
| `logo` | Body | string | A PNG, JPG or WebP picture of up to 500 KB, sent as base64 text or a data address, drawn in the middle of the code. Send an empty string to remove it. |

**Example request**

**cURL**

```bash
curl -X PUT "https://siz.la/api/qr/77/update" \
  -H "Authorization: Bearer $SIZLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data":"https://example.com/new-menu"}'
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/qr/77/update", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "data": "https://example.com/new-menu"
  }),
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.put(
    "https://siz.la/api/qr/77/update",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    json={
        "data": "https://example.com/new-menu",
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/qr/77/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([
        'data' => 'https://example.com/new-menu',
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status 200**

```json
{
    "error": 0,
    "message": "QR code has been updated successfully"
}
```

**Errors specific to this call**

- `400`: A value is not valid. `message` says which.
- `404`: The code does not exist or belongs to someone else.

## Delete a QR code

`DELETE /api/qr/{id}/delete`

Delete a QR code. The short link made for a dynamic code goes with it, and printed copies stop working.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The code's id. At least 1. |

**Example request**

**cURL**

```bash
curl -X DELETE "https://siz.la/api/qr/77/delete" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/qr/77/delete", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.delete(
    "https://siz.la/api/qr/77/delete",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/qr/77/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": "QR code has been deleted successfully"
}
```

**Errors specific to this call**

- `404`: The code does not exist or belongs to someone else.


# Overlays API

An overlay is a call-to-action message drawn over the page a link opens: a line of text and a button, with an optional picture. You make and edit overlays in the members area, under Call to action. The API lists them so you can pick one by id.

To show an overlay on a link, send its id as `cta` when you make or change the link (see (https://siz.la/docs/links)). The number of overlays you can keep depends on the plan.


## List overlays

`GET /api/overlay`

Your call-to-action messages by name. Send an id as `cta` when you make or change a link.

**Needs:** API key.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `limit` | Query | integer | How many overlays to return on a page. 1 to 100. Default `15`. |
| `page` | Query | integer | Which page to return. At least 1. Default `1`. |

**Example request**

**cURL**

```bash
curl "https://siz.la/api/overlay?limit=10&page=1" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/overlay?limit=10&page=1", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/overlay",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    params={
        "limit": 10,
        "page": 1,
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/overlay?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,
        "cta": [
            {
                "id": 4,
                "type": "banner",
                "name": "Lunch deal",
                "date": "2026-11-12 10:15:00"
            }
        ]
    }
}
```

**Notes**

- Overlays are made and edited in the members area, under Call to action. `type` is one of `banner`, `card`, `button`. `error` is the text `"0"` on this endpoint and the number `0` on the others.


# Channels API

A channel keeps links, QR codes and bio pages together, so you can find and manage a set of them in one place. Channels only group: they add no tracking values and do not combine clicks. For that, use (https://siz.la/docs/campaigns).

An item is in one channel at a time. Put a link in a channel with the `channel` option when you make or change it (see (https://siz.la/docs/links)), or move any link, QR code or bio page with the assign call. Deleting a channel leaves everything in it working. Reading needs a key. Making, changing, deleting and filling a channel need a key with write access.


## List channels

`GET /api/channels`

Your channels, starred ones first, then by name.

**Needs:** API key.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `limit` | Query | integer | How many channels to return on a page. 1 to 100. Default `15`. |
| `page` | Query | integer | Which page to return. At least 1. Default `1`. |

**Example request**

**cURL**

```bash
curl "https://siz.la/api/channels?limit=10&page=1" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/channels?limit=10&page=1", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/channels",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    params={
        "limit": 10,
        "page": 1,
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/channels?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,
        "channels": [
            {
                "id": 5,
                "name": "Spring menu",
                "description": "Everything for the spring menu launch",
                "color": "ember",
                "starred": true
            }
        ]
    }
}
```

**Notes**

- `error` is the text `"0"` on this endpoint and the number `0` on the others.

## List what is in a channel

`GET /api/channel/{id}`

The links, QR codes and bio pages in one channel, newest first.

**Needs:** API key.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The channel's id. At least 1. |
| `limit` | Query | integer | How many items to return on a page. 1 to 100. Default `15`. |
| `page` | Query | integer | Which page to return. At least 1. Default `1`. |

**Example request**

**cURL**

```bash
curl "https://siz.la/api/channel/5?limit=10&page=1" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/channel/5?limit=10&page=1", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/channel/5",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    params={
        "limit": 10,
        "page": 1,
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/channel/5?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,
        "items": [
            {
                "type": "link",
                "id": 1042,
                "title": "lunch-menu",
                "preview": "https://example.com/a/long/address",
                "link": "https://siz.la/lunch-menu",
                "date": "2026-11-14 09:30:00"
            }
        ]
    }
}
```

**Errors specific to this call**

- `404`: The channel does not exist or belongs to someone else.

**Notes**

- `type` is `link`, `qr` or `bio`. `preview` is the destination of a link, the kind of a QR code, or the start of a bio page's text. `link` is the short address, empty for a static QR code.

## Make a channel

`POST /api/channel/add`

Make a channel. Put things in it with the `channel` option on a link or with the assign call.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `name` (required) | Body | string | The channel's name. It must be different from your other channels. Up to 80 characters. |
| `description` | Body | string | What the channel is for. Send an empty string to remove it. Up to 300 characters. |
| `color` | Body | string | The color of the channel's dot in the members area. The default is `ink`. One of `ink`, `ember`, `sky`, `mint`, `lilac`, `butter`, `blush`, `slate`. |
| `starred` | Body | boolean | Starred channels are listed first. |

**Example request**

**cURL**

```bash
curl -X POST "https://siz.la/api/channel/add" \
  -H "Authorization: Bearer $SIZLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Spring menu","description":"Everything for the spring menu launch","starred":true}'
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/channel/add", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Spring menu",
    "description": "Everything for the spring menu launch",
    "starred": true
  }),
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://siz.la/api/channel/add",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    json={
        "name": "Spring menu",
        "description": "Everything for the spring menu launch",
        "starred": True,
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/channel/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([
        'name' => 'Spring menu',
        'description' => 'Everything for the spring menu launch',
        'starred' => true,
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status 200**

```json
{
    "error": 0,
    "id": 5,
    "name": "Spring menu",
    "description": "Everything for the spring menu launch",
    "color": "ember",
    "starred": true
}
```

**Errors specific to this call**

- `400`: The name is missing or already used, a value is not allowed, or the account has the most channels it can keep.

## Update a channel

`PUT /api/channel/{id}/update`

Change a channel. Only the fields you send change.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The channel's id. At least 1. |
| `name` | Body | string | The channel's name. It must be different from your other channels. Up to 80 characters. |
| `description` | Body | string | What the channel is for. Send an empty string to remove it. Up to 300 characters. |
| `color` | Body | string | The color of the channel's dot in the members area. The default is `ink`. One of `ink`, `ember`, `sky`, `mint`, `lilac`, `butter`, `blush`, `slate`. |
| `starred` | Body | boolean | Starred channels are listed first. |

**Example request**

**cURL**

```bash
curl -X PUT "https://siz.la/api/channel/5/update" \
  -H "Authorization: Bearer $SIZLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"starred":false}'
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/channel/5/update", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "starred": false
  }),
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.put(
    "https://siz.la/api/channel/5/update",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    json={
        "starred": False,
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/channel/5/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([
        'starred' => false,
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status 200**

```json
{
    "error": 0,
    "message": "Channel has been updated successfully"
}
```

**Errors specific to this call**

- `400`: A value is not allowed. `message` says which.
- `404`: The channel does not exist or belongs to someone else.

## Delete a channel

`DELETE /api/channel/{id}/delete`

Delete a channel. What was in it keeps working and leaves the channel.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The channel's id. At least 1. |

**Example request**

**cURL**

```bash
curl -X DELETE "https://siz.la/api/channel/5/delete" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/channel/5/delete", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.delete(
    "https://siz.la/api/channel/5/delete",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/channel/5/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": "Channel has been deleted successfully"
}
```

**Errors specific to this call**

- `404`: The channel does not exist or belongs to someone else.

## Put something in a channel

`POST /api/channel/{id}/assign/{type}/{item}`

Move one of your links, QR codes or bio pages into a channel. An item is in one channel at a time, so this takes it out of its old one.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The channel's id. At least 1. |
| `type` (required) | Path | string | What kind of item it is. One of `link`, `qr`, `bio`. |
| `item` (required) | Path | integer | The item's id. At least 1. |

**Example request**

**cURL**

```bash
curl -X POST "https://siz.la/api/channel/5/assign/link/1042" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/channel/5/assign/link/1042", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://siz.la/api/channel/5/assign/link/1042",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/channel/5/assign/link/1042');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status 200**

```json
{
    "error": 0,
    "message": "Item has been assigned to the channel."
}
```

**Errors specific to this call**

- `400`: The type is not `link`, `qr` or `bio`.
- `404`: The channel or the item does not exist or belongs to someone else.

## Take something out of a channel

`DELETE /api/channel/{id}/unassign/{type}/{item}`

Take an item out of a channel. The item itself is not touched.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The channel's id. At least 1. |
| `type` (required) | Path | string | What kind of item it is. One of `link`, `qr`, `bio`. |
| `item` (required) | Path | integer | The item's id. At least 1. |

**Example request**

**cURL**

```bash
curl -X DELETE "https://siz.la/api/channel/5/unassign/link/1042" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/channel/5/unassign/link/1042", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.delete(
    "https://siz.la/api/channel/5/unassign/link/1042",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/channel/5/unassign/link/1042');
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": "Item has been taken out of the channel."
}
```

**Errors specific to this call**

- `400`: The type is not `link`, `qr` or `bio`.
- `404`: The channel does not exist, or the item is not in it.


# Splash pages API

A splash page is a page shown for a few seconds before a link opens. It has a title, some text, an optional picture and a button, and a countdown that moves on by itself. Visitors can press the button to go at once or stop the timer to stay. Search engines and link previews skip it and get the link's usual answer.

Make the page with the calls below, or in the members area under Splash pages, where you can also add a picture. Then use it on a link with the `splash` option (see (https://siz.la/docs/links)). A link shows a splash page or a call to action, not both. How many splash pages you can keep depends on your plan.

Pixels set on the link fire on the splash page. Reading needs a key; making, changing and deleting need a key with write access, like the link calls.


## List splash pages

`GET /api/splash`

Your splash pages by name, with how many links use each.

**Needs:** API key.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `limit` | Query | integer | How many splash pages to return on a page. 1 to 100. Default `15`. |
| `page` | Query | integer | Which page to return. At least 1. Default `1`. |

**Example request**

**cURL**

```bash
curl "https://siz.la/api/splash?limit=10&page=1" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/splash?limit=10&page=1", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/splash",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    params={
        "limit": 10,
        "page": 1,
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/splash?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,
        "splash": [
            {
                "id": 7,
                "name": "Menu launch",
                "date": "2026-11-12 10:00:00",
                "title": "Taking you to the new menu",
                "message": "Show this page at the counter for a free coffee.",
                "button_label": "Continue",
                "seconds": 5,
                "background_color": "#ffffff",
                "text_color": "#17171a",
                "button_color": "#e2500f",
                "show_branding": true,
                "links": 3
            }
        ]
    }
}
```

**Notes**

- `error` is the text `"0"` on this endpoint and the number `0` on the others.

## Make a splash page

`POST /api/splash/add`

Make a splash page. Use it on a link with the `splash` option. A picture can be added in the members area.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `name` (required) | Body | string | The splash page's name, for you. Visitors do not see it. Up to 80 characters. |
| `title` (required) | Body | string | The heading visitors see. Up to 120 characters. |
| `message` | Body | string | A few lines under the title. Send an empty string to remove it. Up to 500 characters. |
| `button_label` | Body | string | The words on the button, which skips the wait. The default is `Continue`. Up to 40 characters. |
| `seconds` | Body | integer | How long the page waits before it moves on by itself. 2 to 15. Default `5`. |
| `background_color` | Body | string | Page color as six-digit hex, such as `#ffffff`. |
| `text_color` | Body | string | Text color as six-digit hex. |
| `button_color` | Body | string | Button color as six-digit hex. |
| `show_branding` | Body | boolean | Whether the siz.la mark is shown. It can only be turned off on the plans that remove it. Needs Pro and the plans above it. |

**Example request**

**cURL**

```bash
curl -X POST "https://siz.la/api/splash/add" \
  -H "Authorization: Bearer $SIZLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Menu launch","title":"Taking you to the new menu","message":"Show this page at the counter for a free coffee.","seconds":5}'
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/splash/add", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Menu launch",
    "title": "Taking you to the new menu",
    "message": "Show this page at the counter for a free coffee.",
    "seconds": 5
  }),
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://siz.la/api/splash/add",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    json={
        "name": "Menu launch",
        "title": "Taking you to the new menu",
        "message": "Show this page at the counter for a free coffee.",
        "seconds": 5,
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/splash/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([
        'name' => 'Menu launch',
        'title' => 'Taking you to the new menu',
        'message' => 'Show this page at the counter for a free coffee.',
        'seconds' => 5,
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status 200**

```json
{
    "error": 0,
    "id": 7,
    "name": "Menu launch"
}
```

**Errors specific to this call**

- `400`: The name or title is missing, a value is not allowed, or the account has the most splash pages its plan allows.

## Update a splash page

`PUT /api/splash/{id}/update`

Change a splash page. Only the fields you send change, and every link that uses it shows the new page.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The splash page's id. At least 1. |
| `name` | Body | string | The splash page's name, for you. Visitors do not see it. Up to 80 characters. |
| `title` | Body | string | The heading visitors see. Up to 120 characters. |
| `message` | Body | string | A few lines under the title. Send an empty string to remove it. Up to 500 characters. |
| `button_label` | Body | string | The words on the button, which skips the wait. The default is `Continue`. Up to 40 characters. |
| `seconds` | Body | integer | How long the page waits before it moves on by itself. 2 to 15. Default `5`. |
| `background_color` | Body | string | Page color as six-digit hex, such as `#ffffff`. |
| `text_color` | Body | string | Text color as six-digit hex. |
| `button_color` | Body | string | Button color as six-digit hex. |
| `show_branding` | Body | boolean | Whether the siz.la mark is shown. It can only be turned off on the plans that remove it. Needs Pro and the plans above it. |

**Example request**

**cURL**

```bash
curl -X PUT "https://siz.la/api/splash/7/update" \
  -H "Authorization: Bearer $SIZLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seconds":8}'
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/splash/7/update", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "seconds": 8
  }),
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.put(
    "https://siz.la/api/splash/7/update",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    json={
        "seconds": 8,
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/splash/7/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([
        'seconds' => 8,
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status 200**

```json
{
    "error": 0,
    "id": 7,
    "name": "Menu launch"
}
```

**Errors specific to this call**

- `400`: A value is not allowed. `message` says which.
- `404`: The splash page does not exist or belongs to someone else.

## Delete a splash page

`DELETE /api/splash/{id}/delete`

Delete a splash page. Links that used it keep working and open without it.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The splash page's id. At least 1. |

**Example request**

**cURL**

```bash
curl -X DELETE "https://siz.la/api/splash/7/delete" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/splash/7/delete", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.delete(
    "https://siz.la/api/splash/7/delete",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/splash/7/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": "Splash page has been deleted successfully"
}
```

**Errors specific to this call**

- `404`: The splash page does not exist or belongs to someone else.


# Account API

The account endpoints tell you which account a key belongs to and let you change its email address or password.


## Get the account

`GET /api/account`

The account the key belongs to. A good first call to check that a key works.

**Needs:** API key.

**Example request**

**cURL**

```bash
curl "https://siz.la/api/account" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/account", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/account",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/account');
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": {
        "id": 7,
        "email": "you@example.com",
        "username": "you",
        "avatar": "https://www.gravatar.com/avatar/00000000000000000000000000000000?d=mp",
        "status": "pro",
        "expires": "",
        "registered": "2026-10-02 14:05:11"
    }
}
```

**Notes**

- `status` is `free` on the free plan and `pro` on every paid plan.

## Update the account

`PUT /api/account/update`

Change the email address or the password. Changing either one also needs the current password, so a key alone cannot take an account over.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `email` | Body | string | The new email address. A confirmation message is sent to it. |
| `password` | Body | string | The new password, at least 8 characters. |
| `current_password` | Body | string | The current password. Required when you change the email or the password. |

**Example request**

**cURL**

```bash
curl -X PUT "https://siz.la/api/account/update" \
  -H "Authorization: Bearer $SIZLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"new@example.com","current_password":"your-current-password"}'
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/account/update", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "email": "new@example.com",
    "current_password": "your-current-password"
  }),
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.put(
    "https://siz.la/api/account/update",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    json={
        "email": "new@example.com",
        "current_password": "your-current-password",
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/account/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([
        'email' => 'new@example.com',
        'current_password' => 'your-current-password',
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status 200**

```json
{
    "error": 0,
    "message": "Account has been successfully updated."
}
```

**Errors specific to this call**

- `400`: The email or password is not valid.
- `403`: The current password is missing or wrong.
- `429`: Five wrong passwords in ten minutes. Wait ten minutes.


# Click export API

Every click on a short link is recorded with where it came from and what it was opened on. This endpoint streams those rows to you. It is part of the paid plans, and only clicks your plan still keeps are included. See the plan table on the (https://siz.la/docs/errors) page for how long that is.

The export is streamed, so a large account does not have to fit in memory on either side. Read it line by line.


## Export clicks

`GET /api/clicks`

Stream the raw clicks on one link or on the whole account, as JSON lines or CSV. Only clicks your plan still keeps are included.

**Needs:** API key. Needs Pro and the plans above it.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `format` | Query | string | JSON lines (one object a line) or CSV. One of `jsonl`, `csv`. Default `jsonl`. |
| `link` | Query | integer | Only the clicks on this link id. Leave it out for the whole account. |
| `from` | Query | string | The first day to include, as `YYYY-MM-DD`. |
| `to` | Query | string | The last day to include, as `YYYY-MM-DD`. |

**Example request**

**cURL**

```bash
curl "https://siz.la/api/clicks?format=jsonl&link=1042&from=2026-11-01" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/clicks?format=jsonl&link=1042&from=2026-11-01", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.text();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/clicks",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    params={
        "format": "jsonl",
        "link": 1042,
        "from": "2026-11-01",
    },
)
print(response.text)
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/clicks?format=jsonl&link=1042&from=2026-11-01');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
    ],
]);
$data = curl_exec($ch);
```

**Example answer, status 200**

```json
{"id":90211,"clicked_at":"2026-11-14T09:41:07+00:00","link_id":1042,"code":"lunch-menu","country":"US","city":"Austin","language":"en","referrer_host":"t.co","referrer":"https://t.co/","ai_assistant":null,"browser":"Chrome","os":"iOS","device":"mobile","is_unique":true,"is_bot":false,"is_qr":false,"utm_source":null,"utm_medium":null,"utm_campaign":null,"click_id":"3f9a6c1e5b7d40a28c91e0d4","visitor_hash":"a1b2c3d4"}
```

**Errors specific to this call**

- `400`: The format is not `csv` or `jsonl`.
- `404`: The `link` is not one of yours.

**Notes**

- Every row has the same fields. `is_bot` clicks are included so you can filter them yourself; the totals in the app leave them out.



## Columns

Every row carries these fields, in this order:


- `id`
- `clicked_at`
- `link_id`
- `code`
- `country`
- `city`
- `language`
- `referrer_host`
- `referrer`
- `ai_assistant`
- `browser`
- `os`
- `device`
- `is_unique`
- `is_bot`
- `is_qr`
- `utm_source`
- `utm_medium`
- `utm_campaign`
- `click_id`
- `visitor_hash`



`clicked_at` is in UTC. `is_unique` is true for a visitor's first click on a link. `is_qr` is true when the click came from scanning the link's QR code. `click_id` is the value to send back when you record a conversion.


# Conversions

A conversion is something that happens after a click: a sign-up, a sale, a download. When you turn conversions on for a link, siz.la adds a click id to the address visitors are sent to, as a `sz_cid` query value. When the visitor does something worth counting, you send the click id back and the sale is counted against the click, with its value. Conversion tracking is part of the paid plans.

## How it fits together

1. Turn on conversions for the link when you make or edit it in the members area.
2. A visitor clicks the short link and lands on your page at an address ending in `?sz_cid=3f9a6c1e5b7d40a28c91e0d4`.
3. Your page, or the `sz.js` snippet, keeps that click id for the rest of the visit.
4. When they sign up or buy, you send the click id with a name, and optionally a value, either from your server or from the browser.

A click can be counted for 90 days after it happened. A `reference`, such as an order number, stops the same sale being counted twice.

## From your server

This is the call to use for anything you pay out on. It needs your API key.


## Record a conversion

`POST /api/conversions`

Tell siz.la that a click led to a sign-up or a sale. Call it from your server with your API key.

**Needs:** API key. Needs Pro and the plans above it.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `click_id` (required) | Body | string | The click id, 24 characters, from the `sz_cid` value on the address the visitor landed on. |
| `name` (required) | Body | string | What happened, such as `signup` or `purchase`. Up to 60 characters. |
| `value` | Body | number | What it was worth, such as `49.00`. At least 0. |
| `currency` | Body | string | A three-letter currency code. Used when a value is sent; the default is `USD`. |
| `reference` | Body | string | Your own id for this event, such as an order number. Sending the same reference again for the same link does not count it twice. Up to 100 characters. |

**Example request**

**cURL**

```bash
curl -X POST "https://siz.la/api/conversions" \
  -H "Authorization: Bearer $SIZLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"click_id":"3f9a6c1e5b7d40a28c91e0d4","name":"purchase","value":49,"currency":"USD","reference":"order-1042"}'
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/conversions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "click_id": "3f9a6c1e5b7d40a28c91e0d4",
    "name": "purchase",
    "value": 49,
    "currency": "USD",
    "reference": "order-1042"
  }),
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://siz.la/api/conversions",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    json={
        "click_id": "3f9a6c1e5b7d40a28c91e0d4",
        "name": "purchase",
        "value": 49.0,
        "currency": "USD",
        "reference": "order-1042",
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/conversions');
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([
        'click_id' => '3f9a6c1e5b7d40a28c91e0d4',
        'name' => 'purchase',
        'value' => 49.0,
        'currency' => 'USD',
        'reference' => 'order-1042',
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status 201**

```json
{
    "error": 0,
    "id": 318,
    "duplicate": false
}
```

**Errors specific to this call**

- `403`: The plan does not include conversion tracking.
- `404`: No click of yours matches that id.
- `422`: A field is not valid, or the click is older than the counting window.

**Notes**

- A repeated `reference` answers 200 with `"duplicate": true` and the id of the first one.

## Record a conversion from the browser

`POST /api/conversions/beacon`

The call the browser snippet makes. There is no API key: the click id is the proof. It always answers 204 with no body, even when it refuses the report.

**Needs:** No key. Needs Pro and the plans above it.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `click_id` (required) | Body | string | The click id. |
| `name` (required) | Body | string | What happened. |
| `value` | Body | number | What it was worth. |
| `currency` | Body | string | A three-letter currency code. |
| `reference` | Body | string | Your own id for this event. |

**Example request**

**cURL**

```bash
curl -X POST "https://siz.la/api/conversions/beacon" \
  -H "Content-Type: application/json" \
  -d '{"click_id":"3f9a6c1e5b7d40a28c91e0d4","name":"signup"}'
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/conversions/beacon", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "click_id": "3f9a6c1e5b7d40a28c91e0d4",
    "name": "signup"
  }),
});
const data = response.status;
console.log(data);
```

**Python**

```python
import requests

response = requests.post(
    "https://siz.la/api/conversions/beacon",
    json={
        "click_id": "3f9a6c1e5b7d40a28c91e0d4",
        "name": "signup",
    },
)
print(response.status_code)
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/conversions/beacon');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'click_id' => '3f9a6c1e5b7d40a28c91e0d4',
        'name' => 'signup',
    ]),
]);
curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
```

**Example answer, status 204**

No body.

**Notes**

- Most people use the `sz.js` snippet instead of calling this directly. See the conversions page.
- Anyone who has a click id can report a conversion for it. Use the server call for anything you pay out on.

## List conversions

`GET /api/conversions`

Totals, the conversion rate and the newest conversions for one link or the whole account.

**Needs:** API key. Needs Pro and the plans above it.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `link` | Query | integer | Only this link id. Leave it out for the whole account. |
| `days` | Query | integer | How many days back to report. 1 to 365. Default `30`. |

**Example request**

**cURL**

```bash
curl "https://siz.la/api/conversions?link=1042&days=30" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/conversions?link=1042&days=30", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/conversions",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    params={
        "link": 1042,
        "days": 30,
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/conversions?link=1042&days=30');
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,
    "days": 30,
    "conversions": 4,
    "clicks": 37,
    "conversion_rate": 10.800000000000000710542735760100185871124267578125,
    "value": {
        "USD": 196
    },
    "by_name": {
        "purchase": 3,
        "signup": 1
    },
    "recent": [
        {
            "id": 318,
            "link_id": 1042,
            "click_id": "3f9a6c1e5b7d40a28c91e0d4",
            "name": "purchase",
            "value": 49,
            "currency": "USD",
            "reference": "order-1042",
            "source": "server",
            "converted_at": "2026-11-14T10:02:44+00:00"
        }
    ]
}
```

**Errors specific to this call**

- `403`: The plan does not include conversion tracking.
- `404`: The `link` is not one of yours.

**Notes**

- `recent` holds the newest 100. `value` has one total for each currency.



## From the browser with sz.js

Add the snippet to the page people land on. It reads `sz_cid` from the address, keeps it in the browser for 90 days, and sends a conversion when you call `sizla.convert`.

```html
<script async src="https://siz.la/sz.js"></script>
```

Then, when the thing happens:

```javascript
sizla.convert("signup", { value: 19, currency: "USD", reference: "user-8841" });
```

- The first argument is the name of the conversion. The options are optional.
- `sizla.convert` returns `true` when the report was handed to the browser to send, and `false` when there is no click id to report against.
- `sizla.clickId()` returns the saved click id, or `null`.
- The snippet sends one small request to the beacon call above. It never shows an error to your visitors.
- Anyone who has a click id can report a conversion for it, and the beacon call is limited to 60 requests a minute for each address. Use the server call for anything you pay out on.

## Reading the results

The members area shows conversions next to clicks on each link's statistics page. The list call returns the same totals as JSON, and every new conversion can be sent to you as a `conversion.created` message. See (https://siz.la/docs/webhooks).


# Webhooks

Webhooks send a signed message to an address you choose when something happens to your links, so your own tools can react without polling. They are part of the paid plans.

## Add an endpoint

Open [Webhooks](https://siz.la/user/webhooks) in the members area, add an address that starts with `https://`, and choose the events you want. The address must be reachable on the public internet. You can have up to 5 endpoints. Each has its own signing secret, shown when you add it and again when you make a new one.

Use Send test on an endpoint to get a `webhook.test` message straight away.

## Events


| Event | Sent when |
| --- | --- |
| `link.created` | A link is created. |
| `link.updated` | A link is changed. |
| `link.clicked` | Clicks, sent together once a minute. |
| `conversion.created` | A conversion is recorded. |
| `bio.signup` | Someone signs up for email on a bio page. |
| `qr.scanned` | A QR code is scanned, sent together once a minute. |



## What a message looks like

Every message is a `POST` with a JSON body. These headers come with it:

- `X-Sizla-Event`: the event name.
- `X-Sizla-Delivery`: a unique id for this delivery. The same id is used when a message is sent again, so you can ignore repeats.
- `X-Sizla-Signature`: the timestamp and signature, for example `t=1700000000,v1=3f2a...`.

The body always has an `id`, the `event`, a `created_at` time and the `data`:


**link.created**

```json
{
    "id": "6f1d2c1e-8a47-4c35-9d0b-2a1c0f5e7b90",
    "event": "link.created",
    "created_at": "2026-11-14T10:02:44+00:00",
    "data": {
        "link": {
            "id": 1042,
            "code": "lunch-menu",
            "short_url": "https://siz.la/lunch-menu",
            "destination": "https://example.com/a/long/address",
            "title": null,
            "type": "direct",
            "created_at": "2026-11-14T09:30:00+00:00",
            "updated_at": "2026-11-14T09:30:00+00:00"
        }
    }
}
```

**link.updated**

```json
{
    "id": "6f1d2c1e-8a47-4c35-9d0b-2a1c0f5e7b90",
    "event": "link.updated",
    "created_at": "2026-11-14T10:02:44+00:00",
    "data": {
        "link": {
            "id": 1042,
            "code": "lunch-menu",
            "short_url": "https://siz.la/lunch-menu",
            "destination": "https://example.com/a/long/address",
            "title": null,
            "type": "direct",
            "created_at": "2026-11-14T09:30:00+00:00",
            "updated_at": "2026-11-14T09:30:00+00:00"
        }
    }
}
```

**link.clicked**

```json
{
    "id": "6f1d2c1e-8a47-4c35-9d0b-2a1c0f5e7b90",
    "event": "link.clicked",
    "created_at": "2026-11-14T10:02:44+00:00",
    "data": {
        "count": 1,
        "from": "2026-11-14 09:41:07",
        "to": "2026-11-14 09:41:07",
        "clicks": [
            {
                "id": 90211,
                "link_id": 1042,
                "code": "lunch-menu",
                "short_url": "https://siz.la/lunch-menu",
                "clicked_at": "2026-11-14T09:41:07+00:00",
                "country": "US",
                "city": "Austin",
                "referrer_host": "t.co",
                "ai_assistant": null,
                "browser": "Chrome",
                "os": "iOS",
                "device": "mobile",
                "is_new_visitor": true,
                "is_qr": false,
                "click_id": "3f9a6c1e5b7d40a28c91e0d4"
            }
        ]
    }
}
```

**conversion.created**

```json
{
    "id": "6f1d2c1e-8a47-4c35-9d0b-2a1c0f5e7b90",
    "event": "conversion.created",
    "created_at": "2026-11-14T10:02:44+00:00",
    "data": {
        "conversion": {
            "id": 318,
            "link_id": 1042,
            "click_id": "3f9a6c1e5b7d40a28c91e0d4",
            "name": "purchase",
            "value": 49,
            "currency": "USD",
            "reference": "order-1042",
            "converted_at": "2026-11-14T10:02:44+00:00"
        }
    }
}
```

**bio.signup**

```json
{
    "id": "6f1d2c1e-8a47-4c35-9d0b-2a1c0f5e7b90",
    "event": "bio.signup",
    "created_at": "2026-11-14T10:02:44+00:00",
    "data": {
        "signup": {
            "id": 77,
            "email": "sam@example.com",
            "name": "Sam",
            "page_id": 9,
            "page_name": "Lunch menu",
            "page_url": "https://siz.la/lunch-menu",
            "block_id": "k3d9x2",
            "signed_up_at": "2026-11-14T09:52:10+00:00"
        }
    }
}
```

**qr.scanned**

```json
{
    "id": "6f1d2c1e-8a47-4c35-9d0b-2a1c0f5e7b90",
    "event": "qr.scanned",
    "created_at": "2026-11-14T10:02:44+00:00",
    "data": {
        "count": 1,
        "from": "2026-11-14 09:44:51",
        "to": "2026-11-14 09:44:51",
        "clicks": [
            {
                "id": 90212,
                "is_qr": true,
                "clicked_at": "2026-11-14T09:44:51+00:00",
                "device": "mobile",
                "os": "Android",
                "browser": "Chrome",
                "city": "Leeds",
                "country": "GB",
                "click_id": "8c21d4f0a97e4b1c5e6a0b33",
                "link_id": 1042,
                "code": "lunch-menu",
                "short_url": "https://siz.la/lunch-menu",
                "referrer_host": "t.co",
                "ai_assistant": null,
                "is_new_visitor": true
            }
        ]
    }
}
```



Clicks are batched. All the clicks from the last minute for an endpoint go in one `link.clicked` message, up to 500 in a message. The scans of QR codes among them also go in one `qr.scanned` message, for an endpoint that asked for it. Clicks from bots are left out, and clicks older than an hour are not sent if an endpoint was off.

Zapier, Make, n8n, Slack and Mailchimp use these same messages. See [integrations](https://siz.la/docs/integrations) for how to connect them.

## Check the signature

Anyone who learns your endpoint address can send it fake messages, so check every one. The signature is an HMAC with SHA-256:

1. Read the `t` and `v1` values from the `X-Sizla-Signature` header.
2. Join `t`, a dot and the raw request body, exactly as it arrived. Do not parse and re-encode the JSON first.
3. Sign that text with your endpoint's secret using HMAC-SHA256 and write the result as lowercase hex.
4. Compare it with `v1` using a constant-time comparison.
5. Reject the message if `t` is more than five minutes old.


**JavaScript**

```javascript
import crypto from "node:crypto";

// rawBody is the request body exactly as it arrived, before any JSON parsing.
export function isValid(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const given = Buffer.from(parts.v1 ?? "");
  const wanted = Buffer.from(expected);
  return given.length === wanted.length && crypto.timingSafeEqual(given, wanted);
}
```

**Python**

```python
import hashlib
import hmac
import time


def is_valid(raw_body: bytes, signature_header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False

    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))
```

**PHP**

```php
function isValid(string $rawBody, string $signatureHeader, string $secret): bool
{
    parse_str(str_replace(',', '&', $signatureHeader), $parts);
    if (abs(time() - (int) ($parts['t'] ?? 0)) > 300) {
        return false;
    }

    $expected = hash_hmac('sha256', $parts['t'].'.'.$rawBody, $secret);

    return hash_equals($expected, $parts['v1'] ?? '');
}
```



## Answering and retries

Answer with any `2xx` status within 10 seconds. Redirects are not followed. Anything else counts as a failure, and the message is tried again after 30 seconds, 2 minutes, 10 minutes and 1 hour. An endpoint that fails 25 times in a row is paused, and you can turn it back on in the members area. The delivery log keeps 30 days, and from there you can send a message again.


# Integrations

siz.la connects to Zapier, Make, n8n, Mailchimp and Slack. The automation tools start from events on your account and can make or change links in return. Mailchimp and Slack are set up in the members area, with no code. Open [Integrations](https://siz.la/user/integrations) there to see what is connected.

Triggers, Slack messages and webhooks are part of the paid plans. Making and changing links from an automation tool works on every plan that can write through the API, and sending sign-ups to Mailchimp works on every plan.

## Events a tool can start from

These are the same events the [webhooks](https://siz.la/docs/webhooks) page describes, so Zapier, Make, n8n and your own code all see the same data.

| Event | Trigger name | Runs when |
| --- | --- | --- |
| `link.clicked` | New click | Someone clicks one of your links. Bots are left out. |
| `link.created` | New link | A link is made, from the members area, the API or a bulk upload. |
| `bio.signup` | New email sign-up | Someone joins your email list on a bio page. |
| `qr.scanned` | New QR code scan | Someone scans a QR code that points at one of your links. |

`link.updated` and `conversion.created` are available too, for tools that use webhooks directly.

Clicks and scans are sent together once a minute, so a trigger can run up to a minute after the click.

## Zapier

Connect Zapier with your [API key](https://siz.la/docs/authentication). In a Zap, choose siz.la, paste the key when Zapier asks you to sign in, and pick a trigger or an action.

**Triggers:** New click, New link, New email sign-up and New QR code scan. Each one hands the Zap one item for every click, link or sign-up, with an `id`, so a Zap never runs twice for the same thing.

**Actions:** Create a link, Update a link and Find a link. They call the [links API](https://siz.la/docs/links), so every option there is available, such as a custom ending, a campaign or an expiry date, as far as your plan allows.

When a Zap that starts from a trigger is turned on, Zapier subscribes to the event with the calls described under Hook subscriptions below, and it removes the subscription when the Zap is turned off. Each subscription shows in the members area, where you can pause or remove it.

## Make

Make connects through its custom webhook module for events and its HTTP module for links.

1. In Make, add a Custom webhook module and copy the address it shows.
2. Subscribe that address to an event with one request. Replace `YOUR_API_KEY` and the address.

```bash
curl -X POST https://siz.la/api/hooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "bio.signup", "target_url": "https://hook.eu1.make.com/your-address", "source": "make"}'
```

3. Run the scenario once, then trigger the event. Make learns the fields from the first message it gets. The sample data call under Hook subscriptions shows the shape of every event before one happens.
4. To make or change links, use the HTTP module with the [links API](https://siz.la/docs/links) and your API key.

To stop, send `DELETE https://siz.la/api/hooks/ID` with the id from the subscribe answer, or remove the subscription under Integrations in the members area.

## n8n

n8n works the same way as Make, on n8n Cloud and on a server you run yourself.

1. Add a Webhook node set to `POST` and copy its production address. The address must start with `https://` and be reachable from the public internet, so a workflow that listens on a private machine needs a public address first.
2. Subscribe it with the call above, using `"source": "n8n"`.
3. Add an HTTP Request node when you want to make or change links, with the header `Authorization: Bearer YOUR_API_KEY`.

## Check who sent a message

Every message is signed. A tool that wants to check the signature uses the `secret` from the subscribe answer, which is shown once, and follows the steps on the [webhooks](https://siz.la/docs/webhooks) page. Zapier does not need it.

If the address answers `410 Gone`, siz.la removes the subscription at once. Any other failure is retried and logged like a webhook, and a subscription that fails 25 times in a row is paused.

## Hook subscriptions

These calls are what Zapier makes for you, and what you call yourself for Make, n8n or your own tool. They use the same API key as the rest of the API. An account can hold up to 50 subscriptions.


## List the events

`GET /api/hooks/events`

Every event a subscription can ask for, and the trigger name the Zapier app gives it.

**Needs:** API key.

**Example request**

**cURL**

```bash
curl "https://siz.la/api/hooks/events" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/hooks/events", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/hooks/events",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/hooks/events');
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,
    "events": [
        {
            "event": "bio.signup",
            "description": "Someone signs up for email on a bio page",
            "trigger": "New email sign-up"
        }
    ]
}
```

**Notes**

- The real answer lists every event. The `trigger` is `null` for an event the Zapier app has no trigger for.

## List subscriptions

`GET /api/hooks`

The subscriptions other tools made with your key. Addresses you added yourself on the Webhooks page are not listed here.

**Needs:** API key.

**Example request**

**cURL**

```bash
curl "https://siz.la/api/hooks" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/hooks", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/hooks",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/hooks');
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,
    "hooks": [
        {
            "id": 14,
            "event": "bio.signup",
            "target_url": "https://hooks.zapier.com/hooks/standard/1/abc",
            "source": "zapier",
            "is_active": true,
            "created_at": "2026-11-14T09:30:00+00:00"
        }
    ]
}
```

## Subscribe to an event

`POST /api/hooks`

Ask for a message at `target_url` each time the event happens. The message is the same signed webhook message described on the webhooks page.

**Needs:** API key with write access. Needs Pro and the plans above it.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `event` (required) | Body | string | The event to subscribe to. One of `link.created`, `link.updated`, `link.clicked`, `conversion.created`, `bio.signup`, `qr.scanned`. |
| `target_url` (required) | Body | string | The address that receives the messages. It must start with `https://` and be on the public internet. Up to 500 characters. |
| `source` | Body | string | Which tool is subscribing. Anything else is saved as `api`. One of `zapier`, `make`, `n8n`, `api`. |
| `label` | Body | string | A name to show next to the subscription in the members area. Up to 120 characters. |

**Example request**

**cURL**

```bash
curl -X POST "https://siz.la/api/hooks" \
  -H "Authorization: Bearer $SIZLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event":"bio.signup","target_url":"https://hooks.zapier.com/hooks/standard/1/abc","source":"zapier"}'
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/hooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "event": "bio.signup",
    "target_url": "https://hooks.zapier.com/hooks/standard/1/abc",
    "source": "zapier"
  }),
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://siz.la/api/hooks",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
    json={
        "event": "bio.signup",
        "target_url": "https://hooks.zapier.com/hooks/standard/1/abc",
        "source": "zapier",
    },
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/hooks');
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([
        'event' => 'bio.signup',
        'target_url' => 'https://hooks.zapier.com/hooks/standard/1/abc',
        'source' => 'zapier',
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

**Example answer, status 201**

```json
{
    "error": 0,
    "id": 14,
    "event": "bio.signup",
    "target_url": "https://hooks.zapier.com/hooks/standard/1/abc",
    "source": "zapier",
    "is_active": true,
    "created_at": "2026-11-14T09:30:00+00:00",
    "secret": "whsec_0f1e2d3c4b5a69788796a5b4c3d2e1f001122334"
}
```

**Errors specific to this call**

- `403`: The plan does not include webhooks.
- `422`: The event or address is not valid, or the account holds the most subscriptions it can.

**Notes**

- `secret` is shown once, in this answer. Use it to check the signature on each message, or ignore it if the tool does not check.
- Subscribing the same address to the same event again answers `200` with the subscription that exists and a `secret` of `null`.
- Clicks and scans from now on are sent. Nothing from before the subscription is sent.
- When the address answers `410` to a message, the subscription is removed.

## Remove a subscription

`DELETE /api/hooks/{id}`

Stop the messages for one subscription.

**Needs:** API key with write access.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | Path | integer | The subscription id from the subscribe answer. |

**Example request**

**cURL**

```bash
curl -X DELETE "https://siz.la/api/hooks/14" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/hooks/14", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.delete(
    "https://siz.la/api/hooks/14",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/hooks/14');
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": "Hook subscription has been deleted successfully"
}
```

**Errors specific to this call**

- `404`: The subscription does not exist, or it is not yours.

## Sample data for an event

`GET /api/hooks/sample/{event}`

A worked example of what an event sends, for a tool that shows sample data while a person sets up a step.

**Needs:** API key.

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `event` (required) | Path | string | The event name. One of `link.created`, `link.updated`, `link.clicked`, `conversion.created`, `bio.signup`, `qr.scanned`. |

**Example request**

**cURL**

```bash
curl "https://siz.la/api/hooks/sample/bio.signup" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://siz.la/api/hooks/sample/bio.signup", {
  headers: {
    Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://siz.la/api/hooks/sample/bio.signup",
    headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
)
print(response.json())
```

**PHP**

```php
$ch = curl_init('https://siz.la/api/hooks/sample/bio.signup');
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,
    "event": "bio.signup",
    "items": [
        {
            "id": 77,
            "email": "sam@example.com",
            "name": "Sam",
            "page_id": 9,
            "page_name": "Lunch menu",
            "page_url": "https://siz.la/lunch-menu",
            "block_id": "k3d9x2",
            "signed_up_at": "2026-11-14T09:52:10+00:00"
        }
    ],
    "message": {
        "id": "6f1d2c1e-8a47-4c35-9d0b-2a1c0f5e7b90",
        "event": "bio.signup",
        "created_at": "2026-11-14T10:02:44+00:00",
        "data": {
            "signup": {
                "id": 77,
                "email": "sam@example.com"
            }
        }
    }
}
```

**Errors specific to this call**

- `404`: The event does not exist.

**Notes**

- `items` is what a trigger hands on, one entry for each thing that happened. Each has an `id`. `message` is the whole message as it is sent.



## Mailchimp

Open [Integrations](https://siz.la/user/integrations) in the members area and choose Connect Mailchimp.

1. In Mailchimp, open your profile, then Extras, then API keys, and make a key.
2. Paste the key into siz.la. It is checked with Mailchimp straight away.
3. Choose the audience that gets your sign-ups. If the account has only one, it is chosen for you.
4. Pick every bio page, or only some, and choose whether new subscribers confirm by email first.

From then on each new email sign-up on those pages is added to the audience. Someone who unsubscribed in Mailchimp stays unsubscribed. A name entered on the form goes into the first name field.

The key is stored encrypted and is never shown again. Choose Disconnect to delete it.

Sign-ups are sent in the background, and a busy Mailchimp is tried again several times. A sign-up that still fails, for example one Mailchimp keeps on a do-not-contact list, is listed on the Integrations page with the reason Mailchimp gave. Fix the cause, then choose Try failed ones again. Send existing sign-ups adds the ones you collected before you connected.

## Slack

1. In Slack, make an incoming webhook for the channel you want. Slack gives you an address that starts with `https://hooks.slack.com/services/`.
2. In siz.la, open [Integrations](https://siz.la/user/integrations), paste the address under Slack and tick the events you want. You can connect up to 3 channels.
3. A test message is sent when you add the channel, and Send test sends another.

Slack messages are short sentences, for example a new link, the number of clicks in the last minute by link, or a new sign-up. Treat the address like a password. It is not shown again after you add it, and if Slack stops accepting it the channel is paused and the page says so.


# Errors and rate limits

## The error format

Every answer is JSON and carries `error`. It is `0` when the call worked. When it did not, `error` is `1` and `message` says what went wrong in plain words:

```json
{
  "error": 1,
  "message": "Link does not exist."
}
```

Show or log `message`. Do not match on its exact wording, because it can be improved. Match on the HTTP status.

## Statuses


| Status | Meaning | What to do |
| --- | --- | --- |
| `200`, `201`, `204` | It worked. | Read the body, except on 204. |
| `400` | A value is not allowed. `message` says which one. | Fix the request. Do not repeat it unchanged. |
| `401` | The key is missing, wrong or belongs to a closed account. | Send `Authorization: Bearer YOUR_KEY`. |
| `403` | The plan does not include this, or a required password is wrong. | Check the plan table, or the message. |
| `404` | The link or click does not exist, or belongs to someone else. Both look the same on purpose. | Check the id. |
| `422` | A conversion field is not valid, or the click is too old to count. | Fix the field named in `message`. |
| `429` | More requests in a minute than the plan allows. | Wait for the seconds in the `Retry-After` header. |
| `501` | The path exists but that part of the API is not ready. | See the not available page. |



## Rate limits

Each account can make a number of API requests a minute, set by its plan. All keys and requests of an account count together. The count is a rolling minute.


| Plan | Requests a minute | API access | Links a month | Raw clicks kept |
| --- | --- | --- | --- | --- |
| Free | 60 | Read and change | 500 | 365 days |
| Pro | 120 | Read and change | 5,000 | 1,095 days |
| Team | 300 | Read and change | 25,000 | 3,650 days |
| Business | 600 | Read and change | 100,000 | No limit |
| Organization | 1,200 | Read and change | Agreed per customer | No limit |



Every answer tells you where you stand:

- `X-RateLimit-Limit`: the requests a minute the plan allows.
- `X-RateLimit-Remaining`: how many are left in the current minute.
- `Retry-After`: on a `429` answer only, the seconds to wait before trying again.

When you get a `429`, wait for `Retry-After` and then continue. Do not retry in a tight loop. If you need more than your plan allows, upgrade or [contact us](https://siz.la/contact).

The browser conversion call has its own limit of 60 requests a minute for each address. The AI assistant connector is limited per account by the same plan number, in a count of its own, so an assistant does not use up your API requests. See (https://siz.la/docs/connector).

## Plan features at a glance

Options that need a feature your plan does not include are refused with a `400` or `403` and a message that says so.


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


# Not available yet

Some paths exist in the API but belong to parts of siz.la that are not ready for the API yet. They answer with status `501` and the usual error shape, so a client can tell them from a typo (which is a `404`):

```json
{
  "error": 1,
  "message": "This part of the API is not available yet."
}
```

These parts are listed in the [OpenAPI file](https://siz.la/openapi.json) under the tag Not available yet. When one of them opens, it moves to its own page in these docs.


Nothing is on this list right now.
# AI assistant connector (MCP)

The siz.la connector lets an AI assistant work with your links. Connect it once and you can ask in plain words: shorten a link, list your links, see how one is doing, archive or delete one, or get a QR code. The assistant acts as you, inside your plan's limits, and never sees your password or your API key.

It is a remote MCP server, which is the open standard assistants use to talk to other services. There is nothing to install.

```text
https://siz.la/mcp
```

The server uses the Streamable HTTP transport and signs people in with OAuth.

## What you can ask

- "Shorten https://example.com/a/long/address and call it lunch-menu."
- "How did lunch-menu do over the last 30 days, and where did the clicks come from?"
- "Show my five newest links and archive the ones I have not shared."
- "Make a QR code for lunch-menu."
- "Show my newsletter message over lunch-menu." (Use the message's id from your Call to action page.)
- "Fire my Meta pixel on lunch-menu and put it in the menu launch campaign."
- "Is siz.la/open-mic still working, and where does it lead?"

## Connect your assistant

Pick your assistant. Menu names change from time to time in the assistants themselves; if yours differ, look for the place that adds a custom or remote MCP server.


### Claude

Claude on the web, desktop and phone.

1. Open Customize, then Connectors.
1. Choose Add, then Add custom connector.
1. Enter the name siz.la and the address https://siz.la/mcp.
1. Choose Continue, then Add and Connect.
1. Sign in to siz.la if asked, read what the assistant can do and choose Allow.

On Team and Enterprise plans an owner adds the connector once, under Organization settings, then Connectors. Menu names change from time to time; look for the place that adds a custom connector.

### Claude Code

The terminal.

1. Run the command below.
1. Inside Claude Code run /mcp, pick siz-la and choose to sign in. Your browser opens the siz.la sign-in and consent screen.

```bash
claude mcp add --transport http siz-la https://siz.la/mcp
```

### ChatGPT

ChatGPT on the web.

1. Open the place in ChatGPT where you add your own connectors and choose to add a custom MCP server.
1. Enter the name siz.la and the address https://siz.la/mcp.
1. Choose OAuth for authentication and accept the warning that this is a connection you added yourself.
1. Create it, then sign in to siz.la and choose Allow.

Which plans can add their own connectors, and what the menu is called, is decided by OpenAI and by your workspace admin. Ask the admin if the option is missing.

### Cursor

The Cursor editor.

1. Add the server to .cursor/mcp.json in a project, or to ~/.cursor/mcp.json for every project.
1. Cursor shows siz-la under its MCP list with a sign-in button. Sign in to siz.la and choose Allow.

```json
{
  "mcpServers": {
    "siz-la": {
      "url": "https://siz.la/mcp"
    }
  }
}
```

[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=siz-la&config=eyJ1cmwiOiJodHRwczovL3Npei5sYS9tY3AifQ==)

### VS Code

Visual Studio Code with GitHub Copilot chat.

1. Run MCP: Add Server from the Command Palette and choose HTTP, or add the server to .vscode/mcp.json yourself.
1. Start the server from the editor. VS Code opens the siz.la sign-in and consent screen. Choose Allow.

```json
{
  "servers": {
    "siz-la": {
      "type": "http",
      "url": "https://siz.la/mcp"
    }
  }
}
```

### Windsurf

The Windsurf editor.

1. Open the Cascade MCP menu and choose to open the MCP config file, or use Add Server in Windsurf Settings.
1. Add the entry below and refresh the server list. Sign in to siz.la and choose Allow.

```json
{
  "mcpServers": {
    "siz-la": {
      "serverUrl": "https://siz.la/mcp"
    }
  }
}
```

### Gemini CLI

The terminal.

1. Run the command below.
1. Inside Gemini CLI run /mcp auth siz-la. Sign in to siz.la and choose Allow.

```bash
gemini mcp add --transport http siz-la https://siz.la/mcp
```

### Other MCP clients

Any client that supports remote MCP servers.

1. Choose to add a remote MCP server, with the Streamable HTTP transport, and enter https://siz.la/mcp.
1. The client finds the sign-in on its own: it asks siz.la, gets a 401 answer that points at the sign-in details, registers itself and opens the consent screen.
1. If a client can only start local programs, run it through a bridge such as mcp-remote and keep the same address.

```json
{
  "mcpServers": {
    "siz-la": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://siz.la/mcp"]
    }
  }
}
```



## Signing in

The connector uses OAuth 2.1 with PKCE, and assistants register themselves, so you never copy a key.

1. The assistant calls the server without a token. The server answers `401` with a pointer to its sign-in details at `https://siz.la/.well-known/oauth-protected-resource`.
2. The assistant registers itself and sends you to siz.la.
3. You sign in if needed, and a consent screen shows what the assistant can do, with Allow and Deny.
4. The assistant gets a token. Every tool call then acts as you.

Access is renewed on its own while the assistant is in use. If it lapses, you are asked to allow it again. You can disconnect every assistant at once under Settings, then [Developers](https://siz.la/user/developers). A closed account, or one whose email address is not confirmed, cannot connect.

## Limits

The connector follows your plan exactly like the website and the API do. Links are made and changed through the same checks, so blocked addresses, reserved endings and your monthly link limit all apply, and options your plan does not include are refused with a message that says so.

Requests are limited per minute by plan, in a count of their own, apart from your API requests:


| Plan | Requests a minute | API access | Links a month | Raw clicks kept |
| --- | --- | --- | --- | --- |
| Free | 60 | Read and change | 500 | 365 days |
| Pro | 120 | Read and change | 5,000 | 1,095 days |
| Team | 300 | Read and change | 25,000 | 3,650 days |
| Business | 600 | Read and change | 100,000 | No limit |
| Organization | 1,200 | Read and change | Agreed per customer | No limit |



A link or click that belongs to someone else looks the same as one that does not exist.

## Tools

These are the tools the assistant can call. Each one is marked as read only or as one that changes something, and one cannot be undone. The assistant is told to confirm before using that one. The list is read from the server's own tool registry.


### Shorten a link `shorten_link`

*Changes data*

Make a short siz.la address for a long web address. Returns the short address and the link's id. Safety checks run on every destination, and the account's monthly link limit applies. Password, expiry and click limits work on every plan, the free one included. It can also put the link in a campaign and fire the account's ad pixels on each click.

| Input | Type | What it means |
| --- | --- | --- |
| `destination` (required) | string | The full web address to shorten. It must start with http:// or https://. Up to 4000 characters. |
| `code` | string | A custom code for the short address, for example lunch-menu. Letters, numbers, dashes and underscores. Leave it out to get a random one. Length 3 to 60. |
| `domain` | string | One of the account's connected custom domains, such as go.example.com, to make the link on. Leave it out to use siz.la. Up to 191 characters. |
| `campaign` | string | A campaign to put the link in, by name. A campaign that does not exist yet is made. Needs a paid plan. Up to 80 characters. Needs Pro and the plans above it. |
| `expires_at` | string | When the link stops working, as a date and time such as 2026-12-31 18:00. Up to 40 characters. |
| `password` | string | A password visitors must enter before they are sent on. Up to 191 characters. |
| `title` | string | A name for the link. Only the account owner sees it. Up to 191 characters. |
| `cta_id` | integer | The id of one of the account's call-to-action messages (made on siz.la under Call to action) to show over the page the link opens. At least 1. |
| `pixels` | array | Ids of the account's ad pixels to fire on each click, as listed by list_pixels. Up to 10. |

### List links `list_links`

*Read only*

List the account's links, newest first, with code, short address, destination, clicks and creation date. Search by part of the code, destination or title.

| Input | Type | What it means |
| --- | --- | --- |
| `q` | string | Text to look for in the code, destination or title. Up to 200 characters. |
| `page` | integer | Which page of results to return. At least 1. Default `1`. |
| `per_page` | integer | How many links to return on a page. 1 to 50. Default `15`. |
| `status` | string | Which links to list: active or archived. One of `active`, `archived`. Default `active`. |

### Get link stats `get_link_stats`

*Read only*

Show how a link is doing: total and unique clicks, new and returning visitors, clicks by day, busiest hours of the week, top countries, top referrers, visits from AI assistants such as ChatGPT or Claude, browsers, systems and devices. For a bio page it also gives views and clicks for each button, and on a paid plan the conversions. Visits from bots are reported apart and are not in the totals.

| Input | Type | What it means |
| --- | --- | --- |
| `id` | integer | The link's id, as returned by list_links or shorten_link. Give either id or code. At least 1. |
| `code` | string | The link's code (the part after siz.la/) or its full short address. Give either id or code. Up to 400 characters. |
| `days` | integer | How many days back to report: 7, 30 or 90. The plan may keep less history than that. One of `7`, `30`, `90`. Default `30`. |

### Get conversions `get_conversions`

*Read only*

Show the sign-ups and sales counted against a link's clicks: how many, what share of clicks they are, their value for each currency, and the newest ones. Leave out the link to cover the whole account. Needs a paid plan.

| Input | Type | What it means |
| --- | --- | --- |
| `id` | integer | The link's id, as returned by list_links or shorten_link. Give either id or code. At least 1. |
| `code` | string | The link's code (the part after siz.la/) or its full short address. Give either id or code. Up to 400 characters. |
| `days` | integer | How many days back to report: 7, 30 or 90. One of `7`, `30`, `90`. Default `30`. |

### Update a link `update_link`

*Changes data · Safe to repeat*

Change one of the account's links. Only the fields you send change. The short address stays the same. Expiry, password and click limit work on every plan. It can also change the campaign and the pixels. Leave pixels out to keep them as they are; send an empty list to remove them.

| Input | Type | What it means |
| --- | --- | --- |
| `id` | integer | The link's id, as returned by list_links or shorten_link. Give either id or code. At least 1. |
| `code` | string | The link's code (the part after siz.la/) or its full short address. Give either id or code. Up to 400 characters. |
| `destination` | string | The new full web address the link leads to. It must start with http:// or https://. Up to 4000 characters. |
| `title` | string | A new name for the link. Send an empty string to remove it. Up to 191 characters. |
| `expires_at` | string | When the link stops working, as a date and time such as 2026-12-31 18:00. Send an empty string to remove the expiry. Up to 40 characters. |
| `password` | string | A password visitors must enter before they are sent on. Send an empty string to remove it. Up to 191 characters. |
| `click_limit` | integer | The link stops working after this many clicks. Send 0 to remove the limit. At least 0. |
| `cta_id` | integer | The id of one of the account's call-to-action messages to show over the page the link opens. Send 0 to remove it. At least 0. |
| `campaign` | string | Move the link into a campaign, by name. A campaign that does not exist yet is made. Send an empty string to take the link out of its campaign. Up to 80 characters. Needs Pro and the plans above it. |
| `pixels` | array | Ids of the account's ad pixels to fire on each click, as listed by list_pixels. An empty list removes them. Up to 10. |

### Archive a link `archive_link`

*Changes data · Safe to repeat*

Move a link to the archive. It keeps working and keeps its stats; it is only hidden from the main list. Restore it with restore_link.

| Input | Type | What it means |
| --- | --- | --- |
| `id` | integer | The link's id, as returned by list_links or shorten_link. Give either id or code. At least 1. |
| `code` | string | The link's code (the part after siz.la/) or its full short address. Give either id or code. Up to 400 characters. |

### Restore a link `restore_link`

*Changes data · Safe to repeat*

Bring an archived link back to the main list.

| Input | Type | What it means |
| --- | --- | --- |
| `id` | integer | The link's id, as returned by list_links or shorten_link. Give either id or code. At least 1. |
| `code` | string | The link's code (the part after siz.la/) or its full short address. Give either id or code. Up to 400 characters. |

### Delete a link `delete_link`

*Changes data · Cannot be undone · Safe to repeat*

Delete a link and its stats for good. The short address stops working and cannot be used again. This cannot be undone, so confirm with the person first. To keep the stats, use archive_link instead.

| Input | Type | What it means |
| --- | --- | --- |
| `id` | integer | The link's id, as returned by list_links or shorten_link. Give either id or code. At least 1. |
| `code` | string | The link's code (the part after siz.la/) or its full short address. Give either id or code. Up to 400 characters. |

### Make a QR code `make_qr_code`

*Read only*

Get the address of a QR code image for one of the account's links. The image is an SVG. Scans count as clicks on the link.

| Input | Type | What it means |
| --- | --- | --- |
| `id` | integer | The link's id, as returned by list_links or shorten_link. Give either id or code. At least 1. |
| `code` | string | The link's code (the part after siz.la/) or its full short address. Give either id or code. Up to 400 characters. |

### List domains `list_domains`

*Read only*

List the domains the account can shorten links on: siz.la and any connected custom domains.

No inputs.

### List campaigns `list_campaigns`

*Read only*

List the account's campaigns with how many links each holds and their clicks over the last 30 days.

No inputs.

### Make a campaign `create_campaign`

*Changes data*

Make a campaign to group links, read their clicks together and give them shared UTM values. Put links in it with the campaign option of shorten_link or update_link.

| Input | Type | What it means |
| --- | --- | --- |
| `name` (required) | string | The campaign's name. It must be different from the account's other campaigns. Up to 80 characters. Needs Pro and the plans above it. |
| `utm_source` | string | Added to the address of every link in the campaign as utm_source. Up to 100 characters. |
| `utm_medium` | string | Added as utm_medium. Up to 100 characters. |
| `utm_campaign` | string | Added as utm_campaign. Up to 100 characters. |

### Update a campaign `update_campaign`

*Changes data · Safe to repeat*

Rename a campaign or change its UTM values. Only the fields you send change. New UTM values reach a link the next time it is saved or added to the campaign.

| Input | Type | What it means |
| --- | --- | --- |
| `id` (required) | integer | The campaign's id, as returned by list_campaigns. At least 1. |
| `name` | string | A new name. Up to 80 characters. |
| `utm_source` | string | A new utm_source. Send an empty string to remove it. Up to 100 characters. |
| `utm_medium` | string | A new utm_medium. Send an empty string to remove it. Up to 100 characters. |
| `utm_campaign` | string | A new utm_campaign. Send an empty string to remove it. Up to 100 characters. |

### List pixels `list_pixels`

*Read only*

List the account's ad pixels with their ids, to pass as "pixels" when shortening or updating a link.

No inputs.

### Check a link `check_link`

*Read only*

Check any siz.la short address, whoever owns it: whether it exists, was removed, or has expired, and where it leads. It never shows the destination of a password-protected link and never says who owns a link.

| Input | Type | What it means |
| --- | --- | --- |
| `link` (required) | string | A siz.la short address such as https://siz.la/lunch-menu, or just its code. Up to 500 characters. |



## From code

The REST API does the same jobs without an assistant. See (https://siz.la/docs/links).


