File Storage

All operations require authentication.

5 operationsv2/publicCloud/project

OpenAPI

Agent setup

List file storagesProduction

GET

/v2/publicCloud/project/{projectId}/storage/file/share

Returns the file storages of the project.

Path parameters

projectId

required

string

Project ID

Headers

X-Pagination-Cursor

string

Pagination cursor

X-Pagination-Size

integer

Pagination size

Response

200FileStorage[]successful operation

checksum

read-only

string

Computed hash representing the current target specification value

createdAt

read-only

stringdate-time

Creation date of the file storage

currentState

read-only

FileStorageCurrentState

Current observed state of the file storage from the infrastructure

currentTasks

read-only

CurrentTask[]

Ongoing asynchronous tasks related to the file storage

read-only

stringuuid

Unique identifier of the file storage

resourceStatus

read-only

ResourceStatusEnum

File storage readiness in the system

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING

targetSpec

read-only

FileStorageTargetSpec

Last target specification of the file storage

updatedAt

read-only

stringdate-time

Last update date of the file storage

Example uses projectId = string

$ curl https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/storage/file/share \
  -H "authorization: Bearer $OVH_TOKEN"

ResponseExample

1[2  {3    "checksum": "string",4    "createdAt": "2024-01-01T12:00:00Z",5    "currentState": {6      "capabilities": [7        {8          "enabled": true,9          "name": "ACL_MANAGEMENT",10          "reason": "HAS_DEPENDENT_SNAPSHOTS"11        }12      ],13      "description": "string",14      "encryption": {15        "enabled": true16      },17      "exportLocations": [18        {19          "path": "string",20          "preferred": true21        }22      ],23      "location": {24        "availabilityZone": "string",25        "region": "string"26      },27      "name": "string",28      "protocol": "NFS",29      "shareNetwork": {30        "id": "00000000-0000-0000-0000-000000000000"31      },32      "shareType": "STANDARD_1AZ",33      "size": 034    },35    "currentTasks": [36      {37        "errors": [38          {39            "message": "string"40          }41        ],42        "id": "00000000-0000-0000-0000-000000000000",43        "link": "string",44        "status": "ERROR",45        "type": "string"46      }47    ],48    "id": "00000000-0000-0000-0000-000000000000",49    "resourceStatus": "CREATING",50    "targetSpec": {51      "createFrom": {52        "snapshotId": "00000000-0000-0000-0000-000000000000"53      },54      "description": "string",55      "encryption": {56        "enabled": true57      },58      "location": {59        "availabilityZone": "string",60        "region": "string"61      },62      "name": "string",63      "protocol": "NFS",64      "shareNetwork": {65        "id": "00000000-0000-0000-0000-000000000000"66      },67      "shareType": "STANDARD_1AZ",68      "size": 069    },70    "updatedAt": "2024-01-01T12:00:00Z"71  }72]

Get a file storageProduction

GET

/v2/publicCloud/project/{projectId}/storage/file/share/{fileStorageId}

Returns the file storage configuration and its current state, including the NFS export paths to mount it.

Path parameters

fileStorageId

required

stringuuid

File storage ID

projectId

required

string

Project ID

Response

200FileStoragesuccessful operation

checksum

read-only

string

Computed hash representing the current target specification value

createdAt

read-only

stringdate-time

Creation date of the file storage

currentState

read-only

FileStorageCurrentState

Current observed state of the file storage from the infrastructure

currentTasks

read-only

CurrentTask[]

Ongoing asynchronous tasks related to the file storage

read-only

stringuuid

Unique identifier of the file storage

resourceStatus

read-only

ResourceStatusEnum

File storage readiness in the system

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING

targetSpec

read-only

FileStorageTargetSpec

Last target specification of the file storage

updatedAt

read-only

stringdate-time

Last update date of the file storage

404objectError 404 response

Example uses fileStorageId = 00000000-0000-0000-0000-000000000000, projectId = string

$ curl https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/storage/file/share/{fileStorageId} \
  -H "authorization: Bearer $OVH_TOKEN"

ResponseExample

