openapi: 3.1.0
info:
  title: File Storage API
  description: |-
    Scaleway File Storage provides network-attached storage that can be attached to cloud products such as Instances. File Storage can be accessed simultaneously by multiple Instances in the same region.


    <Message type="important">
    This API documentation is for File Storage Service. File Storage can only be accessed through Private Networks.
    </Message>



    ## Quickstart

    1. Configure environment:
        ```bash
        export SCW_SECRET_KEY="<API secret key>"
        export SCW_DEFAULT_REGION="<Scaleway Region>"
        export SCW_PROJECT_ID="<Scaleway Project ID>"
        ```

    2. Create a Scaleway File Storage:
        ```bash
        curl -X POST \
          -H "X-Auth-Token: $SCW_SECRET_KEY" \
          -H "Content-Type: application/json" \
          https://api.scaleway.com/file/v1alpha1/regions/$SCW_DEFAULT_REGION/filesystems \
          -d '{
            "project_id": "'"$SCW_PROJECT_ID"'",
            "name": "my-fs",
            "size": 30000000000,
          }'
        ```

    3. Attach a Scaleway File Storage:
        ```bash
        curl -X POST 'https://api.scaleway.com/instance/v1/zones/$SCW_DEFAULT_REGION/servers/<instance-id>/attach-filesystem' \
          -H "X-Auth-Token: $SCW_SECRET_KEY" \
          -H "Content-Type: application/json" \
          -d '{"filesystem_id": "<my-fs-id>"}'
        ```

    4. Delete a Scaleway File Storage:
        ```bash
        curl -X DELETE 'https://api.scaleway.com/file/v1alpha1/regions/$SCW_DEFAULT_REGION/filesystems/<filesystem-id>' \
        -H "x-Auth-Token: $SCW_SECRET_KEY"
        ```

    5. Update a Scaleway File Storage:
        ```bash
        curl --request PATCH https://api.scaleway.com/file/v1alpha1/regions/$SCW_DEFAULT_REGION/filesystems/<filesystem-id>' \
        --header 'Content-Type: application/json' \
        --header "x-Auth-Token: $SCW_SECRET_KEY" \
        --data '{
          "name": "my-new-fs-name",
          "size": 200000000000,
          "tags": []
          }'
        ```


    \<Message type="requirement">
    - You have a [Scaleway account](https://console.scaleway.com/)
    - You have created an [API key](https://www.scaleway.com/en/docs/iam/how-to/create-api-keys/) and that the API key has sufficient [IAM permissions](https://www.scaleway.com/en/docs/iam/reference-content/permission-sets/) to perform the actions described on this page
    - You have [installed `curl`](https://curl.se/download.html)
    \</Message>
  version: v1alpha1
servers:
- url: https://api.scaleway.com
tags:
- name: FileSystem
  description: |
    A filesystem is a network-attached shared storage system that can be connected to multiple Instances simultaneously. Filesystems are accessible in read/write modes, and can be created with different sizes.
- name: Attachment
  description: |
    An attachment links a filesystem and a Scaleway resource (such as an Instance).
    An attachment is created when a filesystem is mounted to a resource, and is deleted when a filesystem is unmounted from a resource.
- name: FileSystem Type
  description: |
    Filesystem type are determined by their storage class, performances and resiliency levels
components:
  schemas:
    scaleway.file.v1alpha1.Attachment:
      type: object
      properties:
        id:
          type: string
          description: UUID of the attachment. (UUID format)
          example: 6170692e-7363-616c-6577-61792e636f6d
        filesystem_id:
          type: string
          description: UUID of the filesystem. (UUID format)
          example: 6170692e-7363-616c-6577-61792e636f6d
        resource_id:
          type: string
          description: UUID of the attached resource. (UUID format)
          example: 6170692e-7363-616c-6577-61792e636f6d
        resource_type:
          type: string
          description: The type of the attached resource.
          enum:
          - unknown_resource_type
          - instance_server
          default: unknown_resource_type
        zone:
          type: string
          description: The zone where the resource is located.
          nullable: true
      x-properties-order:
      - id
      - filesystem_id
      - resource_id
      - resource_type
      - zone
    scaleway.file.v1alpha1.FileSystem:
      type: object
      properties:
        id:
          type: string
          description: UUID of the filesystem. (UUID format)
          example: 6170692e-7363-616c-6577-61792e636f6d
        name:
          type: string
          description: Name of the filesystem.
        size:
          type: integer
          description: Filesystem size in bytes. (in bytes)
          format: uint64
        status:
          type: string
          description: Current status of the filesystem (e.g. creating, available,
            ...).
          enum:
          - unknown_status
          - available
          - error
          - creating
          - updating
          x-enum-descriptions:
            values:
              unknown_status: If unspecified, the filesystem status is unknown by
                default
              available: The filesystem is created and available
              error: The filesystem is in error state
              creating: The filesystem is under creation (transient)
              updating: The filesystem is being updated (transient)
          default: unknown_status
        project_id:
          type: string
          description: UUID of the project to which the filesystem belongs. (UUID
            format)
          example: 6170692e-7363-616c-6577-61792e636f6d
        organization_id:
          type: string
          description: UUID of the organization to which the filesystem belongs. (UUID
            format)
          example: 6170692e-7363-616c-6577-61792e636f6d
        tags:
          type: array
          description: List of tags assigned to the filesystem.
          items:
            type: string
        number_of_attachments:
          type: integer
          description: The current number of attachments (mounts) that the filesystem
            has.
          format: uint32
        region:
          type: string
          description: Region where the filesystem is located.
        created_at:
          type: string
          description: Creation date of the filesystem. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        updated_at:
          type: string
          description: Last update date of the properties of the filesystem. (RFC
            3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        filesystem_type_id:
          type: string
          description: UUID of the filesystem type. (UUID format)
          example: 6170692e-7363-616c-6577-61792e636f6d
      x-properties-order:
      - id
      - name
      - size
      - status
      - project_id
      - organization_id
      - tags
      - number_of_attachments
      - region
      - created_at
      - updated_at
      - filesystem_type_id
    scaleway.file.v1alpha1.FileSystemType:
      type: object
      properties:
        name:
          type: string
          description: Filesystem type name.
        filesystem_price_gb_per_hour:
          type: object
          description: Price of the filesystem billed in GB/hour.
          properties:
            currency_code:
              type: string
            units:
              type: integer
              format: int64
            nanos:
              type: integer
              format: int32
          x-properties-order:
          - currency_code
          - units
          - nanos
        snapshot_price_gb_per_hour:
          type: object
          description: Price of the snapshot billed in GB/hour.
          properties:
            currency_code:
              type: string
            units:
              type: integer
              format: int64
            nanos:
              type: integer
              format: int32
          x-properties-order:
          - currency_code
          - units
          - nanos
      x-properties-order:
      - name
      - filesystem_price_gb_per_hour
      - snapshot_price_gb_per_hour
    scaleway.file.v1alpha1.ListAttachmentsResponse:
      type: object
      properties:
        attachments:
          type: array
          description: List of filesystem attachments matching the request criteria.
          items:
            $ref: '#/components/schemas/scaleway.file.v1alpha1.Attachment'
        total_count:
          type: integer
          description: Total number of filesystem attachments matching the criteria.
          format: uint64
      x-properties-order:
      - attachments
      - total_count
    scaleway.file.v1alpha1.ListFileSystemTypesResponse:
      type: object
      properties:
        filesystem_types:
          type: array
          description: Returns paginated list of filesystem-types.
          items:
            $ref: '#/components/schemas/scaleway.file.v1alpha1.FileSystemType'
        total_count:
          type: integer
          description: Total number of file system types.
          format: uint64
      x-properties-order:
      - filesystem_types
      - total_count
    scaleway.file.v1alpha1.ListFileSystemsResponse:
      type: object
      properties:
        filesystems:
          type: array
          description: List of filesystems matching the request criteria.
          items:
            $ref: '#/components/schemas/scaleway.file.v1alpha1.FileSystem'
        total_count:
          type: integer
          description: Total number of filesystems matching the criteria.
          format: uint64
      x-properties-order:
      - filesystems
      - total_count
  securitySchemes:
    scaleway:
      in: header
      name: X-Auth-Token
      type: apiKey
paths:
  /file/v1alpha1/regions/{region}/attachments:
    get:
      tags:
      - Attachment
      operationId: ListAttachments
      summary: List filesystems attachments
      description: |-
        List all existing attachments in a specified region.
        By default, the attachments listed are ordered by creation date in ascending order. This can be modified using the `order_by` field.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
      - in: query
        name: filesystem_id
        description: UUID of the File Storage volume. (UUID format)
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      - in: query
        name: resource_id
        description: Filter by resource ID. (UUID format)
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      - in: query
        name: resource_type
        description: Filter by resource type.
        schema:
          type: string
          enum:
          - unknown_resource_type
          - instance_server
          default: unknown_resource_type
      - in: query
        name: zone
        description: Filter by resource zone.
        schema:
          type: string
      - in: query
        name: page
        description: Page number (starting at 1).
        schema:
          type: integer
          format: int32
      - in: query
        name: page_size
        description: 'Number of entries per page (default: 20, max: 100).'
        schema:
          type: integer
          format: uint32
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.file.v1alpha1.ListAttachmentsResponse'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/file/v1alpha1/regions/{region}/attachments"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/file/v1alpha1/regions/{region}/attachments" \
            X-Auth-Token:$SCW_SECRET_KEY
  /file/v1alpha1/regions/{region}/filesystem-types:
    get:
      tags:
      - FileSystem Type
      operationId: ListFileSystemTypes
      summary: List filesystems types
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
      - in: query
        name: page
        description: Page number (starts at 1).
        schema:
          type: integer
          format: int32
      - in: query
        name: page_size
        description: 'Number of entries per page (default: 50, max: 100).'
        schema:
          type: integer
          format: uint32
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.file.v1alpha1.ListFileSystemTypesResponse'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/file/v1alpha1/regions/{region}/filesystem-types"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/file/v1alpha1/regions/{region}/filesystem-types" \
            X-Auth-Token:$SCW_SECRET_KEY
  /file/v1alpha1/regions/{region}/filesystems:
    get:
      tags:
      - FileSystem
      operationId: ListFileSystems
      summary: List all filesystems
      description: Retrieve all filesystems in the specified region. By default, the
        filesystems listed are ordered by creation date in ascending order. This can
        be modified using the `order_by` field.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
      - in: query
        name: order_by
        description: Criteria to use when ordering the list.
        schema:
          type: string
          enum:
          - created_at_asc
          - created_at_desc
          - name_asc
          - name_desc
          x-enum-descriptions:
            values:
              created_at_asc: Order by creation date (ascending)
              created_at_desc: Order by creation date (descending)
              name_asc: Order by name (ascending)
              name_desc: Order by name (descending)
          default: created_at_asc
      - in: query
        name: project_id
        description: Filter by project ID.
        schema:
          type: string
      - in: query
        name: organization_id
        description: Filter by organization ID.
        schema:
          type: string
      - in: query
        name: page
        description: Page number (starting at 1).
        schema:
          type: integer
          format: int32
      - in: query
        name: page_size
        description: 'Number of entries per page (default: 20, max: 100).'
        schema:
          type: integer
          format: uint32
      - in: query
        name: name
        description: Filter the returned filesystems by their names.
        schema:
          type: string
      - in: query
        name: filesystem_type
        description: Type of the filesystem.
        schema:
          type: string
      - in: query
        name: tags
        description: Filter by tags. Only filesystems with one or more matching tags
          will be returned.
        schema:
          type: array
          items:
            type: string
      - in: query
        name: filesystem_ids
        description: Filter by filesystem IDs. Only filesystems with one or more matching
          IDs will be returned.
        schema:
          type: array
          items:
            type: string
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.file.v1alpha1.ListFileSystemsResponse'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/file/v1alpha1/regions/{region}/filesystems"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/file/v1alpha1/regions/{region}/filesystems" \
            X-Auth-Token:$SCW_SECRET_KEY
    post:
      tags:
      - FileSystem
      operationId: CreateFileSystem
      summary: Create a new filesystem
      description: To create a new filesystem, you must specify a name, a size, and
        a project ID.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.file.v1alpha1.FileSystem'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the filesystem.
                project_id:
                  type: string
                  description: UUID of the project the filesystem belongs to. (UUID
                    format)
                  example: 6170692e-7363-616c-6577-61792e636f6d
                size:
                  type: integer
                  description: |-
                    Filesystem size in bytes, with a granularity of 100 GB (10^11 bytes).
                    Must be compliant with the minimum (100 GB) and maximum (10 TB) allowed size.
                  format: uint64
                type:
                  type: string
                  description: Type of the filesystem.
                  nullable: true
                tags:
                  type: array
                  description: List of tags assigned to the filesystem.
                  items:
                    type: string
              required:
              - name
              - project_id
              - size
              x-properties-order:
              - name
              - project_id
              - size
              - type
              - tags
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X POST \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            -H "Content-Type: application/json" \
            -d '{
              "name": "string",
              "project_id": "6170692e-7363-616c-6577-61792e636f6d",
              "size": 42
            }' \
            "https://api.scaleway.com/file/v1alpha1/regions/{region}/filesystems"
      - lang: HTTPie
        source: |-
          http POST "https://api.scaleway.com/file/v1alpha1/regions/{region}/filesystems" \
            X-Auth-Token:$SCW_SECRET_KEY \
            name="string" \
            project_id="6170692e-7363-616c-6577-61792e636f6d" \
            size:=42
  /file/v1alpha1/regions/{region}/filesystems/{filesystem_id}:
    get:
      tags:
      - FileSystem
      operationId: GetFileSystem
      summary: Get filesystem details
      description: Retrieve all properties and current status of a specific filesystem
        identified by its ID.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
      - in: path
        name: filesystem_id
        description: UUID of the filesystem. (UUID format)
        required: true
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.file.v1alpha1.FileSystem'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/file/v1alpha1/regions/{region}/filesystems/{filesystem_id}"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/file/v1alpha1/regions/{region}/filesystems/{filesystem_id}" \
            X-Auth-Token:$SCW_SECRET_KEY
    patch:
      tags:
      - FileSystem
      operationId: UpdateFileSystem
      summary: Update filesystem properties
      description: Update the technical details of a filesystem, such as its name,
        tags or its new size.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
      - in: path
        name: filesystem_id
        description: UUID of the filesystem. (UUID format)
        required: true
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.file.v1alpha1.FileSystem'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: When defined, is the new name of the filesystem.
                  nullable: true
                size:
                  type: integer
                  description: |-
                    Optional field for increasing the size of the filesystem (must be larger than the current size).
                    Size in bytes, with a granularity of 100 GB (10^11 bytes).
                    Must be compliant with the minimum (100 GB) and maximum (10 TB) allowed size.
                  format: uint64
                  nullable: true
                tags:
                  type: array
                  description: List of tags assigned to the filesystem.
                  nullable: true
                  items:
                    type: string
              x-properties-order:
              - name
              - size
              - tags
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X PATCH \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            -H "Content-Type: application/json" \
            -d '{}' \
            "https://api.scaleway.com/file/v1alpha1/regions/{region}/filesystems/{filesystem_id}"
      - lang: HTTPie
        source: |-
          http PATCH "https://api.scaleway.com/file/v1alpha1/regions/{region}/filesystems/{filesystem_id}" \
            X-Auth-Token:$SCW_SECRET_KEY
    delete:
      tags:
      - FileSystem
      operationId: DeleteFileSystem
      summary: Delete a detached filesystem
      description: You must specify the `filesystem_id` of the filesystem you want
        to delete.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
      - in: path
        name: filesystem_id
        description: UUID of the filesystem. (UUID format)
        required: true
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      responses:
        "204":
          description: ""
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X DELETE \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/file/v1alpha1/regions/{region}/filesystems/{filesystem_id}"
      - lang: HTTPie
        source: |-
          http DELETE "https://api.scaleway.com/file/v1alpha1/regions/{region}/filesystems/{filesystem_id}" \
            X-Auth-Token:$SCW_SECRET_KEY