API v1 · REST · JSON

API для разработчиков

Проверяйте и покупайте домены, выставляйте их на продажу и смотрите историю продаж из своего кода — тем же движком и по тем же ценам, что на сайте.

Получить API-токен Как начать

Базовый адрес

URL

https://hqclouds.com/api/v1

Что умеет API

Проверка доменов

Свободен ли домен, цена регистрации и продления.

Покупка с баланса

Регистрация тем же движком и по тем же ценам, что на сайте, с лимитом трат на ключ.

Мои домены

Список доменов, сроки оплаты, NS и можно ли выставить на продажу.

Продажа доменов

Выставляйте домены, меняйте цену и описание, снимайте с продажи.

История продаж

Продажи, комиссия площадки и сколько зачислено на баланс.

Поиск по магазину

Публичный поиск лотов с фильтрами — без токена.

API работает с сервера: ваш скрипт, бот или сервис (например, HQName) обращается к HQClouds по HTTPS с токеном из кабинета. Все суммы — в USD, деньги списываются с баланса HQClouds.

Быстрый старт

Войдите или зарегистрируйтесь в HQClouds. Если собираетесь покупать домены — пополните баланс.
В кабинете откройте раздел «API» и создайте ключ: название, права и дневной лимит трат.
Скопируйте токен — он показывается только один раз. Сохраните его в переменной окружения или менеджере секретов.
Сделайте первый запрос:

bash

export HQC_TOKEN="hqc_xxxxxxxx_..."

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

Получить API-токен

Аутентификация

Каждый запрос (кроме публичного поиска по магазину) передаёт токен в заголовке Authorization:

http

Authorization: Bearer hqc_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Токен показывается один раз при создании. Мы храним только его хэш — восстановить токен нельзя, только выпустить новый.
Не вставляйте токен в код сайта или мобильного приложения: API рассчитано на вызовы с сервера, CORS для него закрыт.
Если токен утёк — отзовите ключ в кабинете: отзыв действует сразу.
Тело запроса — JSON (Content-Type: application/json) или обычная форма. Для PATCH форма — только application/x-www-form-urlencoded.
Сообщения об ошибках — на английском; с заголовком Accept-Language: ru большинство придёт на русском. Поле code от языка не зависит — в коде опирайтесь на него.

Права ключа

Права задаются при создании ключа. Давайте ключу только то, что нужно программе.

Право	Что разрешает
`read`	Есть у каждого ключа. Чтение: аккаунт и баланс, домены, лоты, продажи, проверка доменов.
`market:write`	Выставлять, изменять и снимать лоты в магазине доменов.
`domains:register`	Покупать домены с баланса. Требует дневной лимит трат.

Лимиты

60запросов в минуту на ключ. Сверх лимита — 429 и заголовок Retry-After; остаток виден в X-RateLimit-Remaining.

$100дневной лимит трат по умолчанию — свой задаётся при создании ключа. Считается за последние 24 часа.

20покупок доменов в час на ключ — защита от ошибки в цикле скрипта.

10активных ключей на аккаунт.

Покупки выполняются строго по одной: если в этот момент идёт другая покупка, придёт 429 busy — повторите через несколько секунд с тем же Idempotency-Key.
Премиум-домены через API не продаются никогда — только вручную в кабинете.
Публичный поиск по магазину: 60 запросов в минуту с одного IP.

Идемпотентность покупок

Сеть может оборваться в момент покупки — и вы не узнаете, прошла ли она. Поэтому каждая покупка требует заголовок Idempotency-Key: любую уникальную строку до 100 символов (латиница, цифры и - _ : .), например UUID.

Повтор с тем же ключом безопасен: API вернёт результат первой попытки и не спишет деньги второй раз.
Новый ключ — это новая покупка. Генерируйте ключ один раз на покупку и сохраняйте его до отправки запроса.
Таймаут, обрыв или ответ 5xx — повторяйте с тем же ключом. Ответ 202 — заказ у регистратора, деньги в резерве: не покупайте заново, а проверяйте GET /domains/{domain}.

