openapi: 3.1.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.


    <Message type="note">
    Check out the [Instance API](https://www.scaleway.com/en/developers/api/instance/)
    </Message>


    ## Concepts

    Refer to [the Instances concepts page](https://www.scaleway.com/en/docs/instances/concepts/) 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:

        ```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": [
                "COPARM1-2C-8G",
                "COPARM1-4C-16G",
                [...]
              ],
              "label": "ubuntu_jammy"
            }
          ],
          "total_count": 2
        }
        ```


    <Message type="requirement">
    - 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)
    </Message>


    ## Technical information

    ### Availability Zones

    Scaleway's infrastructure is spread across different [regions and Availability Zones](https://www.scaleway.com/en/docs/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").
            This label can be used in the image field of the server creation request.
      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.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.
            This label can be used in the image field of the server creation request.
        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.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
          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
          format: uint32
      - in: query
        name: page
        description: A positive integer to choose the page to display.
        schema:
          type: integer
          format: int32
      - in: query
        name: order_by
        description: Ordering to use.
        schema:
          type: string
          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
      - in: query
        name: category
        description: Choose the category of images to get.
        schema:
          type: string
      - in: query
        name: include_eol
        description: Choose to include end-of-life images.
        required: true
        schema:
          type: boolean
      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
          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
        description: A positive integer lower or equal to 100 to select the number
          of items to display.
        schema:
          type: integer
          format: uint32
      - in: query
        name: page
        description: A positive integer to choose the page to display.
        schema:
          type: integer
          format: int32
      - in: query
        name: order_by
        description: Ordering to use.
        schema:
          type: string
          enum:
          - type_asc
          - type_desc
          - created_at_asc
          - created_at_desc
          default: type_asc
      - in: query
        name: zone
        description: Filter local images available on this Availability Zone.
        required: true
        schema:
          type: string
      - in: query
        name: arch
        description: Filter local images available for this machine architecture.
        schema:
          type: string
      - in: query
        name: type
        description: Filter by type.
        schema:
          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
      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
          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
          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
          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