Servers API

GET /api/v1/servers/

List All Servers

Returns the servers in your account, newest first, 25 per page. Servers that are being deleted are not included.

Required permission: servers:list

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number, starting at 1
`page_size`	integer	No	Results per page (default 25, maximum 100)

Example Request

cURL

Python

JavaScript

PHP

curl -X GET "https://admin.vps.org/api/v1/servers/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

import requests

url = "https://admin.vps.org/api/v1/servers/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers)
for server in response.json()["results"]:
    print(server["uuid"], server["hostname"], server["status"])

const response = await fetch('https://admin.vps.org/api/v1/servers/', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});

const data = await response.json();
console.log(data.results);

$ch = curl_init('https://admin.vps.org/api/v1/servers/');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer YOUR_API_TOKEN']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

foreach ($data['results'] as $server) {
    echo $server['hostname'] . ' ' . $server['status'] . "\n";
}

Example Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b",
      "hostname": "web-01",
      "status": "on",
      "error_description": null,
      "location_name": "New Jersey",
      "plan_name": "1 vCPU / 2 GB RAM / 10 GB",
      "os_name": "Ubuntu",
      "ipv4_addresses": ["203.0.113.10"],
      "ipv6_addresses": ["2001:db8:2:dd::f9:6b"],
      "created_at": "2026-07-30T03:54:14.914364Z",
      "deployed": true
    },
    {
      "uuid": "2d7e9b40-6c1a-4f3e-8b5d-9a0c1e2f3b4d",
      "hostname": "db-01",
      "status": "queue",
      "error_description": null,
      "location_name": "New Jersey",
      "os_name": "Debian",
      "ipv4_addresses": [],
      "ipv6_addresses": [],
      "created_at": "2026-09-14T19:33:49.426508Z",
      "deployed": false
    }
  ]
}

Response Fields

Field	Type	Description
`uuid`	string	Server identifier used in every other server endpoint
`hostname`	string	Hostname you chose when creating the server
`status`	string	Current state. See Server Status Values below.
`error_description`	string \| null	Details of the last failure when status is error, otherwise null
`location_name`	string	Name of the location the server runs in
`os_name`	string	Operating system name, without the version
`plan_name`	string	Readable plan summary, for example 1 vCPU / 2 GB RAM / 10 GB
`ipv4_addresses`	array	IPv4 addresses as strings. Empty until the server is deployed, and on plans without IPv4.
`ipv6_addresses`	array	IPv6 addresses as strings. Empty until the server is deployed.
`created_at`	datetime	Creation time (ISO 8601, UTC)
`deployed`	boolean	True once provisioning has finished

Response Status Codes

200	Successfully retrieved server list
403	Missing or invalid API token, or the token lacks the required permission

POST /api/v1/servers/

Create New Server

Queues a new server for deployment and returns it immediately with status queue. Provisioning continues in the background: poll the status endpoint until deployed is true. When the server is ready, its login details are emailed to the account owner.

Your account needs a saved payment method. Depending on your account history, a temporary pre-authorization hold of about one week of the plan price (at least 1 USD) may be placed on your card before the server is created.

Required permission: servers:create

Request Body Parameters

Parameter	Type	Required	Description
`hostname`	string	Yes	At least 3 characters. Letters, digits, hyphens and periods only.
`location_id`	integer	Yes	The id of an active location from the Locations API
`plan_uuid`	string	Yes	The uuid of an active plan from the Plans API
`operating_system_version_uuid`	string	Yes	The uuid of an active entry in an operating system's versions list
`ssh_key_uuids`	array	No	UUIDs of SSH keys from the SSH Keys API to install on the server
`ssh_key_ids`	array	No	Integer ids of SSH keys, as an alternative to ssh_key_uuids. If both are sent, ssh_key_ids is used.
`ssh_key_uuid`, `ssh_key_id`	string, integer	No	Shorthand for a single SSH key
`auth_method`	string	No	password, ssh_key or both. Defaults to password, or to both when SSH keys are supplied.

Example Request

cURL

Python