http

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

Ответы и ошибки

Все ответы — JSON в UTF-8. Успешный ответ содержит "ok": true. Ошибка — "ok": false и объект error с машинным кодом code и сообщением message. Суммы — строки с двумя знаками после точки. Списки отдают items и 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	Что значит
HTTP 400	`invalid_json`	Тело запроса — не JSON-объект.
HTTP 401	`unauthorized`	Нет заголовка Authorization: Bearer.
HTTP 401	`invalid_token`	Токен неверный, отозван или истёк.
HTTP 402	`insufficient_balance`	Не хватает денег на балансе — пополните его в кабинете.
HTTP 403	`scope_required`	У ключа нет нужного права.
HTTP 403	`no_spend_limit`	У ключа нет дневного лимита трат — покупать им нельзя.
HTTP 404	`not_found`	Нет такого адреса API, домена или лота — или он не ваш.
HTTP 405	`method_not_allowed`	Этот адрес не поддерживает такой метод.
HTTP 409	`already_listed`	Домен уже выставлен — в ответе текущий лот.
HTTP 409	`price_above_max`	Итоговая цена выше max_price — покупка не сделана.
HTTP 409	`premium_not_allowed`	Премиум-домен: только вручную в кабинете.
HTTP 409	`…`	Прочие отказы покупки (домен занят, регистратор отказал) — деньги не списаны, причина в message.
HTTP 413	`payload_too_large`	Тело запроса больше 64 КБ.
HTTP 422	`validation_failed`	Ошибка в данных (цена, тематика, домен нельзя выставить и т. п.) — подробности в message.
HTTP 422	`domain_required, invalid_domain, invalid_field, idempotency_key_required`	Не хватает параметра или он в неверном формате.
HTTP 429	`rate_limited`	Превышен лимит запросов в минуту — подождите Retry-After секунд.
HTTP 429	`daily_limit, hourly_limit`	Исчерпан дневной лимит трат ключа или лимит покупок в час.
HTTP 429	`busy`	Сейчас идёт другая покупка — повторите через несколько секунд с тем же Idempotency-Key.
HTTP 500	`internal_error`	Сбой на нашей стороне. Покупку повторяйте с тем же Idempotency-Key.
HTTP 503	`api_disabled, market_disabled`	API или магазин доменов временно выключены.

Эндпоинты

Пути указаны относительно базового адреса https://hqclouds.com/api/v1.

GET /me

Аккаунт, баланс и ключ

Кто владелец токена, сколько денег на балансе, какие права у ключа и сколько из дневного лимита уже потрачено. Удобно проверить токен перед работой.

Право: read

Запрос

bash

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

Ответ

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

Проверить домен

Свободен ли домен и сколько стоят регистрация и продление. Ничего не покупает. Если домен продаётся в магазине HQClouds, в for_sale будут цена и ссылка.

Право: read

Параметр	Тип	Обязателен	Описание
`domain`	`string`	да	Имя домена, например example.com. Домены на кириллице принимаются как есть.

state: available — свободен, taken — занят, premium — премиум-домен (через API не продаётся), for_sale — продаётся в магазине HQClouds, unsupported_tld — зону мы не регистрируем, unknown — проверить не удалось, повторите позже.
Доступность — предварительная: окончательная проверка цены и наличия происходит в момент покупки.

Запрос

bash

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

Ответ

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

Купить домен

Регистрирует домен на 1 год и списывает цену с баланса HQClouds. Перед списанием — та же финальная проверка цены, что и на сайте. Покупки выполняются по одной.

Право: domains:register

Параметр	Тип	Обязателен	Описание
`Idempotency-Key`	`header`	да	Уникальная строка на каждую покупку (до 100 символов). Подробно — в разделе «Идемпотентность покупок».
`domain`	`string`	да	Имя домена.
`max_price`	`number`	нет	Не покупать, если итоговая цена выше этой суммы, USD. Рекомендуем передавать всегда.
`years`	`integer`	нет	Срок регистрации. Через API доступен только 1 год.

