Order

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

  1. Open the panel, Settings, the «API keys» section, and press «New key».
  2. Choose the rights: «Read-only» for monitoring or «Full access» for orders and server actions.
  3. 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

MethodPathWhat it doesKey
GET/accountAccount: balance and currencyread
GET/plansPlans with prices by country and stockread
GET/serversYour serversread
GET/servers/{id}One serverread
GET/billingBalance and transaction historyread
POST/serversA new server, paid from the balancefull
POST/servers/{id}/actionsReboot, power off, power on, reinstallfull
POST/servers/{id}/renewRenew from the balancefull
PATCH/servers/{id}Name and auto-renewalfull
DELETE/servers/{id}Delete the serverfull
GET/servers/{id}/ipsAdditional IPv4 addresses of the server, price and limitread
POST/servers/{id}/ipsBuy one more IPv4, paid from the balancefull
DELETE/servers/{id}/ips/{ip}Remove an additional IPv4full
GET/domainsYour domainsread
GET/domains/{name}/dnsDNS records of the domainread
POST/domains/{name}/dnsNew record: A, AAAA, CNAME, TXT, MX, SRV, CAAfull
PUT/domains/{name}/dns/{id}Change a recordfull
DELETE/domains/{name}/dns/{id}Delete recordfull
GET/domains/{name}/nsDNS servers of the domainread
PUT/domains/{name}/nsOwn DNS servers, an empty list brings ours backfull

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"}:

CodeHTTPWhat it means
auth401No key, or the key is deleted or wrong
read_only403A read-only key, and the method changes something
not_found404There is no such server in your account
not_enough_balance402Not enough money on the balance; top it up in the panel
sold_out409This plan is sold out in this country right now
busy409The server is busy with another action; retry in a minute
bad_order400Wrong plan, term or system
too_many429Too 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.