How to create a dedicated server via public API

This guide provides instructions on configuring and ordering a server using the API. For this example, we're looking at the Dell R220 / Intel Xeon E3-1231 v3 / 32 GB RAM / 2x480 GB SSD server in the AMS1 location. To explore other available server models, configurations, and locations, please visit the Customer Portal.

You can use either a password or an SSH key to authenticate a server. All SSH key fingerprints can be found in the Customer Portal under Identity and Access → SSH & GPG keys. Filling in user information is optional.

As you proceed with the requests, use the IDs obtained in the previous steps. Examples of requests and instructions on setting parameters will be provided in each section.

Environment setup

Before working with the API, set up your environment for making requests. This includes installing the necessary tools for authentication and sending API requests.

Most modern operating systems come with built-in command-line tools like cURL. Additionally, you can use:

• Graphical tools like Postman to simplify sending API requests and receiving responses.
• IDE plugins or built-in tools for working with APIs (e.g., Visual Studio Code and JetBrains IDEs).

Authentication

All requests to the Public API must include your authentication token and must be made using cURL, as specified in the Public API documentation.

To get an API token:

1. Go to the Customer Portal.
2. In the left-hand menu, navigate to Identity and Access and select API keys.
3. Click Create.
4. Specify the name of the API key and select Read & Write permissions.
5. Click Create.

An API token will be generated. Replace TOKEN with your API token in each request.

Getting a list of available locations

Before finding the required server and its ID, get a list of available locations and choose the desired one.

curl -g "https://api.servers.com/v1/locations" -X GET \
  -H "Authorization: Bearer TOKEN"

The same request using the srvctl CLI:

srvctl locations list

View the request/response details in the Public API documentation

For this example, the AMS1 location (Amsterdam Metropolitan Area, The Netherlands) has id: 1.

Getting a list of available dedicated servers in the selected location

curl -g "https://api.servers.com/v1/locations/{location_id}/order_options/server_models" -X GET \
  -H "Authorization: Bearer TOKEN"

The same request using srvctl:

srvctl server-models list --location-id {location_id}

View the request/response details in the Public API documentation

The response will include a list of available servers and their configurations for the selected location. For custom configurations, all necessary parameters can be specified in the request body. See: Create a dedicated server.

For this example, the required server model has ID: 10522.

Configuring the selected server

Before ordering the server, perform several GET requests to retrieve required IDs and parameters such as uplink_models, bandwidth_id, drives, and more.

Getting the list of uplinks

curl -g "https://api.servers.com/v1/locations/{location_id}/order_options/server_models/{server_model_id}/uplink_models" -X GET \
  -H "Authorization: Bearer TOKEN"

The same request using srvctl:

srvctl uplink-models list --location-id {location_id} --server-model-id {server_model_id}

View the request/response details in the Public API documentation

For this example:

• Private 1 Gbps without redundancy has ID: 10201
• Public 1 Gbps without redundancy has ID: 10198

Getting available bandwidths for public uplink

curl -g "https://api.servers.com/v1/locations/{location_id}/order_options/server_models/{server_model_id}/uplink_models/{uplink_model_id}/bandwidth" -X GET \
  -H "Authorization: Bearer TOKEN"

The same request using srvctl:

srvctl uplink-bandwidths list --location-id {location_id} --server-model-id {server_model_id} --uplink-model-id {uplink_model_id}

View the request/response details in the Public API documentation

For this example, the bandwidth has ID: 13744.

Selecting the RAM size

Select the RAM size based on the ram and max_ram parameters in the response for the selected server configuration.

curl -g "https://api.servers.com/v1/locations/{location_id}/order_options/server_models/{server_model_id}/ram" -X GET \
  -H "Authorization: Bearer TOKEN"

The same request using srvctl:

srvctl server-ram-options list --location-id {location_id} --server-model-id {server_model_id}

View the request/response details in the Public API documentation

For this example, the selected server has a fixed memory size of 32 GB.

Getting disk models

At this step, determine which disks will be installed and in which slots.

curl -g "https://api.servers.com/v1/locations/{location_id}/order_options/server_models/{server_model_id}/drive_models" -X GET \
  -H "Authorization: Bearer TOKEN"

The same request using srvctl:

srvctl drive-models list --location-id {location_id} --server-model-id {server_model_id}

View the request/response details in the Public API documentation

For this example, two 2 TB SATA3 HDDs with ID: 10306 will be mounted in each slot.

Disk partitioning

For this example, a simple disk partitioning setup with software RAID 0 is used. The server model chosen for this example does not have a hardware RAID controller.

Getting the list of available operating systems

curl -g "https://api.servers.com/v1/locations/{location_id}/order_options/server_models/{server_model_id}/operating_systems" -X GET \
  -H "Authorization: Bearer TOKEN"

The same request using srvctl:

srvctl server-os-options list --location-id {location_id} --server-model-id {server_model_id}

View the request/response details in the Public API documentation

For this example, Ubuntu 20.04-server x86_64 has ID: 49.

Ordering a server

Once all parameters have been defined, submit the POST request to order the server.

curl "https://api.servers.com/v1/hosts/dedicated_servers" \
  -d '{
    "server_model_id": {server_model_id},
    "location_id": {location_id},
    "ram_size": {ram_size},
    "uplink_models": {
      "public": {
        "id": {public_uplink_id},
        "bandwidth_model_id": {bandwidth_id}
      },
      "private": {
        "id": {private_uplink_id}
      }
    },
    "drives": {
      "slots": [
        {
          "position": {position_num},
          "drive_model_id": {drive_id}
        },
        {
          "position": {position_num},
          "drive_model_id": {drive_id}
        }
      ],
      "layout": [
        {
          "slot_positions": [
            {position_num},
            {position_num}
          ],
          "raid": {raid_level},
          "partitions": [
            {
              "target": "/boot",
              "size": {boot_partition_size},
              "fill": false,
              "fs": "ext4"
            },
            {
              "target": "swap",
              "size": {swap_partition_size},
              "fill": false
            },
            {
              "target": "/",
              "size": {root_partition_size},
              "fill": true,
              "fs": "ext4"
            }
          ]
        }
      ]
    },
    "ipv6": false,
    "hosts": [
      {
        "hostname": "{hostname}"
      }
    ],
    "operating_system_id": {operating_system_id}
  }' \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN"

The same request using the srvctl CLI: save the request body above as dedicated-server.json (it mirrors the API body 1:1) and pass it to add.

srvctl hosts ebm add --input dedicated-server.json

View the request/response details in the Public API documentation

If successful, you will receive a response containing the order details and the ID of the newly created server. If there are any issues with the request, error messages will be displayed in the console.

Checking the status of a created server

You can also find the server ID in the Customer Portal:

1. Go to the Customer Portal.
2. In the left-hand menu, navigate to Dedicated Servers → Manage.
3. Find the dedicated server by its name and click Details.

curl -g "https://api.servers.com/v1/hosts/dedicated_servers/{server_id}" -X GET \
  -H "Authorization: Bearer TOKEN"

The same request using srvctl:

srvctl hosts ebm get {server_id}

View the request/response details in the Public API documentation