File Storage

Download schema

File Storage is a scalable file storage service that provides shared access to files over a network using the NFS protocol.

The File Storage API allows the creation, configuration, and deletion of file storage service, as well as monitoring of network and storage usage.

API follows JSON Merge Patch semantics. Note when modifying nested structures payload should contain entire array, which in a sense is PUT within PATCH for them. JSON Merge Patch uses null to explicitly indicate property deletion while absent properties are ignored, i.e. not modified.

List services

GET

https://api.upcloud.com

/1.3/file-storage

Returns a list of File Storage services.

List services › query Parameters

limit

fileStorageQueryParameterLimit · min: 0 · max: 100

Number of entries to receive at most.

Schema for the limit query parameter, used to specify the maximum number of items to return in a paginated response.

Default: 10

offset

fileStorageQueryParamOffset · min: 0

Offset for retrieved results.

Query parameter to specify the offset for pagination in API responses, allowing clients to retrieve results starting from a specific point.

Default: 0

sort

fileStorageQueryParamSort · enum

Order of returned results.

Query parameter to specify the sorting order of results in API responses, allowing clients to order data based on specific fields.

Enum values:

created_at

-created_at

Default: -created_at

List services › Responses

Success

fileStorageServiceDetailResponse[]

Schema for the response containing a list of services.

Example: [{"configured_status":"started","created_at":"2025-08-01T10:40:04.140473Z","encrypted":false,"labels":[{"key":"environment","value":"production"}],"name":"test2","networks":[{"family":"IPv4","ip_address":"10.10.10.50","name":"net","uuid":"0391f203-6eef-4a69-bfcc-fffffbdfdc32"}],"operational_state":"running","shares":[{"acl":[{"name":"test-name","permission":"ro","target":"*"}],"name":"read","path":"/public"},{"acl":[{"name":"test-name","permission":"rw","target":"10.10.10.0/24"},{"name":"test-name","permission":"rw","target":"local.domain"}],"name":"write","path":"/project/data"}],"size_gib":250,"state_messages":[],"updated_at":"2025-08-03T19:23:52.350216Z","uuid":"17871d62-6964-4336-b68d-4a85a8ee10fe","zone":"fi-dev2"}]

Schema for the detailed response of a service.

fileStorageServiceDetailResponse

uuid

string

name

string

zone

string

configured_status

string

operational_state

string

size_gib

integer · int32

encrypted

boolean

fileStorageNetworkDetailResponse[]

fileStorageShareDetailResponse[]

fileStorageLabelDetails[]

object[]

created_at

string · date-time

updated_at

string · date-time

GET/1.3/file-storage

curl https://api.upcloud.com/1.3/file-storage \
  --header 'Authorization: Bearer <token>'

Example Responses

[
  {
    "configured_status": "started",
    "created_at": "2025-08-01T10:40:04.140473Z",
    "encrypted": false,
    "labels": [
      {
        "key": "environment",
        "value": "production"
      }
    ],
    "name": "test2",
    "networks": [
      {
        "family": "IPv4",
        "ip_address": "10.10.10.50",
        "name": "net",
        "uuid": "0391f203-6eef-4a69-bfcc-fffffbdfdc32"
      }
    ],
    "operational_state": "running",
    "shares": [
      {
        "acl": [
          {
            "name": "test-name",
            "permission": "ro",
            "target": "*"
          }
        ],
        "name": "read",
        "path": "/public"
      },
      {
        "acl": [
          {
            "name": "test-name",
            "permission": "rw",
            "target": "10.10.10.0/24"
          },
          {
            "name": "test-name",
            "permission": "rw",
            "target": "local.domain"
          }
        ],
        "name": "write",
        "path": "/project/data"
      }
    ],
    "size_gib": 250,
    "state_messages": [],
    "updated_at": "2025-08-03T19:23:52.350216Z",
    "uuid": "17871d62-6964-4336-b68d-4a85a8ee10fe",
    "zone": "fi-dev2"
  }
]

json

application/json

Create service

POST

https://api.upcloud.com

