An API (Application Programming Interface) is a program that allows different applications to communicate with each other to share information and functionality.
Our API lets you manage everything you can do in the Clouding panel: create servers from different sources, archive and unarchive them, create snapshots, enable backups, add firewall rules, and more.
In this tutorial, we will use cURL to create the server. cURL is installed by default on many Linux and macOS systems. If you use Windows, follow our tutorial on how to install cURL on Windows.
Check the official Clouding API documentation
To follow this article and find more information, we recommend checking the official Clouding API documentation.
Before you start
You will need an API-KEY to follow this tutorial. To obtain one, follow the steps in How to create an API key in Clouding.
Create a server using cURL
To create a server using cURL, run a command with the following structure:
Note: for more information about the parameters, check the official Clouding API documentation.
# curl -X POST \
-H "Content-Type: application/json" \
-H "X-API-KEY: $CLOUDING_APIKEY" \
-d '{"name":"Server name","hostname":"myserver.example.com","flavorId":"1x2","accessConfiguration":{"sshKeyId":"SSH key ID","password":null,"savePassword":false},"volume":{"source":"image","id":"Image ID","ssdGb":10,"shutDownSource":null},"enableStrictAntiDDoSFiltering":false,"userData":null,"backupPreferences":null,"vpcs":[],"publicPortFirewallIds":["Firewall ID"]}' \
"https://api.clouding.io/v1/servers"To run this command correctly, you will need the following parameters:
- “name”: the server's name.
- “hostname”: the server's hostname.
-
“flavorId”: specifies the vCores and RAM in GB. For example, “2x4” means 2 vCores and 4 GB of RAM. You can view the available options using the flavors endpoint.
You can also list them with this cURL command:
# curl -X GET -H "Content-Type: application/json" -H "X-API-KEY: $CLOUDING_APIKEY" "https://api.clouding.io/v1/sizes/flavors?page=1&pageSize=100" -
“accessConfiguration”: this section contains several access settings, including the password.
Important
If the server has QEMU-AGENT, you can choose a password. Otherwise, the password must be empty or set to null.
“savePassword” specifies whether you want to save the password in the panel, and “sshKeyId” identifies the SSH key.
To list the SSH keys:
# curl -X GET -H "Content-Type: application/json" -H "X-API-KEY: $CLOUDING_APIKEY" "https://api.clouding.io/v1/keypairs?page=1&pageSize=100" -
“volume”: configures the server's disk. Choose a value for “source”: “image”, “backup”, “snapshot”, or “server”. In this example, we will use an image.
Then provide the source volume's ID. To list the available images:
# curl -X GET -H "Content-Type: application/json" -H "X-API-KEY: $CLOUDING_APIKEY" "https://api.clouding.io/v1/images?page=1&pageSize=100"Finally, set “ssdGb”, which specifies the disk size in GB.
Optional parameters
-
“vpcs”: select one or more VPCs [Private network (VPC)] to associate with the new server. If set to null, the server will not be associated with any VPC when created.
You will need to provide the VPC ID. To list the available VPCs, run:
# curl -X GET -H "Content-Type: application/json" -H "X-API-KEY: $CLOUDING_APIKEY" "https://api.clouding.io/v1/vpcs?page=1&pageSize=100" -
“publicPortFirewallIds”: select one or more unique firewall IDs to apply to the server's public port. These firewalls control incoming traffic to the server's public IP address.
If this parameter is undefined, null, or empty, all incoming traffic through the public port will be blocked. To list the available firewall profiles:
# curl -X GET -H "Content-Type: application/json" -H "X-API-KEY: $CLOUDING_APIKEY" "https://api.clouding.io/v1/firewalls?page=1&pageSize=100"
Check the process status
When you send a request to create a new server through the Clouding API, you will receive a response like this:
{
"id": "MjB54KODX5JnYWkp",
"name": "Server name",
"hostname": "myserver.example.com",
"vCores": 1,
"ramGb": 2,
"flavor": "1x2",
"volumeSizeGb": 10,
"image": {
"id": "DgNMqlnNpZd7pyke",
"name": "Debian 12 (64 Bit)"
},
"status": "Pending",
"pendingFeatures": [
"PrivateNetwork"
],
"pendingFirewalls": null,
"requestedAccessConfiguration": {
"sshKeyId": "BojVWnrYBmK0wavR",
"hasPassword": true,
"savePassword": true
},
"backupPreferences": null,
"pendingPublicPortFirewalls": [
{
"id": "RYXvMdx85Jd63Vl5",
"name": "default"
}
],
"pendingVpcs": [
{
"id": "PAQmBdaAp6dDJE97",
"ip": null,
"pendingFirewalls": [
{
"id": "RYXvMdx85Jd63Vl5",
"name": "default"
}
]
}
],
"action": {
"id": "GeNo3KJL4QG2vE5x",
"status": "inProgress",
"type": "create",
"startedAt": "2025-04-15T12:07:42.4846986Z",
"completedAt": null,
"resourceId": "MjB54KODX5JnYWkp",
"resourceType": "server"
}
}The last property, “action”, provides information about the request:
- “id”: the action's unique identifier.
- “status”: the action's current status. It can indicate that the action is pending, in progress, completed, or has encountered an error.
- “type”: the type of action being performed, such as creating a snapshot. In this case, creating a server.
- “startedAt”: the date and time the action started, in UTC.
- “completedAt”: the completion date and time, in UTC. This field is null while the action is still in progress, as in this example.
- “resourceId”: the unique identifier of the resource the action applies to, such as a server.
- “resourceType”: the type of resource the action applies to, such as a server or snapshot.
As you can see, this action is in progress and has not yet finished. You can query it through a dedicated endpoint to check its status or find out whether it has completed successfully.
For example, to check the action using the ID above:
# curl -X GET \
-H "Content-Type: application/json" \
-H "X-API-KEY: $CLOUDING_APIKEY" \
"https://api.clouding.io/v1/actions/GeNo3KJL4QG2vE5x"The example result is:
{
"action": {
"id": "GeNo3KJL4QG2vE5x",
"status": "inProgress",
"type": "create",
"startedAt": "2025-04-15T12:07:42.4846986Z",
"completedAt": null,
"resourceId": "MjB54KODX5JnYWkp",
"resourceType": "server"
}
}In this case, the action is still in progress and does not yet have a completion date.
We hope this has helped. Have you tried it? Leave us your comments! 🙂
Remember, if you have any questions about this or any other matter related to your servers at Clouding, feel free to email soporte@clouding.io We’re here for whatever you need. Just ask us!