201 — домен зарегистрирован и уже ваш. 202 — регистратор ещё обрабатывает заказ: деньги зарезервированы, не покупайте заново, а проверяйте GET /domains/{domain} раз в минуту-две.
Если покупка не удалась (домен занят, регистратор отказал), деньги не списываются, а резерв дневного лимита освобождается.

Запрос

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}'

Ответ

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

Мои домены

Все домены аккаунта постранично. can_list — можно ли выставить домен на продажу прямо сейчас, list_blocked_reason — почему нельзя, listing — текущий лот, если домен уже продаётся.

Право: read

Параметр	Тип	Обязателен	Описание
`page`	`integer`	нет	Номер страницы, с 1.
`per_page`	`integer`	нет	Размер страницы: по умолчанию 50, максимум 100.

Запрос

bash

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

Ответ

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}

Один домен

Статус, срок оплаты, NS-серверы и текущий лот одного домена. Этим же запросом дожидаются выдачи домена после ответа 202.

Право: read

Параметр	Тип	Обязателен	Описание
`domain`	`path`	да	Имя домена в адресе.

Запрос

bash

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

Ответ

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

Мои лоты

Ваши лоты в магазине доменов, новые сверху (последние 1000). Каждый элемент items — объект лота, как в ответе на выставление.

Право: read

Параметр	Тип	Обязателен	Описание
`status`	`string`	нет	Фильтр: active (продаётся или забронирован), listed, reserved, sold, delisted, cancelled.
`page`	`integer`	нет	Номер страницы, с 1.
`per_page`	`integer`	нет	Размер страницы: по умолчанию 50, максимум 100.

status лота: for_sale — продаётся, reserved — покупатель оплачивает счёт, sold — продан, unavailable — снят с продажи. raw_status — точный статус: listed, reserved, sold, delisted (сняли вы), cancelled (снят системой: домен истёк или ушёл из аккаунта).

Запрос

bash

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

Ответ

200 OK (поля лота сокращены)

{
  "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

Выставить домен на продажу

Создаёт лот в магазине доменов. Домен должен быть в вашем аккаунте HQClouds, активным, оплаченным ещё минимум на 30 дн. и без идущих операций у регистратора.

Право: market:write

Параметр	Тип	Обязателен	Описание
`domain`	`string`	да	Домен из вашего аккаунта.
`price`	`number`	да	Цена в USD: от $5 до $100 000.
`category`	`string`	нет	Тематика — ключ из таблицы ниже.
`tags`	`array \| string`	нет	До 10 тегов (каждый до 30 символов): массив или строка через запятую.
`headline`	`string`	нет	Заголовок до 160 символов.
`description`	`string`	нет	Описание до 2000 символов.
`metadata`	`object`	нет	Ваши данные: до 20 полей, только строки, числа и true/false. Возвращаются в ответах как есть — например, оценка домена из HQName.

При продаже площадка удерживает комиссию 10% от цены, остальное сразу зачисляется на ваш баланс HQClouds.
Повторное выставление того же домена вернёт 409 already_listed и текущий лот — ретрай скрипта ничего не сломает.

Запрос

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}}'

Ответ

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}

Один лот

Лот по имени домена или по id лота (lot_…). Если домен выставлялся несколько раз, вернётся живой лот, иначе последний.

Право: read

Параметр	Тип	Обязателен	Описание
`domain`	`path`	да	Имя домена или id лота.

Запрос

bash

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

Ответ

200 OK

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

PATCH /market/lots/{domain}

Изменить лот

Передайте только те поля, которые меняете: price, category, tags, headline, description. Пустая строка очищает поле (кроме цены).

Право: market:write

