Getting Started With Proxmox HTTP API Commands

Proxmox has 2 API access points that can be used to control your Proxmox server and virtual guests. One of the API access points is using the command line, which you’re likely already familiar with. The other is the HTTP web API which is exposed as part of the WEB GUI on port 8006.

The Proxmox uses a JSON data format for returning data that can easily be parsed programmatically. Every command available to the pvesh command line command are available to the web based API as they share the same endpoint.

The endpoint for the Web API can be called using anything that can send and receive web based requests. We’ll use curl for the below examples. The endpoint to call would be similar to below – be sure you substitute yourip for the IP or hostname of your Proxmox server.

https://yourip:8006/api2/json/

API Authentication

The next step is to authenticate your API requests with the Proxmox server. API authentication uses the same mechanism that logging into the Web GUI uses and requires a username, password and security realm.

Authentication is based on a token method which provides a ticket that must accompany all API requests except for the request that generates the token. A username and password will not be accepted for authentication with all other API requests. In addition, any requests that POST or write to the API endpoint must contain a CSRF Prevention Token.

To obtain an authentication token, run the below curl command and substitute your values as required – this example uses the root user and the default PAM realm.

curl https://yourip:8006/api2/json/access/ticket -k -d 'username=root@pam&password=PASSWORD'

Example output:

{  
  "data":{  
    "CSRFPreventionToken":"5922F2C4:e7n+eQ9Lipbga3bY00Jh79MBATk",
    "username":"root@pam"
    },
    "ticket":"PVE:J38560@AD:5922F2C4::oOAcgXvCcAdLG+B50sRZ9WeaKn3gCFEktnHtegUVEcdtYO0NE7THA7pmzKZ14MgOYrp6vrye4ZBDocpu/nhuvUUL3vZeAT7YMstBXR3YLN8IlwQl5HJdgOikdz+gMdWyfx3JxcNhaNpJlHDL8Vm7D0r7GKGsHPirB098eG7pg1MgrkW7U6R5piW66c/p3kdJvT5beD+IPOhst76SoVlFo3ZxFFcqpcD5RFsUpKl9K1/5tgPReh1sErcDhOgUeiAE5XZHFsTE/jBVeSv9O2cXb5fESRtTU3986Gtw85hPJlWDzMz+X94H0rlL25cYkIbnOx5KJi9IcNTnvTHdpaoXuQ=="
}

The two interesting parts here are the ticket value and the CSRFPreventionToken and should be parsed out for use in later requests.

A token is valid for 2 hours and should be re-requested when it expires. Alternatively each request could generate it’s own token, however this generates added overhead.

List of Proxmox API Requests

pvesh is a command line utility can be used to perform the same actions as the web based API. You can, therefore, use the pvesh command to list all the possible API calls and navigate through the API call tree.

# pvesh
entering PVE shell - type 'help' for help
pve:/> 

pve:/> ls
Dr--- access
Dr--- cluster
Dr--- nodes
Dr-c- pools
Dr-c- storage
-r--- version

pve:/>cd nodes

pve:/nodes>ls
Dr--- prox-node1

You can then list the available commands from the root of the API using ls and then change into one of the child paths using cd. You can navigate throughout the whole API tree using these two methods to see what commands are available for calling. This is often the best way to get started with the Proxmox API.

Examples of API Requests

As stated earlier, all operations available in the Proxmox Web GUI can be performed through the API. Here are a few examples of API requests using Bash:

• Parse authentication ticket value and the CSRFPreventionToken value in Bash
• Start/ Stop LXC Container
• Create new LXC Container
• Destroy LXC Container