/1.3/file-storage

Creates a new File Storage service.

Create service › Request Body

Schema for creating a new service.

fileStorageServiceCreate

name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

A resource name.

Example: test-name

zone

string · pattern: ^[a-z]{2}-[a-z]{3}\d… · required

Indicates the zone where the service will be created.

Example: fi-hel2

configured_status

fileStorageConfiguredStatus · enum · required

The service configured status indicates the service's current intended status. Managed by the customer.

Enum values:

started

stopped

Example: started

size_gib

fileStorageSizeGiB · int32 · min: 250 · max: 25000 · required

The size of the service in gibibytes (GiB)

Example: 250

encrypted

boolean

Indicates whether encryption at rest is enabled for the service.

Example: true

Default: false

fileStorageNetworkCreate[] · maxItems: 1

fileStorageShareCreate[] · maxItems: 50

fileStorageLabelCreate[] · maxItems: 255

Labels

Create service › Responses

Success

Schema for the detailed response of a service.

fileStorageServiceDetailResponse

uuid

string

name

string

zone

string

configured_status

string

operational_state

string

size_gib

integer · int32

encrypted

boolean

fileStorageNetworkDetailResponse[]

fileStorageShareDetailResponse[]

fileStorageLabelDetails[]

object[]

created_at

string · date-time

updated_at

string · date-time

POST/1.3/file-storage

curl https://api.upcloud.com/1.3/file-storage \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "test-name",
  "zone": "fi-hel2",
  "configured_status": "started",
  "size_gib": 250,
  "encrypted": false,
  "networks": [
    {
      "uuid": "03720d07-80a9-41ac-90b0-68a932109339",
      "name": "net",
      "family": "IPv4",
      "ip_address": "192.168.147.120"
    }
  ],
  "shares": [
    {
      "name": "read",
      "path": "/public",
      "acl": [
        {
          "name": "test-name",
          "target": "*",
          "permission": "ro"
        }
      ]
    },
    {
      "name": "write",
      "path": "/project/data",
      "acl": [
        {
          "name": "test-name",
          "target": "192.168.147.0/24",
          "permission": "rw"
        },
        {
          "name": "test-name",
          "target": "local.domain",
          "permission": "rw"
        }
      ]
    }
  ],
  "labels": [
    {
      "key": "environment",
      "value": "production"
    }
  ]
}'

Example Request Body

{
  "name": "test-name",
  "zone": "fi-hel2",
  "configured_status": "started",
  "size_gib": 250,
  "encrypted": false,
  "networks": [
    {
      "uuid": "03720d07-80a9-41ac-90b0-68a932109339",
      "name": "net",
      "family": "IPv4",
      "ip_address": "192.168.147.120"
    }
  ],
  "shares": [
    {
      "name": "read",
      "path": "/public",
      "acl": [
        {
          "name": "test-name",
          "target": "*",
          "permission": "ro"
        }
      ]
    },
    {
      "name": "write",
      "path": "/project/data",
      "acl": [
        {
          "name": "test-name",
          "target": "192.168.147.0/24",
          "permission": "rw"
        },
        {
          "name": "test-name",
          "target": "local.domain",
          "permission": "rw"
        }
      ]
    }
  ],
  "labels": [
    {
      "key": "environment",
      "value": "production"
    }
  ]
}

json

Example Responses

{
  "configured_status": "started",
  "created_at": "2025-08-01T10:40:04.140473Z",
  "encrypted": false,
  "labels": [
    {
      "key": "environment",
      "value": "production"
    }
  ],
  "name": "test2",
  "networks": [
    {
      "family": "IPv4",
      "ip_address": "10.10.10.50",
      "name": "net",
      "uuid": "0391f203-6eef-4a69-bfcc-fffffbdfdc32"
    }
  ],
  "operational_state": "running",
  "shares": [
    {
      "acl": [
        {
          "name": "test-name",
          "permission": "ro",
          "target": "*"
        }
      ],
      "name": "read",
      "path": "/public"
    },
    {
      "acl": [
        {
          "name": "test-name",
          "permission": "rw",
          "target": "10.10.10.0/24"
        },
        {
          "name": "test-name",
          "permission": "rw",
          "target": "local.domain"
        }
      ],
      "name": "write",
      "path": "/project/data"
    }
  ],
  "size_gib": 250,
  "state_messages": [],
  "updated_at": "2025-08-03T19:23:52.350216Z",
  "uuid": "17871d62-6964-4336-b68d-4a85a8ee10fe",
  "zone": "fi-dev2"
}

