Indexed parameters

The Proxmox VE API has parameters that exist once per device: net0, net1, scsi0, scsi1, ipconfig0. The value of each is the configuration string that Proxmox VE expects.

In the generated methods each family is one argument, named with an N at the end, of type Map<Integer, String>: the key is the index. These arguments belong to the methods with about a hundred parameters (createVm, updateVm), so in practice they are sent with a raw call, where the names are those of the API:

import java.util.HashMap;

var parameters = new HashMap<String, Object>();
parameters.put("net0", "model=virtio,bridge=vmbr0,firewall=1");
parameters.put("net1", "model=virtio,bridge=vmbr1,tag=100");

var result = client.set("/nodes/pve01/qemu/100/config", parameters);

With the devices already in a map by index, PveClientBase.addIndexedParameter adds them to the parameters under those names:

import it.corsinvest.proxmoxve.api.PveClientBase;

var networks = new HashMap<Integer, String>();
networks.put(0, "model=virtio,bridge=vmbr0,firewall=1");   // net0
networks.put(1, "model=virtio,bridge=vmbr1,tag=100");      // net1

var parameters = new HashMap<String, Object>();
PveClientBase.addIndexedParameter(parameters, "net", networks);

var result = client.set("/nodes/pve01/qemu/100/config", parameters);

Only the indexes you send change: the calls above leave net2 as it is. The value of an index replaces the whole device: when you change an existing network device keep its macaddr, or Proxmox VE generates a new one. The most used families:

Family	Sent as	For
netN	net0, net1, …	Network devices of VMs and containers
scsiN, virtioN, sataN, ideN	scsi0, virtio0, …	Disks and CD-ROM drives of VMs
ipconfigN	ipconfig0, …	Cloud-init IP configuration of VMs
hostpciN, usbN	hostpci0, usb0, …	Passthrough of host devices
mpN	mp0, mp1, …	Mount points of containers

The format of each value is in the description of the parameter in the API viewer, and in the pages of the Proxmox VE administration guide linked below. The client does not check the string: Proxmox VE does, and a wrong one gives status 400 with the reason in getError().

Network of a VM

model=<model>,bridge=<bridge> followed by options, as described in Network Device.

Option	Meaning	Example
model	Emulated card	virtio, e1000, vmxnet3
bridge	Bridge of the node to attach to	vmbr0
tag	VLAN tag	tag=100
firewall	Apply the Proxmox VE firewall	firewall=1
macaddr	MAC address, generated when left out	macaddr=BC:24:11:00:00:01
rate	Rate limit in MB/s	rate=100
mtu	MTU, virtio only	mtu=9000
queues	Multiqueue, virtio only	queues=4
link_down	Create the device disconnected	link_down=1

Disks of a VM

To create a new disk give the storage and the size in GiB: <storage>:<size>. To attach an existing volume give its id: <storage>:<volume>. Options follow, as described in Hard Disk.

var disks = new HashMap<String, Object>();
disks.put("scsi0", "local-lvm:32,discard=on,iothread=1");      // new 32 GiB disk
disks.put("scsi1", "local-lvm:100,backup=0");                  // new 100 GiB disk, left out of backups
disks.put("ide2", "local:iso/debian-13.1.0-amd64-netinst.iso,media=cdrom");

// POST: allocating a disk runs as a task
var result = client.create("/nodes/pve01/qemu/100/config", disks);

The configuration of a VM has two endpoints: PUT (client.set) applies the change and returns nothing, POST (client.create) returns a task, which is what you need when the change allocates a disk.

Bus	Indexes	Notes
scsiN	0 to 30	The usual choice, with scsihw set to virtio-scsi-single
virtioN	0 to 15	VirtIO block
sataN	0 to 5
ideN	0 to 3	Mostly CD-ROM drives

Option	Meaning	Values
cache	Cache mode	none, writethrough, writeback, directsync, unsafe
discard	Pass TRIM to the storage	on, ignore
iothread	Dedicated I/O thread	0, 1
ssd	Present the disk as SSD	0, 1
backup	Include the disk in backups	0, 1
media	Kind of drive	disk, cdrom

The EFI disk and the TPM state exist only once, so they are plain parameters, efidisk0 and tpmstate0:

var efi = new HashMap<String, Object>();
efi.put("bios", "ovmf");
efi.put("efidisk0", "local-lvm:1,efitype=4m,pre-enrolled-keys=1");

var result = client.create("/nodes/pve01/qemu/100/config", efi);

Cloud-init

ipconfigN configures the network device with the same index: ipconfig0 is for net0. See Cloud-Init Support.

import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

var cloudInit = new HashMap<String, Object>();
cloudInit.put("ciuser", "admin");
cloudInit.put("sshkeys", URLEncoder.encode(publicKey, StandardCharsets.UTF_8).replace("+", "%20"));
cloudInit.put("ipconfig0", "ip=192.168.1.100/24,gw=192.168.1.1");   // static
cloudInit.put("ipconfig1", "ip=dhcp");                              // DHCP

var result = client.set("/nodes/pve01/qemu/100/config", cloudInit);

The API wants sshkeys URL-encoded, with spaces as %20: encode it yourself, as above.

Containers

Containers use the same pattern with their own formats: netN carries name, bridge and addresses, mpN a volume and its path in the container.

var container = new HashMap<String, Object>();
container.put("net0", "name=eth0,bridge=vmbr0,ip=dhcp");
container.put("mp0", "local-lvm:8,mp=/var/lib/data");   // new 8 GiB volume mounted at /var/lib/data

var result = client.set("/nodes/pve01/lxc/200/config", container);

A complete VM, from nothing to started, is in Create a VM.