Reseller API

• Base URL: https://www.bluewhaledns.com/api/v1/reseller. HTTPS only. Use www: https://bluewhaledns.com/api/… also works, but the site itself lives on www.
• REST: resources are nouns in the path, and the HTTP method says what happens to them.
• Every request and response body is JSON (Content-Type: application/json), errors, deletes and unknown paths included.
• The API works while your reseller plan is active. Keys are made in the reseller dashboard under API.
• Changes to /api/v1 only add fields and endpoints: nothing your code reads is renamed or removed.

1. Create an API key in the reseller dashboard. It's shown once: keep it on your server.
2. Send it as the bearer on every call.

# Your domains
curl https://www.bluewhaledns.com/api/v1/reseller/domains \
  -H "Authorization: Bearer bwd_live_6f1c…_9a2b…"

# Add a record
curl -X POST https://www.bluewhaledns.com/api/v1/reseller/domains/example.com/dns-records \
  -H "Authorization: Bearer bwd_live_6f1c…_9a2b…" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","name":"www","value":"203.0.113.10","ttl":3600}'

Every call sends Authorization: Bearer <credential>. The credential is your API key (bwd_live_…) or, if you'd rather not send the key on every call, a short-lived access token.

HTTP/1.1 200 OK
{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "expires_in": 3600,
  "expires_at": "2026-10-19T16:04:11.000Z"
}

• An expired or altered token answers 401 invalid_token: request a new one.
• Both are checked against your key and plan on every call: revoking the key, or a plan that lapses, stops them at once (401 key_revoked, 403 reseller_inactive).
• Test keys (bwd_test_…) can read, but every change answers 403 test_mode_unavailable for now.
• Never put an API key or token in a web page or app your clients can see. Call the API from your server.

The API acts for your reseller account only. You buy domains and services for your clients on your account, then put each one on a client in the dashboard (Domains, Services, or the client's page).

• Every domain call checks that the domain in the path is an active registration on your account. {domain} can be the domain name (example.com) or its id from GET /domains.
• Add ?client_id=<id> to any domain or record call to limit it to one client's domains. A portal you build for a client can pass that client's id on every call, so it can't reach anyone else's domains.
• A domain that isn't yours, isn't active, or isn't that client's answers 404 domain_not_found. The API never says whether someone else holds it.

• One budget per account for the whole API (/api/v1/reseller/… and /api/v1/domains/… together), counted per minute.
• Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time, in seconds, when the minute starts again).
• Past the limit, calls answer 429 rate_limited with Retry-After (seconds). The token endpoint has its own limit of 30 requests a minute from one address.
• When our domain Provider is limiting us or down, calls that need it answer 429 upstream_rate_limited or 503 upstream_unavailable, also with Retry-After.

Paths are relative to https://www.bluewhaledns.com/api/v1/reseller. The earlier https://www.bluewhaledns.com/api/v1/domains, /domains/check, /domains/register and /domains/transfer stay available with the same answers.

The domain object

{
  "page": 1,
  "per_page": 25,
  "total": 3,
  "domains": [
    { "id": null, "name": "new-client.com", "status": "pending", "expires_at": null,
      "auto_renew": true, "client_id": null, "order_id": "5b1e…" },
    { "id": "d6a1…", "name": "client-a.com", "status": "active",
      "expires_at": "2027-03-02T00:00:00Z", "auto_renew": true, "client_id": "c41f…" },
    { "id": "8b02…", "name": "client-b.net", "status": "active",
      "expires_at": "2026-12-18T00:00:00Z", "auto_renew": true, "client_id": null }
  ]
}

The earlier GET /api/v1/domains lists every registration on the account, newest first, with the same object plus domain, years and created_at.

Orders are priced at your plan, charged at once to the card saved under API in the reseller dashboard, and set up in the background: they answer 202 with an order_id to follow.

{ "results": [
  { "domain": "acme.com", "available": true, "price_cents": 1499, "currency": "USD" },
  { "domain": "acme.io", "available": false, "price_cents": null, "currency": "USD" }
] }

HTTP/1.1 202 Accepted
{
  "order_id": "5b1e…", "job_id": "9c07…", "domain": "acme.com", "years": 1,
  "price_cents": 1499, "currency": "USD", "status": "queued",
  "registration": { "id": null, "name": "acme.com", "status": "pending", "expires_at": null,
                    "auto_renew": true, "client_id": null, "order_id": "5b1e…" }
}

{
  "id": "5b1e…", "kind": "register", "domain": "acme.com", "years": 1,
  "status": "completed", "price_cents": 1499, "currency": "USD",
  "created_at": "2026-10-20T09:00:00Z", "completed_at": "2026-10-20T09:41:12Z"
}