json

application/json

Get service details

GET

https://api.upcloud.com

/1.3/file-storage/{service-uuid}

Returns managed File Storage details by given {service_uuid}.

Get service details › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

Get service details › Responses

Success

Schema for the detailed response of a service.

fileStorageServiceDetailResponse

uuid

string

name

string

zone

string

configured_status

string

operational_state

string

size_gib

integer · int32

encrypted

boolean

fileStorageNetworkDetailResponse[]

fileStorageShareDetailResponse[]

fileStorageLabelDetails[]

object[]

created_at

string · date-time

updated_at

string · date-time

GET/1.3/file-storage/{service-uuid}

curl https://api.upcloud.com/1.3/file-storage/:service-uuid \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "configured_status": "started",
  "created_at": "2025-08-01T10:40:04.140473Z",
  "encrypted": false,
  "labels": [
    {
      "key": "environment",
      "value": "production"
    }
  ],
  "name": "test2",
  "networks": [
    {
      "family": "IPv4",
      "ip_address": "10.10.10.50",
      "name": "net",
      "uuid": "0391f203-6eef-4a69-bfcc-fffffbdfdc32"
    }
  ],
  "operational_state": "running",
  "shares": [
    {
      "acl": [
        {
          "name": "test-name",
          "permission": "ro",
          "target": "*"
        }
      ],
      "name": "read",
      "path": "/public"
    },
    {
      "acl": [
        {
          "name": "test-name",
          "permission": "rw",
          "target": "10.10.10.0/24"
        },
        {
          "name": "test-name",
          "permission": "rw",
          "target": "local.domain"
        }
      ],
      "name": "write",
      "path": "/project/data"
    }
  ],
  "size_gib": 250,
  "state_messages": [],
  "updated_at": "2025-08-03T19:23:52.350216Z",
  "uuid": "17871d62-6964-4336-b68d-4a85a8ee10fe",
  "zone": "fi-dev2"
}

json

application/json

Replace service

PUT

https://api.upcloud.com

/1.3/file-storage/{service-uuid}

Replaces existing File Storage service by given {service_uuid}.

Replace service › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

Replace service › Request Body

Schema for replacing an existing service with a new configuration.

fileStorageServiceReplace

name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

A resource name.

Example: test-name

configured_status

fileStorageConfiguredStatus · enum · required

The service configured status indicates the service's current intended status. Managed by the customer.

Enum values:

started

stopped

Example: started

size_gib

fileStorageSizeGiB · int32 · min: 250 · max: 25000 · required

The size of the service in gibibytes (GiB)

Example: 250

fileStorageNetworkCreate[] · maxItems: 1

fileStorageLabelCreate[] · maxItems: 255

Labels

Replace service › Responses

Success

Schema for the detailed response of a service.

fileStorageServiceDetailResponse

uuid

string

name

string

zone

string

configured_status

string

operational_state

string

size_gib

integer · int32

encrypted

boolean

fileStorageNetworkDetailResponse[]

fileStorageShareDetailResponse[]

fileStorageLabelDetails[]

object[]

created_at

string · date-time

updated_at

string · date-time

PUT/1.3/file-storage/{service-uuid}

curl https://api.upcloud.com/1.3/file-storage/:service-uuid \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "test-name",
  "configured_status": "started",
  "size_gib": 250,
  "networks": [
    {
      "uuid": "03720d07-80a9-41ac-90b0-68a932109339",
      "name": "net",
      "family": "IPv4",
      "ip_address": "192.168.147.120"
    }
  ],
  "labels": [
    {
      "key": "environment",
      "value": "production"
    }
  ]
}'

