VPS.org API

REST API Documentation

Operating Systems API

List the operating systems you can install and their versions. Pass a version's uuid as operating_system_version_uuid when you create a server.

Endpoints 2
Base Path /api/v1/operating-systems
GET /api/v1/operating-systems/

List Operating Systems

Returns each operating system with its active versions. The list has no filters.

Required permission: operating-systems:list

Example Request

cURL
Python
JavaScript
curl -X GET "https://admin.vps.org/api/v1/operating-systems/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
import requests

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

response = requests.get(url, headers=headers)
for os_entry in response.json()["results"]:
    for version in os_entry["versions"]:
        print(os_entry["name"], version["name"], version["uuid"])
const response = await fetch('https://admin.vps.org/api/v1/operating-systems/', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});

const data = await response.json();
for (const os of data.results) {
  for (const version of os.versions) {
    console.log(os.name, version.name, version.uuid);
  }
}

Example Response

{
  "count": 6,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Ubuntu",
      "svg_icon": "<svg ...>",
      "versions": [
        {
          "uuid": "2fdead8f-81a2-4a23-9a81-0cf969fe1266",
          "name": "22.04 LTS x64",
          "os_name": "Ubuntu",
          "os_svg_icon": "<svg ...>",
          "is_active": true
        },
        {
          "uuid": "c3418f90-80a0-4e00-a7e1-d0ab1822b941",
          "name": "24.04 LTS x64",
          "os_name": "Ubuntu",
          "os_svg_icon": "<svg ...>",
          "is_active": true
        }
      ]
    }
  ]
}

Shortened: only one operating system is shown and the SVG markup is cut.

Response Fields

Field Type Description
id integer Operating system identifier
name string Distribution name, for example Ubuntu or Debian
svg_icon string Inline SVG markup of the logo (not a URL)
versions array Active versions you can install
versions[].uuid string Use as operating_system_version_uuid when creating a server
versions[].name string Version and architecture, for example 24.04 LTS x64
versions[].os_name, versions[].os_svg_icon string Name and icon of the parent operating system
versions[].is_active boolean Whether the version can be used for new servers

Response Status Codes

200 Successfully retrieved operating systems list
403 Missing or invalid API token, or the token lacks the required permission
GET /api/v1/operating-systems/{id}/

Get an Operating System

Returns one operating system and its active versions, with the fields above.

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

Response Status Codes

200 Success
404 No operating system with that id

Picking a Version

Look versions up by name at runtime instead of hardcoding a uuid, so your integration keeps working when versions are added or retired. Root login details are emailed to the account owner once the server is ready; add an SSH key when creating the server to log in with a key instead.