JavaScript

PHP

curl -X POST "https://admin.vps.org/api/v1/servers/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "web-01",
    "location_id": 1,
    "plan_uuid": "3bc2faf6-8f8b-4978-b62d-b52ed3f858e9",
    "operating_system_version_uuid": "c3418f90-80a0-4e00-a7e1-d0ab1822b941",
    "ssh_key_uuids": ["YOUR_SSH_KEY_UUID"]
  }'

import requests

url = "https://admin.vps.org/api/v1/servers/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
data = {
    "hostname": "web-01",
    "location_id": 1,
    "plan_uuid": "3bc2faf6-8f8b-4978-b62d-b52ed3f858e9",
    "operating_system_version_uuid": "c3418f90-80a0-4e00-a7e1-d0ab1822b941",
    "ssh_key_uuids": ["YOUR_SSH_KEY_UUID"],
}

response = requests.post(url, headers=headers, json=data)
server = response.json()
print(response.status_code, server["uuid"], server["status"])

const response = await fetch('https://admin.vps.org/api/v1/servers/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    hostname: 'web-01',
    location_id: 1,
    plan_uuid: '3bc2faf6-8f8b-4978-b62d-b52ed3f858e9',
    operating_system_version_uuid: 'c3418f90-80a0-4e00-a7e1-d0ab1822b941',
    ssh_key_uuids: ['YOUR_SSH_KEY_UUID']
  })
});

const server = await response.json();
console.log(server.uuid, server.status);

$data = [
    'hostname' => 'web-01',
    'location_id' => 1,
    'plan_uuid' => '3bc2faf6-8f8b-4978-b62d-b52ed3f858e9',
    'operating_system_version_uuid' => 'c3418f90-80a0-4e00-a7e1-d0ab1822b941',
    'ssh_key_uuids' => ['YOUR_SSH_KEY_UUID']
];

$ch = curl_init('https://admin.vps.org/api/v1/servers/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_TOKEN',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$server = json_decode(curl_exec($ch), true);
curl_close($ch);

Example Response

201 Created with the full server object described under Get Server Details. Addresses and vmid are filled in once deployment finishes.

{
  "uuid": "5f0c8e2a-6b1d-4c3e-9a7f-2d4b6c8e0a1f",
  "hostname": "web-01",
  "vmid": null,
  "status": "queue",
  "error_description": null,
  "location": {
    "id": 1,
    "name": "New Jersey",
    "country_name": "United States",
    "is_active": true
  },
  "plan": {
    "uuid": "3bc2faf6-8f8b-4978-b62d-b52ed3f858e9",
    "cpu": 1,
    "ram": 2,
    "ram_unit": "GB",
    "disk_space": 10,
    "disk_space_total": 10240,
    "transfer": 500,
    "price": "3.50",
    "cpu_type_name": "Shared",
    "is_active": true,
    "hourly_price": "0.005",
    "monthly_price": "3.50",
    "is_gpu": false,
    "gpu_count": 0,
    "gpu_model": ""
  },
  "operating_system": {
    "id": 1,
    "name": "Ubuntu",
    "svg_icon": "<svg ...>",
    "versions": [ ... ]
  },
  "operating_system_version": {
    "uuid": "c3418f90-80a0-4e00-a7e1-d0ab1822b941",
    "name": "24.04 LTS x64",
    "os_name": "Ubuntu",
    "os_svg_icon": "<svg ...>",
    "is_active": true
  },
  "ipv4_addresses": [],
  "ipv6_addresses": [],
  "deployed": false,
  "created_at": "2026-09-14T21:02:11.402113Z",
  "recent_actions": []
}

Response Status Codes

201	Server created and queued for deployment
400	Validation error, for example an inactive location, plan or operating system version
402	No payment method on file, unpaid invoices, or the card pre-authorization was declined
403	Missing or invalid API token, or the token lacks the required permission
429	Your account has reached its server creation limit

GET /api/v1/servers/{uuid}/

Get Server Details

Returns one server with its location, plan, operating system, IP addresses and the five most recent actions.

Required permission: servers:list

curl -X GET "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "uuid": "8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b",
  "hostname": "web-01",
  "vmid": 1042,
  "status": "on",
  "error_description": null,
  "location": {
    "id": 1,
    "name": "New Jersey",
    "country_name": "United States",
    "is_active": true
  },
  "plan": {
    "uuid": "14186969-fbaf-43e1-9ab2-b1f1aeb66674",
    "cpu": 1,
    "ram": 2,
    "ram_unit": "GB",
    "disk_space": 25,
    "disk_space_total": 25600,
    "transfer": 1,
    "price": "5.00",
    "cpu_type_name": "Shared",
    "is_active": true,
    "hourly_price": "0.007",
    "monthly_price": "5.00",
    "is_gpu": false,
    "gpu_count": 0,
    "gpu_model": ""
  },
  "operating_system": {
    "id": 1,
    "name": "Ubuntu",
    "svg_icon": "<svg ...>",
    "versions": [ ... ]
  },
  "operating_system_version": {
    "uuid": "c3418f90-80a0-4e00-a7e1-d0ab1822b941",
    "name": "24.04 LTS x64",
    "os_name": "Ubuntu",
    "os_svg_icon": "<svg ...>",
    "is_active": true
  },
  "ipv4_addresses": [
    {
      "ip": "203.0.113.10",
      "gateway": "203.0.113.1",
      "subnet": "203.0.113.0",
      "rdns": "web-01.example.com"
    }
  ],
  "ipv6_addresses": [
    {
      "ip": "2001:db8:2:dd::f9:6b",
      "gateway": "2001:db8:2:dd::f9:1",
      "subnet": "2001:db8:2:dd::f9:0",
      "rdns": "web-01.example.com"
    }
  ],
  "deployed": true,
  "created_at": "2026-07-30T03:54:14.914364Z",
  "recent_actions": [
    {
      "id": 17028,
      "action": "create",
      "action_display": "Create",
      "description": "Server deployed with VMID 1042",
      "user_email": "you@example.com",
      "created_at": "2026-07-30T03:54:32.860854Z"
    }
  ]
}