• kind: register, transfer or renew. status: queued, processing, completed or failed (then with error: code and message). A transfer stays processing until the registry completes it.
• warnings appears when something needs you, e.g. nameservers_not_set: the registry didn't take the nameservers sent with the registration.

{ "prices": [
  { "tld": "com", "register_cents": 1499, "renew_cents": 1699, "transfer_cents": 1499, "currency": "USD" },
  { "tld": "co.uk", "register_cents": 899, "renew_cents": 899, "transfer_cents": null, "currency": "USD" }
] }

Prices are for a standard name; a premium or sale-priced name differs, and /domains/check gives its exact price. null means that operation isn't available for the extension.

Retrying safely: Idempotency-Key

Register, transfer and renew charge your card, so a retry after a timeout must not order twice. Send an Idempotency-Key header (1 to 255 characters, e.g. your own order id or a UUID) and send the same key, with the same body, on every retry of that order.

curl -X POST https://www.bluewhaledns.com/api/v1/reseller/domains/register \
  -H "Authorization: Bearer bwd_live_6f1c…_9a2b…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-81723" \
  -d '{"domain":"acme.com","years":1}'

• The same key and body within 24 hours answers with the first answer (same status and body, plus Idempotent-Replayed: true). Your card is charged once.
• Answers from before the charge (a validation error, the domain taken, the Provider busy) don't use the key up: fix the problem and retry with the same key. Once the card was charged or declined, the answer is final for that key; after a declined card, use a new key.
• The same key with a different body, or on another endpoint or domain, answers 422 idempotency_key_reused.
• A retry while the first request is still running answers 409 request_in_progress: wait a few seconds and retry.
• Without a key, a second order for a domain whose first order is still being set up answers 409 order_pending with details.order_id.

• With other nameservers, the domain's records are managed there: the DNS record endpoints then answer 409 dns_not_managed.
• Nameservers inside the domain itself (e.g. ns1.acme.com for acme.com) need glue records: 400 nameservers_need_glue, contact support.
• To move a domain to BlueWhale DNS, use its Nameservers tab in the dashboard, which copies the records into a zone first (400 bluewhale_nameservers here).

The record object

List records

{
  "domain": { "id": "d6a1…", "name": "client-a.com", "client_id": "c41f…" },
  "dns": {
    "host": "bluewhale_dns",
    "nameservers": ["ns1.bluewhaledns.net", "ns2.bluewhaledns.net", "ns3.bluewhaledns.net", "ns4.bluewhaledns.net"],
    "record_types": ["A", "AAAA", "CNAME", "MX", "TXT", "SRV", "ALIAS"],
    "ttl": { "fixed": 3600 }
  },
  "records": [
    { "id": "rec_3f9a0c1e2b7d4a5f6e8c9b0a", "type": "A", "name": "@", "fqdn": "client-a.com",
      "value": "203.0.113.10", "ttl": 3600, "priority": null, "weight": null, "port": null,
      "read_only": false, "managed_by": null },
    { "id": "rec_9c2e4b6a8d0f1e3c5a7b9d1f", "type": "MX", "name": "@", "fqdn": "client-a.com",
      "value": "mx1.example-mail.net", "ttl": 3600, "priority": 10, "weight": null, "port": null,
      "read_only": false, "managed_by": null }
  ],
  "total": 2
}

Get one record

Create a record

POST /domains/client-a.com/dns-records
{ "type": "MX", "name": "@", "value": "mx2.example-mail.net", "priority": 20, "ttl": 300 }

HTTP/1.1 201 Created
Location: /api/v1/reseller/domains/d6a1…/dns-records/rec_1d7f…
{
  "domain": { … },
  "dns": { … },
  "record": { "id": "rec_1d7f…", "type": "MX", "name": "@", "fqdn": "client-a.com",
              "value": "mx2.example-mail.net", "ttl": 3600, "priority": 20, "weight": null, "port": null, "read_only": false },
  "warnings": [ { "code": "ttl_adjusted", "message": "BlueWhale DNS serves every record with a 3600-second TTL." } ]
}

Update a record

PATCH /domains/client-a.com/dns-records/rec_9c2e4b6a8d0f1e3c5a7b9d1f
{ "priority": 5 }

HTTP/1.1 200 OK
{ "domain": { … }, "dns": { … }, "record": { "id": "rec_77b0…", "type": "MX", "priority": 5, … }, "warnings": [] }

The answer carries the record's new id.

Delete a record

