JSON and JSON Schema

The API use JSON as data format, because it is simple and parse-able by any
web browser.

Additionally, we use JSON Schema [2] to formally describe our API. So
we can automatically generate the whole API Documentation, and we can
verify all parameters and return values.

An great side effect was that we are able to use JSON Schema to
produce command line argument parsers automatically. In fact, the REST
API and the command line tools use the same code. A small utility called 'pvesh'
exposes the whole REST API on the command line.

So here is a summary of the advantage:

easy, human readable data format (native web browser format)

automatic parameter verification (we can also verify return values)

automatic generation of API documentation

easy way to create command line tools (use the same API)

API URL

The API uses the HTTPS protocol and the server listens to port 8006. So the base URL for that API is

It is possible specify the return format in the URL. Above example uses 'json', but you can use any of the following values:

json: JSON

extjs: JSON variant compatible with ExtJS forms

html: html formatted text - sometimes useful for debugging

text: plain text - sometimes useful for debugging

Please contact use on the development mailing list if you need other data formats.

Authentification

PVE uses a Token Based Authentication. All request to the API need to include that token inside a Cookie. We usually call that token a 'ticket'. Additionally, any write request must include a CSRF prevention token inside the HTTP header. The following examples use the 'curl' command line tool.