SVG icon markup and the versions list are shortened here.

Response Fields

Field	Type	Description
`vmid`	integer \| null	Virtual machine number, set during deployment
`location`	object	Location object, as returned by the Locations API
`plan`	object	Plan object, as returned by the Plans API
`operating_system`, `operating_system_version`	object	Operating system and the installed version, as returned by the Operating Systems API
`ipv4_addresses`, `ipv6_addresses`	array	One object per address with ip, gateway, subnet and rdns (the reverse DNS hostname)
`recent_actions`	array	Up to five latest actions: id, action, action_display, description, user_email, created_at

Response Status Codes

200	Successfully retrieved server details
404	Not found, or it belongs to another account

GET /api/v1/servers/{uuid}/status/

Get Server Status

A lightweight call for polling after you create, power or resize a server.

curl -X GET "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/status/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "status": "on",
  "deployed": true,
  "resizing": false
}

Server Status Values

Value	Description
`queue`	An action (deploy, power, resize, restore) is queued or in progress
`deploying`	Being provisioned. Servers created from the control panel use this state; servers created through the API stay in queue until they are ready.
`on`	Running
`off`	Powered off
`error`	The last action failed. See error_description.
`suspended_payment`	Suspended because of unpaid invoices

POST /api/v1/servers/{uuid}/power/

Control Server Power

Queues a power action. The server status changes to queue until the action completes.

Required permission: servers:power

Request Body Parameters

Parameter	Type	Required	Description
`action`	string	Yes	`start`: power on `shutdown`: graceful shutdown, forced off if the guest does not stop `restart`: hard power cycle (stop, then start) `stop`: currently performs the same power cycle as restart. Use shutdown to leave a server off.

Example Request

cURL

Python

curl -X POST "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/power/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "restart"}'

import requests

server_uuid = "8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b"
url = f"https://admin.vps.org/api/v1/servers/{server_uuid}/power/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.post(url, headers=headers, json={"action": "restart"})
print(response.json())

