Start using the IaaS API

Prerequisites

• You have a STACKIT customer account: Create a customer Account
• You have a STACKIT user account: Create a user account
• You have a STACKIT project: Create a project
• You have the STACKIT CLI installed: Install STACKIT CLI

Authenticate with the STACKIT CLI

Before sending any API request, you must authenticate with the STACKIT CLI. This ensures your requests are authorized and executed in the context of your STACKIT project.

stackit auth login

To confirm your setup, try your first simple API call:

stackit curl https://iaas.api.eu01.stackit.cloud/v1/projects/[ProjectID]

You can find the Project ID by logging in to the STACKIT Portal and navigating to the Project information section.

If authentication is configured correctly, the API will respond with basic project information.

Create a Volume

In the following steps, you will create a bootable volume based on a public image. This volume will later serve as the root disk for a new server.

1. Find an image.

   First, list all available images in your project and filter for a specific one, such as Ubuntu 20.04.

   stackit curl https://iaas.api.eu01.stackit.cloud/v1/projects/[ProjectID]/images | jq '.items[]|select(.name =="Ubuntu 20.04")|{id,name,status,scope}'

   {
       "id": "edfded8c-6351-4528-829a-3aa2a7ad856c",
       "name": "Ubuntu 20.04",
       "status": "AVAILABLE",
       "scope": "public"
   }

   Note the id of the desired image. You will need it for the volume creation request.

2. Create the volume.

   Now create a new volume using the image ID. In this example, a 10GB volume is created in availability zone eu01-1.

   stackit curl -X POST -H "Content-Type: application/json" --data '{"availabilityZone":"eu01-1","size":10,"name":"my-volume","source":{"id":"edfded8c-6351-4528-829a-3aa2a7ad856c","type":"image"}}' https://iaas.api.eu01.stackit.cloud/v1/projects/[ProjectID]/volumes

   The API returns information about your new volume. Initially, its status will be CREATING.

   {
       "availabilityZone": "eu01-1",
       "bootable": false,
       "createdAt": "2025-12-01T06:17:42Z",
       "encrypted": false,
       "id": "97527f6b-531a-453c-b7b1-50d0b7bb22d9",
       "imageConfig": {},
       "labels": {},
       "name": "my-volume",
       "performanceClass": "storage_premium_perf1",
       "size": 10,
       "source": {
           "id": "edfded8c-6351-4528-829a-3aa2a7ad856c",
           "type": "image"
       },
       "status": "CREATING"
       }

3. Check the volume status.

   Before you can use the volume, it must transition to AVAILABLE.

   stackit curl https://iaas.api.eu01.stackit.cloud/v1/projects/[ProjectID]/volumes | jq '.items[]|select(.name =="my-volume")|{id,name,status}'

   {
       "id": "97527f6b-531a-453c-b7b1-50d0b7bb22d9",
       "name": "my-volume",
       "status": "AVAILABLE"
   }

Create a server

With a boot volume ready, you can now create your first server instance. In this example, you provision a small compute instance using machine type g2i.1 and boot it from your previously created volume.

stackit curl -X POST -H "Content-Type: application/json" --data '{"bootVolume":{"source":{"id":"97527f6b-531a-453c-b7b1-50d0b7bb22d9","type":"volume"}},"machineType":"g2i.1","name":"my-server-1"}' https://iaas.api.eu01.stackit.cloud/v1/projects/[ProjectID]/servers

You will receive an immediate response showing the server in CREATING state.

{
  "availabilityZone": "eu01-1",
  "bootVolume": {
    "id": "97527f6b-531a-453c-b7b1-50d0b7bb22d9"
  },
  "id": "f014565d-54bf-442e-9e19-f3311ea6cc42",
  "labels": {},
  "machineType": "g2i.1",
  "metadata": {},
  "name": "my-server-1",
  "status": "CREATING"
}

Servers typically become ready within a short time. You can check when it reaches ACTIVE.

stackit curl https://iaas.api.eu01.stackit.cloud/v1/projects/[ProjectID]/servers | jq '.items[]|select(.name =="my-server-1")|{id,name,status}'

{
  "id": "f014565d-54bf-442e-9e19-f3311ea6cc42",
  "name": "my-server-1",
  "status": "ACTIVE"
}

Your first server is now successfully deployed via the IaaS API. From here, you can connect to it, attach additional volumes, configure networking, and automate more complex deployments.

This guide covered only the basics. For more advanced workflows, such as managing Linux servers, attaching additional block storage, or automating your infrastructure with the IaaS API, refer to the available How-tos for practical examples and the Compute Engine Linux Server documentation for detailed server management best practices.