Instance API

Scaleway Instances are virtual machines in the cloud. Different Instance typesOpen in new context offer different technical specifications in terms of vCPU, RAM, bandwidth, and storage. Once you have created your Instance and installed your image of choice (e.g. an operating system), you can connect to your Instance via SSHOpen in new context to use it as you wish. When you are done using the Instance, you can delete it from your account.

(switchcolumn)

Concepts

Refer to our dedicated concepts pageOpen in new context to find definitions of all concepts and terminology related to Instances.

(switchcolumn) (switchcolumn)

Quickstart

1. Configure your environment variables:

   Note

   This is an optional step that seeks to simplify your usage of the Instances API. See Availability Zones below for help choosing an Availability Zone. You can find your Project ID in the Scaleway consoleOpen in new context.

   Code
   export SCW_SECRET_KEY="<API secret key>"
   export SCW_DEFAULT_ZONE="<Scaleway Availability Zone>"
   export SCW_PROJECT_ID="<Scaleway Project ID>"

2. Create an Instance: Run the following command to create an Instance. You can customize the details in the payload (name, description, type, tags etc) to your needs: use the information below to adjust the payload as necessary.

   Code
   curl -X POST \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     -H "Content-Type: application/json" \
     "https://api.scaleway.com/instance/v2alpha1/zones/$SCW_DEFAULT_ZONE/servers" \
       -d '{
         "name": "my-new-instance",
         "project_id": "'"$SCW_PROJECT_ID"'",
         "server_type": "GP1-S",
         "public_network_interface": {
           "ips": [
             {
               "new_ip": {
                 "type": "zonal_ipv4"
               }
             },
             {
               "ipam_ip_id": "<IP-ID>"
             }
           ]
         },
         "volumes": [
           {
             "volume_type": "l_ssd",
             "new_volume": {
               "name": "my-new-volume",
               "image_label": "ubuntu_noble"
             }
           },
           {
             "volume_type": "sbs",
             "volume_id": "<Volume-ID>"
           }
         ]
       }'

   Code
    | Parameter       | Description                                                                                                                                              | Valid values                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

   | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | A name of your choice for the Instance (string) | Any string containing only alphanumeric characters, dots, spaces and dashes, e.g. "my-new-instance". | | project_id | The Project in which the Instance should be created (string) | Any valid Scaleway Project ID (see above), e.g. "b4bd99e0-b389-11ed-afa1-0242ac120002" | | server_type | The commercial Instance type to create (string) | Any valid ID of a Scaleway commercial Instance type, e.g. "GP1-S", "PRO2-M". Use the List Instance Types endpoint to get a list of all valid Instance types and their IDs. | | public_network_interface | A list that specifies the IPs to attach to the Instance. | A list where each item is a dictionary containing either "ipam_ip_id" with the IP ID as its value, or "new_ip" containing "type" (values: "zonal_ipv4", or "zonal_ipv6"). | | volumes | A list that specifies the storage volumes to attach to the Instance. | A list where each item is a dictionary containing the key "volume_type" (values: "l_ssd", "sbs", or "scratch") and either the key "volume_id" or "new_volume". "volume_id" is used to attach a volume with the volume ID as its value. "new_volume" is used to create a volume from a Scaleway image ("image_label") or a snapshot ("base_snapshot_id"). Further parameters are available. |

3. List your Instances: Run the following command to get a list of all the Instances in your account, with their details:

   Code
   curl -X GET \
     -H "Content-Type: application/json" \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     "https://api.scaleway.com/instance/v2alpha1/zones/$SCW_DEFAULT_ZONE/servers/"

4. Delete an Instance: Run the following command to delete an Instance, specified by its Instance ID:

   Code
   curl -X DELETE \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     -H "Content-Type: application/json" \
     "https://api.scaleway.com/instance/v2alpha1/zones/$SCW_DEFAULT_ZONE/servers/<Instance-ID>"

   The expected successful response is empty.

(switchcolumn)

• You have a Scaleway accountOpen in new context
• You have created an API keyOpen in new context and the API key has sufficient IAM permissionsOpen in new context to perform the actions described on this page
• You have installed curlOpen in new context

(switchcolumn)

Technical information

Availability Zones

You can deploy Instances in the following Availability Zones:

(switchcolumn) (switchcolumn)

Pagination

The listing requests receive a paginated response. They accept two query arguments:

• page_token, a string representing the wanted page. If it's not provided the first page will be returned.
• page_size, a positive integer lower or equal to 100 to select the number of items to return per page. The default value is 100.

Paginated endpoints usually also accept filters to search and sort results. These filters are documented along each endpoint documentation.

The listing response contain the next_page_token, the token to retrieve the next page.

(switchcolumn) (switchcolumn)

Going further

For more help using Scaleway Instances, check out the following resources:

• Our main documentationOpen in new context
• The #instance channel on our Slack CommunityOpen in new context
• Our support ticketing systemOpen in new context.