1{2  "checksum": "string",3  "createdAt": "2024-01-01T12:00:00Z",4  "currentState": {5    "capabilities": [6      {7        "enabled": true,8        "name": "ACL_MANAGEMENT",9        "reason": "HAS_DEPENDENT_SNAPSHOTS"10      }11    ],12    "description": "string",13    "encryption": {14      "enabled": true15    },16    "exportLocations": [17      {18        "path": "string",19        "preferred": true20      }21    ],22    "location": {23      "availabilityZone": "string",24      "region": "string"25    },26    "name": "string",27    "protocol": "NFS",28    "shareNetwork": {29      "id": "00000000-0000-0000-0000-000000000000"30    },31    "shareType": "STANDARD_1AZ",32    "size": 033  },34  "currentTasks": [35    {36      "errors": [37        {38          "message": "string"39        }40      ],41      "id": "00000000-0000-0000-0000-000000000000",42      "link": "string",43      "status": "ERROR",44      "type": "string"45    }46  ],47  "id": "00000000-0000-0000-0000-000000000000",48  "resourceStatus": "CREATING",49  "targetSpec": {50    "createFrom": {51      "snapshotId": "00000000-0000-0000-0000-000000000000"52    },53    "description": "string",54    "encryption": {55      "enabled": true56    },57    "location": {58      "availabilityZone": "string",59      "region": "string"60    },61    "name": "string",62    "protocol": "NFS",63    "shareNetwork": {64      "id": "00000000-0000-0000-0000-000000000000"65    },66    "shareType": "STANDARD_1AZ",67    "size": 068  },69  "updatedAt": "2024-01-01T12:00:00Z"70}

Create a file storageProduction

POST

/v2/publicCloud/project/{projectId}/storage/file/share

Creates a file storage, either empty or from a snapshot.

Without createFrom, shareType, shareNetwork and size are required.

With createFrom.snapshotId, the file storage is created from that snapshot, which must belong to the same project and be in the region set in location.region. An unknown snapshot is rejected with a 404. The snapshot must be available: a snapshot in any other status is rejected with a 409. shareType and encryption are the values of the snapshot's source file storage and are returned in targetSpec: requesting encryption.enabled true from a snapshot of an unencrypted file storage is rejected as an invalid parameter, and requesting encryption.enabled false from a snapshot of an encrypted file storage is ignored. size is optional: when omitted, the snapshot's size is used and returned in targetSpec, and a size smaller than the snapshot's size is rejected. shareNetwork is optional: when omitted, the share network of the snapshot's source file storage is used and returned in targetSpec, and a different share network is rejected.

createFrom is set at creation only and cannot be changed afterward.

Path parameters

projectId

required

string

Project ID

Request body (required)

targetSpec

required

FileStorageTargetSpec

Desired target specification for the file storage

Response

200FileStoragesuccessful operation

checksum

read-only

string

Computed hash representing the current target specification value

createdAt

read-only

stringdate-time

Creation date of the file storage

currentState

read-only

FileStorageCurrentState

Current observed state of the file storage from the infrastructure

currentTasks

read-only

CurrentTask[]

Ongoing asynchronous tasks related to the file storage

read-only

stringuuid

Unique identifier of the file storage

resourceStatus

read-only

ResourceStatusEnum

File storage readiness in the system

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING

targetSpec

read-only

FileStorageTargetSpec

Last target specification of the file storage

updatedAt

read-only

stringdate-time

Last update date of the file storage

400objectError 400 response

404objectError 404 response

409objectError 409 response

Example uses projectId = string

$ curl https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/storage/file/share \
  -H "authorization: Bearer $OVH_TOKEN"

ResponseExample

