API v1 · REST · JSON

Developer API

Check and buy domains, list them for sale and track your sales from your own code — with the same engine and prices as the website.

Get an API token How to start

Base URL

URL

https://hqclouds.com/api/v1

What the API can do

Domain checks

Whether a domain is available, registration and renewal prices.

Buying from balance

Registration with the same engine and prices as the website, with a spend limit per key.

My domains

Your domains, paid-until dates, nameservers and whether they can be listed for sale.

Sell domains

List domains, change price and description, remove them from sale.

Sales history

Sales, marketplace commission and how much was credited to your balance.

Marketplace search

Public listing search with filters — no token needed.

The API is server-side: your script, bot or service (for example, HQName) calls HQClouds over HTTPS with a token from the dashboard. All amounts are in USD; money is charged to your HQClouds balance.

Quick start

Sign in or sign up at HQClouds. If you plan to buy domains, top up your balance.
In the dashboard, open the “API” section and create a key: name, scopes and daily spend limit.
Copy the token — it is shown only once. Keep it in an environment variable or a secrets manager.
Make your first request:

bash

export HQC_TOKEN="hqc_xxxxxxxx_..."

curl -s https://hqclouds.com/api/v1/me \
  -H "Authorization: Bearer $HQC_TOKEN"

Get an API token

Authentication

Every request (except the public marketplace search) sends the token in the Authorization header:

http

Authorization: Bearer hqc_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The token is shown once at creation. We store only its hash — a token cannot be recovered, only reissued.
Do not put the token into website or mobile app code: the API is meant for server-side calls and CORS is closed for it.
If a token leaks, revoke the key in the dashboard: revocation is immediate.
The request body is JSON (Content-Type: application/json) or a regular form. For PATCH, forms must be application/x-www-form-urlencoded.
Error messages are in English; with an Accept-Language: ru header most of them come in Russian. The code field does not depend on the language — rely on it in your code.

Key scopes

Scopes are set when the key is created. Give a key only what your software needs.

Scope	What it allows
`read`	Every key has it. Read access: account and balance, domains, listings, sales, domain checks.
`market:write`	Create, update and remove listings in the domain marketplace.
`domains:register`	Buy domains from the balance. Requires a daily spend limit.

Limits

60requests per minute per key. Over the limit — 429 with a Retry-After header; the remainder is in X-RateLimit-Remaining.

$100default daily spend limit — set your own when creating a key. Counted over the last 24 hours.

20domain purchases per hour per key — protection against a runaway script loop.

10active keys per account.

Purchases run strictly one at a time: if another purchase is in progress you get 429 busy — retry in a few seconds with the same Idempotency-Key.
Premium domains are never sold via the API — only manually in the dashboard.
Public marketplace search: 60 requests per minute per IP.

Idempotent purchases

The connection can drop mid-purchase, and you will not know whether it went through. That is why every purchase requires an Idempotency-Key header: any unique string up to 100 characters (Latin letters, digits and - _ : .), such as a UUID.

Retrying with the same key is safe: the API returns the result of the first attempt and does not charge you twice.
A new key means a new purchase. Generate the key once per purchase and save it before sending the request.
Timeout, dropped connection or a 5xx response — retry with the same key. A 202 response means the order is with the registrar and the money is reserved: do not buy again, poll GET /domains/{domain}.

http

-H "Idempotency-Key: 3f6d1c52-8a4e-4b0f-9e21-7c5d9a0b4e18"

Responses and errors

All responses are JSON in UTF-8. A successful response contains "ok": true. An error has "ok": false and an error object with a machine-readable code and a human-readable message. Amounts are strings with two decimals. Lists return items plus total, page, pages, per_page.

json

{
  "ok": false,
  "error": {
    "code": "daily_limit",
    "message": "Daily spend limit reached: spent $95.00 of $100.00 in the last 24 hours, this purchase is $12.99."
  }
}