Example Request Body

{
  "name": "test-name",
  "configured_status": "started",
  "size_gib": 250,
  "networks": [
    {
      "uuid": "03720d07-80a9-41ac-90b0-68a932109339",
      "name": "net",
      "family": "IPv4",
      "ip_address": "192.168.147.120"
    }
  ],
  "labels": [
    {
      "key": "environment",
      "value": "production"
    }
  ]
}

json

Example Responses

{
  "configured_status": "started",
  "created_at": "2025-08-01T10:40:04.140473Z",
  "encrypted": false,
  "labels": [
    {
      "key": "environment",
      "value": "production"
    }
  ],
  "name": "test2",
  "networks": [
    {
      "family": "IPv4",
      "ip_address": "10.10.10.50",
      "name": "net",
      "uuid": "0391f203-6eef-4a69-bfcc-fffffbdfdc32"
    }
  ],
  "operational_state": "running",
  "shares": [
    {
      "acl": [
        {
          "name": "test-name",
          "permission": "ro",
          "target": "*"
        }
      ],
      "name": "read",
      "path": "/public"
    },
    {
      "acl": [
        {
          "name": "test-name",
          "permission": "rw",
          "target": "10.10.10.0/24"
        },
        {
          "name": "test-name",
          "permission": "rw",
          "target": "local.domain"
        }
      ],
      "name": "write",
      "path": "/project/data"
    }
  ],
  "size_gib": 250,
  "state_messages": [],
  "updated_at": "2025-08-03T19:23:52.350216Z",
  "uuid": "17871d62-6964-4336-b68d-4a85a8ee10fe",
  "zone": "fi-dev2"
}

json

application/json

Delete service

DELETE

https://api.upcloud.com

/1.3/file-storage/{service-uuid}

Deletes existing File Storage service by given {service_uuid}.

Delete service › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

Delete service › Responses

No Content

No data returned

Modify service

PATCH

https://api.upcloud.com

/1.3/file-storage/{service-uuid}

Modifies existing File Storage service by given {service_uuid}.

Modify service › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

Modify service › Request Body

Schema for modifying an existing service.

fileStorageServiceModify

name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$

A resource name.

Example: test-name

configured_status

fileStorageConfiguredStatus · enum

The service configured status indicates the service's current intended status. Managed by the customer.

Enum values:

started

stopped

Example: started

size_gib

fileStorageSizeGiB · int32 · min: 250 · max: 25000

The size of the service in gibibytes (GiB)

Example: 250

array | null · maxItems: 1

array | null · maxItems: 255

Modify service › Responses

Success

Schema for the detailed response of a service.

fileStorageServiceDetailResponse

uuid

string

name

string

zone

string

configured_status

string

operational_state

string

size_gib

integer · int32

encrypted

boolean

fileStorageNetworkDetailResponse[]

fileStorageShareDetailResponse[]

fileStorageLabelDetails[]

object[]

created_at

string · date-time

updated_at

string · date-time

PATCH/1.3/file-storage/{service-uuid}

curl https://api.upcloud.com/1.3/file-storage/:service-uuid \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "test-name",
  "configured_status": "started",
  "size_gib": 250,
  "networks": [
    {
      "uuid": "03720d07-80a9-41ac-90b0-68a932109339",
      "name": "net",
      "family": "IPv4",
      "ip_address": "192.168.147.120"
    }
  ],
  "labels": [
    {
      "key": "environment",
      "value": "production"
    }
  ]
}'

Example Request Body

{
  "name": "test-name",
  "configured_status": "started",
  "size_gib": 250,
  "networks": [
    {
      "uuid": "03720d07-80a9-41ac-90b0-68a932109339",
      "name": "net",
      "family": "IPv4",
      "ip_address": "192.168.147.120"
    }
  ],
  "labels": [
    {
      "key": "environment",
      "value": "production"
    }
  ]
}

json

Example Responses

