API NexorPanel

Всё, что делает интерфейс панели, делается теми же запросами: интерфейс — обычный клиент этого API, и другого пути у него нет. Поэтому здесь не бывает «в панели можно, а через API нельзя».

Основы

Базовый адрес — та же машина, на которой открывается панель:

https://panel.example.com/api/v1

• Тело запроса и ответа — JSON в UTF-8; Content-Type: application/json нужен там, где тело есть.
• Время везде в UTC по RFC 3339: 2026-09-24T08:12:30Z.
• Язык сообщений выбирается заголовком Accept-Language: русский, украинский, белорусский, английский, немецкий или польский.
• Слеш на конце не важен: /api/v1/sites и /api/v1/sites/ — один и тот же адрес, и он отвечает сам, а не перенаправляет (перенаправление после POST у части клиентов теряет тело).
• Версия одна — v1. Внутри неё поля могут добавляться, но не менять смысл; ломающее изменение получит v2.
• GET /healthz отвечает без ключа: {"status":"ok","version":"…"} — удобно проверять, что обновление доехало.

Ключи API

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

Ключ заводится в панели: Настройки → Ключи API (или POST /api/v1/tokens из сессии). Показывается он один раз — панель хранит только его отпечаток SHA-256. Передаётся заголовком:

Authorization: Bearer nxp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• Не в строке запроса: панель его там не ищет, потому что адрес попадает в журнал веб-сервера, в историю команд и в Referer.
• Ключ наследует права своей учётной записи и перечитывает их на каждом запросе. Разжалованный администратор перестаёт быть им и по ключу; ключи заблокированной записи перестают работать.
• Ключ «только для чтения» отвечает на GET, HEAD и OPTIONS, а на остальное — 403 read_only_key. Мониторингу и выгрузке большего не нужно.
• Ключом нельзя завести ключ — 403 key_by_key: иначе утёкший ключ выпускал бы себе следующий быстрее, чем это заметят.
• Смена пароля ключи не отзывает. Если пароль меняют из-за утечки, ключи надо отозвать отдельно.
• Срок — от одного дня до года, 0 — бессрочно. На учётную запись — до 32 ключей (409 too_many_keys).

Тайный вход

У установки может быть своя строка в адресе (NEXOR_ENTRANCE). Тогда все адреса ниже живут не на /api/v1/…, а на /<строка>/api/v1/…, а всё, что приходит мимо, — в том числе и в API — получает пустую 404. Снаружи остаётся только /healthz. Строку сообщает администратор машины: угадать её нельзя, в этом и смысл.

Правила адресов

Поля для создания и изменения — те же, что показывает форма панели: заполните её и посмотрите в инструментах браузера, какой JSON ушёл. Форма и API — одно и то же. Списки для форм (машины, версии PHP, адреса, тарифы) отдают адреса *-options.

Списки

Списки устроены одинаково:

GET /api/v1/sites?limit=25&offset=0&search=example

{"items":[…],"total":42,"limit":25,"offset":0}

limit — не больше 200; большее значение возвращает к умолчанию, а не отказывает. search ищет по имени. Некоторые списки сужаются ещё: ?site=126 — по сайту, ?domain=example.org — по почтовому домену. Ответ клиенту содержит только его объекты.

Отказы

Отказ — это JSON с кодом, сообщением и, если отказ про одно поле, именем поля:

{"code":"invalid_input","message":"Домен должен содержать хотя бы одну точку.","field":"domain"}

Разбирать надо code, а не message. Сообщение написано для человека и меняется вместе с языком; код — нет. Самые частые коды:

Чужой объект и несуществующий отвечают одинаково — 404 not_found: разница в ответах позволила бы пересчитать чужие сайты.

Примеры

Адрес панели и ключ — в переменных:

export NX=https://panel.example.com/api/v1
export KEY=nxp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
curl -sS -H "Authorization: Bearer $KEY" $NX/version

Список сайтов и их размер на диске

curl -sS -H "Authorization: Bearer $KEY" "$NX/sites?limit=200" |
  jq -r '.items[] | "\(.domain)\t\(.usedMb) МБ"'

Место сайта — три числа: usedMb (каталог), databasesMb и backupsMb. -1 значит «ещё не посчитали», а не ноль.

Завести сайт

curl -sS -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"domain":"example.org","serverId":1,"active":true,"quotaMb":-1,
       "phpMode":"php-fpm","ssl":true,"letsEncrypt":true,"forceHttps":true,
       "wwwAlias":true,"backupInterval":"daily","backupCopies":7}' \
  $NX/sites

serverId — машина; номер берут из GET /site-options (servers), там же версии PHP и адреса этой машины. Нуль или отсутствие поля — машина панели; сайт клиента всегда ложится туда.

Поставить сайт на паузу и снять с паузы