HTTP	code	Meaning
HTTP 400	`invalid_json`	The request body is not a JSON object.
HTTP 401	`unauthorized`	No Authorization: Bearer header.
HTTP 401	`invalid_token`	The token is wrong, revoked or expired.
HTTP 402	`insufficient_balance`	Not enough money on the balance — top it up in the dashboard.
HTTP 403	`scope_required`	The key lacks the required scope.
HTTP 403	`no_spend_limit`	The key has no daily spend limit — it cannot buy.
HTTP 404	`not_found`	No such API endpoint, domain or listing — or it is not yours.
HTTP 405	`method_not_allowed`	This endpoint does not support this method.
HTTP 409	`already_listed`	The domain is already listed — the response contains the current listing.
HTTP 409	`price_above_max`	The final price is above max_price — nothing was bought.
HTTP 409	`premium_not_allowed`	Premium domain: manual purchase in the dashboard only.
HTTP 409	`…`	Other purchase refusals (domain taken, registrar refused) — no money charged, the reason is in message.
HTTP 413	`payload_too_large`	The request body is larger than 64 KB.
HTTP 422	`validation_failed`	Invalid data (price, category, the domain cannot be listed, etc.) — details in message.
HTTP 422	`domain_required, invalid_domain, invalid_field, idempotency_key_required`	A parameter is missing or has the wrong format.
HTTP 429	`rate_limited`	Per-minute rate limit exceeded — wait Retry-After seconds.
HTTP 429	`daily_limit, hourly_limit`	The daily spend limit or the hourly purchase limit of the key is used up.
HTTP 429	`busy`	Another purchase is in progress — retry in a few seconds with the same Idempotency-Key.
HTTP 500	`internal_error`	Failure on our side. Retry purchases with the same Idempotency-Key.
HTTP 503	`api_disabled, market_disabled`	The API or the domain marketplace is temporarily disabled.

Endpoints

Paths are relative to the base URL https://hqclouds.com/api/v1.

GET /me

Account, balance and key

Who owns the token, how much money is on the balance, which scopes the key has and how much of the daily limit is already spent. Handy for checking a token before you start.

Scope: read

Request

bash

curl -s https://hqclouds.com/api/v1/me \
  -H "Authorization: Bearer $HQC_TOKEN"

Response

200 OK

{
  "ok": true,
  "user": {"id": "6f1c2a9e-3b7d-4e2a-9c51-8d0f2b7a4e13", "email": "[email protected]"},
  "balance": {"amount": "120.50", "currency": "USD"},
  "key": {
    "id": "key_4b2f9a1c7d3e5f60a1b2c3d4",
    "name": "HQName",
    "scopes": ["read", "domains:register", "market:write"],
    "daily_spend_limit": "100.00",
    "spent_24h": "12.99",
    "rate_limit_per_minute": 60,
    "expires_at": null
  }
}

GET /domains/check

Check a domain

Whether a domain is available and how much registration and renewal cost. Buys nothing. If the domain is for sale in the HQClouds marketplace, for_sale contains the price and a link.

Scope: read

Parameter	Type	Required	Description
`domain`	`string`	yes	Domain name, e.g. example.com. Internationalized (non-Latin) domains are accepted as is.

state: available — free, taken — registered, premium — premium domain (not sold via the API), for_sale — for sale in the HQClouds marketplace, unsupported_tld — we do not register this zone, unknown — could not check, retry later.
Availability is indicative: the final price and availability check happens at purchase.

Request

bash

curl -s "https://hqclouds.com/api/v1/domains/check?domain=example.com" \
  -H "Authorization: Bearer $HQC_TOKEN"

Response

200 OK

{
  "ok": true,
  "domain": "example.com",
  "state": "available",
  "available": true,
  "premium": false,
  "price": {"register": "12.99", "renew": "14.99", "currency": "USD"},
  "for_sale": null,
  "note": "Availability is indicative; the final check happens at purchase."
}

POST /domains/register

Buy a domain

Registers a domain for 1 year and charges the price to your HQClouds balance. Before charging, the same final price check runs as on the website. Purchases are processed one at a time.

Scope: domains:register

Parameter	Type	Required	Description
`Idempotency-Key`	`header`	yes	A unique string per purchase (up to 100 characters). See “Idempotent purchases” for details.
`domain`	`string`	yes	Domain name.
`max_price`	`number`	no	Do not buy if the final price is above this amount, USD. We recommend always sending it.
`years`	`integer`	no	Registration period. Only 1 year is available via the API.

201 — the domain is registered and already yours. 202 — the registrar is still processing the order: the money is reserved; do not buy again, poll GET /domains/{domain} every minute or two.
If the purchase fails (domain taken, registrar refused), no money is charged and the daily limit reservation is released.

Request

bash

