Docs menu

Domains API

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.

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

NameInTypeDescription
limitQueryintegerHow many domains to return on a page. 1 to 100. Default 15.
pageQueryintegerWhich page to return. At least 1. Default 1.

Example request

Shell
curl "https://siz.la/api/domains?limit=10&page=1" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
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
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
$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

NameInTypeDescription
domain (required)BodystringThe domain, such as go.example.com. A scheme, path or port is dropped.
redirectrootBodystringWhere the bare domain sends visitors. It must start with http:// or https://.
redirect404BodystringWhere an ending that does not exist sends visitors.

Example request

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

NameInTypeDescription
id (required)PathintegerThe domain's id. At least 1.
redirectrootBodystringWhere the bare domain sends visitors. Send an empty string to remove it.
redirect404BodystringWhere an ending that does not exist sends visitors. Send an empty string to remove it.

Example request

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

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

Example request

Shell
curl -X POST "https://siz.la/api/domain/31/check" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
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
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
$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

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

Example request

Shell
curl -X DELETE "https://siz.la/api/domain/31/delete" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
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
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
$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.