{
  "configured_status": "started",
  "created_at": "2025-08-01T10:40:04.140473Z",
  "encrypted": false,
  "labels": [
    {
      "key": "environment",
      "value": "production"
    }
  ],
  "name": "test2",
  "networks": [
    {
      "family": "IPv4",
      "ip_address": "10.10.10.50",
      "name": "net",
      "uuid": "0391f203-6eef-4a69-bfcc-fffffbdfdc32"
    }
  ],
  "operational_state": "running",
  "shares": [
    {
      "acl": [
        {
          "name": "test-name",
          "permission": "ro",
          "target": "*"
        }
      ],
      "name": "read",
      "path": "/public"
    },
    {
      "acl": [
        {
          "name": "test-name",
          "permission": "rw",
          "target": "10.10.10.0/24"
        },
        {
          "name": "test-name",
          "permission": "rw",
          "target": "local.domain"
        }
      ],
      "name": "write",
      "path": "/project/data"
    }
  ],
  "size_gib": 250,
  "state_messages": [],
  "updated_at": "2025-08-03T19:23:52.350216Z",
  "uuid": "17871d62-6964-4336-b68d-4a85a8ee10fe",
  "zone": "fi-dev2"
}

json

application/json

List networks

GET

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/networks

Returns a list of available service networks by given {service_uuid}.

List networks › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

List networks › Responses

Success

fileStorageNetworkDetailResponse[]

Schema for the response containing a list of networks.

Example: [{"family":"IPv4","ip_address":"192.168.147.250","name":"test-name","uuid":"03720d07-80a9-41ac-90b0-68a932109339"}]

Schema for the detailed response of a network.

fileStorageNetworkDetailResponse

family

string

ip_address

string

name

string

uuid

string

Create network

POST

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/networks

Creates a new service network by given {service_uuid}.

Create network › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

Create network › Request Body

Schema for creating a network.

fileStorageNetworkCreate

uuid

fileStorageNetworkUUID · uuid · required

Unique identifier for the network.

Example: 03720d07-80a9-41ac-90b0-68a932109339

name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

A resource name.

Example: test-name

family

fileStorageNetworkFamily · enum · required

Network family. IPv6 currently not supported.

Enum values:

IPv4

IPv6

Example: IPv4

ip_address

fileStorageIPAddress · ipv4

The desired IP address for the service. If not specified, the service will be assigned an IP address from the network's pool.

Example: 10.20.30.40

Create network › Responses

Success

Schema for the detailed response of a network.

fileStorageNetworkDetailResponse

family

string

ip_address

string

name

string

uuid

string

Get network details

GET

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/networks/{network-name}

Returns service network details by given {service_uuid} and {network_name}.

Get network details › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

network-name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

The name of the network.

A resource name.

Example: test-name

Get network details › Responses

Success

Schema for the detailed response of a network.

fileStorageNetworkDetailResponse

family

string

ip_address

string

name

string

uuid

string

Delete network

DELETE

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/networks/{network-name}

Deletes existing network by given {service_uuid} and {network_name}.

Delete network › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

network-name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

The name of the network.

A resource name.

Example: test-name

Delete network › Responses

No Content

No data returned

Modify network

PATCH

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/networks/{network-name}

Modifies existing service network by given {service_uuid} and {network_name}.

Modify network › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

network-name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

The name of the network.

A resource name.

Example: test-name

Modify network › Request Body

Schema for modifying an existing network.

fileStorageNetworkModify

uuid

fileStorageNetworkUUID · uuid

Unique identifier for the network.

Example: 03720d07-80a9-41ac-90b0-68a932109339

name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$

A resource name.

Example: test-name

family

fileStorageNetworkFamily · enum

Network family. IPv6 currently not supported.

Enum values:

IPv4

IPv6

Example: IPv4

ip_address

fileStorageIPAddress · ipv4

The desired IP address for the service. If not specified, the service will be assigned an IP address from the network's pool.

Example: 10.20.30.40

Modify network › Responses

Success

Schema for the detailed response of a network.

fileStorageNetworkDetailResponse

family

