Marketplace API

Introduction

The Marketplace API serves as a catalog of available Instance images. Its goal is to help find the specific image ID to use when launching an Instance.

Users can launch Instances through the Instances API. These Instances use a predefined disk state, called an image. To launch an Instance with a specific image, you must know the image's ID to pass to the Instance API.

These IDs can change over time as the Scaleway team releases new versions of the images, so the Marketplace API can be used to find the most up-to-date image to use.

Note

Check out the Instance API

Concepts

Refer to the Instances concepts page to learn more about images and other concepts related to Instances.

Quickstart

This API uses calls to the /local-images?image_label=<label> endpoint to get the IDs of specific images.

For example, make the following call to the endpoint /local-images?image_label=ubuntu_jammy&zone=fr-par-1 to get the local images for Ubuntu 22.04 LTS (Jammy Jellyfish) in the fr-par-1 Availability Zone:

$ curl -X GET https://api.scaleway.com/marketplace/v2/local-images\?image_label\=ubuntu_jammy\&zone\=fr-par-1 |jq

The following list of images is returned:

{
  "local_images": [
    {
      "id": "350a06b2-ecd0-48b9-ba9e-495a51345a68",
      "arch": "x86_64",
      "zone": "fr-par-1",
      "compatible_commercial_types": [
        [...]
        "STARDUST1-S",
        "PLAY2-MICRO",
        "PLAY2-NANO",
        "PLAY2-PICO"
      ],
      "label": "ubuntu_jammy"
    },
    {
      "id": "94299452-12c4-4d79-9c79-ced52967d75f",
      "arch": "arm64",
      "zone": "fr-par-1",
      "compatible_commercial_types": [
        "AMP2-C1",
        "AMP2-C2",
        [...]
      ],
      "label": "ubuntu_jammy"
    }
  ],
  "total_count": 2
}

Requirements

You have installed curl
You have installed jq (this will make it significantly easier to read the information returned by the Marketplace API)

Technical information

Availability Zones

Scaleway's infrastructure is spread across different regions and Availability Zones.

The Marketplace API is a global API and provides information about Instance images in all Availability Zones.

Authentication

No authentication or API key is required to use the Marketplace API.

Pagination

Most listing requests receive a paginated response. Requests against paginated endpoints accept two query arguments:

page, a positive integer to choose which page to return. The default value is 1.
page_size, an positive integer lower or equal to 100 to select the number of items to return per page. The default value is 20.

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

Going further

For more help using the Marketplace API, check out the following resources:

Our Instances API documentation.

Marketplace Images

Marketplace Images represent the generalized images available through the Marketplace API. For each image, information returned includes its name (e.g. Arch Linux), description, category and label. Note that the IDs returned by this endpoint are not the IDs required by the Instance API to specify the image to install on an Instance. You can, however, use the IDs provided by this endpoint as a filter with the Marketplace Local Images to find the right local image for your Instance, and its ID

GET/marketplace/v2/images

GET/marketplace/v2/images/{image_id}

Marketplace Local Images

Marketplace Local Images represent the local images available to be installed on Scaleway Instances. Each local image is specific to an Availability Zone, and has an ID (which can be used with the Instance API to request installation of this image) as well as information about its zone, compatible Instance types, supported architecture, and label (typically an identifier for the distribution). If the same distribution is available on multiple Availability Zones, it will have one local image per Availability Zone. When selecting an image to install on an Instance, you must ensure that it is compatible with that Instance in terms of zone, architecture, Instance type etc

GET/marketplace/v2/local-images

GET/marketplace/v2/local-images/{local_image_id}

Marketplace Image Versions

Marketplace Image Versions represent the different versions of Marketplace Images. Scaleway regularly releases new versions of images, for example to update an OS or fix a known issue. The IDs returned by this endpoint can be used with the Marketplace Local Images endpoint to find the different local images available for a given version

GET/marketplace/v2/versions

GET/marketplace/v2/versions/{version_id}

Marketplace Image Categories

Marketplace Image Categories represent the different categories of image available through the Marketplace API (e.g. distributions, InstantApps and Machine Learning images)

GET/marketplace/v2/categories

GET/marketplace/v2/categories/{category_id}