The Domains You Own
The five endpoints that read, set, renew and extend a domain you own.
Overview
A domain is a service too, and it carries endpoints of its own: the service endpoints answer not found for it. These five read a domain you own, set it, renew it and open its add-ons.
The address takes either the domain name itself or the service number, and both open the same record.
The capability list in the detail says which jobs can be done. It differs from provider to provider, so the interface should be built from that list.
Reference
Listing the Domains
Returns the account's domains.
curl 'https://panel.example.com/api/v1/client/domains?tld=com' \
-H "Authorization: Bearer $CLIENT_KEY"const res = await fetch('https://panel.example.com/api/v1/client/domains?status=active', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const expiring = data.filter((d) => d.due_date && d.due_date < horizon);$ch = curl_init('https://panel.example.com/api/v1/client/domains?status=active');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);// The lock and privacy values are a MIRROR: the last value saved rather than the current one.
$rows = Kernel::internal('client:Domains/GetDomains', ['owner_id' => $uid])['data'];
// for the live one: client:Domains/GetTransferLockReading a Domain
Returns a domain, what its provider can do and the renewal terms.
curl 'https://panel.example.com/api/v1/client/domains/example.com' \
-H "Authorization: Bearer $CLIENT_KEY"const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
if (data.capabilities.dns_records) showDnsTab();$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);// Build the interface FROM THE CAPABILITIES: not every provider does everything, and a closed surface answers 422.
$d = Kernel::internal('client:Domains/GetDomain',
['owner_id' => $uid, 'domain' => $domain])['data'];
$tabs = array_keys(array_filter($d['capabilities']));Changing the Domain Preferences
Changes automatic renewal and the billing profile.
curl -X PATCH 'https://panel.example.com/api/v1/client/domains/example.com' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"auto_renew":true}'const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ auto_renew: true }),
});
if (res.status === 422) explainLock(await res.json());$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['auto_renew' => true]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);// With automatic renewal off a domain expires QUIETLY: setting a reminder is left to you.
Kernel::internal('client:Domains/UpdateDomain',
['owner_id' => $uid, 'domain' => $domain, 'auto_renew' => true]);Raising a Renewal Invoice
Raises a renewal invoice for the number of years asked.
curl -X POST 'https://panel.example.com/api/v1/client/domains/example.com/renew' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"years":2}'const d = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}`, {
headers: { Authorization: `Bearer ${clientKey}` },
}).then((r) => r.json());
const terms = d.data.renewal.terms;
await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/renew`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ years: terms[0].years }),
});$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/renew');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['years' => 2]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);// The terms offered are bounded by THE REGISTRY CEILING: a ten-year name may take no further two.
$d = Kernel::internal('client:Domains/GetDomain',
['owner_id' => $uid, 'domain' => $domain])['data'];
$years = array_column($d['renewal']['terms'], 'years');Buying a Domain Add-on
Buys the name management, privacy or forwarding add-on.
curl -X POST 'https://panel.example.com/api/v1/client/domains/example.com/addons/whois-privacy' \
-H "Authorization: Bearer $CLIENT_KEY"const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/addons/${key}`, {
method: 'POST',
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
goPay(data.invoice_id);$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/addons/' . $key);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);// An add-on does not open until THE INVOICE IS PAID: the purchase call raises the document alone.
$inv = Kernel::internal('client:Domains/BuyDomainAddon',
['owner_id' => $uid, 'domain' => $domain, 'key' => 'whois-privacy'])['data'];
Kernel::internal('client:Invoices/PayInvoice',
['owner_id' => $uid, 'id' => $inv['invoice_id'], 'payment' => ['method' => 'balance']]);Pitfalls
The capability list in the detail carries eleven fields and no provider offers them all. Calling a closed surface comes back with a plain error. Draw the tabs and the buttons from that list, since a fixed interface breaks when the provider changes.
The transfer lock and privacy values in the listing and the detail are the last ones saved rather than the provider's current state. Read the real value live from the lock endpoint. On a domain where the mirror was never written the safe assumption is locked.
Buying an add-on raises an invoice and nothing more; the surface stays closed until it is paid. A second purchase is refused while one waits, and the answer says which invoice blocks it. The first period is prorated to the time left.
The renewal rows in the detail show the terms the operator prices and that fit under the registry's total ceiling. A domain expiring far out can leave one year in the list, or none. Pick the term from the list rather than guessing.
A domain with automatic renewal off expires quietly on its due date and enters the recovery window. The API gives no separate warning. Read the expiry from the listing and set a reminder of your own.
Related Articles
Thanks for your feedback!
Our support team is here around the clock for anything you can't find above.