curl -sS -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"active":false}' $NX/sites/126/status

Завести клиента с лимитом на сайты

curl -sS -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"username":"lira","password":"correct horse battery","company":"ООО «Лира»",
       "email":"petr@example.org","active":true,
       "limits":{"webDomain":5,"database":5,"cron":10,"ftpUser":5}}' \
  $NX/clients

Сделать копию сайта прямо сейчас

curl -sS -X POST -H "Authorization: Bearer $KEY" $NX/sites/126/backups

Перезапустить службу на машине — действия: start, stop, restart, reload.

curl -sS -X POST -H "Authorization: Bearer $KEY" $NX/servers/1/services/nginx/restart

Посмотреть, чем занято место

curl -sS -H "Authorization: Bearer $KEY" $NX/servers/1/disk |
  jq -r '.parts[] | "\(.key)\t\(.bytes)"'

Проверить, что всё в порядке — для мониторинга хватает ключа только на чтение:

curl -sS -H "Authorization: Bearer $KEY" $NX/attention |
  jq -r '.items[] | select(.level != "ok") | .text'

Скачать файл сайта

curl -sS -H "Authorization: Bearer $KEY" \
  "$NX/sites/126/files/download?path=/web/index.php" -o index.php

Развернуть сайт из репозитория

curl -sS -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"url":"https://github.com/owner/repo","ref":"main","webDir":"public"}' \
  $NX/sites/12/deploy

Машина забирает репозиторий и заменяет им папку сайта целиком — не git pull, который останавливается на первом же местном расхождении и оставляет сайт наполовину обновлённым. Ответ — то, что развернулось: {"commit":"a1b2c3d","ref":"main","webDir":"public"}. webDir — папка, которую отдаёт веб-сервер, считая от папки сайта.

Для приватного репозитория в поле key передаётся закрытый ключ развёртывания, а адрес — ssh; панель его не хранит — он живёт на машине во временном файле на время клонирования. Не принимаются: ext::, file:// и локальные пути, нешифрованные git:// и http://, пароль в ссылке. Подмодули не забираются, каталог .git в папку сайта не попадает. Файлы из .gitignore репозитория остаются на месте; что ещё сохранить — перечисляется в .deployignore в папке сайта на сервере.

Все адреса

Адресов: 219. Пути — от адреса панели. Если не отмечено иное, адрес открыт любой вошедшей роли, а клиент видит только свои объекты.

Вход и своя учётная запись

auth/login и auth/2fa существуют для браузера: они ставят cookie, требуют второй фактор и ограничены по частоте. Скрипту нужен ключ.

Ключи API

Ключом нельзя завести ключ (403 key_by_key). На учётную запись — до 32 ключей.

Главная, поиск и состояние

/healthz доступен и при тайном входе и отвечает версией сборки.

Сайты

Сайт заводится на машине из serverId (номер берут из site-options) и правкой на другую не переезжает: другой serverId отвечает 409 cannot_move. Удаление снимает конфигурацию, но не трогает файлы.

Развёртывание из репозитория

deploy заменяет папку сайта репозиторием целиком. Для приватного репозитория в запросе передаётся закрытый ключ развёртывания; панель его не хранит.

Файлы сайта

Путь не выходит за пределы папки сайта (403 bad_path). Удаление переносит файл в корзину сайта на 30 дней. Большие файлы загружаются по частям.

SSL-сертификаты

Let's Encrypt включается в самом сайте (letsEncrypt); эти адреса — для своего сертификата.

Резервные копии сайтов

Сайт входит в адрес: номер копии сам по себе не говорит, чья она.

Базы данных

temp-login открывает phpMyAdmin получасовой учётной записью, заведённой под один вход; пароли баз панель не хранит.

Доступ SFTP, FTP и WebDAV

FTP-доступы — те же записи, что shell: FTP открывается полем ftp у shell-доступа, а DELETE ftp-users/{id} закрывает только FTP.

Защищённые папки

Задания по расписанию

Почта

Списки сужаются по ?domain=. Транспорты и получатели ретрансляции — только администратору.

Почта в браузере

У почты в браузере свой вход: права доказывает пароль ящика, а держит запечатанное cookie почты, поэтому номера ящика в адресах нет. mail/mailboxes/{id}/webmail открывает ящик из сессии панели.

DNS

Клиенты и тарифы

Раздел «Клиенты» открыт и реселлеру, но только с его собственными клиентами.

Серверы и службы

Действия со службами: start, stop, restart, reload. Терминал выполняет команду на машине только там, где у агента стоит NEXOR_AGENT_CONSOLE=1.

Межсетевой экран и IP-адреса

Копии панели, журналы и обновления

update сообщает, совпадают ли версии панели и агентов на всех машинах и есть ли выпуск новее.