string

ip_address

string

name

string

uuid

string

List shares

GET

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/shares

Returns a list of available service shares by given {service_uuid}.

List shares › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

List shares › Responses

Success

fileStorageShareDetailResponse[]

Schema for the response containing a list of shares.

Example: [{"name":"write","path":"/project/data","acl":[{"name":"test-name","target":"*","permission":"rw"}]},{"name":"read","path":"/project/logs","acl":[{"name":"test-name","target":"192.168.147.0/24","permission":"ro"}]}]

Schema for the detailed response of a share.

fileStorageShareDetailResponse

name

string

path

string

object[]

POST

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/shares

Creates a new service share by given {service_uuid}.

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

Schema for creating a new share with access control lists (ACLs).

fileStorageShareCreate

name

string · minLength: 1 · maxLength: 128 · pattern: ^[a-zA-Z0-9_-]+$ · required

A resource name.

Example: test-name

path

fileStoragePath · minLength: 1 · maxLength: 512 · pattern: ^/[a-zA-Z0-9/_-]*$ · required

The absolute path of the share.

Example: /public

fileStorageAclCreate[] · maxItems: 50 · required

Success

Schema for the detailed response of a share.

fileStorageShareDetailResponse

name

string

path

string

object[]

GET

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/shares/{share-name}

Returns service share details by given {service_uuid} and {share_name}.

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

share-name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

The name of the share.

A resource name.

Example: test-name

Success

Schema for the detailed response of a share.

fileStorageShareDetailResponse

name

string

path

string

object[]

DELETE

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/shares/{share-name}

Deletes existing share by given {service_uuid} and {share_name}.

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

share-name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

The name of the share.

A resource name.

Example: test-name

No Content

No data returned

PATCH

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/shares/{share-name}

Modifies existing service share by given {service_uuid} and {share_name}.

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

share-name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

The name of the share.

A resource name.

Example: test-name

Schema for modifying an existing share.

fileStorageShareModify

name

string · minLength: 1 · maxLength: 128 · pattern: ^[a-zA-Z0-9_-]+$

A resource name.

Example: test-name

fileStorageAclCreate[] · maxItems: 50

Success

Schema for the detailed response of a share.

fileStorageShareDetailResponse

name

string

path

string

object[]

List ACLs

GET

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/shares/{share-name}/acl

Returns a list of available ACLs by given {service_uuid} and {share_name}.

List ACLs › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

share-name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

The name of the share.

A resource name.

Example: test-name

List ACLs › Responses

Success

fileStorageAclDetailResponse[]

Schema for the response containing a list of ACLs.

Example: [{"name":"test-name-1","target":"*","permission":"rw"},{"name":"test-name-2","target":"192.168.147.0/24","permission":"ro"}]

Schema for the detailed response of an ACL.

fileStorageAclDetailResponse

name

string

target

string

permission

string

Create ACL

POST

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/shares/{share-name}/acl

Creates a new share ACL by given {service_uuid} and {share_name}.

Create ACL › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

share-name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

The name of the share.

A resource name.

Example: test-name

Create ACL › Request Body

Schema for creating an ACL entry.

fileStorageAclCreate

name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

A resource name.

Example: test-name

target

string · minLength: 1 · maxLength: 255 · required

The target of the ACL entry. It can be a IP Address, Network Prefix or a wildcard.

Example: 192.168.25.147

permission

fileStoragePermission · enum · required

The permission level for the ACL target.

Enum values:

Example: rw

Create ACL › Responses

Success

Schema for the detailed response of an ACL.

fileStorageAclDetailResponse

name

string

target

string

permission

string

Get ACL details

GET

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/shares/{share-name}/acl/{acl-name}

Returns ACL details by given {service_uuid}, {share_name} and {acl_name}.

Get ACL details › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

share-name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

The name of the share.

A resource name.

Example: test-name

acl-name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

The name of the ACL.

A resource name.

Example: test-name

Get ACL details › Responses

Success

Schema for the detailed response of an ACL.

fileStorageAclDetailResponse

