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.\n\n(switchcolumn)\n<Message type=\"important\">\nThis
    API documentation is for File Storage Service. File Storage can only be accessed
    through Private Networks.\n</Message>\n(switchcolumn)\n\n\n## Quickstart\n\n1.
    Configure environment:\n```bash\nexport SCW_SECRET_KEY=\"<API secret key>\" \nexport
    SCW_DEFAULT_REGION=\"<Scaleway Region>\"\nexport SCW_PROJECT_ID=\"<Scaleway Project
    ID>\"\n```\n\n2. Create a Scaleway File Storage:\n```bash\ncurl -X POST \\\n  -H
    \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n  -H \"Content-Type: application/json\"
    \\\n  https://api.scaleway.com/file/v1alpha1/regions/$SCW_DEFAULT_REGION/filesystems
    \\\n  -d '{\n    \"project_id\": \"'\"$SCW_PROJECT_ID\"'\",\n    \"name\": \"my-fs\",\n
    \   \"size\": 30000000000,\n  }'\n```\n\n3. Attach a Scaleway File Storage:\n```bash\ncurl
    -X POST 'https://api.scaleway.com/instance/v1/zones/$SCW_DEFAULT_REGION/servers/<instance-id>/attach-filesystem'
    \\\n  -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n  -H \"Content-Type: application/json\"
    \\\n  -d '{\"filesystem_id\": \"<my-fs-id>\"}'\n```\n\n4. Delete a Scaleway File
    Storage:\n```bash\ncurl -X DELETE 'https://api.scaleway.com/file/v1alpha1/regions/$SCW_DEFAULT_REGION/filesystems/<filesystem-id>'
    \\\n-H \"x-Auth-Token: $SCW_SECRET_KEY\"\n```\n\n5. Update a Scaleway File Storage:\n```bash\ncurl
    --request PATCH https://api.scaleway.com/file/v1alpha1/regions/$SCW_DEFAULT_REGION/filesystems/<filesystem-id>'
    \\\n--header 'Content-Type: application/json' \\\n--header \"x-Auth-Token: $SCW_SECRET_KEY\"
    \\\n--data '{\n  \"name\": \"my-new-fs-name\",\n  \"size\": 200000000000,\n  \"tags\":
    [] \n  }'\n```\n\n(switchcolumn)       \n\\<Message type=\"requirement\">\n- You
    have a [Scaleway account](https://console.scaleway.com/)\n- You have created an
    [API key](https://www.scaleway.com/en/docs/identity-and-access-management/iam/how-to/create-api-keys/)
    and that the API key has sufficient [IAM permissions](https://www.scaleway.com/en/docs/identity-and-access-management/iam/reference-content/permission-sets/)
    to perform the actions described on this page\n- You have [installed `curl`](https://curl.se/download.html)\n\\</Message>\n(switchcolumn)."
  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.
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.
      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
      x-properties-order:
      - id
      - name
      - size
      - status
      - project_id
      - organization_id
      - tags
      - number_of_attachments
      - region
      - created_at
      - updated_at
    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.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
          description: The region you want to target
          enum:
          - fr-par
      - in: query
        name: filesystem_id
        description: UUID of the File Storage volume. (UUID format)
        schema:
          type: string
          description: UUID of the File Storage volume. (UUID format)
          example: 6170692e-7363-616c-6577-61792e636f6d
      - in: query
        name: resource_id
        description: Filter by resource ID. (UUID format)
        schema:
          type: string
          description: Filter by resource ID. (UUID format)
          example: 6170692e-7363-616c-6577-61792e636f6d
      - in: query
        name: resource_type
        description: Filter by resource type.
        schema:
          type: string
          description: Filter by resource type.
          enum:
          - unknown_resource_type
          - instance_server
          default: unknown_resource_type
      - in: query
        name: zone
        description: Filter by resource zone.
        schema:
          type: string
          description: Filter by resource zone.
      - in: query
        name: page
        description: Page number (starting at 1).
        schema:
          type: integer
          description: Page number (starting at 1).
          format: int32
      - in: query
        name: page_size
        description: 'Number of entries per page (default: 20, max: 100).'
        schema:
          type: integer
          description: 'Number of entries per page (default: 20, max: 100).'
          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/fr-par/attachments"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/file/v1alpha1/regions/fr-par/attachments" \
            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
          description: The region you want to target
          enum:
          - fr-par
      - in: query
        name: order_by
        description: Criteria to use when ordering the list.
        schema:
          type: string
          description: Criteria to use when ordering the list.
          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
          description: Filter by project ID.
      - in: query
        name: organization_id
        description: Filter by organization ID.
        schema:
          type: string
          description: Filter by organization ID.
      - in: query
        name: page
        description: Page number (starting at 1).
        schema:
          type: integer
          description: Page number (starting at 1).
          format: int32
      - in: query
        name: page_size
        description: 'Number of entries per page (default: 20, max: 100).'
        schema:
          type: integer
          description: 'Number of entries per page (default: 20, max: 100).'
          format: uint32
      - in: query
        name: name
        description: Filter the returned filesystems by their names.
        schema:
          type: string
          description: Filter the returned filesystems by their names.
      - in: query
        name: tags
        description: Filter by tags. Only filesystems with one or more matching tags
          will be returned.
        schema:
          type: array
          description: Filter by tags. Only filesystems with one or more matching
            tags will be returned.
          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/fr-par/filesystems"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/file/v1alpha1/regions/fr-par/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
          description: The region you want to target
          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
                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
              - 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/fr-par/filesystems"
      - lang: HTTPie
        source: |-
          http POST "https://api.scaleway.com/file/v1alpha1/regions/fr-par/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
          description: The region you want to target
          enum:
          - fr-par
      - in: path
        name: filesystem_id
        description: UUID of the filesystem. (UUID format)
        required: true
        schema:
          type: string
          description: UUID of the filesystem. (UUID format)
          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/fr-par/filesystems/{filesystem_id}"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/file/v1alpha1/regions/fr-par/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
          description: The region you want to target
          enum:
          - fr-par
      - in: path
        name: filesystem_id
        description: UUID of the filesystem. (UUID format)
        required: true
        schema:
          type: string
          description: UUID of the filesystem. (UUID format)
          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.
                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
                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/fr-par/filesystems/{filesystem_id}"
      - lang: HTTPie
        source: |-
          http PATCH "https://api.scaleway.com/file/v1alpha1/regions/fr-par/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
          description: The region you want to target
          enum:
          - fr-par
      - in: path
        name: filesystem_id
        description: UUID of the filesystem. (UUID format)
        required: true
        schema:
          type: string
          description: UUID of the filesystem. (UUID format)
          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/fr-par/filesystems/{filesystem_id}"
      - lang: HTTPie
        source: |-
          http DELETE "https://api.scaleway.com/file/v1alpha1/regions/fr-par/filesystems/{filesystem_id}" \
            X-Auth-Token:$SCW_SECRET_KEY
