File Storage

File Storage provides NFS-based storage shares for workloads requiring file-level access with a standard POSIX interface. Mount storage directly on Linux, Unix, and other compatible systems.

This API follows JSON Merge Patch semantics where null indicates property deletion and absent properties are not modified.

GET/1.3/file-storage

List services

Returns a list of all file storage services in the account.

Query parameters

Name
limit
Type
integer
Description
Number of entries to return (0-100). Default: 10.
Name
offset
Type
integer
Description
Offset for pagination. Default: 0.
Name
sort
Type
string
Description
Sort order: created_at or -created_at.

Request

GET

/1.3/file-storage

curl -X GET https://api.upcloud.com/1.3/file-storage \
  -u your_username:your_password

GET/1.3/file-storage/{uuid}

Get service details

Returns detailed information about a specific file storage service, including networks, shares, and ACLs.

Request

GET

/1.3/file-storage/{uuid}

curl -X GET https://api.upcloud.com/1.3/file-storage/0ad24fe5-d08a-44ea-a0a8-169a46e0cc90 \
  -u your_username:your_password

POST/1.3/file-storage

Create service

Creates a new file storage service.

Attributes

Name
name
Type
string
Description
Service name (1-64 characters, alphanumeric with - and _). Required.
Name
zone
Type
string
Description
Zone identifier. Required.
Name
size_gib
Type
integer
Description
Storage size in GiB (250-25000). Required.
Name
configured_status
Type
string
Description
Initial status: "started" or "stopped". Required.
Name
networks
Type
array
Description
Network attachments (0-1 networks).
Name
shares
Type
array
Description
NFS shares to create (1-255 shares).
Name
labels
Type
array
Description
Labels for classification (0-255 labels).

Request

POST

/1.3/file-storage

curl -X POST https://api.upcloud.com/1.3/file-storage \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-file-storage",
    "zone": "fi-hel2",
    "size_gib": 250,
    "configured_status": "started",
    "networks": [
      {
        "uuid": "03720d07-80a9-41ac-90b0-68a932109339",
        "name": "net",
        "family": "IPv4",
        "ip_address": "192.168.147.120"
      }
    ],
    "shares": [
      {
        "name": "public",
        "path": "/public",
        "acl": [
          {"name": "read", "target": "*", "permission": "ro"}
        ]
      }
    ]
  }'

PATCH/1.3/file-storage/{uuid}

Modify service

Modifies an existing file storage service. Uses JSON Merge Patch semantics.

Request

PATCH

/1.3/file-storage/{uuid}

curl -X PATCH https://api.upcloud.com/1.3/file-storage/0ad24fe5-d08a-44ea-a0a8-169a46e0cc90 \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "size_gib": 500,
    "configured_status": "stopped"
  }'

DELETE/1.3/file-storage/{uuid}

Delete service

Deletes a file storage service and all its shares.

Request

DELETE

/1.3/file-storage/{uuid}

curl -X DELETE https://api.upcloud.com/1.3/file-storage/0ad24fe5-d08a-44ea-a0a8-169a46e0cc90 \
  -u your_username:your_password

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

Get current state

Returns the current operational state of a file storage service including network connectivity and share status.

Request

GET

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

curl -X GET https://api.upcloud.com/1.3/file-storage/0ad24fe5-d08a-44ea-a0a8-169a46e0cc90/current-state \
  -u your_username:your_password

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

List shares

Returns a list of all shares within a file storage service.

Request

GET

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

curl -X GET https://api.upcloud.com/1.3/file-storage/0ad24fe5-d08a-44ea-a0a8-169a46e0cc90/shares \
  -u your_username:your_password

GET/1.3/file-storage/{uuid}/shares/{share_name}

Returns details of a specific share including its ACL entries.

Request

GET

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

curl -X GET https://api.upcloud.com/1.3/file-storage/0ad24fe5-d08a-44ea-a0a8-169a46e0cc90/shares/public \
  -u your_username:your_password

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

Creates a new NFS share within the file storage service.

Attributes

Name
name
Type
string
Description
Share name. Required.
Name
path
Type
string
Description
Mount path (e.g., "/data"). Required.
Name
acl
Type
array
Description
Access control list entries.

ACL entry attributes

Name
name
Type
string
Description
ACL entry name.
Name
target
Type
string
Description
IP address, CIDR, or "*" for all.
Name
permission
Type
string
Description
"ro" for read-only or "rw" for read-write.

Request

POST

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

curl -X POST https://api.upcloud.com/1.3/file-storage/0ad24fe5-d08a-44ea-a0a8-169a46e0cc90/shares \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data",
    "path": "/data",
    "acl": [
      {"name": "rw-access", "target": "192.168.0.0/24", "permission": "rw"}
    ]
  }'

PATCH/1.3/file-storage/{uuid}/shares/{share_uuid}

Modifies an existing share. Note that updating ACLs requires sending the complete ACL array.

Request

PATCH

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

curl -X PATCH https://api.upcloud.com/1.3/file-storage/0ad24fe5-d08a-44ea-a0a8-169a46e0cc90/shares/0c34d56e-7890-12fg-h345-678901ijklmn \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "acl": [
      {"name": "rw-access", "target": "10.0.0.0/8", "permission": "rw"},
      {"name": "ro-access", "target": "*", "permission": "ro"}
    ]
  }'

DELETE/1.3/file-storage/{uuid}/shares/{share_uuid}

Deletes a share from the file storage service.

Request

DELETE

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

curl -X DELETE https://api.upcloud.com/1.3/file-storage/0ad24fe5-d08a-44ea-a0a8-169a46e0cc90/shares/0c34d56e-7890-12fg-h345-678901ijklmn \
  -u your_username:your_password