GET
/api/application/serversFetching servers
Query parameters
pageinteger- The page to return.
per_pageinteger- Results per page. Defaults to
50; the most is100. filter[name]string- Servers whose name contains this text, ignoring case.
filter[node_id]integer- Servers on the node with this ID.
filter[user_id]integer- Servers owned by the user with this ID.
Request
GET
/api/application/serverscurl "https://panel.example.com/api/application/servers" \ -H "Authorization: Bearer <token>" \ -H "Accept: application/json"
use Illuminate\Support\Facades\Http; $response = Http::withToken($token) ->acceptJson() ->get('https://panel.example.com/api/application/servers');
const response = await fetch('https://panel.example.com/api/application/servers', { headers: { Authorization: `Bearer ${token}`, Accept: 'application/json', }, })
Response
{ "data": [ { "id": "ffa92c56", "uuid": "ffa92c56-42e3-4dd4-9999-698008d8c8c9", "node_id": 4418, "hostname": "langosh.info", "name": "culpa", "description": null, "status": null, "usages": { "bandwidth": 0 }, "limits": { "cpu": 2, "memory": 2147483648, "disk": 21474836480, "snapshots": 16, "backups": 16, "bandwidth": 107374182400, "addresses": { "ipv4": [], "ipv6": [] }, "mac_address": null }, "user_id": 10, "vmid": 1631, "internal_id": 30 }, { "id": "01b8d6e4", "uuid": "01b8d6e4-0dd2-4050-a134-aead28cea52e", "node_id": 4419, "hostname": "rolfson.com", "name": "tempora", "description": null, "status": null, "usages": { "bandwidth": 0 }, "limits": { "cpu": 2, "memory": 2147483648, "disk": 21474836480, "snapshots": 16, "backups": 16, "bandwidth": 107374182400, "addresses": { "ipv4": [], "ipv6": [] }, "mac_address": null }, "user_id": 11, "vmid": 702, "internal_id": 32 } ], "meta": { "pagination": { "total": 302, "count": 50, "per_page": 50, "current_page": 1, "total_pages": 7, "links": { "next": "https://advinservers.com/api/admin/servers?page=2" } } } }
GET
/api/application/servers/<uuid>Fetching a server
Request
GET
/api/application/servers/<uuid>curl "https://panel.example.com/api/application/servers/<uuid>" \ -H "Authorization: Bearer <token>" \ -H "Accept: application/json"
use Illuminate\Support\Facades\Http; $response = Http::withToken($token) ->acceptJson() ->get('https://panel.example.com/api/application/servers/<uuid>');
const response = await fetch('https://panel.example.com/api/application/servers/<uuid>', { headers: { Authorization: `Bearer ${token}`, Accept: 'application/json', }, })
Response
{ "data": { "id": "ffa92c56", "uuid": "ffa92c56-42e3-4dd4-9999-698008d8c8c9", "node_id": 4418, "hostname": "langosh.info", "name": "culpa", "description": null, "status": null, "usages": { "bandwidth": 0 }, "limits": { "cpu": 2, "memory": 2147483648, "disk": 21474836480, "snapshots": 16, "backups": 16, "bandwidth": 107374182400, "addresses": { "ipv4": [], "ipv6": [] }, "mac_address": null }, "user_id": 10, "vmid": 1631, "internal_id": 30 } }
PATCH
/api/application/servers/<uuid>Updating a server's general information
Body parameters
namestring- The server's name. Up to 40 characters.
hostnamestring- The server's hostname. Up to 191 characters. Changing it also changes the hostname in the VM's cloud-init settings.
user_idinteger- ID of the user who owns the server.
vmidinteger- ID of the VM on the node that this server is linked to, from
100to999999999. Changing it links the server to a different VM; it doesn't renumber the VM. statusstring or nullinstalling,install_failed,suspended,restoring_backup,restoring_snapshot,deleting, ordeletion_failed.
Request
PATCH
/api/application/servers/<uuid>curl -X PATCH "https://panel.example.com/api/application/servers/<uuid>" \ -H "Authorization: Bearer <token>" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ --data '{ "user_id": 1, "status": null, "name": "ubunt", "hostname": "ubuntu.org", "vmid": 127080199 }'
use Illuminate\Support\Facades\Http; $response = Http::withToken($token) ->acceptJson() ->patch('https://panel.example.com/api/application/servers/<uuid>', [ 'user_id' => 1, 'status' => null, 'name' => 'ubunt', 'hostname' => 'ubuntu.org', 'vmid' => 127080199, ]);
const response = await fetch('https://panel.example.com/api/application/servers/<uuid>', { method: 'PATCH', headers: { Authorization: `Bearer ${token}`, Accept: 'application/json', 'Content-Type': 'application/json', }, body: JSON.stringify({ "user_id": 1, "status": null, "name": "ubunt", "hostname": "ubuntu.org", "vmid": 127080199 }), })
Response
{ "data": { "id": "72ddf699", "uuid": "72ddf699-1468-43e2-bd14-65d0d51c9299", "node_id": 4417, "hostname": "ubuntu.org", "name": "ubunt", "description": null, "status": null, "usages": { "bandwidth": 0 }, "limits": { "cpu": 3, "memory": 4294967296, "disk": 4294967296, "snapshots": 0, "backups": null, "bandwidth": null, "addresses": { "ipv4": [ { "id": 6, "server_id": 352, "type": "ipv4", "address": "1.1.1.2", "cidr": 24, "gateway": "127.0.0.1", "mac_address": null }, { "id": 7, "server_id": 352, "type": "ipv4", "address": "192.168.1.2", "cidr": 24, "gateway": "192.168.1.1", "mac_address": null } ], "ipv6": [] }, "mac_address": null }, "user_id": 1, "vmid": 127080199, "internal_id": 352, "user": { "data": { "id": 1, "name": "Mike Hawk", "email": "[email protected]", "email_verified_at": null, "root_admin": true, "servers_count": 0 } }, "node": { "data": { "id": 4417, "location_id": 5340, "name": "us-southeast", "cluster": "us-southeast", "fqdn": "us-southeast.performave.com", "port": 8006, "memory": 68719476736, "memory_overallocate": 0, "memory_allocated": 6442450944, "disk": 137438953472, "disk_overallocate": 0, "disk_allocated": 6442450944, "vm_storage": "local", "backup_storage": "local", "iso_storage": "local", "network": "vmbr0", "servers_count": 0 } } } }
PATCH
/api/application/servers/<uuid>/settings/buildUpdating a server's build
Body parameters
cpuintegerrequired- Number of CPU cores.
memoryintegerrequired- Memory in bytes. At least
16777216(16 MiB), and within what the node has left. diskintegerrequired- Disk size in bytes, within what the node has left.
address_idsarray of integers or nullrequired- IDs of every address the server should have. Addresses left out are taken off the server, so
[]ornullremoves them all. An address that belongs to another server is refused. snapshot_limitinteger or nullrequired- The server's snapshot limit.
backup_limitinteger or nullrequired- How many backups the server may have. Use
nullfor no limit. bandwidth_limitinteger or nullrequired- The server's bandwidth limit. Use
nullfor no limit. bandwidth_usageinteger- Bandwidth the server has used so far.
Request
PATCH
/api/application/servers/<uuid>/settings/buildcurl -X PATCH "https://panel.example.com/api/application/servers/<uuid>/settings/build" \ -H "Authorization: Bearer <token>" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ --data '{ "address_ids": [ 6, 7 ], "snapshot_limit": 0, "backup_limit": null, "bandwidth_limit": null, "bandwidth_usage": 0, "cpu": 3, "memory": 4294967296, "disk": 4294967296 }'
use Illuminate\Support\Facades\Http; $response = Http::withToken($token) ->acceptJson() ->patch('https://panel.example.com/api/application/servers/<uuid>/settings/build', [ 'address_ids' => [ 6, 7, ], 'snapshot_limit' => 0, 'backup_limit' => null, 'bandwidth_limit' => null, 'bandwidth_usage' => 0, 'cpu' => 3, 'memory' => 4294967296, 'disk' => 4294967296, ]);
const response = await fetch('https://panel.example.com/api/application/servers/<uuid>/settings/build', { method: 'PATCH', headers: { Authorization: `Bearer ${token}`, Accept: 'application/json', 'Content-Type': 'application/json', }, body: JSON.stringify({ "address_ids": [ 6, 7 ], "snapshot_limit": 0, "backup_limit": null, "bandwidth_limit": null, "bandwidth_usage": 0, "cpu": 3, "memory": 4294967296, "disk": 4294967296 }), })
Response
{ "data": { "id": "72ddf699", "uuid": "72ddf699-1468-43e2-bd14-65d0d51c9299", "node_id": 4417, "hostname": "ubuntu.org", "name": "ubuntu", "description": null, "status": null, "usages": { "bandwidth": 0 }, "limits": { "cpu": 3, "memory": 4294967296, "disk": 4294967296, "snapshots": 0, "backups": null, "bandwidth": null, "addresses": { "ipv4": [ { "id": 6, "server_id": 352, "type": "ipv4", "address": "1.1.1.2", "cidr": 24, "gateway": "127.0.0.1", "mac_address": null }, { "id": 7, "server_id": 352, "type": "ipv4", "address": "192.168.1.2", "cidr": 24, "gateway": "192.168.1.1", "mac_address": null } ], "ipv6": [] }, "mac_address": null }, "user_id": 1, "vmid": 127080199, "internal_id": 352, "user": { "data": { "id": 1, "name": "Mike Hawk", "email": "[email protected]", "email_verified_at": null, "root_admin": true, "servers_count": 0 } }, "node": { "data": { "id": 4417, "location_id": 5340, "name": "us-southeast", "cluster": "us-southeast", "fqdn": "us-southeast.performave.com", "port": 8006, "memory": 68719476736, "memory_overallocate": 0, "memory_allocated": 6442450944, "disk": 137438953472, "disk_overallocate": 0, "disk_allocated": 6442450944, "vm_storage": "local", "backup_storage": "local", "iso_storage": "local", "network": "vmbr0", "servers_count": 0 } } } }
POST
/api/application/serversCreating a server
Body parameters
namestringrequired- The server's name. Up to 40 characters.
user_idintegerrequired- ID of the user who owns the server.
node_idintegerrequired- ID of the node to put the server on.
vmidinteger or nullrequired- The VM's ID on the node, from
100to999999999.nulllets Convoy pick a free one. hostnamestringrequired- The server's hostname. Up to 191 characters.
limits.cpuintegerrequired- Number of CPU cores.
limits.memoryintegerrequired- Memory in bytes. At least
16777216(16 MiB), and within what the node has left. limits.diskintegerrequired- Disk size in bytes, within what the node has left.
limits.snapshotsinteger or nullrequired- The server's snapshot limit.
limits.backupsinteger or nullrequired- How many backups the server may have. Use
nullfor no limit. limits.bandwidthinteger or nullrequired- The server's bandwidth limit. Use
nullfor no limit. limits.address_idsarray of integers or null- IDs of unallocated addresses to give the server.
should_create_serverbooleanrequiredtruebuilds a new VM fromtemplate_uuid.falsetakes over the VM that already has thisvmidon the node.template_uuidstring- UUID of the template to build from, which must be on the node in
node_id. Use the template's own UUID from the Templates API, not its group's. Required whenshould_create_serveristrue. account_passwordstring- Password for the VM's account. 8 to 191 printable ASCII characters, with a lowercase letter, an uppercase letter, a digit, and one of
!@#$%^&*. Required whenshould_create_serveristrue. start_on_completionbooleanrequiredtruestarts the server once it is created.
Request
POST
/api/application/serverscurl -X POST "https://panel.example.com/api/application/servers" \ -H "Authorization: Bearer <token>" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ --data '{ "node_id": 4417, "user_id": 1, "name": "testee", "hostname": "advinservers.com", "vmid": null, "limits": { "cpu": 3, "memory": 4294967296, "disk": 3145728000, "snapshots": 0, "backups": null, "bandwidth": null, "address_ids": [] }, "account_password": "q%#tUyLPAm@2q", "should_create_server": true, "template_uuid": "d176b498-87e8-421f-a958-048ef15ef199", "start_on_completion": false }'
use Illuminate\Support\Facades\Http; $response = Http::withToken($token) ->acceptJson() ->post('https://panel.example.com/api/application/servers', [ 'node_id' => 4417, 'user_id' => 1, 'name' => 'testee', 'hostname' => 'advinservers.com', 'vmid' => null, 'limits' => [ 'cpu' => 3, 'memory' => 4294967296, 'disk' => 3145728000, 'snapshots' => 0, 'backups' => null, 'bandwidth' => null, 'address_ids' => [], ], 'account_password' => 'q%#tUyLPAm@2q', 'should_create_server' => true, 'template_uuid' => 'd176b498-87e8-421f-a958-048ef15ef199', 'start_on_completion' => false, ]);
const response = await fetch('https://panel.example.com/api/application/servers', { method: 'POST', headers: { Authorization: `Bearer ${token}`, Accept: 'application/json', 'Content-Type': 'application/json', }, body: JSON.stringify({ "node_id": 4417, "user_id": 1, "name": "testee", "hostname": "advinservers.com", "vmid": null, "limits": { "cpu": 3, "memory": 4294967296, "disk": 3145728000, "snapshots": 0, "backups": null, "bandwidth": null, "address_ids": [] }, "account_password": "q%#tUyLPAm@2q", "should_create_server": true, "template_uuid": "d176b498-87e8-421f-a958-048ef15ef199", "start_on_completion": false }), })
Response
{ "data": { "id": "d45309ad", "uuid": "d45309ad-9c9e-4ea7-b386-01a2e54a421e", "node_id": 4417, "hostname": "advinservers.com", "name": "testee", "description": null, "status": "installing", "usages": { "bandwidth": 0 }, "limits": { "cpu": 3, "memory": 4294967296, "disk": 3145728000, "snapshots": 0, "backups": null, "bandwidth": null, "addresses": { "ipv4": [], "ipv6": [] }, "mac_address": null }, "user_id": 1, "vmid": 549998493, "internal_id": 355, "user": { "data": { "id": 1, "name": "Mike Hawk", "email": "[email protected]", "email_verified_at": null, "root_admin": true, "servers_count": 0 } }, "node": { "data": { "id": 4417, "location_id": 5340, "name": "us-southeast", "cluster": "us-southeast", "fqdn": "us-southeast.performave.com", "port": 8006, "memory": 68719476736, "memory_overallocate": 0, "memory_allocated": 10737418240, "disk": 137438953472, "disk_overallocate": 0, "disk_allocated": 9588178944, "vm_storage": "local", "backup_storage": "local", "iso_storage": "local", "network": "vmbr0", "servers_count": 0 } } } }
DELETE
/api/application/servers/<uuid>Deleting a server
Query parameters
no_purgebooleantruekeeps the VM and its files on the Proxmox node and only removes the server from Convoy.
Returns no content
Request
DELETE
/api/application/servers/<uuid>curl -X DELETE "https://panel.example.com/api/application/servers/<uuid>" \ -H "Authorization: Bearer <token>" \ -H "Accept: application/json"
use Illuminate\Support\Facades\Http; $response = Http::withToken($token) ->acceptJson() ->delete('https://panel.example.com/api/application/servers/<uuid>');
const response = await fetch('https://panel.example.com/api/application/servers/<uuid>', { method: 'DELETE', headers: { Authorization: `Bearer ${token}`, Accept: 'application/json', }, })
POST
/api/application/servers/<uuid>/settings/suspendSuspending a server
No parameters/body is needed and no content is returned if successful
Request
POST
/api/application/servers/<uuid>/settings/suspendcurl -X POST "https://panel.example.com/api/application/servers/<uuid>/settings/suspend" \ -H "Authorization: Bearer <token>" \ -H "Accept: application/json"
use Illuminate\Support\Facades\Http; $response = Http::withToken($token) ->acceptJson() ->post('https://panel.example.com/api/application/servers/<uuid>/settings/suspend');
const response = await fetch('https://panel.example.com/api/application/servers/<uuid>/settings/suspend', { method: 'POST', headers: { Authorization: `Bearer ${token}`, Accept: 'application/json', }, })
POST
/api/application/servers/<uuid>/settings/unsuspendUnsuspending a server
No parameters/body is needed and no content is returned if successful
Request
POST
/api/application/servers/<uuid>/settings/unsuspendcurl -X POST "https://panel.example.com/api/application/servers/<uuid>/settings/unsuspend" \ -H "Authorization: Bearer <token>" \ -H "Accept: application/json"
use Illuminate\Support\Facades\Http; $response = Http::withToken($token) ->acceptJson() ->post('https://panel.example.com/api/application/servers/<uuid>/settings/unsuspend');
const response = await fetch('https://panel.example.com/api/application/servers/<uuid>/settings/unsuspend', { method: 'POST', headers: { Authorization: `Bearer ${token}`, Accept: 'application/json', }, })