Example Response

{
  "message": "Server restart queued"
}

Response Status Codes

200	The action was queued
400	Missing or unsupported action
402	start refused because the account has unpaid invoices
404	Not found, or it belongs to another account

POST /api/v1/servers/{uuid}/resize/

Resize a Server

Moves the server to another active plan. The new plan cannot have less disk space than the current one, and the request body must include action set to resize. Hypervisor capacity for the new plan is checked before anything is queued, so a refused request leaves the server unchanged.

The server is shut down while it is resized and started again afterwards. If the resize fails, the server is put back on its previous plan and started again if it was running. Disk growth cannot be undone.

Required permission: servers:resize

Request Body Parameters

Parameter	Type	Required	Description
`action`	string	Yes	Must be resize
`new_plan_uuid`	string	Yes	The uuid of the plan to move to

curl -X POST "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/resize/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "resize", "new_plan_uuid": "5e26a4a6-bd0c-467c-abca-da036c811c3f"}'

{
  "message": "Resize queued successfully"
}

Example of a refused resize (409):

{
  "error": "Not enough hypervisor capacity for the selected plan; the server was not changed"
}

Response Status Codes

200	The action was queued
400	Missing action or new_plan_uuid, invalid or inactive plan, a plan with less disk space, or a GPU plan (GPU plans cannot be resized through the API)
404	Not found, or it belongs to another account
409	A resize or storage change is already in progress, or there is not enough hypervisor capacity for the new plan
503	Capacity could not be checked right now. The server was not changed; retry later.

POST /api/v1/servers/{uuid}/reset-password/

Reset Root Password

Generates a new root password, returns it in the response and queues the change on the server. The new password is also emailed to you. The server must be deployed. No request body is needed.

curl -X POST "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/reset-password/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "message": "Password reset queued. New password will also be emailed to you.",
  "password": "generated-password",
  "job_id": "b6f1c7e2-3a4d-4f5e-8b9c-0d1e2f3a4b5c"
}

Response Status Codes

200	The action was queued
400	The server is not deployed yet
404	Not found, or it belongs to another account

GET POST /api/v1/servers/{uuid}/rdns/

Reverse DNS (PTR)

GET lists the reverse DNS hostname of every IPv4 and IPv6 address on the server. POST sets it for one address. Sending an empty hostname resets the address to its default reverse DNS name.

Required permission: servers:update

Request Body Parameters (POST)

Parameter	Type	Required	Description
`ip`	string	Yes	An IPv4 or IPv6 address assigned to this server
`hostname`	string	No	The PTR hostname. Leave empty to reset to the default.

curl -X POST "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/rdns/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ip": "203.0.113.10", "hostname": "mail.example.com"}'

{
  "message": "Reverse DNS for 203.0.113.10 set to mail.example.com",
  "ip": "203.0.113.10",
  "hostname": "mail.example.com"
}

GET response:

{
  "rdns": [
    {"ip": "203.0.113.10", "hostname": "mail.example.com"},
    {"ip": "2001:db8:2:dd::f9:6b", "hostname": "mail.example.com"}
  ]
}

Response Status Codes

400	ip missing, or the hostname could not be set
404	The IP address is not assigned to this server

POST /api/v1/servers/{uuid}/exec/

Run a Command on a Server

Runs a shell command inside the server through the QEMU guest agent and waits for it to finish. The server must be deployed and running, and qemu-guest-agent must be installed and running in the guest.

Required permission: servers:exec

Request Body Parameters

Parameter	Type	Required	Description
`command`	string	Yes	Command line run with /bin/sh -c, up to 2000 characters
`timeout`	integer	No	Seconds to wait for the command, 1 to 300 (default 30)

curl -X POST "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/exec/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command": "uptime", "timeout": 30}'

{
  "stdout": " 21:14:03 up 46 days,  2:10,  0 users,  load average: 0.08, 0.03, 0.01\n",
  "stderr": "",
  "exit_code": 0,
  "timed_out": false
}

