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
| 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 "https://siz.la/api/domains?limit=10&page=1" \
-H "Authorization: Bearer $SIZLA_API_KEY"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);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())$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
{
"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
statusispendinguntil the DNS records are in place,activewhile links work on the domain andfailedwhen the records stop pointing here. Only anactivedomain can be used on a link.erroris the text"0"on this endpoint and the number0on 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 -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"}'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);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())$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
{
"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.messagesays 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 -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"}'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);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())$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
{
"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.messagesays 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 -X POST "https://siz.la/api/domain/31/check" \
-H "Authorization: Bearer $SIZLA_API_KEY"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);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())$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
{
"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 -X DELETE "https://siz.la/api/domain/31/delete" \
-H "Authorization: Bearer $SIZLA_API_KEY"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);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())$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
{
"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.