Создайте API-токен и выполните первый вызов

Создайте токен с минимально необходимой областью действия

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

Два параметра, которые стоит задать там же: срок действия и ограничение по источнику, привязывающее токен к префиксу, с которого запускается ваша автоматизация. Они оба необязательны. Они оба дёшевы.

Значение показывается один раз, потому что мы храним его хэш, а не сам токен. Потеря означает создание нового.

export Paragon_TOKEN=...

Лучше, чем история команд, на машине, работающей без присмотра:

systemd-creds encrypt token.txt /etc/credstore.encrypted/paragon-token

Первый вызов

curl -s https://paragonvps.com/api/v1/account -H "Authorization: Bearer $Paragon_TOKEN" | jq .

Всё — JSON, всё находится в /api/v1, и каждый ответ содержит заголовок request_id. Укажите его в тикете, и мы найдём нужный вызов за секунды, а не будем спрашивать, во сколько это было.

curl -s https://paragonvps.com/api/v1/instances -H "Authorization: Bearer $Paragon_TOKEN" | jq -r '.[] | .id + " " + .hostname + " " + .site + " " + .state'

Заказ сервера

curl -s -X POST https://paragonvps.com/api/v1/instances -H "Authorization: Bearer $Paragon_TOKEN" -H "Content-Type: application/json" -H "Idempotency-Key: 2026-07-16-edge-01" -d '{"plan":"r-8","site":"AMS-01","image":"debian-13","hostname":"edge-01","ssh_keys":["primary"]}'

Отправьте заголовок Idempotency-Key. Повторный POST без него — вот как получаются два сервера вместо одного намерения; ключ запоминается на двадцать четыре часа и возвращает исходный результат, а не создаёт второй экземпляр. Данные cloud-init user-data передаются в том же теле, в кодировке base64, в поле user_data_b64.

Заказ списывается с баланса, если баланс покрывает первый платёжный период. В противном случае ответ содержит счёт и адрес для оплаты, и экземпляр появляется после оплаты счёта.

Лимиты запросов и ошибки

Шестьсот запросов в минуту на токен. Превышение приводит к коду 429 с заголовком Retry-After, который следует читать, а не заменять фиксированной задержкой в цикле.

Ошибки — это JSON с полями code, человекочитаемым message и request_id. Статус указывает на класс: 400 — вы отправили что-то не то, 401 — токен недействителен или отозван, 403 — у токена нет области, 404 — объект не существует или не ваш, 409 — экземпляр в состоянии, которое не допускает операцию, а 5xx — это наша ошибка.

Пагинация и опрос

Коллекции принимают ?page= и ?per_page= и возвращают заголовок Link. Долгие операции возвращают задание, а не блокируют выполнение; это касается подготовки, миграции и восстановления:

curl -s https://paragonvps.com/api/v1/jobs/<job-id> -H "Authorization: Bearer $Paragon_TOKEN" | jq -r .state

Опрашивайте его каждые несколько секунд или зарегистрируйте вебхук и вовсе прекратите опрос. Вебхуки подписаны; проверяйте подпись, прежде чем реагировать.

Отзыв

Мгновенный, из панели или с помощью другого токена:

curl -s -X DELETE https://paragonvps.com/api/v1/tokens/<token-id> -H "Authorization: Bearer $Paragon_TOKEN"

Текущие запросы завершаются, а следующий получит 401. Если вы подозреваете утечку токена, сначала отзовите его, а потом разбирайтесь. Токен не может изменить вашу почту аккаунта или второй фактор, но он точно может потратить деньги.

Полная документация, все конечные точки и все поля: /docs/api.