Параметр	Тип	Обязателен	Описание
`domain`	`path`	да	Имя домена или id лота.
`price`	`number`	нет	Новая цена в USD.
`category, tags, headline, description`		нет	Как при выставлении.

Пока покупатель оплачивает домен (reserved), лот нельзя ни изменить, ни снять — после окончания брони можно.

Запрос

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"}'

Ответ

200 OK

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

DELETE /market/lots/{domain}

Снять с продажи

Снимает лот с витрины. Повторный вызов безопасен: вернёт уже снятый лот.

Право: market:write

Параметр	Тип	Обязателен	Описание
`domain`	`path`	да	Имя домена или id лота.

Запрос

bash

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

Ответ

200 OK

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

GET /market/sales

История продаж

Завершённые продажи, новые сверху (последние 5000), и итоги по аккаунту.

Право: read

Параметр	Тип	Обязателен	Описание
`page`	`integer`	нет	Номер страницы, с 1.
`per_page`	`integer`	нет	Размер страницы: по умолчанию 50, максимум 100.

stats: sold — продано доменов, revenue — сумма продаж, commission — комиссия площадки, proceeds — зачислено вам на баланс, listed — сейчас в продаже, views — просмотры активных лотов.

Запрос

bash

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

Ответ

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

Поиск по магазину доменов

Публичный поиск лотов — без токена, CORS открыт, можно вызывать прямо из браузера. Лимит — 60 запросов в минуту с одного IP.

Без токена

Параметр	Тип	Обязателен	Описание
`q`	`string`	нет	Часть имени домена.
`tld`	`string`	нет	Зона, например .com.
`theme`	`string`	нет	Тематика — ключ из таблицы ниже.
`len_min, len_max`	`integer`	нет	Длина имени без зоны.
`price_min, price_max`	`number`	нет	Цена в USD.
`no_digits, no_hyphen`	`1`	нет	Без цифр / без дефиса.
`sort`	`string`	нет	new (по умолчанию), price_asc, price_desc, length, popular.
`page, per_page`	`integer`	нет	Страница и её размер: по умолчанию 24, максимум 100.

Запрос

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"

Ответ

200 OK (поля лота сокращены)

{
  "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}
}

Тематики лотов (category, theme)

brand Бренд tech Технологии ai ИИ business Бизнес finance Финансы crypto Крипто ecommerce Магазин creative Творчество social Сообщество health Здоровье education Образование travel Путешествия food Еда realestate Недвижимость fun Хобби и игры

Пример: купить домен и выставить на продажу

Два вызова подряд — так работает связка с HQName: нашли хорошее имя, купили его с баланса и сразу выставили в магазин доменов HQClouds.

bash

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

# 1. Купить домен. Повтор с тем же KEY безопасен — второй раз деньги не спишутся.
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. Ответ 201 — домен ваш, сразу выставляем на продажу.
#    Ответ 202 — ждём, пока GET /domains/$DOMAIN не вернёт 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\"}}"

Только что купленный домен оплачен на год — условие «оплачен ещё минимум на 30 дн.» выполняется сразу.
Для покупки нужен ключ с правом domains:register, для выставления — с правом market:write. Можно один ключ с обоими правами.

Вопросы

Сколько стоит API?

API бесплатно. Домены через API стоят столько же, сколько на сайте, деньги списываются с баланса HQClouds.

Что делать, если запрос на покупку оборвался по таймауту?

Повторите тот же запрос с тем же заголовком Idempotency-Key. Если покупка уже прошла, API вернёт её результат и не спишет деньги второй раз.

Можно ли купить премиум-домен через API?

Нет. Цена премиум-домена может быть в сотни раз выше обычной, поэтому такие домены покупаются только вручную в кабинете.

Как отозвать токен?

В кабинете, в разделе «API»: отзыв действует мгновенно. Создайте новый ключ и замените токен в своей программе.

Готовы начать?

Создайте ключ в кабинете — это бесплатно и займёт минуту.

Получить API-токен Магазин доменов