openapi: 3.0.0
info:
title: Marketplace API
description: |-
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.
(switchcolumn)
Check out the [Instance API](https://www.scaleway.com/en/developers/api/instance/)
(switchcolumn)
## Concepts
Refer to [the Instances concepts page](https://www.scaleway.com/en/docs/compute/instances/concepts/) to learn more about images and other concepts related to Instances.
(switchcolumn)
(switchcolumn)
## Quickstart
This API uses calls to the `/local-images?image_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:
```bash
$ 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:
```bash
{
"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
}
```
(switchcolumn)
- You have [installed `curl`](https://curl.se/download.html)
- You have [installed `jq`](https://stedolan.github.io/jq/download/) (this will make it significantly easier to read the information returned by the Marketplace API)
(switchcolumn)
## Technical information
### Availability Zones
Scaleway's infrastructure is spread across different [regions and Availability Zones](https://www.scaleway.com/en/docs/console/my-account/reference-content/products-availability/).
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](https://www.scaleway.com/en/developers/api/instance/).
version: v2
servers:
- url: https://api.scaleway.com
tags:
- name: Marketplace Images
description: |
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](#path-marketplace-local-images-list-local-images-from-a-specific-image-or-version) to find the right local image for your Instance, and its ID
- name: Marketplace Local Images
description: |
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
- name: Marketplace Image Versions
description: |
Marketplace Image Versions represent the different versions of [Marketplace Images](#path-marketplace-images-list-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](#path-marketplace-local-images-list-local-images-from-a-specific-image-or-version) endpoint to find the different local images available for a given version
- name: Marketplace Image Categories
description: |
Marketplace Image Categories represent the different categories of image available through the Marketplace API (e.g. distributions, InstantApps and Machine Learning images)
components:
schemas:
google.protobuf.Int32Value:
type: integer
format: int32
nullable: true
scaleway.marketplace.v2.Category:
type: object
properties:
id:
type: string
description: (UUID format)
example: 6170692e-7363-616c-6577-61792e636f6d
name:
type: string
description:
type: string
x-properties-order:
- id
- name
- description
scaleway.marketplace.v2.Image:
type: object
properties:
id:
type: string
description: UUID of this image. (UUID format)
example: 6170692e-7363-616c-6577-61792e636f6d
name:
type: string
description: Name of the image.
description:
type: string
description: Text description of this image.
logo:
type: string
description: URL of this image's logo.
categories:
type: array
description: List of categories this image belongs to.
items:
type: string
created_at:
type: string
description: Creation date of this image. (RFC 3339 format)
format: date-time
example: "2022-03-22T12:34:56.123456Z"
nullable: true
updated_at:
type: string
description: Date of the last modification of this image. (RFC 3339 format)
format: date-time
example: "2022-03-22T12:34:56.123456Z"
nullable: true
valid_until:
type: string
description: Expiration date of this image. (RFC 3339 format)
format: date-time
example: "2022-03-22T12:34:56.123456Z"
nullable: true
label:
type: string
description: |-
Label of this image.
Typically an identifier for a distribution (ex. "ubuntu_focal").
x-properties-order:
- id
- name
- description
- logo
- categories
- created_at
- updated_at
- valid_until
- label
scaleway.marketplace.v2.ListCategoriesResponse:
type: object
properties:
categories:
type: array
items:
$ref: '#/components/schemas/scaleway.marketplace.v2.Category'
total_count:
type: integer
format: uint32
x-properties-order:
- categories
- total_count
scaleway.marketplace.v2.ListImagesResponse:
type: object
properties:
images:
type: array
items:
$ref: '#/components/schemas/scaleway.marketplace.v2.Image'
total_count:
type: integer
format: uint32
x-properties-order:
- images
- total_count
scaleway.marketplace.v2.ListLocalImagesRequest.OrderBy:
type: string
enum:
- created_at_asc
- created_at_desc
default: created_at_asc
scaleway.marketplace.v2.ListLocalImagesResponse:
type: object
properties:
local_images:
type: array
items:
$ref: '#/components/schemas/scaleway.marketplace.v2.LocalImage'
total_count:
type: integer
format: uint32
x-properties-order:
- local_images
- total_count
scaleway.marketplace.v2.ListVersionsRequest.OrderBy:
type: string
enum:
- created_at_asc
- created_at_desc
default: created_at_asc
scaleway.marketplace.v2.ListVersionsResponse:
type: object
properties:
versions:
type: array
items:
$ref: '#/components/schemas/scaleway.marketplace.v2.Version'
total_count:
type: integer
format: uint32
x-properties-order:
- versions
- total_count
scaleway.marketplace.v2.LocalImage:
type: object
properties:
id:
type: string
description: |-
UUID of this local image.
Version you will typically use to define an image in an API call. (UUID format)
example: 6170692e-7363-616c-6577-61792e636f6d
compatible_commercial_types:
type: array
description: List of all commercial types that are compatible with this
local image.
items:
type: string
arch:
type: string
description: Supported architecture for this local image.
zone:
type: string
description: Availability Zone where this local image is available.
label:
type: string
description: Image label this image belongs to.
type:
type: string
description: Type of this local image.
enum:
- unknown_type
- instance_local
- instance_sbs
x-enum-descriptions:
values:
unknown_type: Unspecified image type
instance_local: An image type that can be used to create volumes which
are managed via the Instance API.
instance_sbs: An image type that can be used to create volumes which
are managed via the Scaleway Block Storage (SBS) API.
default: unknown_type
x-properties-order:
- id
- compatible_commercial_types
- arch
- zone
- label
- type
scaleway.marketplace.v2.LocalImage.Type:
type: string
enum:
- unknown_type
- instance_local
- instance_sbs
x-enum-descriptions:
values:
unknown_type: Unspecified image type
instance_local: An image type that can be used to create volumes which are
managed via the Instance API.
instance_sbs: An image type that can be used to create volumes which are
managed via the Scaleway Block Storage (SBS) API.
default: unknown_type
scaleway.marketplace.v2.Version:
type: object
properties:
id:
type: string
description: UUID of this version. (UUID format)
example: 6170692e-7363-616c-6577-61792e636f6d
name:
type: string
description: Name of this version.
created_at:
type: string
description: Creation date of this image version. (RFC 3339 format)
format: date-time
example: "2022-03-22T12:34:56.123456Z"
nullable: true
updated_at:
type: string
description: Date of the last modification of this version. (RFC 3339 format)
format: date-time
example: "2022-03-22T12:34:56.123456Z"
nullable: true
published_at:
type: string
description: Date this version was officially published. (RFC 3339 format)
format: date-time
example: "2022-03-22T12:34:56.123456Z"
nullable: true
x-properties-order:
- id
- name
- created_at
- updated_at
- published_at
securitySchemes:
scaleway:
in: header
name: X-Auth-Token
type: apiKey
paths:
/marketplace/v2/categories:
get:
tags:
- Marketplace Image Categories
operationId: ListCategories
summary: List existing image categories
description: Get a list of all existing categories. The output can be paginated.
parameters:
- in: query
name: page_size
schema:
type: integer
format: uint32
- in: query
name: page
schema:
$ref: '#/components/schemas/google.protobuf.Int32Value'
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: '#/components/schemas/scaleway.marketplace.v2.ListCategoriesResponse'
security:
- scaleway: []
x-codeSamples:
- lang: cURL
source: |-
curl -X GET \
-H "X-Auth-Token: $SCW_SECRET_KEY" \
"https://api.scaleway.com/marketplace/v2/categories"
- lang: HTTPie
source: |-
http GET "https://api.scaleway.com/marketplace/v2/categories" \
X-Auth-Token:$SCW_SECRET_KEY
/marketplace/v2/categories/{category_id}:
get:
tags:
- Marketplace Image Categories
operationId: GetCategory
summary: Get a specific category
description: Get information about a specific category of the marketplace catalog,
specified by its `category_id` (UUID format).
parameters:
- in: path
name: category_id
description: (UUID format)
required: true
schema:
type: string
description: (UUID format)
example: 6170692e-7363-616c-6577-61792e636f6d
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: '#/components/schemas/scaleway.marketplace.v2.Category'
security:
- scaleway: []
x-codeSamples:
- lang: cURL
source: |-
curl -X GET \
-H "X-Auth-Token: $SCW_SECRET_KEY" \
"https://api.scaleway.com/marketplace/v2/categories/{category_id}"
- lang: HTTPie
source: |-
http GET "https://api.scaleway.com/marketplace/v2/categories/{category_id}" \
X-Auth-Token:$SCW_SECRET_KEY
/marketplace/v2/images:
get:
tags:
- Marketplace Images
operationId: ListImages
summary: List marketplace images
description: List all available images on the marketplace, their UUID, CPU architecture
and description.
parameters:
- in: query
name: page_size
description: A positive integer lower or equal to 100 to select the number
of items to display.
schema:
type: integer
description: A positive integer lower or equal to 100 to select the number
of items to display.
format: uint32
- in: query
name: page
description: A positive integer to choose the page to display.
schema:
type: integer
description: A positive integer to choose the page to display.
format: int32
- in: query
name: order_by
description: Ordering to use.
schema:
type: string
description: Ordering to use.
enum:
- name_asc
- name_desc
- created_at_asc
- created_at_desc
- updated_at_asc
- updated_at_desc
default: name_asc
- in: query
name: arch
description: Choose for which machine architecture to return images.
schema:
type: string
description: Choose for which machine architecture to return images.
- in: query
name: category
description: Choose the category of images to get.
schema:
type: string
description: Choose the category of images to get.
- in: query
name: include_eol
description: Choose to include end-of-life images.
required: true
schema:
type: boolean
description: Choose to include end-of-life images.
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: '#/components/schemas/scaleway.marketplace.v2.ListImagesResponse'
security:
- scaleway: []
x-codeSamples:
- lang: cURL
source: |-
curl -X GET \
-H "X-Auth-Token: $SCW_SECRET_KEY" \
"https://api.scaleway.com/marketplace/v2/images?include_eol=false"
- lang: HTTPie
source: |-
http GET "https://api.scaleway.com/marketplace/v2/images" \
X-Auth-Token:$SCW_SECRET_KEY \
include_eol==false
/marketplace/v2/images/{image_id}:
get:
tags:
- Marketplace Images
operationId: GetImage
summary: Get a specific marketplace image
description: Get detailed information about a marketplace image, specified by
its `image_id` (UUID format).
parameters:
- in: path
name: image_id
description: Display the image name. (UUID format)
required: true
schema:
type: string
description: Display the image name. (UUID format)
example: 6170692e-7363-616c-6577-61792e636f6d
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: '#/components/schemas/scaleway.marketplace.v2.Image'
security:
- scaleway: []
x-codeSamples:
- lang: cURL
source: |-
curl -X GET \
-H "X-Auth-Token: $SCW_SECRET_KEY" \
"https://api.scaleway.com/marketplace/v2/images/{image_id}"
- lang: HTTPie
source: |-
http GET "https://api.scaleway.com/marketplace/v2/images/{image_id}" \
X-Auth-Token:$SCW_SECRET_KEY
/marketplace/v2/local-images:
get:
tags:
- Marketplace Local Images
operationId: ListLocalImages
summary: List local images from a specific image or version
description: List information about local images in a specific Availability
Zone, specified by its `image_id` (UUID format), `version_id` (UUID format)
or `image_label`. Only one of these three parameters may be set.
parameters:
- in: query
name: page_size
schema:
type: integer
format: uint32
- in: query
name: page
schema:
$ref: '#/components/schemas/google.protobuf.Int32Value'
- in: query
name: order_by
schema:
$ref: '#/components/schemas/scaleway.marketplace.v2.ListLocalImagesRequest.OrderBy'
- in: query
name: zone
description: The zone you want to target
required: true
schema:
type: string
description: The zone you want to target
- in: query
name: type
schema:
$ref: '#/components/schemas/scaleway.marketplace.v2.LocalImage.Type'
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: '#/components/schemas/scaleway.marketplace.v2.ListLocalImagesResponse'
security:
- scaleway: []
x-codeSamples:
- lang: cURL
source: |-
curl -X GET \
-H "X-Auth-Token: $SCW_SECRET_KEY" \
"https://api.scaleway.com/marketplace/v2/local-images?zone=string"
- lang: HTTPie
source: |-
http GET "https://api.scaleway.com/marketplace/v2/local-images" \
X-Auth-Token:$SCW_SECRET_KEY \
zone==string
/marketplace/v2/local-images/{local_image_id}:
get:
tags:
- Marketplace Local Images
operationId: GetLocalImage
summary: Get a specific local image by ID
description: Get detailed information about a local image, including compatible
commercial types, supported architecture, labels and the Availability Zone
of the image, specified by its `local_image_id` (UUID format).
parameters:
- in: path
name: local_image_id
description: (UUID format)
required: true
schema:
type: string
description: (UUID format)
example: 6170692e-7363-616c-6577-61792e636f6d
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: '#/components/schemas/scaleway.marketplace.v2.LocalImage'
security:
- scaleway: []
x-codeSamples:
- lang: cURL
source: |-
curl -X GET \
-H "X-Auth-Token: $SCW_SECRET_KEY" \
"https://api.scaleway.com/marketplace/v2/local-images/{local_image_id}"
- lang: HTTPie
source: |-
http GET "https://api.scaleway.com/marketplace/v2/local-images/{local_image_id}" \
X-Auth-Token:$SCW_SECRET_KEY
/marketplace/v2/versions:
get:
tags:
- Marketplace Image Versions
operationId: ListVersions
summary: List versions of an Image
description: Get a list of all available version of an image, specified by its
`image_id` (UUID format).
parameters:
- in: query
name: image_id
description: (UUID format)
required: true
schema:
type: string
description: (UUID format)
example: 6170692e-7363-616c-6577-61792e636f6d
- in: query
name: page_size
schema:
type: integer
format: uint32
- in: query
name: page
schema:
$ref: '#/components/schemas/google.protobuf.Int32Value'
- in: query
name: order_by
schema:
$ref: '#/components/schemas/scaleway.marketplace.v2.ListVersionsRequest.OrderBy'
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: '#/components/schemas/scaleway.marketplace.v2.ListVersionsResponse'
security:
- scaleway: []
x-codeSamples:
- lang: cURL
source: |-
curl -X GET \
-H "X-Auth-Token: $SCW_SECRET_KEY" \
"https://api.scaleway.com/marketplace/v2/versions?image_id=6170692e-7363-616c-6577-61792e636f6d"
- lang: HTTPie
source: |-
http GET "https://api.scaleway.com/marketplace/v2/versions" \
X-Auth-Token:$SCW_SECRET_KEY \
image_id==6170692e-7363-616c-6577-61792e636f6d
/marketplace/v2/versions/{version_id}:
get:
tags:
- Marketplace Image Versions
operationId: GetVersion
summary: Get a specific image version
description: Get information such as the name, creation date, last update and
published date for an image version specified by its `version_id` (UUID format).
parameters:
- in: path
name: version_id
description: (UUID format)
required: true
schema:
type: string
description: (UUID format)
example: 6170692e-7363-616c-6577-61792e636f6d
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: '#/components/schemas/scaleway.marketplace.v2.Version'
security:
- scaleway: []
x-codeSamples:
- lang: cURL
source: |-
curl -X GET \
-H "X-Auth-Token: $SCW_SECRET_KEY" \
"https://api.scaleway.com/marketplace/v2/versions/{version_id}"
- lang: HTTPie
source: |-
http GET "https://api.scaleway.com/marketplace/v2/versions/{version_id}" \
X-Auth-Token:$SCW_SECRET_KEY