API PIRS
Те же действия, что в кабинете, из вашего кода: заказ, продление, перезагрузка, список серверов и баланс. JSON на входе и на выходе.
Как начать
- Откройте кабинет, Настройки, раздел «API-ключи», и нажмите «Новый ключ».
- Выберите права: «Только чтение» для мониторинга или «Полный доступ» для заказов и действий с серверами.
- Скопируйте ключ сразу: потом мы покажем только его начало.
Ключ и запросы
Адрес API: https://pirs.host/api/v1. Ключ передаётся в заголовке, тело запросов и ответов в JSON:
curl https://pirs.host/api/v1/account \
-H "Authorization: Bearer pirs_ваш_ключ"
{"id": 42, "email": "you@example.com", "balance": 2500, "currency": "RUB", "units": "rubles", "lang": "ru"}
Храните ключ как пароль. Если он мог попасть к чужим людям, удалите его в кабинете: он перестанет работать сразу.
Деньги
Суммы приходят в единицах вашего аккаунта: в рублях для аккаунта в рублях, в центах для аккаунта в долларах (поле units). Заказ, продление и смена тарифа через API оплачиваются с баланса, а пополнить его можно в кабинете.
Методы
| Метод | Путь | Что делает | Ключ |
|---|---|---|---|
| GET | /account | Аккаунт: баланс и валюта | чтение |
| GET | /plans | Тарифы с ценами по странам и наличием | чтение |
| GET | /servers | Ваши серверы | чтение |
| GET | /servers/{id} | Один сервер | чтение |
| GET | /billing | Баланс и история операций | чтение |
| POST | /servers | Новый сервер, оплата с баланса | полный |
| POST | /servers/{id}/actions | Перезагрузить, выключить, включить, переустановить | полный |
| POST | /servers/{id}/renew | Продлить с баланса | полный |
| PATCH | /servers/{id} | Имя и автопродление | полный |
| DELETE | /servers/{id} | Удалить сервер | полный |
| GET | /servers/{id}/ips | Дополнительные IPv4 сервера, цена и лимит | чтение |
| POST | /servers/{id}/ips | Купить ещё один IPv4, оплата с баланса | полный |
| DELETE | /servers/{id}/ips/{ip} | Снять дополнительный IPv4 | полный |
| GET | /domains | Ваши домены | чтение |
| GET | /domains/{name}/dns | DNS-записи домена | чтение |
| POST | /domains/{name}/dns | Новая запись: A, AAAA, CNAME, TXT, MX, SRV, CAA | полный |
| PUT | /domains/{name}/dns/{id} | Изменить запись | полный |
| DELETE | /domains/{name}/dns/{id} | Удалить запись | полный |
| GET | /domains/{name}/ns | DNS-серверы домена | чтение |
| PUT | /domains/{name}/ns | Свои DNS-серверы, пустой список возвращает наши | полный |
Примеры
Новый сервер
Тариф, срок в месяцах (1, 3 или 12), система, страна и имя. Список тарифов, стран и систем отдаёт GET /plans.
curl -X POST https://pirs.host/api/v1/servers \
-H "Authorization: Bearer $PIRS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"plan": "start", "months": 1, "os": "ubuntu", "region": "pl", "name": "web-1"}'
{"id": "s7k2q9", "name": "web-1", "plan": "start", "status": "create", "ip": "203.0.113.42",
"paid_until": "2026-12-11T10:00:00+00:00", "auto_renew": true, "price": 690, "region": "pl"}
Сервер создаётся пару минут: поле status станет run, когда он готов. Пароль root смотрите в кабинете.
Перезагрузка
curl -X POST https://pirs.host/api/v1/servers/s7k2q9/actions \
-H "Authorization: Bearer $PIRS_TOKEN" -H "Content-Type: application/json" \
-d '{"action": "reboot"}'
Действия: reboot, power_off, power_on и reinstall с полем os (все данные на диске удаляются).
Дополнительный IPv4
curl -X POST https://pirs.host/api/v1/servers/s7k2q9/ips \
-H "Authorization: Bearer $PIRS_TOKEN"
{"ips": ["203.0.113.43"], "price": 199, "max": 4, "allowed": true, "main": "203.0.113.42", "prefix": 32}
Сразу списывается часть цены за уже оплаченные дни сервера, дальше адрес продлевается вместе с ним. Адрес той же страны, что и сервер; на машине его добавляют как /32 рядом с основным.
Свои DNS-серверы для домена
curl -X PUT https://pirs.host/api/v1/domains/example.com/ns \
-H "Authorization: Bearer $PIRS_TOKEN" -H "Content-Type: application/json" \
-d '{"ns": ["clark.ns.cloudflare.com", "karsyn.ns.cloudflare.com"]}'
От 2 до 8 имён. С ними записи живут у того сервиса. Пустой список {"ns": []} возвращает наши, тогда снова работают записи через /domains/{name}/dns.
Python
import os, requests
API = "https://pirs.host/api/v1"
H = {"Authorization": f"Bearer {os.environ['PIRS_TOKEN']}"}
for s in requests.get(f"{API}/servers", headers=H).json()["servers"]:
print(s["name"], s["ip"], s["status"], s["paid_until"])
JavaScript
const api = (path, body) => fetch(`https://pirs.host/api/v1${{path}}`, {{
method: body ? "POST" : "GET",
headers: {{ Authorization: `Bearer ${{process.env.PIRS_TOKEN}}`, "Content-Type": "application/json" }},
body: body && JSON.stringify(body),
}}).then((r) => r.json());
await api("/servers/s7k2q9/renew", {{ months: 3 }});
Ошибки
Ошибка приходит с кодом HTTP и телом {"error": "код"}:
| Код | HTTP | Что значит |
|---|---|---|
auth | 401 | Нет ключа, ключ удалён или неверный |
read_only | 403 | Ключ только для чтения, а метод что-то меняет |
not_found | 404 | Такого сервера нет в вашем аккаунте |
not_enough_balance | 402 | На балансе не хватает денег, пополните его в кабинете |
sold_out | 409 | Этот тариф в этой стране сейчас разобрали |
busy | 409 | Сервер занят другим действием, повторите через минуту |
bad_order | 400 | Неверный тариф, срок или система |
too_many | 429 | Слишком много запросов, подождите минуту |
Лимиты
На один ключ: 240 запросов на чтение и 30 действий в минуту. До 20 ключей в аккаунте. Нужно больше? Напишите в поддержку.