API PIRS
The same actions as in the panel, from your own code: order, renew, reboot, the server list and the balance. JSON in and out.
Getting started
- Open the panel, Settings, the «API keys» section, and press «New key».
- Choose the rights: «Read-only» for monitoring or «Full access» for orders and server actions.
- Copy the key right away: later we only show its beginning.
Key and requests
API address: https://pirs.host/api/v1. The key goes in a header; request and response bodies are JSON:
curl https://pirs.host/api/v1/account \
-H "Authorization: Bearer pirs_your_key"
{"id": 42, "email": "you@example.com", "balance": 2500, "currency": "RUB", "units": "rubles", "lang": "ru"}
Keep the key like a password. If it may have reached other people, delete it in the panel: it stops working at once.
Money
Amounts come in your account's units: rubles for an account in rubles, cents for an account in US dollars (the field units). Orders, renewals and plan changes through the API are paid from the balance; top it up in the panel.
Methods
| Method | Path | What it does | Key |
|---|---|---|---|
| GET | /account | Account: balance and currency | read |
| GET | /plans | Plans with prices by country and stock | read |
| GET | /servers | Your servers | read |
| GET | /servers/{id} | One server | read |
| GET | /billing | Balance and transaction history | read |
| POST | /servers | A new server, paid from the balance | full |
| POST | /servers/{id}/actions | Reboot, power off, power on, reinstall | full |
| POST | /servers/{id}/renew | Renew from the balance | full |
| PATCH | /servers/{id} | Name and auto-renewal | full |
| DELETE | /servers/{id} | Delete the server | full |
| GET | /servers/{id}/ips | Additional IPv4 addresses of the server, price and limit | read |
| POST | /servers/{id}/ips | Buy one more IPv4, paid from the balance | full |
| DELETE | /servers/{id}/ips/{ip} | Remove an additional IPv4 | full |
| GET | /domains | Your domains | read |
| GET | /domains/{name}/dns | DNS records of the domain | read |
| POST | /domains/{name}/dns | New record: A, AAAA, CNAME, TXT, MX, SRV, CAA | full |
| PUT | /domains/{name}/dns/{id} | Change a record | full |
| DELETE | /domains/{name}/dns/{id} | Delete record | full |
| GET | /domains/{name}/ns | DNS servers of the domain | read |
| PUT | /domains/{name}/ns | Own DNS servers, an empty list brings ours back | full |
Examples
New server
Plan, term in months (1, 3 or 12), system, country and name. The list of plans, countries and systems comes from 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"}
A server takes a couple of minutes to create: the field status becomes runwhen it is ready. See the root password in the panel.
Rebooting
curl -X POST https://pirs.host/api/v1/servers/s7k2q9/actions \
-H "Authorization: Bearer $PIRS_TOKEN" -H "Content-Type: application/json" \
-d '{"action": "reboot"}'
Actions: reboot, power_off, power_on and reinstall with the field os (all data on the disk is erased).
Additional 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}
The share of the price for the days the server is already paid for is charged at once, then the address renews with the server. The address is in the same country as the server; on the machine it is added as a /32 next to the main one.
Own DNS servers for a domain
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"]}'
From 2 to 8 names. With them the records live at that service. An empty list {"ns": []} brings ours back, then the records work again through /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 }});
Errors
An error comes with an HTTP code and the body {"error": "code"}:
| Code | HTTP | What it means |
|---|---|---|
auth | 401 | No key, or the key is deleted or wrong |
read_only | 403 | A read-only key, and the method changes something |
not_found | 404 | There is no such server in your account |
not_enough_balance | 402 | Not enough money on the balance; top it up in the panel |
sold_out | 409 | This plan is sold out in this country right now |
busy | 409 | The server is busy with another action; retry in a minute |
bad_order | 400 | Wrong plan, term or system |
too_many | 429 | Too many requests; wait a minute |
Limits
Per key: 240 read requests and 30 actions a minute. Up to 20 keys per account. Need more? Write to support.