Заказать

API PIRS

Те же действия, что в кабинете, из вашего кода: заказ, продление, перезагрузка, список серверов и баланс. JSON на входе и на выходе.

Как начать

  1. Откройте кабинет, Настройки, раздел «API-ключи», и нажмите «Новый ключ».
  2. Выберите права: «Только чтение» для мониторинга или «Полный доступ» для заказов и действий с серверами.
  3. Скопируйте ключ сразу: потом мы покажем только его начало.

Ключ и запросы

Адрес 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}/dnsDNS-записи доменачтение
POST/domains/{name}/dnsНовая запись: A, AAAA, CNAME, TXT, MX, SRV, CAAполный
PUT/domains/{name}/dns/{id}Изменить записьполный
DELETE/domains/{name}/dns/{id}Удалить записьполный
GET/domains/{name}/nsDNS-серверы доменачтение
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Что значит
auth401Нет ключа, ключ удалён или неверный
read_only403Ключ только для чтения, а метод что-то меняет
not_found404Такого сервера нет в вашем аккаунте
not_enough_balance402На балансе не хватает денег, пополните его в кабинете
sold_out409Этот тариф в этой стране сейчас разобрали
busy409Сервер занят другим действием, повторите через минуту
bad_order400Неверный тариф, срок или система
too_many429Слишком много запросов, подождите минуту

Лимиты

На один ключ: 240 запросов на чтение и 30 действий в минуту. До 20 ключей в аккаунте. Нужно больше? Напишите в поддержку.