Домен
API подключает собственный домен к сайту, меняет адрес платформы, показывает статус подключения и освобождает адрес со снятием публикации сайта. Настройка DNS — в гайде «Домен».
| Метод | Путь | Действие |
|---|---|---|
PUT | /data/domain | Подключить домен |
GET | /data/domain | Получить статус подключения |
DELETE | /data/domain | Отключить домен |
Во всех примерах API — https://onpress.pro/api/v2, SITE — id сайта (SITE_ID), OP_TOKEN — токен op_XXXX. Права на всех эндпоинтах страницы — администратор сайта. Как получить токен и в какой форме приходят отказы — Авторизация.
Подключить домен
PUT /data/domain
Подключает собственный домен к сайту или меняет его адрес в зоне onpress.pro (адрес в этой зоне меняет только суперадмин сети). Для собственного домена платформа ведет подключение сама: ждет записи DNS, выпускает сертификат и переводит сайт на домен. Сайт на другом своем домене работает на нем, пока новый не станет active; старый домен после перевода снимается с сервера. Повтор после failed начинает подключение заново. Например, подключить example.com:
curl -s -X PUT "$API/site/$SITE/data/domain" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"domain": "example.com"}'
Адрес платформы выдается сайту при создании, и сменить его может только суперадмин сети — остальным PUT с адресом .onpress.pro отвечает 403 insufficient_role. Суперадмин меняет его тем же запросом: если сайт работает на old-name.onpress.pro, передайте свободный адрес, например:
curl -s -X PUT "$API/site/$SITE/data/domain" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"domain": "new-name.onpress.pro"}'
Платформа меняет адрес сайта и обновляет его публикацию. В items[0] приходят mode: "assign", status: "none", новый site_domain и site_url, а domain равен null. Отдельная настройка DNS для адреса платформы не нужна. Прежний адрес освобождается. Чтобы перевести сайт с собственного домена обратно на адрес платформы, используйте DELETE /data/domain с полем to.
Параметры пути. Сайт задает общий префикс /site/{siteId}; выбор сайта.
Параметры строки запроса
| Параметр | Тип | Обязателен | По умолчанию | Описание |
|---|---|---|---|---|
dry_run | boolean | нет | false | проверить запрос без записи; общие правила |
Параметры тела
| Поле | Тип | Обязателен | По умолчанию | Описание |
|---|---|---|---|---|
domain | string | да | — | собственный домен, например example.com, или свободный адрес <name>.onpress.pro. Для собственного домена схема, путь, порт и www. отбрасываются, кириллица переводится в punycode. Адрес платформы передавайте только именем хоста, без этих частей. Имя перед .onpress.pro — от 1 до 50 строчных латинских букв, цифр и дефисов, без дефиса по краям; вложенные и зарезервированные имена отклоняются |
dry_run | bool | нет | false | проверить подключение собственного домена или смену адреса платформы без записи; можно и ?dry_run=1 |
Для адресов платформы зарезервированы имена www, api, admin, mail, ftp, cdn, static, app, apps, stage, test, dashboard, docs, support, status, storage, assets, base-v2 и onpress.
Ответ
{
"success": true,
"site_id": "FJyyv3Xiv",
"name": "domain",
"origin": "system",
"contextual": false,
"writable": true,
"write": {
"method": "PUT",
"methods": [
"PUT",
"DELETE"
],
"at": "/data/domain",
"forwards_to": "the existing domain connection service of the selected site",
"dry_run": true,
"body": "{\"domain\":\"example.com\",\"dry_run\"?:true} connects an external domain with the existing DNS and certificate lifecycle, or renames the platform address to a free non-reserved <name>.onpress.pro hostname",
"changes": "the custom domain of the selected site; DNS, certificate and switching status are returned in items[0]",
"delete": {
"method": "DELETE",
"dry_run": true,
"body": "without to: release the domain and take the retained site offline; {\"to\":\"mysite.onpress.pro\",\"dry_run\"?:true} keeps the address-change flow"
}
},
"total": 1,
"items": [
{
"status": "pending_dns",
"domain": "example.com",
"site_domain": "mysite.onpress.pro",
"site_url": "https://mysite.onpress.pro",
"server_ip": "31.128.47.177",
"started_at": "2026-10-27T12:03:56+00:00",
"elapsed": 0,
"dns": {
"ok": false,
"records": [
{
"type": "A",
"host": "example.com",
"value": "31.128.47.177",
"found": [],
"ok": false
},
{
"type": "A",
"host": "www.example.com",
"value": "31.128.47.177",
"found": [],
"ok": false
}
],
"problems": []
},
"previous_domain": "mysite.onpress.pro",
"next": "add the DNS records from dns.records at your registrar; …"
}
],
"dry_run": false,
"changed": true,
"applied": true,
"source": "domain"
}
changed: false — домен уже активен, подключение уже идет или адрес платформы совпадает с текущим. При подключении собственного домена applied: true означает старт изменения, а не завершение подключения. Текущее состояние находится в items[0], как у GET /data/domain.
Запись возвращает тот же конверт данных, что и чтение, с полями source, dry_run, changed и applied. При пробном прогоне applied: false, а items[0] содержит план; у плана может не быть status и site_url. Общие правила пробного прогона.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
lang_not_accepted | 400 | у домена нет языковых вариантов | уберите lang из строки запроса и тела |
source_auth_required | 403 | источник вызван без пользователя с правами на сайт | передайте токен администратора сайта |
wrong_method_for_source | 405 | метод не поддерживает источник domain | используйте GET, PUT или DELETE |
invalid_domain | 400 | не имя хоста | передайте домен вида example.com |
invalid_platform_domain | 400 | адрес платформы вложенный, зарезервирован, содержит схему или путь либо имя не подходит по длине и символам | передайте свободный прямой адрес вида my-site.onpress.pro |
insufficient_role | 403 | запрошен адрес .onpress.pro, а вы не суперадмин сети | адрес платформы выдается при создании сайта; подключите собственный домен |
use_domain_disconnect | 409 | сайт работает на собственном домене, а PUT запрашивает адрес платформы | верните сайт через DELETE /data/domain с нужным to |
platform_domain | 400 | собственный домен относится к служебной зоне платформы | выберите собственный домен или прямой адрес .onpress.pro |
unknown_field | 400 | в теле лишнее поле | оставьте domain и dry_run |
site_not_found | 404 | сайта нет или он не ваш | проверьте {id} |
domain_taken | 409 | собственный домен или адрес платформы уже у другого сайта | освободите адрес на другом своем сайте или выберите свободный |
domain_changed_meanwhile | 409 | адрес сайта изменился во время обработки запроса | прочитайте состояние и повторите запрос |
domain_busy | 409 | идет выпуск сертификата или переезд, текущий статус в current_status | повторите через минуту |
main_site_locked | 409 | домен главного сайта платформы не меняется | проверьте параметр из message и повторите запрос |
wrong_realm | 409 | запрос пришел не на рабочий адрес API | повторите на адресе из сообщения |
domain_step_failed | статус шага или 502 | шаг подключения не выполнился; причина — в message | исправьте причину и повторите запрос |
internal_unavailable | 502 | сайт не ответил | повторите запрос |
domain_publisher_missing, domain_storage_failed | 503 | публикация нового адреса или очистка прежнего не завершилась | повторите позже; при повторном отказе передайте код и id сайта в поддержку |
Получить статус подключения
GET /data/domain
Возвращает состояние домена в единственной записи items[0] системных данных domain. При незавершенном подключении чтение запускает проверку, а первое чтение после перевода сбрасывает кэши и пересобирает фреймы; результат приходит один раз в items[0].finished. Например:
curl -s "$API/site/$SITE/data/domain" -H "Authorization: Bearer $OP_TOKEN"
Параметры пути. Сайт задает общий префикс /site/{siteId}; выбор сайта.
Параметры строки запроса. Дополнительных параметров нет.
Тело запроса. Не требуется.
Ответ
{
"success": true,
"site_id": "x9HTLHECq",
"name": "domain",
"origin": "system",
"contextual": false,
"writable": true,
"write": {
"method": "PUT",
"methods": [
"PUT",
"DELETE"
],
"at": "/data/domain",
"forwards_to": "the existing domain connection service of the selected site",
"dry_run": true,
"body": "{\"domain\":\"example.com\",\"dry_run\"?:true} connects an external domain with the existing DNS and certificate lifecycle, or renames the platform address to a free non-reserved <name>.onpress.pro hostname",
"changes": "the custom domain of the selected site; DNS, certificate and switching status are returned in items[0]",
"delete": {
"method": "DELETE",
"dry_run": true,
"body": "without to: release the domain and take the retained site offline; {\"to\":\"mysite.onpress.pro\",\"dry_run\"?:true} keeps the address-change flow"
}
},
"total": 1,
"items": [
{
"status": "none",
"domain": null,
"site_domain": "test.onpress.pro",
"site_url": "https://test.onpress.pro",
"server_ip": "31.128.47.177",
"next": "PUT /data/domain with {\"domain\": \"example.com\"} to connect a domain"
}
]
}
status | Что происходит |
|---|---|
none | сайт работает на адресе платформы, подключения собственного домена нет |
detached | адрес освобожден, публичная публикация снята; данные сайта сохранены |
pending_dns | ждем A-записи example.com и www.example.com на server_ip; проверка через публичные DNS (8.8.8.8, 1.1.1.1, 9.9.9.9) |
issuing_cert | Let’s Encrypt выпускает сертификат на example.com и www.example.com |
switching | сайт переходит на https://example.com |
active | сайт работает на домене; www и http:// ведут на https://example.com |
disconnecting | сайт возвращается на адрес платформы |
failed | остановлено: failed_stage — dns (записи не появились за 24 часа), cert (сертификат не выпущен), switch или disconnect; причина — в error |
| Поле | Описание |
|---|---|
domain | подключаемый или действующий свой домен, иначе null |
site_domain, site_url | где сайт отвечает сейчас; null при detached |
published | false при detached: у сайта нет публичной публикации |
server_ip | адрес для A-записей |
server_ips, cloudflare_ips | массивы строк с адресами сервера и сетями Cloudflare для настройки DNS |
free_domain_eligible, free_domain_claimed | boolean: доступен ли бесплатный домен и был ли он уже получен |
domain_display | исходное написание домена, если оно отличается от punycode |
failed_stage, error | этап и причина сбоя при status: failed |
dns.records[] | что прописать: type, host (полное имя записи), value; found — что отдают публичные DNS сейчас, ok |
dns.problems[] | что помешает сертификату: aaaa_record (IPv6-запись), cloudflare_proxy (включен прокси Cloudflare), extra_a_record (лишний адрес рядом с адресом сервера) |
started_at, elapsed | начало подключения и секунды с него |
previous_domain | прежний адрес платформы; сам по себе не включает возврат при DELETE без to |
finished | adopt, cache, rebake — один раз после перевода |
next | что делать дальше, одной строкой |
dns приходит, пока ждем записи, и после отказа на dns или cert. Вместо A-записи у www можно поставить CNAME на основной домен. Поля состояния перечислены для items[0]. У domain нет языковых вариантов.
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
lang_not_accepted | 400 | у домена нет языковых вариантов | уберите lang из строки запроса и тела |
source_auth_required | 403 | источник вызван без пользователя с правами на сайт | передайте токен администратора сайта |
wrong_method_for_source | 405 | метод не поддерживает источник domain | используйте GET, PUT или DELETE |
site_not_found | 404 | сайта нет или он не ваш | проверьте site_id в GET /sites |
domain_step_failed | 502 или статус шага | проверка или завершение подключения не удались | исправьте причину из message и повторите |
internal_unavailable | 502 | сервис подключения недоступен | повторите позже |
Отключить домен
DELETE /data/domain
Без поля to освобождает текущий адрес сайта и снимает его публичную публикацию. Данные, id сайта и права доступа сохраняются. Применяется и к собственному домену, и к адресу на onpress.pro. Освободившийся домен можно назначить другому своему сайту через PUT /data/domain.
curl -s -X DELETE "$API/site/$SITE/data/domain" -H "Authorization: Bearer $OP_TOKEN"
После освобождения в items[0] приходят mode: "release", status: "detached", domain: null, site_domain: null, site_url: null и published: false. Повторный DELETE возвращает changed: false. GET этого состояния не запускает подключение заново.
Чтобы вместо снятия публикации перевести сайт на конкретный адрес платформы, передайте to:
curl -s -X DELETE "$API/site/$SITE/data/domain" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"to":"mysite.onpress.pro"}'
В этом режиме незавершенное подключение (pending_dns, failed) отменяется с mode: "cancel"; сайт остается на прежнем адресе. Не суперадмину в to доступен только прежний адрес платформы этого сайта, другой отклоняется 403 insufficient_role. Сайт на собственном домене возвращается на выбранный адрес платформы с mode: "move_back", status: "disconnecting", затем none. Домен снимается с сервера; записи DNS у регистратора удаляете вы.
Параметры пути. Сайт задает общий префикс /site/{siteId}; выбор сайта.
Параметры строки запроса
| Параметр | Тип | Обязателен | По умолчанию | Описание |
|---|---|---|---|---|
dry_run | boolean | нет | false | проверить отключение без записи; общие правила |
Параметры тела
| Поле | Тип | Обязателен | По умолчанию | Описание |
|---|---|---|---|---|
to | string | нет | — | свободный прямой адрес <name>.onpress.pro для режима возврата на адрес платформы; правила имени те же, что у PUT. Без to адрес освобождается и публикация снимается |
dry_run | bool | нет | false | показать, что будет, ничего не меняя; можно и ?dry_run=1 |
Ответ
{
"success": true,
"site_id": "FJyyv3Xiv",
"name": "domain",
"origin": "system",
"contextual": false,
"writable": true,
"write": {
"method": "PUT",
"methods": [
"PUT",
"DELETE"
],
"at": "/data/domain",
"forwards_to": "the existing domain connection service of the selected site",
"dry_run": true,
"body": "{\"domain\":\"example.com\",\"dry_run\"?:true} connects an external domain with the existing DNS and certificate lifecycle, or renames the platform address to a free non-reserved <name>.onpress.pro hostname",
"changes": "the custom domain of the selected site; DNS, certificate and switching status are returned in items[0]",
"delete": {
"method": "DELETE",
"dry_run": true,
"body": "without to: release the domain and take the retained site offline; {\"to\":\"mysite.onpress.pro\",\"dry_run\"?:true} keeps the address-change flow"
}
},
"total": 1,
"items": [
{
"mode": "release",
"status": "detached",
"domain": null,
"site_domain": null,
"site_url": null,
"published": false,
"next": "PUT /data/domain with a domain to publish the retained site again"
}
],
"dry_run": false,
"changed": true,
"applied": true,
"source": "domain"
}
Ошибки
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
lang_not_accepted | 400 | у домена нет языковых вариантов | уберите lang из строки запроса и тела |
source_auth_required | 403 | источник вызван без пользователя с правами на сайт | передайте токен администратора сайта |
wrong_method_for_source | 405 | метод не поддерживает источник domain | используйте GET, PUT или DELETE |
invalid_to | 400 | to не адрес в зоне onpress.pro | передайте адрес вида mysite.onpress.pro |
invalid_platform_domain | 400 | to вложенный, зарезервированный или не подходит по правилам адреса платформы | передайте свободный прямой адрес вида my-site.onpress.pro |
unknown_field | 400 | в теле лишнее поле | оставьте to и dry_run |
site_not_found | 404 | сайта нет или он не ваш | проверьте {id} |
domain_taken | 409 | адрес to занят | выберите другой |
domain_busy | 409 | идет подключение домена, переезд или обновление публикации; освобождение адреса пока недоступно | завершите или отмените текущее подключение и повторите запрос |
main_site_locked, wrong_realm | 409 | как у PUT | проверьте параметр из message и повторите запрос |
internal_unavailable | 502 | шаг не выполнился | повторите запрос |
domain_publisher_missing, domain_storage_failed | 503 | снятие публикации или сохранение изменения адреса не завершилось | повторите позже; при повторном отказе передайте код и id сайта в поддержку |