Create register

Buys a domain for your org and answers the ownership record together with the quote it was bought at.

POST /v1/domain/register

Domain → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/domain/register`
Method	`POST`
Operation	`post_domain_register`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Buys a domain for your org and answers the ownership record together with the quote it was bought at.

The order of operations is the product guarantee: quote, refuse anything unpurchasable or unpriced, AUTHORIZE the org's prepaid balance, provision the authoritative zone in Hanzo DNS, register at the registrar already pointing at Hanzo's nameservers, and only then CAPTURE the charge and record ownership. A registrar failure therefore leaves the balance untouched — the org is never billed for a domain it did not get.

It requires a validated principal; that principal's org owns the domain and is the ledger the charge lands on. Re-buying a name the org already holds is 409, not a second purchase.

Refusals are distinct on purpose: 402 when the prepaid balance cannot cover the quoted price, 409 when the name is not available, 503 when the deployment has no registrar credentials, and the registrar's own message with its own 4xx — or 502 for its 5xx — when it rejects the purchase. Zone provisioning is best-effort: if the zone service is down the domain is still registered against Hanzo's nameservers and the zone reconciles afterwards, rather than the purchase failing.

Request

55 fields, body application/json (required).

Field	In	Type	Required	Description
`contacts`	body	domain.Contacts	—
`contacts.admin`	body	domain.Registrant	—
`contacts.admin.address1`	body	string	—	street address
`contacts.admin.address2`	body	string	—	second address line
`contacts.admin.city`	body	string	—	city or locality
`contacts.admin.companyName`	body	string	—	the organisation the contact acts for
`contacts.admin.country`	body	string	—	ISO-3166 alpha-2, e.g. "US"
`contacts.admin.email`	body	string	—	where WHOIS correspondence is sent
`contacts.admin.fax`	body	string	—	fax number, in the same form as phone
`contacts.admin.firstName`	body	string	—	the contact's given name
`contacts.admin.lastName`	body	string	—	the contact's family name
`contacts.admin.phone`	body	string	—	+NN.NNNNNNN
`contacts.admin.state`	body	string	—	state, province or region
`contacts.admin.zip`	body	string	—	postal code
`contacts.billing`	body	domain.Registrant	—
`contacts.billing.address1`	body	string	—	street address
`contacts.billing.address2`	body	string	—	second address line
`contacts.billing.city`	body	string	—	city or locality
`contacts.billing.companyName`	body	string	—	the organisation the contact acts for
`contacts.billing.country`	body	string	—	ISO-3166 alpha-2, e.g. "US"
`contacts.billing.email`	body	string	—	where WHOIS correspondence is sent
`contacts.billing.fax`	body	string	—	fax number, in the same form as phone
`contacts.billing.firstName`	body	string	—	the contact's given name
`contacts.billing.lastName`	body	string	—	the contact's family name
`contacts.billing.phone`	body	string	—	+NN.NNNNNNN
`contacts.billing.state`	body	string	—	state, province or region
`contacts.billing.zip`	body	string	—	postal code
`contacts.registrant`	body	domain.Registrant	—
`contacts.registrant.address1`	body	string	—	street address
`contacts.registrant.address2`	body	string	—	second address line
`contacts.registrant.city`	body	string	—	city or locality
`contacts.registrant.companyName`	body	string	—	the organisation the contact acts for
`contacts.registrant.country`	body	string	—	ISO-3166 alpha-2, e.g. "US"
`contacts.registrant.email`	body	string	—	where WHOIS correspondence is sent
`contacts.registrant.fax`	body	string	—	fax number, in the same form as phone
`contacts.registrant.firstName`	body	string	—	the contact's given name
`contacts.registrant.lastName`	body	string	—	the contact's family name
`contacts.registrant.phone`	body	string	—	+NN.NNNNNNN
`contacts.registrant.state`	body	string	—	state, province or region
`contacts.registrant.zip`	body	string	—	postal code
`contacts.tech`	body	domain.Registrant	—
`contacts.tech.address1`	body	string	—	street address
`contacts.tech.address2`	body	string	—	second address line
`contacts.tech.city`	body	string	—	city or locality
`contacts.tech.companyName`	body	string	—	the organisation the contact acts for
`contacts.tech.country`	body	string	—	ISO-3166 alpha-2, e.g. "US"
`contacts.tech.email`	body	string	—	where WHOIS correspondence is sent
`contacts.tech.fax`	body	string	—	fax number, in the same form as phone
`contacts.tech.firstName`	body	string	—	the contact's given name
`contacts.tech.lastName`	body	string	—	the contact's family name
`contacts.tech.phone`	body	string	—	+NN.NNNNNNN
`contacts.tech.state`	body	string	—	state, province or region
`contacts.tech.zip`	body	string	—	postal code
`domain`	body	string	yes	Domain is the name to buy.
`years`	body	integer (int64)	—	Years is the term to buy, defaulting to 1.

Response

Status	Body	Meaning
`200`	domain.RegisterResult	ok
`default`	problem-details	refused

200 body — 17 fields.

Field	In	Type	Always	Description
`quote`	body	domain.Offer	—
`quote.available`	body	boolean	—	whether it can be bought right now
`quote.currency`	body	string	—	the currency both prices are in
`quote.domain`	body	string	—	the name this quote prices
`quote.premium`	body	boolean	—	whether the registry prices it above the standard rate
`quote.priceCents`	body	integer (int64)	—	sell (first-term registration)
`quote.renewalPriceCents`	body	integer (int64)	—	sell (renewal)
`quote.tld`	body	string	—	the top-level domain the name sits under
`record`	body	domain.Holding	—
`record.costCents`	body	integer (int64)	—	wholesale cost
`record.domain`	body	string	—	the name owned
`record.expiresAt`	body	string	—	when the registration lapses, RFC3339
`record.nameservers`	body	string[]	—	the authoritative nameservers the name points at
`record.order`	body	integer (int64)	—	registrar order id
`record.org`	body	string	—	the org that owns the domain
`record.priceCents`	body	integer (int64)	—	what the customer paid (sell)
`record.registeredAt`	body	integer (int64)	—	unix seconds

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo domain register --domain <domain>

.ts

.py

.go

.rs

.java

import { Configuration, DomainApi } from 'hanzoai';

const api = new DomainApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postDomainRegister({ domain: "<domain>" });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import DomainApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = DomainApi(client).post_domain_register(domain="<domain>")

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.DomainAPI.PostDomainRegister(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, domain_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = domain_api::post_domain_register(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.DomainApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new DomainApi(client).postDomainRegister();

curl -X POST https://api.hanzo.ai/v1/domain/register \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "domain": "<domain>"
     }'

MCP reaches domain through the domain tool, which names its 7 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "get_domain_availability"
         }
       }
     }'

Domain API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousSearch domain NextCreate renew