Regional VPS API

Regional VPS servers (such as region iran-1) have their own API: ordering servers, power, reinstalling, resizing, resetting the root password, a browser console and traffic. The arianet vps regional CLI commands are built on it.

• Base URL: https://api.ariaservice.net/vps/v1
• Format: JSON over HTTPS
• Authentication: a personal API token sent as a Bearer token (Authentication)
• OpenAPI 3.1: https://api.ariaservice.net/vps/v1/openapi.json, browsable in the interactive reference

Which API?

VPS servers ordered through /api/v1/servers (the arianet vps commands) are described in the VPS API. This page covers the regional VPS servers, which the panel lists next to the others. Both APIs accept the same token.

Quick start

1. In the panel, at cloud.ariaservice.net/users/api-tokens, create a token with the scopes vps:servers:read and vps:servers:write.
2. Call the API:

export ARIANET_TOKEN="paste-your-token-here"
BASE=https://api.ariaservice.net/vps/v1
AUTH="Authorization: Bearer $ARIANET_TOKEN"

curl -s $BASE/datacenters -H "$AUTH"
curl -s "$BASE/plans?datacenter=thr-1" -H "$AUTH"
curl -s "$BASE/images?datacenter=thr-1" -H "$AUTH"
curl -s -X POST $BASE/servers -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"datacenter":"thr-1","plan_id":4,"image":"ubuntu-24.04","hostname":"web-1","billing_mode":"hourly"}'

An order answers with the server and an action. Without a password a root password is generated and returned only once, in that answer. Follow the operation with GET /actions/{id} until state is success or error.

Authentication and scopes

Scope	Allows
vps:servers:read	datacenters, plans, images, servers, traffic and operations
vps:servers:write	every change: ordering, deleting, power, reinstalling, resizing, passwords and the console

A token without any scope is unrestricted. For a team member the account's IAM policies on VPS servers apply too.

Regions

The Arianet-Region header picks the region; without it the request goes to the default region (today iran-1). An unknown region answers 404 region_not_found. Requests to this region travel over the secure link between regions, so event streams (text/event-stream) are not available there and answer 501 streaming_unsupported; follow operations with GET /actions/{id}.

Resources

Method and path	Purpose
GET /datacenters, GET /plans, GET /images	the region's catalog
GET /servers, POST /servers	list and order servers
GET /servers/{id}, DELETE /servers/{id}	details and deletion (what it cost so far is settled)
POST /servers/{id}/actions/{op}	start, stop (graceful), restart, kill (hard power-off)
POST /servers/{id}/reinstall	reinstall from an image ({"image":"..."}); the disk is wiped
POST /servers/{id}/resize	move to another plan ({"plan_id":5}); disks only grow
POST /servers/{id}/reset-password	set the root password
POST /servers/{id}/console	a one-time browser console URL
GET /servers/{id}/traffic	traffic and the period's quota (from, to, granularity)
PUT /servers/{id}/traffic-settings	turn overage billing on or off ({"overage_billing": true}); off means overage is never billed and the network is cut once the period's quota is used up, until the next period. Team members need the vps:manage IAM permission
GET /servers/{id}/actions, GET /actions, GET /actions/{id}	asynchronous operations

Errors

Errors are JSON, {"error": "...", "code": "..."}.

HTTP	code
400	invalid_input, invalid_region
401	unauthorized
402	insufficient balance
403	forbidden, insufficient_scope
404	not_found, region_not_found
409	the server's state does not allow it now
429	rate_limit_exceeded
501	streaming_unsupported
503	vps_unavailable, region_unavailable
504	gateway_timeout: the region did not answer in time; the request may still have been applied, check before retrying