Application API

Servers API

GET/api/application/servers

Fetching servers

Query parameters

pageinteger
The page to return.
per_pageinteger
Results per page. Defaults to 50; the most is 100.
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/servers
curl "https://panel.example.com/api/application/servers" \
  -H "Authorization: Bearer <token>" \
  -H "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"
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 100 to 999999999. Changing it links the server to a different VM; it doesn't renumber the VM.
statusstring or null
installing, install_failed, suspended, restoring_backup, restoring_snapshot, deleting, or deletion_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
  }'
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/build

Updating 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 [] or null removes 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 null for no limit.
bandwidth_limitinteger or nullrequired
The server's bandwidth limit. Use null for no limit.
bandwidth_usageinteger
Bandwidth the server has used so far.
Request
PATCH/api/application/servers/<uuid>/settings/build
curl -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
  }'
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/servers

Creating 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 100 to 999999999. null lets 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 null for no limit.
limits.bandwidthinteger or nullrequired
The server's bandwidth limit. Use null for no limit.
limits.address_idsarray of integers or null
IDs of unallocated addresses to give the server.
should_create_serverbooleanrequired
true builds a new VM from template_uuid. false takes over the VM that already has this vmid on 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 when should_create_server is true.
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 when should_create_server is true.
start_on_completionbooleanrequired
true starts the server once it is created.
Request
POST/api/application/servers
curl -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
  }'
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_purgeboolean
true keeps 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"
POST/api/application/servers/<uuid>/settings/suspend

Suspending a server

No parameters/body is needed and no content is returned if successful

Request
POST/api/application/servers/<uuid>/settings/suspend
curl -X POST "https://panel.example.com/api/application/servers/<uuid>/settings/suspend" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"
POST/api/application/servers/<uuid>/settings/unsuspend

Unsuspending a server

No parameters/body is needed and no content is returned if successful

Request
POST/api/application/servers/<uuid>/settings/unsuspend
curl -X POST "https://panel.example.com/api/application/servers/<uuid>/settings/unsuspend" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"