If the command is still running when the timeout expires, the response has timed_out set to true and exit_code set to null.

Response Status Codes

200	Command finished or timed out
400	Server not deployed or not running, or invalid parameters
409	The QEMU guest agent is not running on the server
503	Temporary connection problem. Retry after the Retry-After header.

DELETE /api/v1/servers/{uuid}/

Delete Server

Queues the server for permanent deletion. The server disappears from the list immediately and cannot be recovered.

Required permission: servers:delete

curl -X DELETE "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "message": "Server deletion queued"
}

Response Status Codes

202	Accepted: the request was queued
404	Not found, or it belongs to another account

GET POST /api/v1/ssh-keys/

SSH Keys

Store public SSH keys in your account, then pass their uuids as ssh_key_uuids when you create a server. GET lists your keys (25 per page); POST adds one.

Required permission: ssh-keys:list (GET), ssh-keys:create (POST)

Request Body Parameters (POST)

Parameter	Type	Required	Description
`name`	string	Yes	A name to recognise the key by, up to 100 characters
`public_key`	string	Yes	The public key in OpenSSH format, for example the contents of id_ed25519.pub

Example Request

cURL

Python

curl -X POST "https://admin.vps.org/api/v1/ssh-keys/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "laptop", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... you@laptop"}'

import requests

url = "https://admin.vps.org/api/v1/ssh-keys/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

with open("/home/you/.ssh/id_ed25519.pub") as f:
    data = {"name": "laptop", "public_key": f.read().strip()}

response = requests.post(url, headers=headers, json=data)
print(response.status_code, response.json()["uuid"])

Example Response

{
  "id": 19,
  "uuid": "6e1b9c52-3f8a-4d7e-a2c4-5b9d0e1f2a3c",
  "name": "laptop",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... you@laptop",
  "fingerprint": "0b:4c:9b:48:76:e7:1d:07:b9:ac:71:90:70:f7:9a:69",
  "created_at": "2026-08-23T19:16:11.547183Z",
  "last_used_at": null
}

Response Fields

Field	Type	Description
`id`, `uuid`	integer, string	Key identifiers. Use uuid in ssh_key_uuids and in the URL below; id works in ssh_key_ids.
`fingerprint`	string	MD5 fingerprint of the key, computed by the platform
`last_used_at`	datetime \| null	When the key was last installed on a new server

Response Status Codes

201	Key added
400	Missing name, or the public key is not a valid SSH public key

GET DELETE /api/v1/ssh-keys/{uuid}/

Get or Delete an SSH Key

GET returns one key with the fields above. DELETE removes it from your account and returns 204 with no body. Deleting a key does not remove it from servers it was already installed on. Keys cannot be edited: delete and add again.

Required permission: ssh-keys:list (GET), ssh-keys:delete (DELETE)

curl -X DELETE "https://admin.vps.org/api/v1/ssh-keys/6e1b9c52-3f8a-4d7e-a2c4-5b9d0e1f2a3c/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Backups and Snapshots

Creating a backup or a snapshot is also a server action:

POST /api/v1/servers/{uuid}/backup/: Backups API
POST /api/v1/servers/{uuid}/snapshot/: Snapshots API

VPS.org API

List All Servers

Query Parameters

Example Request

Example Response

Response Fields

Response Status Codes

Create New Server

Request Body Parameters

Example Request

Example Response

Response Status Codes

Get Server Details

Example Response

Response Fields

Response Status Codes

Get Server Status

Server Status Values

Control Server Power

Request Body Parameters

Example Request

Example Response

Response Status Codes

Resize a Server

Request Body Parameters

Response Status Codes

Reset Root Password

Response Status Codes

Reverse DNS (PTR)

Request Body Parameters (POST)

Response Status Codes

Run a Command on a Server

Request Body Parameters

Response Status Codes

Delete Server

Response Status Codes

SSH Keys

Request Body Parameters (POST)

Example Request

Example Response

Response Fields

Response Status Codes

Get or Delete an SSH Key

Backups and Snapshots