curl -s -X POST https://hqclouds.com/api/v1/domains/register \
  -H "Authorization: Bearer $HQC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: buy-example-com-20261001" \
  -d '{"domain":"example.com","max_price":15}'

Response

201 Created

{
  "ok": true,
  "status": "registered",
  "price": "12.99",
  "currency": "USD",
  "domain": {
    "id": "svc_9d3a1f0b2c4e6a8b0d1f3e5a",
    "domain": "example.com",
    "status": "active",
    "expires_at": "2027-10-01 09:14:52",
    "auto_renew": true,
    "parked": false,
    "nameservers": [],
    "listing": null
  }
}

202 Accepted

{
  "ok": true,
  "status": "pending",
  "price": "12.99",
  "domain_name": "example.com",
  "message": "The registrar is still processing this order. Poll GET /api/v1/domains/example.com in a few minutes."
}

GET /domains

My domains

All domains of the account, paginated. can_list — whether the domain can be listed for sale right now, list_blocked_reason — why not, listing — the current listing if the domain is already for sale.

Scope: read

Parameter	Type	Required	Description
`page`	`integer`	no	Page number, starting from 1.
`per_page`	`integer`	no	Page size: 50 by default, 100 max.

Request

bash

curl -s "https://hqclouds.com/api/v1/domains?page=1&per_page=50" \
  -H "Authorization: Bearer $HQC_TOKEN"

Response

200 OK

{
  "ok": true,
  "items": [
    {
      "id": "svc_9d3a1f0b2c4e6a8b0d1f3e5a",
      "domain": "example.com",
      "status": "active",
      "expires_at": "2027-10-01 09:14:52",
      "auto_renew": true,
      "parked": true,
      "nameservers": ["ns1.hqclouds.com", "ns2.hqclouds.com"],
      "listing": null,
      "can_list": true,
      "list_blocked_reason": null
    }
  ],
  "total": 1,
  "page": 1,
  "pages": 1,
  "per_page": 50
}

GET /domains/{domain}

Single domain

Status, paid-until date, nameservers and current listing of one domain. Use the same request to wait for the domain after a 202 response.

Scope: read

Parameter	Type	Required	Description
`domain`	`path`	yes	Domain name in the path.

Request

bash

curl -s https://hqclouds.com/api/v1/domains/example.com \
  -H "Authorization: Bearer $HQC_TOKEN"

Response

200 OK

{
  "ok": true,
  "domain": {
    "id": "svc_9d3a1f0b2c4e6a8b0d1f3e5a",
    "domain": "example.com",
    "status": "active",
    "expires_at": "2027-10-01 09:14:52",
    "auto_renew": true,
    "parked": false,
    "nameservers": [],
    "listing": {
      "id": "lot_1a2b3c4d5e6f7a8b9c0d1e2f",
      "price": "249.00",
      "status": "listed",
      "url": "https://hqclouds.com/market/example.com"
    }
  }
}

GET /market/lots

My listings

Your listings in the domain marketplace, newest first (last 1000). Each element of items is a listing object, as in the response to creating a listing.

Scope: read

Parameter	Type	Required	Description
`status`	`string`	no	Filter: active (for sale or reserved), listed, reserved, sold, delisted, cancelled.
`page`	`integer`	no	Page number, starting from 1.
`per_page`	`integer`	no	Page size: 50 by default, 100 max.

Listing status: for_sale — for sale, reserved — a buyer is paying an invoice, sold — sold, unavailable — removed from sale. raw_status — the exact status: listed, reserved, sold, delisted (removed by you), cancelled (removed by the system: the domain expired or left your account).

Request

bash

curl -s "https://hqclouds.com/api/v1/market/lots?status=active" \
  -H "Authorization: Bearer $HQC_TOKEN"

Response

200 OK (listing fields shortened)

{
  "ok": true,
  "items": [
    {
      "id": "lot_1a2b3c4d5e6f7a8b9c0d1e2f",
      "domain": "example.com",
      "price": "249.00",
      "status": "for_sale",
      "raw_status": "listed",
      "views": 12,
      "url": "https://hqclouds.com/market/example.com"
    }
  ],
  "total": 1,
  "page": 1,
  "pages": 1,
  "per_page": 50
}

POST /market/lots

List a domain for sale

Creates a listing in the domain marketplace. The domain must be in your HQClouds account, active, paid for at least 30 more days and have no pending registrar operations.

Scope: market:write

