Domains
Search, register, renew and transfer domains, and manage their DNS, nameservers and forwarding, from the dashboard, the API or an agent. Paid in credits, priced by plan, with auto-renew included.
Last updated
On this page
Your workspace, and the agents that work for it, can buy and run domains with the same key and the same credits as every API. Check up to 20 names at once, register one, and it renews itself from your credits before it expires.
curl -sS -X POST "https://api.primaryapi.com/v1/domains/check" \
-H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domains":["acme-labs.com","acme-labs.dev"],"years":1}'Each result says whether the name is available and what it costs this workspace, in dollars and in credits. Then register it with POST /v1/domains (API reference), or in the dashboard under Domains › Find a domain.
What you get
- Registration, renewal and transfers for the common endings, one to ten years at a time.
- Auto-renew, on by default: 30 days before a domain expires it renews from your credits (below).
- DNS records, nameservers and forwarding (web addresses and email), managed here, free.
- WHOIS privacy, on by default and free where the ending allows it.
- The same rules for people and agents. The dashboard, the REST API and the MCP server share one set of permissions and prices.
Every domain is registered through a named registrar, its sponsoring registrar, and you accept that registrar's Registration Agreement when you buy. Each domain's page and its API object (registrar) name the registrar and link its agreement. The Domain registration terms cover the registrar, renewals, expiry notices and transfers.
Pricing
A domain costs what the registrar charges for it plus a markup that depends on your plan. The markup is a share of the registrar's price, capped in dollars for each year you buy:
| Plan | Markup | Capped at |
|---|---|---|
| Pay as you go | 80% | $20 a year |
| Builder | 60% | $15 a year |
| Pro | 40% | $10 a year |
| Scale | 20% | $5 a year |
| Enterprise | None: at cost | — |
For example, a name the registrar sells for $10.00 a year costs $18.00 on Pay as you go and $14.00 on Pro. A $90.00 name costs $110.00 on Pay as you go, where the cap applies. Totals round up to the cent. Premium names, which the registry prices above the usual price for their ending, follow the same rule; buying one needs maxUsd set to at least its price, and their renewals can cost more too.
POST /v1/domains/check and POST /v1/domains/quote are free and always answer with your workspace's own price. Every domain also carries renewal: one year's renewal at today's price.
Which credits pay
Domains are paid in credits valued at what they cost you:
- Credits included with your plan go first, each at your plan's credit price.
- Credits you bought pay the rest, at your top-up price.
Welcome credits and other free credits never pay for domains, and neither do the included credits of a plan assigned by PrimaryAPI rather than paid for. So the same domain can take a different number of credits from one balance to the next: each price answers with credits, includedCredits and boughtCredits, and affordable says whether your balance covers it now.
Management is free: DNS, nameservers, forwarding, privacy, locks, transfer codes and contacts cost nothing. Only registrations, renewals and transfers in are charged.
Before your first domain
- A verified email. The person buying (or, with an API key, the workspace's owner) must have verified their email address.
- Credits bought once. The workspace must have bought credits, or paid for a plan, at least once.
Until both are true, purchases answer 403 domains_not_allowed, with what is missing in details.missing (email_verified, bought_credits). Nothing is charged. A workspace can add up to 10 new domains (registrations and transfers in) a day.
The registrant
The registrant is who holds the domain: you, or the person or organisation you register it for, never PrimaryAPI. Add registrant contacts under Domains › Contacts (or POST /v1/domain-contacts); one is the workspace's default for new domains.
The registrar emails the registrant contact a link to verify the address when a domain is registered or transferred in. Click it within 15 days, or the registrar puts the domain on hold, which stops its website and email, until it is. A domain's verification shows pending (with its deadline) until then. With WHOIS privacy on, verification is usually not needed.
Auto-renew
Auto-renew is PrimaryAPI's own, never the registrar's. It is on for every new domain unless you turn it off:
- 30 days before expiry it charges the renewal to your credits and renews the domain.
nextAutoRenewAtsays when. - If it can't (most often, not enough credits), the domain shows
autoRenewProblem, we email the workspace's owner, admins and billing members why, and it tries again every day until it works or the domain expires. - Expiry reminders go to the same people 30 days, 7 days and 1 day before a domain expires, and once more after it expires.
Renewing by hand (POST /v1/domains/{domain}/renew) works any time and adds the years you choose.
Who can do what
| Read | Buy, renew, transfer, settings, contacts | DNS, nameservers, forwarding | |
|---|---|---|---|
| Dashboard | every member | owners, admins, billing members | owners, admins, developers |
| API key | full, run, view | full, run | full, run |
| Agent trial key, OAuth token | yes | prices only | — |
Purchases made with a key count against that key's spend limit, like any call.
DNS, nameservers and forwarding
A new domain uses the registrar's DNS, so its records and forwarding are managed here: A, AAAA, CNAME, MX, TXT, SRV and CAA records, with TTLs from 300 to 86,400 seconds. Web address forwarding sends the domain or a subdomain to a URL (permanent, temporary or masked); email forwarding sends an address, or every address, to up to five inboxes.
A record's id changes whenever the record is edited: read the list again after a change rather than keeping ids.
Point the domain at custom nameservers (2 to 13) to use another DNS host. Its records and forwarding are then managed there, and changing them here answers 409 domain_conflict until you switch back to the registrar's DNS ({"useRegistrarDns": true}).
Transfers
In. Unlock the domain at its current registrar and get its transfer code there, then send both with POST /v1/domains/transfers or Domains › Transfer a domain in. The transfer is priced and paid like any order and usually takes a few days; its order stays processing until the registrar finishes it.
Away. Unlock the domain (PATCH with "locked": false), then ask for its transfer code with POST /v1/domains/{domain}/transfer-code. The registrar emails the code to the domain's registrant contact: it is never returned by the API or shown in the dashboard. Give it to the new registrar. A transfer code is never withheld over unpaid credits.
Orders and safe retries
Every purchase is an order: pending, processing, completed, failed (never charged: the credits come back) or checking. Registrars don't take idempotency keys, so we never send an order twice: when the registrar's answer is lost, the order is checking while we read the registrar's own records, and its credits stay held until we know.
Send an Idempotency-Key with every purchase. The same key with the same body returns the same order instead of buying again; the same key with a different body answers 409 idempotency_conflict. Set maxUsd to the price you were quoted: an order that would cost more is refused with 409 domain_price_limit, free, and you can quote again.
Agents and MCP
The MCP server gives agents the same domain tools, with the same permissions, prices and errors as the API:
| Tool | What it does |
|---|---|
check_domains | Availability and this workspace's price, up to 20 names |
quote_domain | The price of one registration, renewal or transfer |
register_domain, renew_domain, transfer_domain_in | Purchases, paid in credits |
list_domains, get_domain | The workspace's domains |
update_domain_settings | Auto-renew, privacy, lock, registrant |
set_nameservers | Custom nameservers, or back to the registrar's DNS |
list_dns_records, set_dns_record, delete_dns_record | DNS records |
list_domain_contacts, create_domain_contact | Registrant contacts |
An agent buying a domain should check, quote, and register with maxUsd and an idempotency key, then tell its human that the registrant must click the registrar's verification email.
Errors
| Code | HTTP | When |
|---|---|---|
domains_not_allowed | 403 | The workspace can't buy domains yet: details.missing lists what to do. |
domain_unavailable | 409 | The name can't be registered or transferred in: details.reason says why. |
domain_price_limit | 409 | The order would cost more than maxUsd (or a premium name was ordered without it): quote again. |
domain_conflict | 409 | The domain's state blocks the change: details.reason names it (custom nameservers, another order in progress…). |
domain_suspended | 403 | PrimaryAPI suspended the domain: it can be read, not changed. |
insufficient_balance | 402 | The credits that can pay for domains don't cover the order. |
rate_limited | 429 | More than 10 new domains in a UTC day. |
None of them is charged. Errors lists every code.