Scaleway Volumes API

openapi: 3.2.0
info:
  title: Instance Volumes API
  description: Scaleway Instances are virtual machines in the cloud.
  version: v1
servers:
- url: https://api.scaleway.com
tags:
- name: Volumes
  description: A volume is where you store your data inside your Instance.
paths:
  /instance/v1/zones/{zone}/block-migration/apply:
    post:
      tags:
      - Volumes
      operationId: ApplyBlockMigration
      summary: Migrate a volume and/or snapshots to SBS (Scaleway Block Storage)
      description: To be used, the call to this endpoint must be preceded by a call to the Get a volume or snapshot's migration plan endpoint. To migrate all resources mentioned in the migration plan, the validation_key returned in the plan must be provided.
      parameters:
      - in: path
        name: zone
        description: The zone you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par-1
          - fr-par-2
          - fr-par-3
          - nl-ams-1
          - nl-ams-2
          - nl-ams-3
          - pl-waw-1
          - pl-waw-2
          - pl-waw-3
          - it-mil-1
      responses:
        '204':
          description: ''
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                volume_id:
                  type: string
                  description: The volume to migrate, along with potentially other resources, according to the migration plan generated with a call to the [Get a volume or snapshot's migration plan](#path-volumes-get-a-volume-or-snapshots-migration-plan) endpoint.
                  nullable: true
                  x-one-of: resource
                snapshot_id:
                  type: string
                  description: The snapshot to migrate, along with potentially other resources, according to the migration plan generated with a call to the [Get a volume or snapshot's migration plan](#path-volumes-get-a-volume-or-snapshots-migration-plan) endpoint.
                  nullable: true
                  x-one-of: resource
                validation_key:
                  type: string
                  description: A value to be retrieved from a call to the [Get a volume or snapshot's migration plan](#path-volumes-get-a-volume-or-snapshots-migration-plan) endpoint, to confirm that the volume and/or snapshots specified in said plan should be migrated.
              required:
              - validation_key
              x-properties-order:
              - volume_id
              - snapshot_id
              - validation_key
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: "curl -X POST \\\n  -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"validation_key\":\"string\"}' \\\n  \"https://api.scaleway.com/instance/v1/zones/{zone}/block-migration/apply\""
      - lang: HTTPie
        source: "http POST \"https://api.scaleway.com/instance/v1/zones/{zone}/block-migration/apply\" \\\n  X-Auth-Token:$SCW_SECRET_KEY \\\n  validation_key=\"string\""
  /instance/v1/zones/{zone}/block-migration/plan:
    post:
      tags:
      - Volumes
      operationId: PlanBlockMigration
      summary: Get a volume or snapshot's migration plan
      description: 'Given a volume or snapshot, returns the migration plan but does not perform the actual migration. To perform the migration, you have to call the Migrate a volume and/or snapshots to SBS endpoint afterward.

        The endpoint returns the resources that should be migrated together:

        - the volume and any snapshots created from the volume, if the call was made to plan a volume migration.

        - the base volume of the snapshot (if the volume is not deleted) and its related snapshots, if the call was made to plan a snapshot migration.

        The endpoint also returns the validation_key, which must be provided to the Migrate a volume and/or snapshots to SBS endpoint to confirm that all resources listed in the plan should be migrated.'
      parameters:
      - in: path
        name: zone
        description: The zone you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par-1
          - fr-par-2
          - fr-par-3
          - nl-ams-1
          - nl-ams-2
          - nl-ams-3
          - pl-waw-1
          - pl-waw-2
          - pl-waw-3
          - it-mil-1
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.instance.v1.MigrationPlan'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                volume_id:
                  type: string
                  description: The volume for which the migration plan will be generated.
                  nullable: true
                  x-one-of: resource
                snapshot_id:
                  type: string
                  description: The snapshot for which the migration plan will be generated.
                  nullable: true
                  x-one-of: resource
              x-properties-order:
              - volume_id
              - snapshot_id
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: "curl -X POST \\\n  -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}' \\\n  \"https://api.scaleway.com/instance/v1/zones/{zone}/block-migration/plan\""
      - lang: HTTPie
        source: "http POST \"https://api.scaleway.com/instance/v1/zones/{zone}/block-migration/plan\" \\\n  X-Auth-Token:$SCW_SECRET_KEY"
  /instance/v1/zones/{zone}/volumes:
    get:
      tags:
      - Volumes
      operationId: ListVolumes
      summary: List volumes
      description: List volumes in the specified Availability Zone. You can filter the output by volume type.
      parameters:
      - in: path
        name: zone
        description: The zone you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par-1
          - fr-par-2
          - fr-par-3
          - nl-ams-1
          - nl-ams-2
          - nl-ams-3
          - pl-waw-1
          - pl-waw-2
          - pl-waw-3
          - it-mil-1
      - in: query
        name: volume_type
        description: Filter by volume type.
        schema:
          type: string
          enum:
          - l_ssd
          - b_ssd
          - unified
          - scratch
          - sbs_volume
          - sbs_snapshot
          x-enum-descriptions:
            values:
              b_ssd: Deprecated
              unified: Deprecated
          default: l_ssd
      - in: query
        name: per_page
        description: A positive integer lower or equal to 100 to select the number of items to return.
        schema:
          type: integer
          format: uint32
      - in: query
        name: page
        description: A positive integer to choose the page to return.
        schema:
          type: integer
          format: int32
      - in: query
        name: organization
        description: Filter volume by Organization ID.
        schema:
          type: string
      - in: query
        name: project
        description: Filter volume by Project ID.
        schema:
          type: string
      - in: query
        name: tags
        description: Filter volumes with these exact tags (to filter with several tags, use commas to separate them).
        schema:
          type: string
      - in: query
        name: name
        description: Filter volume by name (for eg. "vol" will return "myvolume" but not "data").
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.instance.v1.ListVolumesResponse'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: "curl -X GET \\\n  -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n  \"https://api.scaleway.com/instance/v1/zones/{zone}/volumes\""
      - lang: HTTPie
        source: "http GET \"https://api.scaleway.com/instance/v1/zones/{zone}/volumes\" \\\n  X-Auth-Token:$SCW_SECRET_KEY"
    post:
      tags:
      - Volumes
      operationId: CreateVolume
      summary: Create a volume
      description: Create a volume of a specified type in an Availability Zone.
      parameters:
      - in: path
        name: zone
        description: The zone you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par-1
          - fr-par-2
          - fr-par-3
          - nl-ams-1
          - nl-ams-2
          - nl-ams-3
          - pl-waw-1
          - pl-waw-2
          - pl-waw-3
          - it-mil-1
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.instance.v1.CreateVolumeResponse'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Volume name.
                organization:
                  type: string
                  description: Volume Organization ID.
                  deprecated: true
                  nullable: true
                  x-one-of: ProjectIdentifier
                project:
                  type: string
                  description: Volume Project ID.
                  nullable: true
                  x-one-of: ProjectIdentifier
                tags:
                  type: array
                  description: Volume tags.
                  items:
                    type: string
                volume_type:
                  type: string
                  description: Volume type.
                  enum:
                  - l_ssd
                  - b_ssd
                  - unified
                  - scratch
                  - sbs_volume
                  - sbs_snapshot
                  x-enum-descriptions:
                    values:
                      b_ssd: Deprecated
                      unified: Deprecated
                  default: l_ssd
                size:
                  type: integer
                  description: Volume disk size, must be a multiple of 512. (in bytes)
                  format: uint64
                  nullable: true
                  x-one-of: from
                base_snapshot:
                  type: string
                  description: ID of the snapshot on which this volume will be based.
                  nullable: true
                  x-one-of: from
              x-properties-order:
              - name
              - organization
              - project
              - tags
              - volume_type
              - size
              - base_snapshot
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: "curl -X POST \\\n  -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"string\"}' \\\n  \"https://api.scaleway.com/instance/v1/zones/{zone}/volumes\""
      - lang: HTTPie
        source: "http POST \"https://api.scaleway.com/instance/v1/zones/{zone}/volumes\" \\\n  X-Auth-Token:$SCW_SECRET_KEY \\\n  name=\"string\""
  /instance/v1/zones/{zone}/volumes/{id}:
    put:
      tags:
      - Volumes
      operationId: SetVolume
      summary: Update volume
      description: Replace all volume properties with a volume message.
      parameters:
      - in: path
        name: zone
        description: The zone you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par-1
          - fr-par-2
          - fr-par-3
          - nl-ams-1
          - nl-ams-2
          - nl-ams-3
          - pl-waw-1
          - pl-waw-2
          - pl-waw-3
          - it-mil-1
      - in: path
        name: id
        description: Unique ID of the volume.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.instance.v1.SetVolumeResponse'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the volume.
                tags:
                  type: array
                  description: Tags of the volume.
                  nullable: true
                  items:
                    type: string
                export_uri:
                  type: string
                  description: NBD export URI of the Volume (deprecated, this field is ignored).
                  deprecated: true
                size:
                  type: integer
                  description: Volume's disk size, must be a multiple of 512. (in bytes)
                  format: uint64
                volume_type:
                  type: string
                  description: Volume type.
                  enum:
                  - l_ssd
                  - b_ssd
                  - unified
                  - scratch
                  - sbs_volume
                  - sbs_snapshot
                  x-enum-descriptions:
                    values:
                      b_ssd: Deprecated
                      unified: Deprecated
                  default: l_ssd
                creation_date:
                  type: string
                  description: Volume creation date. (RFC 3339 format)
                  format: date-time
                  example: '2022-03-22T12:34:56.123456Z'
                  nullable: true
                modification_date:
                  type: string
                  description: Volume modification date. (RFC 3339 format)
                  format: date-time
                  example: '2022-03-22T12:34:56.123456Z'
                  nullable: true
                organization:
                  type: string
                  description: Volume Organization ID.
                project:
                  type: string
                  description: Volume Project ID.
                server:
                  type: object
                  description: Instance attached to the volume.
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                  x-properties-order:
                  - id
                  - name
                state:
                  type: string
                  description: Volume state.
                  enum:
                  - available
                  - snapshotting
                  - fetching
                  - saving
                  - attaching
                  - resizing
                  - hotsyncing
                  - error
                  default: available
              x-properties-order:
              - name
              - tags
              - export_uri
              - size
              - volume_type
              - creation_date
              - modification_date
              - organization
              - project
              - server
              - state
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: "curl -X PUT \\\n  -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"export_uri\": \"string\",\n    \"name\": \"string\",\n    \"organization\": \"string\",\n    \"project\": \"string\",\n    \"size\": 42\n  }' \\\n  \"https://api.scaleway.com/instance/v1/zones/{zone}/volumes/{id}\""
      - lang: HTTPie
        source: "http PUT \"https://api.scaleway.com/instance/v1/zones/{zone}/volumes/{id}\" \\\n  X-Auth-Token:$SCW_SECRET_KEY \\\n  export_uri=\"string\" \\\n  name=\"string\" \\\n  organization=\"string\" \\\n  project=\"string\" \\\n  size:=42"
  /instance/v1/zones/{zone}/volumes/{volume_id}:
    get:
      tags:
      - Volumes
      operationId: GetVolume
      summary: Get a volume
      description: Get details of a volume with the specified ID.
      parameters:
      - in: path
        name: zone
        description: The zone you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par-1
          - fr-par-2
          - fr-par-3
          - nl-ams-1
          - nl-ams-2
          - nl-ams-3
          - pl-waw-1
          - pl-waw-2
          - pl-waw-3
          - it-mil-1
      - in: path
        name: volume_id
        description: UUID of the volume you want to get.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.instance.v1.GetVolumeResponse'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: "curl -X GET \\\n  -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n  \"https://api.scaleway.com/instance/v1/zones/{zone}/volumes/{volume_id}\""
      - lang: HTTPie
        source: "http GET \"https://api.scaleway.com/instance/v1/zones/{zone}/volumes/{volume_id}\" \\\n  X-Auth-Token:$SCW_SECRET_KEY"
    patch:
      tags:
      - Volumes
      operationId: UpdateVolume
      summary: Update a volume
      description: Replace the name and/or size properties of a volume specified by its ID, with the specified value(s).
      parameters:
      - in: path
        name: zone
        description: The zone you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par-1
          - fr-par-2
          - fr-par-3
          - nl-ams-1
          - nl-ams-2
          - nl-ams-3
          - pl-waw-1
          - pl-waw-2
          - pl-waw-3
          - it-mil-1
      - in: path
        name: volume_id
        description: UUID of the volume.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.instance.v1.UpdateVolumeResponse'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Volume name.
                  nullable: true
                tags:
                  type: array
                  description: Tags of the volume.
                  nullable: true
                  items:
                    type: string
                size:
                  type: integer
                  description: Volume disk size, must be a multiple of 512. (in bytes)
                  format: uint64
                  nullable: true
              x-properties-order:
              - name
              - tags
              - size
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: "curl -X PATCH \\\n  -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}' \\\n  \"https://api.scaleway.com/instance/v1/zones/{zone}/volumes/{volume_id}\""
      - lang: HTTPie
        source: "http PATCH \"https://api.scaleway.com/instance/v1/zones/{zone}/volumes/{volume_id}\" \\\n  X-Auth-Token:$SCW_SECRET_KEY"
    delete:
      tags:
      - Volumes
      operationId: DeleteVolume
      summary: Delete a volume
      description: Delete the volume with the specified ID.
      parameters:
      - in: path
        name: zone
        description: The zone you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par-1
          - fr-par-2
          - fr-par-3
          - nl-ams-1
          - nl-ams-2
          - nl-ams-3
          - pl-waw-1
          - pl-waw-2
          - pl-waw-3
          - it-mil-1
      - in: path
        name: volume_id
        description: UUID of the volume you want to delete.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: ''
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: "curl -X DELETE \\\n  -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n  \"https://api.scaleway.com/instance/v1/zones/{zone}/volumes/{volume_id}\""
      - lang: HTTPie
        source: "http DELETE \"https://api.scaleway.com/instance/v1/zones/{zone}/volumes/{volume_id}\" \\\n  X-Auth-Token:$SCW_SECRET_KEY"
components:
  schemas:
    scaleway.instance.v1.MigrationPlan:
      type: object
      properties:
        volume:
          type: object
          description: A volume which will be migrated to SBS together with the snapshots, if present.
          properties:
            id:
              type: string
              description: Volume unique ID.
            name:
              type: string
              description: Volume name.
            export_uri:
              type: string
              description: Show the volume NBD export URI (deprecated, will always be empty).
              deprecated: true
            size:
              type: integer
              description: Volume disk size. (in bytes)
              format: uint64
            volume_type:
              type: string
              description: Volume type.
              enum:
              - l_ssd
              - b_ssd
              - unified
              - scratch
              - sbs_volume
              - sbs_snapshot
              x-enum-descriptions:
                values:
                  b_ssd: Deprecated
                  unified: Deprecated
              default: l_ssd
            creation_date:
              type: string
              description: Volume creation date. (RFC 3339 format)
              format: date-time
              example: '2022-03-22T12:34:56.123456Z'
              nullable: true
            modification_date:
              type: string
              description: Volume modification date. (RFC 3339 format)
              format: date-time
              example: '2022-03-22T12:34:56.123456Z'
              nullable: true
            organization:
              type: string
              description: Volume Organization ID.
            project:
              type: string
              description: Volume Project ID.
            tags:
              type: array
              description: Volume tags.
              items:
                type: string
            server:
              type: object
              description: Instance attached to the volume.
              properties:
                id:
                  type: string
                name:
                  type: string
              x-properties-order:
              - id
              - name
            state:
              type: string
              description: Volume state.
              enum:
              - available
              - snapshotting
              - fetching
              - saving
              - attaching
              - resizing
              - hotsyncing
              - error
              default: available
            zone:
              type: string
              description: Zone in which the volume is located.
          x-properties-order:
          - id
          - name
          - export_uri
          - size
          - volume_type
          - creation_date
          - modification_date
          - organization
          - project
          - tags
          - server
          - state
          - zone
        snapshots:
          type: array
          description: A list of snapshots which will be migrated to SBS together and with the volume, if present.
          items:
            $ref: '#/components/schemas/scaleway.instance.v1.Snapshot'
        validation_key:
          type: string
          description: A value to be passed to the call to the [Migrate a volume and/or snapshots to SBS](#path-volumes-migrate-a-volume-andor-snapshots-to-sbs-scaleway-block-storage) endpoint, to confirm that the execution of the plan is being requested.
      x-properties-order:
      - volume
      - snapshots
      - validation_key
    scaleway.instance.v1.CreateVolumeResponse:
      type: object
      properties:
        volume:
          $ref: '#/components/schemas/scaleway.instance.v1.Volume'
      x-properties-order:
      - volume
    scaleway.instance.v1.ListVolumesResponse:
      type: object
      properties:
        volumes:
          type: array
          description: List of volumes.
          items:
            $ref: '#/components/schemas/scaleway.instance.v1.Volume'
      x-properties-order:
      - volumes
    scaleway.instance.v1.SetVolumeResponse:
      type: object
      properties:
        volume:
          $ref: '#/components/schemas/scaleway.instance.v1.Volume'
      x-properties-order:
      - volume
    scaleway.instance.v1.UpdateVolumeResponse:
      type: object
      properties:
        volume:
          $ref: '#/components/schemas/scaleway.instance.v1.Volume'
      x-properties-order:
      - volume
    scaleway.instance.v1.Volume:
      type: object
      properties:
        id:
          type: string
          description: Volume unique ID.
        name:
          type: string
          description: Volume name.
        export_uri:
          type: string
          description: Show the volume NBD export URI (deprecated, will always be empty).
          deprecated: true
        size:
          type: integer
          description: Volume disk size. (in bytes)
          format: uint64
        volume_type:
          type: string
          description: Volume type.
          enum:
          - l_ssd
          - b_ssd
          - unified
          - scratch
          - sbs_volume
          - sbs_snapshot
          x-enum-descriptions:
            values:
              b_ssd: Deprecated
              unified: Deprecated
          default: l_ssd
        creation_date:
          type: string
          description: Volume creation date. (RFC 3339 format)
          format: date-time
          example: '2022-03-22T12:34:56.123456Z'
          nullable: true
        modification_date:
          type: string
          description: Volume modification date. (RFC 3339 format)
          format: date-time
          example: '2022-03-22T12:34:56.123456Z'
          nullable: true
        organization:
          type: string
          description: Volume Organization ID.
        project:
          type: string
          description: Volume Project ID.
        tags:
          type: array
          description: Volume tags.
          items:
            type: string
        server:
          type: object
          description: Instance attached to the volume.
          properties:
            id:
              type: string
            name:
              type: string
          x-properties-order:
          - id
          - name
        state:
          type: string
          description: Volume state.
          enum:
          - available
          - snapshotting
          - fetching
          - saving
          - attaching
          - resizing
          - hotsyncing
          - error
          default: available
        zone:
          type: string
          description: Zone in which the volume is located.
      x-properties-order:
      - id
      - name
      - export_uri
      - size
      - volume_type
      - creation_date
      - modification_date
      - organization
      - project
      - tags
      - server
      - state
      - zone
    scaleway.instance.v1.Snapshot:
      type: object
      properties:
        id:
          type: string
          description: Snapshot ID.
        name:
          type: string
          description: Snapshot name.
        organization:
          type: string
          description: Snapshot Organization ID.
        project:
          type: string
          description: Snapshot Project ID.
        tags:
          type: array
          description: Snapshot tags.
          items:
            type: string
        volume_type:
          type: string
          description: Snapshot volume type.
          enum:
          - l_ssd
          - b_ssd
          - unified
          - scratch
          - sbs_volume
          - sbs_snapshot
          x-enum-descriptions:
            values:
              b_ssd: Deprecated
              unified: Deprecated
          default: l_ssd
        size:
          type: integer
          description: Snapshot size. (in bytes)
          format: uint64
        state:
          type: string
          description: Snapshot state.
          enum:
          - available
          - snapshotting
          - error
          - invalid_data
          - importing
          - exporting
          default: available
        base_volume:
          type: object
          description: Volume on which the snapshot is based on.
          properties:
            id:
              type: string
              description: Volume ID on which the snapshot is based.
            name:
              type: string
              description: Volume name on which the snapshot is based on.
          x-properties-order:
          - id
          - name
        creation_date:
          type: string
          description: Snapshot creation date. (RFC 3339 format)
          format: date-time
          example: '2022-03-22T12:34:56.123456Z'
          nullable: true
        modification_date:
          type: string
          description: Snapshot modification date. (RFC 3339 format)
          format: date-time
          example: '2022-03-22T12:34:56.123456Z'
          nullable: true
        zone:
          type: string
          description: Snapshot zone.
        error_reason:
          type: string
          description: Reason for the failed snapshot import.
          nullable: true
      x-properties-order:
      - id
      - name
      - organization
      - project
      - tags
      - volume_type
      - size
      - state
      - base_volume
      - creation_date
      - modification_date
      - zone
      - error_reason
    scaleway.instance.v1.GetVolumeResponse:
      type: object
      properties:
        volume:
          $ref: '#/components/schemas/scaleway.instance.v1.Volume'
      x-properties-order:
      - volume
  securitySchemes:
    scaleway:
      in: header
      name: X-Auth-Token
      type: apiKey