HTTP/1.1 200 OK
{ "deleted": true, "id": "rec_77b0…", "domain": { "id": "d6a1…", "name": "client-a.com", "client_id": "c41f…" } }

Say what a name's records of one type should be, and we make the zone match in one change: records already right are left alone, the rest are added or removed. Sending the same set again changes nothing, so it's safe to call on every deploy instead of listing, comparing, deleting and adding records one at a time.

PUT /domains/client-a.com/dns-records/rrset
{ "name": "@", "type": "MX", "values": ["10 mx1.example-mail.net", "20 mx2.example-mail.net"], "ttl": 3600 }

HTTP/1.1 200 OK
{
  "domain": { … },
  "dns": { … },
  "name": "@",
  "type": "MX",
  "records": [
    { "id": "rec_9c2e…", "type": "MX", "name": "@", "value": "mx1.example-mail.net", "priority": 10, … },
    { "id": "rec_51ad…", "type": "MX", "name": "@", "value": "mx2.example-mail.net", "priority": 20, … }
  ],
  "changed": { "added": 1, "removed": 0, "updated": 0, "kept": 1 },
  "warnings": []
}

• records is the set after the change. changed counts records added, removed, updated (only their TTL changed) and kept as they were.
• The same conflicts as single records apply (409 cname_conflict, alias_conflict). Records in the set the API can't change answer 409 record_read_only.
• With "type": "ALIAS" it sets or deletes the domain's ALIAS record, replacing any A and AAAA records on the domain itself (see ALIAS records).

A CNAME can't be on the domain itself, so pointing client-a.com (not just www) at your app usually means copying your app's IP addresses into A records, which go stale when they change. An ALIAS record does it for you: give it a host name and we keep the domain's A and AAAA records set to that host's addresses.

POST /domains/client-a.com/dns-records
{ "type": "ALIAS", "name": "@", "value": "saas-target.example.net" }

# or, replacing any A/AAAA records the domain has:
PUT /domains/client-a.com/dns-records/rrset
{ "name": "@", "type": "ALIAS", "values": ["saas-target.example.net"] }

• Only on @, with a fully qualified host name as the value (not the domain itself). ttl defaults to 900.
• We look up the host's IPv4 and IPv6 addresses and write them as the domain's A and AAAA records in the same change. A host with no addresses answers 422 (alias_target_unresolvable).
• Every 10 minutes we look the host up again and change only the records that differ. If the host can't be looked up, the records are kept as they are.
• Lists show one ALIAS record, and the A/AAAA records it keeps with "read_only": true and "managed_by": "alias". Change or delete the ALIAS, not those records.
• While a domain has an ALIAS it can't have other A/AAAA records on @ (409 alias_conflict); a plain create is refused when it already has some (use the record set, which replaces them). Deleting the ALIAS removes its A/AAAA records.
• Check for ALIAS in dns.record_types before relying on it.

How soon a change of address is seen

When you move your app to new addresses, keep the old ones answering for that long.

A record that breaks a rule answers 422 validation_failed, with every problem listed in error.details.errors (each has field, code and message). Unknown fields are refused too, so a typo like prio doesn't pass silently.

Host names (CNAME, MX, NS and SRV targets) must be fully qualified: at least two labels ending in a real extension. A final dot is removed. An exact copy of an existing record answers 409 duplicate_record; a CNAME sharing a name with other records answers 409 cname_conflict.

The domain's nameservers decide where its records live, and so what they can hold. dns.host in every answer says which.

A type the zone doesn't take answers 422 with unsupported_record_type. A domain on other nameservers (Cloudflare, another host…) answers 409 dns_not_managed: its records are managed there. Both zones take ALIAS: it's written as A and AAAA records.

A record's id comes from what it holds (type, name, value, priority, weight and port), so it stays the same however often you read the zone, and changes when the record changes. A TTL-only change keeps it. After an update use the id in the answer; an old id answers 404 record_not_found. If in doubt, list the zone again.

Instead of polling orders, let us tell you. Add up to 5 HTTPS endpoints in the reseller dashboard under API → Webhooks, for every event or the ones you pick. Each endpoint gets a signing secret (whsec_…), shown once when you add it.

Each event is a POST with a JSON body. order.failed comes with domain.registration_failed or domain.transfer_failed where one applies, and on its own for a renewal. The dashboard's "Send test event" sends webhook.test.