1{2  "checksum": "string",3  "createdAt": "2024-01-01T12:00:00Z",4  "currentState": {5    "capabilities": [6      {7        "enabled": true,8        "name": "ACL_MANAGEMENT",9        "reason": "HAS_DEPENDENT_SNAPSHOTS"10      }11    ],12    "description": "string",13    "encryption": {14      "enabled": true15    },16    "exportLocations": [17      {18        "path": "string",19        "preferred": true20      }21    ],22    "location": {23      "availabilityZone": "string",24      "region": "string"25    },26    "name": "string",27    "protocol": "NFS",28    "shareNetwork": {29      "id": "00000000-0000-0000-0000-000000000000"30    },31    "shareType": "STANDARD_1AZ",32    "size": 033  },34  "currentTasks": [35    {36      "errors": [37        {38          "message": "string"39        }40      ],41      "id": "00000000-0000-0000-0000-000000000000",42      "link": "string",43      "status": "ERROR",44      "type": "string"45    }46  ],47  "id": "00000000-0000-0000-0000-000000000000",48  "resourceStatus": "CREATING",49  "targetSpec": {50    "createFrom": {51      "snapshotId": "00000000-0000-0000-0000-000000000000"52    },53    "description": "string",54    "encryption": {55      "enabled": true56    },57    "location": {58      "availabilityZone": "string",59      "region": "string"60    },61    "name": "string",62    "protocol": "NFS",63    "shareNetwork": {64      "id": "00000000-0000-0000-0000-000000000000"65    },66    "shareType": "STANDARD_1AZ",67    "size": 068  },69  "updatedAt": "2024-01-01T12:00:00Z"70}

Delete a file storageProduction

DELETE

/v2/publicCloud/project/{projectId}/storage/file/share/{fileStorageId}

Deletes the file storage. A file storage that still has snapshots cannot be deleted: delete them first.

Path parameters

fileStorageId

required

stringuuid

File storage ID

projectId

required

string

Project ID

Response

200FileStoragesuccessful operation

checksum

read-only

string

Computed hash representing the current target specification value

createdAt

read-only

stringdate-time

Creation date of the file storage

currentState

read-only

FileStorageCurrentState

Current observed state of the file storage from the infrastructure

currentTasks

read-only

CurrentTask[]

Ongoing asynchronous tasks related to the file storage

read-only

stringuuid

Unique identifier of the file storage

resourceStatus

read-only

ResourceStatusEnum

File storage readiness in the system

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING

targetSpec

read-only

FileStorageTargetSpec

Last target specification of the file storage

updatedAt

read-only

stringdate-time

Last update date of the file storage

404objectError 404 response

409objectError 409 response

Example uses fileStorageId = 00000000-0000-0000-0000-000000000000, projectId = string

$ curl https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/storage/file/share/{fileStorageId} \
  -H "authorization: Bearer $OVH_TOKEN"

ResponseExample

1{2  "checksum": "string",3  "createdAt": "2024-01-01T12:00:00Z",4  "currentState": {5    "capabilities": [6      {7        "enabled": true,8        "name": "ACL_MANAGEMENT",9        "reason": "HAS_DEPENDENT_SNAPSHOTS"10      }11    ],12    "description": "string",13    "encryption": {14      "enabled": true15    },16    "exportLocations": [17      {18        "path": "string",19        "preferred": true20      }21    ],22    "location": {23      "availabilityZone": "string",24      "region": "string"25    },26    "name": "string",27    "protocol": "NFS",28    "shareNetwork": {29      "id": "00000000-0000-0000-0000-000000000000"30    },31    "shareType": "STANDARD_1AZ",32    "size": 033  },34  "currentTasks": [35    {36      "errors": [37        {38          "message": "string"39        }40      ],41      "id": "00000000-0000-0000-0000-000000000000",42      "link": "string",43      "status": "ERROR",44      "type": "string"45    }46  ],47  "id": "00000000-0000-0000-0000-000000000000",48  "resourceStatus": "CREATING",49  "targetSpec": {50    "createFrom": {51      "snapshotId": "00000000-0000-0000-0000-000000000000"52    },53    "description": "string",54    "encryption": {55      "enabled": true56    },57    "location": {58      "availabilityZone": "string",59      "region": "string"60    },61    "name": "string",62    "protocol": "NFS",63    "shareNetwork": {64      "id": "00000000-0000-0000-0000-000000000000"65    },66    "shareType": "STANDARD_1AZ",67    "size": 068  },69  "updatedAt": "2024-01-01T12:00:00Z"70}