Parameter	Type	Required	Description
`domain`	`string`	yes	A domain from your account.
`price`	`number`	yes	Price in USD: from $5 to $100 000.
`category`	`string`	no	Category — a key from the table below.
`tags`	`array \| string`	no	Up to 10 tags (each up to 30 characters): an array or a comma-separated string.
`headline`	`string`	no	Headline, up to 160 characters.
`description`	`string`	no	Description, up to 2000 characters.
`metadata`	`object`	no	Your own data: up to 20 fields, strings, numbers and true/false only. Returned in responses as is — for example, a domain score from HQName.

On sale the marketplace keeps a 10% commission; the rest is credited to your HQClouds balance right away.
Listing the same domain again returns 409 already_listed with the current listing — a script retry breaks nothing.

Request

bash

curl -s -X POST https://hqclouds.com/api/v1/market/lots \
  -H "Authorization: Bearer $HQC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","price":"249","category":"tech","tags":["short","brandable"],"headline":"Short brandable .com","metadata":{"source":"hqname","score":87}}'

Response

201 Created

{
  "ok": true,
  "lot": {
    "id": "lot_1a2b3c4d5e6f7a8b9c0d1e2f",
    "domain": "example.com",
    "domain_display": "example.com",
    "sld": "example",
    "tld": ".com",
    "length": 7,
    "has_digits": false,
    "has_hyphen": false,
    "price": "249.00",
    "currency": "USD",
    "status": "for_sale",
    "category": "tech",
    "category_label": "Technology",
    "tags": ["short", "brandable"],
    "headline": "Short brandable .com",
    "description": null,
    "paid_until": "2027-10-01",
    "listed_at": "2026-10-01",
    "raw_status": "listed",
    "views": 0,
    "source": "api",
    "reserved_until": null,
    "sold_at": null,
    "delisted_at": null,
    "metadata": {"source": "hqname", "score": 87},
    "url": "https://hqclouds.com/market/example.com"
  }
}

GET /market/lots/{domain}

Single listing

A listing by domain name or listing id (lot_…). If the domain was listed several times, the live listing is returned, otherwise the latest one.

Scope: read

Parameter	Type	Required	Description
`domain`	`path`	yes	Domain name or listing id.

Request

bash

curl -s https://hqclouds.com/api/v1/market/lots/example.com \
  -H "Authorization: Bearer $HQC_TOKEN"

Response

200 OK

{
  "ok": true,
  "lot": { … }
}

PATCH /market/lots/{domain}

Update a listing

Send only the fields you change: price, category, tags, headline, description. An empty string clears a field (except the price).

Scope: market:write

Parameter	Type	Required	Description
`domain`	`path`	yes	Domain name or listing id.
`price`	`number`	no	New price in USD.
`category, tags, headline, description`		no	Same as when listing.

While a buyer is paying for the domain (reserved), the listing cannot be changed or removed — it can once the reservation ends.

Request

bash

curl -s -X PATCH https://hqclouds.com/api/v1/market/lots/example.com \
  -H "Authorization: Bearer $HQC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"price":"199.00"}'

Response

200 OK

{
  "ok": true,
  "lot": { … "price": "199.00" … }
}

DELETE /market/lots/{domain}

Remove from sale

Removes the listing from the marketplace. Calling it again is safe: it returns the already removed listing.

Scope: market:write

Parameter	Type	Required	Description
`domain`	`path`	yes	Domain name or listing id.

Request

bash

curl -s -X DELETE https://hqclouds.com/api/v1/market/lots/example.com \
  -H "Authorization: Bearer $HQC_TOKEN"

Response

200 OK

{
  "ok": true,
  "lot": { … "status": "unavailable", "raw_status": "delisted" … }
}

GET /market/sales

Sales history

Completed sales, newest first (last 5000), plus account totals.

Scope: read

Parameter	Type	Required	Description
`page`	`integer`	no	Page number, starting from 1.
`per_page`	`integer`	no	Page size: 50 by default, 100 max.

stats: sold — domains sold, revenue — total sales, commission — marketplace commission, proceeds — credited to your balance, listed — currently for sale, views — views of active listings.

Request

bash

curl -s https://hqclouds.com/api/v1/market/sales \
  -H "Authorization: Bearer $HQC_TOKEN"

Response

200 OK