name

string

target

string

permission

string

Delete ACL

DELETE

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/shares/{share-name}/acl/{acl-name}

Deletes existing ACL by given {service_uuid}, {share_name} and {acl_name}.

Delete ACL › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

share-name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

The name of the share.

A resource name.

Example: test-name

acl-name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

The name of the ACL.

A resource name.

Example: test-name

Delete ACL › Responses

No Content

No data returned

Modify ACL

PATCH

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/shares/{share-name}/acl/{acl-name}

Modifies existing ACL by given {service_uuid}, {share_name} and {acl_name}.

Modify ACL › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

share-name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

The name of the share.

A resource name.

Example: test-name

acl-name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$ · required

The name of the ACL.

A resource name.

Example: test-name

Modify ACL › Request Body

Schema for modifying an existing ACL.

fileStorageAclModify

name

fileStorageName · minLength: 1 · maxLength: 64 · pattern: ^[a-zA-Z0-9_-]+$

A resource name.

Example: test-name

target

string · minLength: 1 · maxLength: 255

The target of the ACL entry. It can be a IP Address, Network Prefix or a wildcard.

Example: 192.168.25.147

permission

fileStoragePermission · enum

The permission level for the ACL target.

Enum values:

Example: rw

Modify ACL › Responses

Success

Schema for the detailed response of an ACL.

fileStorageAclDetailResponse

name

string

target

string

permission

string

List labels

GET

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/labels

Returns a list of available service labels by given {service_uuid}.

List labels › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

List labels › Responses

Success

fileStorageLabelDetails[]

Response schema for listing labels.

Example: [{"key":"environment","value":"production"}]

Schema for label details including key-value pairs.

fileStorageLabelDetails

key

string

value

string

Create label

POST

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/labels

Creates a new label by given {service_uuid}. Labels are used for service filtering.

Create label › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

Create label › Request Body

Schema for creating a new label.

fileStorageLabelCreate

key

