Invapi API FAQ¶

In this article

• Instant Server Ordering Algorithm with eq/orderinstance
• Reinstalling a server via eq/orderinstance

Instant Server Ordering Algorithm with eq/order_instance¶

1. Create a client API key;

2. Choose the server location: NL/US/FI/DE/IS/TR/UK/ES/IT/PL/CH (Netherlands, USA, Finland, Germany, Iceland, Turkey, UK, Spain, Italy, Poland, Switzerland);

3. Use the presets/list request to determine the preset ID for deployment.

   This ID will later be used as instance_id or preset. For example, if "id": 108, the values are instance_id=108 and preset=108;

4. Use the os/list request to determine the os_id or os_name of the operating system you want to install, using the instance ID from step 3 or its alias. For example, for Ubuntu 22.04, this value will be returned in the response as "id": 187 and "alias": ubuntu. You can also find OS IDs and information on which server types they are available in the list of currently supported OSs;

   Note

   If you do not want to install an OS during deployment, specify own_os=1 later.

5. Use the software/list request to identify available software for this instance and get its ID (the soft_id parameter). For example, for the WordPress CMS, the value in the request output will be "id": 20. You can find a list of installable software and its installation parameters (ID, server type, required RAM and disk space, number of CPU cores, etc.) in the supported software list;

   Note

   You can skip pre-installing software during deployment if you wish to do it manually later.

6. Use the traffic_plans/list request to get the network traffic plan ID for your server. For example, for the 3Tb traffic (1Gbps) VM plan, the call will return "id": 25;

7. Obtain a session token $HOSTKEY_TOKEN via the auth/login request;

8. Order the server by inserting the data obtained in steps 2-7 into the eq/order_instance request. You must specify your root password, the server billing period deploy_period (monthly, quarterly, 6 months, or yearly), and whether you want an email notification upon deployment via deploy_notify (we recommend setting this to true by default).

Optional additional parameters can be specified as described in the eq/order_instance call.

Below is an example of ordering a server with WordPress (id=20) on Debian 11 (id=108):

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=order_instance" \
--data "token=eeee51003b1d81d2eca65660735c0531" \
--data "deploy_period=monthly" \
--data "deploy_notify=true" \
--data "preset=108" \
--data "location_name=NL" \
--data "os_id=180" \
--data "soft_id=20" \
--data "traffic_plan=25" \
--data "root_pass=mdLus8Ng" \

{
    "result": "OK",
    "action": "order_instance",
    "invoice": 50062,
    "status": "Paid"
}

Invapi will select/create the corresponding server in the specified location and proceed with deployment. Before any installation, a check for sufficient funds on the credit balance will be performed (if automatic payments from credit balance are enabled) or an invoice will be issued. If the installation is successful, the new server will be linked to the client's account. The client will be notified by email upon request. All paid licenses will be added as order add-ons.

{
"result": -1,
"error": "reinstall: extra software Odoo (#49) is not compatible with Ubuntu 22.04"
}

{
"result": "OK",
"scope": "Autodeploy completed, check VRI-208-64405",
"context": {
    "action": "deploy_vm",
    "id": "32645",
    "location": "NL",
    "ip": "176.222.34.23",
    "ip_ipmi": "0.0.0.0"
},
"debug": "0",
"key": "9889fcb51255146e04224205c04976e8"
}

Reinstalling a server via eq/order_instance¶

Reinstalling a server is performed similarly to ordering one; it differs only by passing an additional id parameter in the eq/order_instance request—the ID of the server being reinstalled from Invapi—and not using the preset parameter. During a reinstall, you can choose a different operating system and pre-installed software, or perform a "clean" reinstall by setting the own_os=1 parameter (in which case you must set os_id = 0).

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=order_instance" \
--data "token=$HOSTKEY_TOKEN" \
--data "hostname={Hostname}" \
--data "os_id={OS ID}" \
--data "soft_id={Software ID}" \
--data "root_pass={root password}" \
--data "ssh_key={public SSH key}" \
--data "post_install_script=" \
--data "own_os=" \
--data "root_size=100" \
--data "location_name={Server location with specified ID}" \
--data "id={Invapi Server ID}" // Presence of ID triggers the server reinstallation process.

{
"result": -1,
"error": "reinstall: extra software Odoo (#49) is not compatible with Ubuntu 22.04"
}

{"result":-1,"error":"another reinstall in progress for XXXXX, please wait"}

For example, suppose we want to reinstall our server from the previous example to Rocky Linux 9 (id=205) and Grafana (id=18). The request would be as follows:

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=order_instance" \
--data "token=5e731472b19f25c7fe61c9eb5c2ea4e3" \
--data "deploy_notify=true" \
--data "os_id=205" \
--data "soft_id=18" \
--data "root_pass=mnN48Dl@4" \
--data "location_name=NL" \
--data "id=32645"

{
    "result": "OK",
    "action": "order_instance",
    "callback": "e2fbe5f43796d4139983b695271da9aa", // asynchronous key
    "deploy_status": "reinstall",
    "id": 32645,
    "os_name": "RockyLinux 9",
    "soft_name": "Grafana"
}

By using this asynchronous key (the callback field), we can track the reinstallation process using asynchronous actions.

{
    "result": "OK",
    "scope": "{"result":"deploy_done"}",
    "context": {
        "action": "reinstall_vm",
        "id": "32645",
        "location": "NL",
        "ip": "176.222.34.23",
        "ip_ipmi": "0.0.0.0",
        "reinstall": 1
    },
    "debug": "",
    "key": "a129bad13781bdf5790746064aba0af6"
}