POST https://app.example.com/webhooks/bluewhale
content-type: application/json
webhook-id: msg_2c1f9e0b8a7d4c3e9f1a6b5d4c3e2f1a
webhook-timestamp: 1792512000
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{
  "type": "domain.registered",
  "timestamp": "2026-10-20T14:00:00.000Z",
  "data": {
    "domain": { "name": "client-a.com", "client_id": "c41f…", "expires_at": "2027-10-20T14:00:00.000Z" },
    "order_id": "7b0e…",
    "years": 1
  }
}

Checking the signature

Events are signed with the Standard Webhooks scheme, so their libraries (e.g. standardwebhooks on npm) verify them with your secret. By hand: HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>, keyed with the base64-decoded part of the secret after whsec_, base64-encoded, must equal one of the space-separated v1,… signatures. Refuse timestamps more than 5 minutes from now.

import crypto from "node:crypto";

function verify(secret, headers, rawBody) {
  const id = headers["webhook-id"], ts = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const expected = crypto.createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest("base64");
  return headers["webhook-signature"].split(" ").some((s) => {
    const sig = s.slice(s.indexOf(",") + 1);
    return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  });
}

Delivery and retries

• Answer with any 2xx within 10 seconds; do slow work afterwards. Redirects aren't followed.
• Anything else is retried about 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours and 10 hours later, with a last try 24 hours after the event. Retries go out with our 10-minute run, so allow a few minutes either way.
• A retry has the same webhook-id (a new timestamp and signature): use it to ignore an event you've already handled. Events can arrive out of order.
• The dashboard shows the latest deliveries and the last error for each endpoint. Turning an endpoint off drops its retries.

Every error, on every /api/v1 path, has the same shape: error.code for your code to check, error.message for people, and sometimes error.details.

{
  "error": {
    "code": "validation_failed",
    "message": "The record isn't valid.",
    "details": {
      "errors": [
        { "field": "value", "code": "invalid_ipv4", "message": "An A record's value must be an IPv4 address, e.g. 203.0.113.10." },
        { "field": "ttl", "code": "invalid_ttl", "message": "ttl must be a whole number of seconds from 60 to 86400." }
      ]
    }
  }
}

Warnings aren't errors: warnings in an answer lists things worth knowing, e.g. ttl_adjusted (the zone serves another TTL) or nameservers_not_set on an order.

JavaScript (Node 18+)

const BASE = "https://www.bluewhaledns.com/api/v1/reseller";
const KEY = process.env.BLUEWHALE_API_KEY;

async function api(method, path, data, idempotencyKey) {
  const res = await fetch(`${BASE}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
      ...(idempotencyKey && { "Idempotency-Key": idempotencyKey }),
    },
    body: data ? JSON.stringify(data) : undefined,
  });
  const body = await res.json();
  if (!res.ok) throw Object.assign(new Error(body.error.message), body.error, { status: res.status });
  return body;
}

// Register a domain for one of your orders (safe to retry with the same key).
const order = await api("POST", "/domains/register", { domain: "client-a.com", years: 1 }, "my-order-1042");
console.log(order.order_id, order.registration.status); // "…", "pending"

// Point a client's domain at your app: www by CNAME, the domain itself by ALIAS.
// Safe to run on every deploy: a set that's already right isn't touched.
await api("PUT", "/domains/client-a.com/dns-records/rrset", { name: "www", type: "CNAME", values: ["saas-target.example.net"] });
await api("PUT", "/domains/client-a.com/dns-records/rrset", { name: "@", type: "ALIAS", values: ["saas-target.example.net"] });

// Point www at a new server for one client's domain, one record at a time.
const clientId = "c41f…";
const { records } = await api("GET", `/domains/client-a.com/dns-records?type=A&name=www&client_id=${clientId}`);
if (records[0]) {
  await api("PATCH", `/domains/client-a.com/dns-records/${records[0].id}?client_id=${clientId}`, { value: "203.0.113.20" });
} else {
  await api("POST", `/domains/client-a.com/dns-records?client_id=${clientId}`, { type: "A", name: "www", value: "203.0.113.20" });
}

curl: replace and delete

curl -X PUT https://www.bluewhaledns.com/api/v1/reseller/domains/client-a.com/dns-records/rec_3f9a0c1e2b7d4a5f6e8c9b0a \
  -H "Authorization: Bearer $BLUEWHALE_API_KEY" -H "Content-Type: application/json" \
  -d '{"type":"CNAME","name":"shop","value":"shops.myshopify.com","ttl":3600}'

curl -X DELETE https://www.bluewhaledns.com/api/v1/reseller/domains/client-a.com/dns-records/rec_3f9a0c1e2b7d4a5f6e8c9b0a \
  -H "Authorization: Bearer $BLUEWHALE_API_KEY"