Update a file storageProduction

PUT

/v2/publicCloud/project/{projectId}/storage/file/share/{fileStorageId}

Replaces the file storage's target specification as a whole. The body carries the complete desired state of every field publicCloud.storage.file.FileStorageUpdateTargetSpec exposes (description, name and size), so read the file storage first and restate every value you want to keep: a field left out of targetSpec is cleared, not carried over from the stored specification. Leaving description out clears the description.

The create-only fields protocol, shareType, shareNetwork, location, encryption and createFrom cannot be changed once the file storage exists. They are deliberately absent from the update model, and sending one is rejected with a 400.

name and size are both required. size can only grow: restate the current size to keep it, or send a larger value to extend the file storage, because shrinking one is not supported.

The optional checksum guards against a lost update: when supplied it must match the file storage's current checksum or the request is rejected with a 409 checksum mismatch. Omitting it skips the check and forces the write (last-write-wins).

Path parameters

fileStorageId

required

stringuuid

File storage ID

projectId

required

string

Project ID

Request body (required)

checksum

string

Optional concurrency-control checksum. When supplied, it must match the resource's current checksum or the request is rejected with a 409 checksum-mismatch conflict. When omitted or empty, the concurrency check is skipped and the write is forced (last-write-wins).

targetSpec

required

FileStorageUpdateTargetSpec

Desired target specification for the file storage

Response

200FileStoragesuccessful operation

checksum

read-only

string

Computed hash representing the current target specification value

createdAt

read-only

stringdate-time

Creation date of the file storage

currentState

read-only

FileStorageCurrentState

Current observed state of the file storage from the infrastructure

currentTasks

read-only

CurrentTask[]

Ongoing asynchronous tasks related to the file storage

read-only

stringuuid

Unique identifier of the file storage

resourceStatus

read-only

ResourceStatusEnum

File storage readiness in the system

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING

targetSpec

read-only

FileStorageTargetSpec

Last target specification of the file storage

updatedAt

read-only

stringdate-time

Last update date of the file storage

400objectError 400 response

404objectError 404 response

409objectError 409 response

Example uses fileStorageId = 00000000-0000-0000-0000-000000000000, projectId = string

$ curl https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/storage/file/share/{fileStorageId} \
  -H "authorization: Bearer $OVH_TOKEN"

ResponseExample

1{2  "checksum": "string",3  "createdAt": "2024-01-01T12:00:00Z",4  "currentState": {5    "capabilities": [6      {7        "enabled": true,8        "name": "ACL_MANAGEMENT",9        "reason": "HAS_DEPENDENT_SNAPSHOTS"10      }11    ],12    "description": "string",13    "encryption": {14      "enabled": true15    },16    "exportLocations": [17      {18        "path": "string",19        "preferred": true20      }21    ],22    "location": {23      "availabilityZone": "string",24      "region": "string"25    },26    "name": "string",27    "protocol": "NFS",28    "shareNetwork": {29      "id": "00000000-0000-0000-0000-000000000000"30    },31    "shareType": "STANDARD_1AZ",32    "size": 033  },34  "currentTasks": [35    {36      "errors": [37        {38          "message": "string"39        }40      ],41      "id": "00000000-0000-0000-0000-000000000000",42      "link": "string",43      "status": "ERROR",44      "type": "string"45    }46  ],47  "id": "00000000-0000-0000-0000-000000000000",48  "resourceStatus": "CREATING",49  "targetSpec": {50    "createFrom": {51      "snapshotId": "00000000-0000-0000-0000-000000000000"52    },53    "description": "string",54    "encryption": {55      "enabled": true56    },57    "location": {58      "availabilityZone": "string",59      "region": "string"60    },61    "name": "string",62    "protocol": "NFS",63    "shareNetwork": {64      "id": "00000000-0000-0000-0000-000000000000"65    },66    "shareType": "STANDARD_1AZ",67    "size": 068  },69  "updatedAt": "2024-01-01T12:00:00Z"70}