Домены
Свой домен подключается одним адресом /sites/{id}/custom-domain: POST начинает подключение, GET показывает статус и DNS-записи и заодно продвигает подключение, DELETE отменяет его или возвращает сайт на адрес платформы. Дальше платформа ведёт подключение сама: ждёт записей DNS, выпускает сертификат и переводит сайт на домен. Эндпоинты пишутся без префикса /site/$SITE: сайт задаёт {id} в пути, как у всех эндпоинтов сайтов. По шагам с записями у регистратора — Домены.
Во всех примерах API — https://onpress.pro/api/v2, SITE — id сайта (SITE_ID), OP_TOKEN — токен op_XXXX. Как получить токен и в какой форме приходят отказы — на странице «Доступ и токен».
POST /sites/{id}/custom-domain
Начинает подключение своего домена к сайту. Дальше платформа ведёт подключение сама: ждёт записи DNS, выпускает сертификат и переводит сайт на домен. Сайт на другом своём домене работает на нём, пока новый не станет active; старый домен после перевода снимается с сервера. Повтор после failed начинает подключение заново. Например, подключить example.com:
curl -s -X POST "$API/sites/$SITE/custom-domain" \
-H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
-d '{"domain": "example.com"}'| Поле | Тип | По умолчанию | Описание |
|---|---|---|---|
domain | string | — | домен, например example.com или shop.example.com; схема, путь, порт и www. в начале отбрасываются, кириллический домен переводится в punycode |
dry_run | bool | false | проверить домен и показать записи DNS, ничего не меняя; можно и ?dry_run=1 |
{ "success": true, "site_id": "FJyyv3Xiv", "changed": true, "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; …" }changed: false — этот домен уже active или уже ждёт DNS, тогда проверка просто запускается заново. Поля ответа — как у GET /sites/{id}/custom-domain.
| Код | Статус | Когда | Что делать |
|---|---|---|---|
invalid_domain | 400 | не имя хоста | передайте домен вида example.com |
platform_domain | 400 | домен в зоне onpress.pro | подключайте только свой домен |
unknown_field | 400 | в теле лишнее поле | оставьте domain и dry_run |
site_not_found | 404 | сайта нет или он не ваш | проверьте {id} |
domain_taken | 409 | домен уже у другого сайта | снимите его там или выберите другой |
domain_busy | 409 | идёт выпуск сертификата или переезд, текущий статус в current_status | повторите через минуту |
main_site_locked | 409 | домен главного сайта платформы не меняется | — |
wrong_realm | 409 | запрос пришёл не в тот контур | повторите на адресе из сообщения |
domain_step_failed, internal_unavailable | 502 | шаг подключения не выполнился | повторите запрос |
GET /sites/{id}/custom-domain
Отдаёт статус подключения. Каждое чтение заодно продвигает подключение, не дожидаясь плановой проверки раз в пять минут, а первое чтение после перевода доводит сайт: сбрасывает кэши и пересобирает фреймы; что сделано — один раз в поле finished. Например:
curl -s "$API/sites/$SITE/custom-domain" -H "Authorization: Bearer $OP_TOKEN"{ "success": true, "site_id": "x9HTLHECq", "status": "none", "domain": null, "site_domain": "test.onpress.pro", "site_url": "https://test.onpress.pro", "server_ip": "31.128.47.177", "next": "POST /sites/{id}/custom-domain with {\"domain\": \"example.com\"} to connect a domain" }status | Что происходит |
|---|---|
none | своего домена и подключения нет |
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 | где сайт отвечает сейчас |
server_ip | адрес для A-записей |
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 |
finished | adopt, cache, rebake — один раз после перевода |
next | что делать дальше, одной строкой |
dns приходит, пока ждём записи, и после отказа на dns или cert. Вместо A-записи у www можно поставить CNAME на основной домен. Отказ — 404 site_not_found, если сайта нет или он не ваш.
DELETE /sites/{id}/custom-domain
Отменяет подключение или возвращает сайт на адрес платформы. Незавершённое подключение (pending_dns, failed) отменяется: сайт остаётся на прежнем адресе, а настройки сервера и сертификат домена, если успели появиться, удаляются — mode: "cancel", cleanup.result: removed, nothing или denied. Сайт на своём домене возвращается на адрес платформы — mode: "move_back", status: "disconnecting", затем none; домен снимается с сервера, записи DNS у регистратора удаляете вы. Без подключения — changed: false. Например:
curl -s -X DELETE "$API/sites/$SITE/custom-domain" -H "Authorization: Bearer $OP_TOKEN"| Поле | Тип | По умолчанию | Описание |
|---|---|---|---|
to | string | previous_domain | адрес платформы, на который вернуть сайт, например mysite.onpress.pro; только зона onpress.pro и только свободный адрес |
dry_run | bool | false | показать, что будет, ничего не меняя; можно и ?dry_run=1 |
{ "success": true, "site_id": "FJyyv3Xiv", "changed": true, "mode": "move_back", "to": "mysite.onpress.pro", "status": "disconnecting", "domain": "example.com", "site_domain": "example.com", "site_url": "https://example.com", "server_ip": "31.128.47.177", "previous_domain": "mysite.onpress.pro", "next": "the site is moving back to the platform address; check again in a minute" }| Код | Статус | Когда | Что делать |
|---|---|---|---|
invalid_to | 400 | to не адрес в зоне onpress.pro | передайте адрес вида mysite.onpress.pro |
fallback_required | 400 | нет previous_domain | передайте to |
unknown_field | 400 | в теле лишнее поле | оставьте to и dry_run |
site_not_found | 404 | сайта нет или он не ваш | проверьте {id} |
domain_taken | 409 | адрес to занят | выберите другой |
domain_busy | 409 | идёт выпуск сертификата или переезд (current_status) | повторите через минуту |
main_site_locked, wrong_realm | 409 | как у POST | — |
internal_unavailable | 502 | шаг не выполнился | повторите запрос |