{
  "ok": true,
  "stats": {
    "sold": 3,
    "revenue": "747.00",
    "commission": "74.70",
    "proceeds": "672.30",
    "listed": 5,
    "views": 214
  },
  "items": [
    {
      "id": "mko_7c1e3a5b9d0f2a4c6e8b1d3f",
      "domain": "example.com",
      "price": "249.00",
      "commission": "24.90",
      "proceeds": "224.10",
      "currency": "USD",
      "sold_at": "2026-09-28 14:03:11"
    }
  ],
  "total": 3,
  "page": 1,
  "pages": 1,
  "per_page": 50
}

GET /market/search

Search the domain marketplace

Public listing search — no token, CORS enabled, can be called right from a browser. Limit — 60 requests per minute per IP.

No token

Parameter	Type	Required	Description
`q`	`string`	no	Part of the domain name.
`tld`	`string`	no	Zone, e.g. .com.
`theme`	`string`	no	Category — a key from the table below.
`len_min, len_max`	`integer`	no	Name length without the zone.
`price_min, price_max`	`number`	no	Price in USD.
`no_digits, no_hyphen`	`1`	no	No digits / no hyphen.
`sort`	`string`	no	new (default), price_asc, price_desc, length, popular.
`page, per_page`	`integer`	no	Page and page size: 24 by default, 100 max.

Request

bash

curl -s "https://hqclouds.com/api/v1/market/search?tld=.com&theme=tech&len_max=8&price_max=500&no_digits=1&sort=price_asc"

Response

200 OK (listing fields shortened)

{
  "ok": true,
  "items": [
    {
      "id": "lot_1a2b3c4d5e6f7a8b9c0d1e2f",
      "domain": "example.com",
      "length": 7,
      "price": "249.00",
      "currency": "USD",
      "status": "for_sale",
      "category": "tech",
      "category_label": "Technology",
      "tags": ["short", "brandable"],
      "paid_until": "2027-10-01",
      "url": "https://hqclouds.com/market/example.com"
    }
  ],
  "total": 1,
  "page": 1,
  "pages": 1,
  "per_page": 24,
  "filters": {"q": "", "tld": ".com", "theme": "tech", "len_min": null, "len_max": 8,
              "price_min": null, "price_max": "500", "no_digits": true, "no_hyphen": false,
              "sort": "price_asc", "page": 1}
}

Listing categories (category, theme)

brand Brandable tech Technology ai AI business Business finance Finance crypto Crypto ecommerce Shopping creative Creative social Community health Health education Education travel Travel food Food realestate Real Estate fun Hobbies & Games

Example: buy a domain and list it for sale

Two calls in a row — this is how the HQName integration works: find a good name, buy it from the balance and list it in the HQClouds domain marketplace right away.

bash

export HQC_TOKEN="hqc_xxxxxxxx_..."
DOMAIN="example.com"
KEY="buy-$DOMAIN-$(date +%Y%m%d)"

# 1. Buy the domain. Retrying with the same KEY is safe — you will not be charged twice.
curl -s -X POST https://hqclouds.com/api/v1/domains/register \
  -H "Authorization: Bearer $HQC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d "{\"domain\":\"$DOMAIN\",\"max_price\":15}"

# 2. Response 201 — the domain is yours, list it for sale right away.
#    Response 202 — wait until GET /domains/$DOMAIN returns status "active".
curl -s -X POST https://hqclouds.com/api/v1/market/lots \
  -H "Authorization: Bearer $HQC_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"domain\":\"$DOMAIN\",\"price\":\"249\",\"category\":\"tech\",\"metadata\":{\"source\":\"hqname\"}}"

A freshly bought domain is paid for a year, so the “paid for at least 30 more days” rule is met immediately.
Buying needs a key with the domains:register scope, listing — with market:write. One key can have both.

FAQ

How much does the API cost?

The API is free. Domains bought via the API cost the same as on the website; the money is charged to your HQClouds balance.

What if a purchase request times out?

Repeat the same request with the same Idempotency-Key header. If the purchase already went through, the API returns its result and does not charge you twice.

Can I buy a premium domain via the API?

No. A premium domain can cost hundreds of times more than a regular one, so such domains can only be bought manually in the dashboard.

How do I revoke a token?

In the dashboard, in the “API” section: revocation takes effect immediately. Create a new key and replace the token in your software.

Ready to start?

Create a key in the dashboard — it is free and takes a minute.

Get an API token Domain marketplace