fileStorageLabelKey · minLength: 2 · maxLength: 32 · pattern: ^[\x20-\x5E\x60-\x7E… · required

Represents the label identifier. The key is unique within a service.

Example: environment

value

fileStorageLabelValue · maxLength: 255 · pattern: \A[\p{L}\p{N}\p{P}\p… · required

Represents the label value.

Example: development

Create label › Responses

Success

Schema for label details including key-value pairs.

fileStorageLabelDetails

key

string

value

string

Get label details

GET

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/labels/{label-key}

Returns label details by given {service_uuid} and {key}.

Get label details › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

label-key

fileStorageLabelKey · minLength: 2 · maxLength: 32 · pattern: ^[\x20-\x5E\x60-\x7E… · required

The key of the label.

Represents the label identifier. The key is unique within a service.

Example: environment

Get label details › Responses

Success

Schema for label details including key-value pairs.

fileStorageLabelDetails

key

string

value

string

Delete label

DELETE

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/labels/{label-key}

Deletes existing label by given {service_uuid} and {key}.

Delete label › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

label-key

fileStorageLabelKey · minLength: 2 · maxLength: 32 · pattern: ^[\x20-\x5E\x60-\x7E… · required

The key of the label.

Represents the label identifier. The key is unique within a service.

Example: environment

Delete label › Responses

No Content

No data returned

Modify label

PATCH

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/labels/{label-key}

Modifies existing label by given {service_uuid} and {key}.

Modify label › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

label-key

fileStorageLabelKey · minLength: 2 · maxLength: 32 · pattern: ^[\x20-\x5E\x60-\x7E… · required

The key of the label.

Represents the label identifier. The key is unique within a service.

Example: environment

Modify label › Request Body

Schema for modifying an existing label.

fileStorageLabelModify

key

fileStorageLabelKey · minLength: 2 · maxLength: 32 · pattern: ^[\x20-\x5E\x60-\x7E…

Represents the label identifier. The key is unique within a service.

Example: environment

value

fileStorageLabelValue · maxLength: 255 · pattern: \A[\p{L}\p{N}\p{P}\p…

Represents the label value.

Example: development

Modify label › Responses

Success

Schema for label details including key-value pairs.

fileStorageLabelDetails

key

string

value

string

Get service current state

GET

https://api.upcloud.com

/1.3/file-storage/{service-uuid}/current-state

Returns the current state of the File Storage service by given {service_uuid}.

Get service current state › path Parameters

service-uuid

fileStorageEntityUUID · uuid · required

Service UUID

The unique identifier.

Example: 17fd43a5-a97e-44f7-98a8-0a787da67069

Get service current state › Responses

Success

Schema for the detailed response of a service.

fileStorageServiceDetailResponse

uuid

string

name

string

zone

string

configured_status

string

operational_state

string

size_gib

integer · int32

encrypted

boolean

fileStorageNetworkDetailResponse[]

fileStorageShareDetailResponse[]

fileStorageLabelDetails[]

object[]

created_at

string · date-time

updated_at

string · date-time

GET/1.3/file-storage/{service-uuid}/current-state

curl https://api.upcloud.com/1.3/file-storage/:service-uuid/current-state \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "configured_status": "started",
  "created_at": "2025-08-01T10:40:04.140473Z",
  "encrypted": false,
  "labels": [
    {
      "key": "environment",
      "value": "production"
    }
  ],
  "name": "test2",
  "networks": [
    {
      "family": "IPv4",
      "ip_address": "10.10.10.50",
      "name": "net",
      "uuid": "0391f203-6eef-4a69-bfcc-fffffbdfdc32"
    }
  ],
  "operational_state": "running",
  "shares": [
    {
      "acl": [
        {
          "name": "test-name",
          "permission": "ro",
          "target": "*"
        }
      ],
      "name": "read",
      "path": "/public"
    },
    {
      "acl": [
        {
          "name": "test-name",
          "permission": "rw",
          "target": "10.10.10.0/24"
        },
        {
          "name": "test-name",
          "permission": "rw",
          "target": "local.domain"
        }
      ],
      "name": "write",
      "path": "/project/data"
    }
  ],
  "size_gib": 250,
  "state_messages": [],
  "updated_at": "2025-08-03T19:23:52.350216Z",
  "uuid": "17871d62-6964-4336-b68d-4a85a8ee10fe",
  "zone": "fi-dev2"
}

json

application/json

Object Storage Database

File Storage

List services

List services › query Parameters

List services › Responses

Create service

Create service › Request Body

Create service › Responses

Get service details

Get service details › path Parameters

Get service details › Responses

Replace service

Replace service › path Parameters

Replace service › Request Body

Replace service › Responses

Delete service

Delete service › path Parameters

Delete service › Responses

Modify service

Modify service › path Parameters

Modify service › Request Body

Modify service › Responses

List networks

List networks › path Parameters

List networks › Responses

Create network

Create network › path Parameters

Create network › Request Body

Create network › Responses

Get network details

Get network details › path Parameters

Get network details › Responses

Delete network

Delete network › path Parameters

Delete network › Responses

Modify network

Modify network › path Parameters

Modify network › Request Body

Modify network › Responses

List shares

List shares › path Parameters

List shares › Responses

Create share

Create share › path Parameters

Create share › Request Body

Create share › Responses

Get share details

Get share details › path Parameters

Get share details › Responses

Delete share

Delete share › path Parameters

Delete share › Responses

Modify share

Modify share › path Parameters

Modify share › Request Body

Modify share › Responses

List ACLs

List ACLs › path Parameters

List ACLs › Responses

Create ACL

Create ACL › path Parameters

Create ACL › Request Body

Create ACL › Responses

Get ACL details

Get ACL details › path Parameters

Get ACL details › Responses

Delete ACL

Delete ACL › path Parameters

Delete ACL › Responses

Modify ACL

Modify ACL › path Parameters

Modify ACL › Request Body

Modify ACL › Responses

List labels

List labels › path Parameters

List labels › Responses

Create label

Create label › path Parameters

Create label › Request Body

Create label › Responses

Get label details