Restore a cloud backup

Download a cloud backup and always create a fresh local profile. This operation never overwrites an existing profile and does not launch the restored profile. The new profile keeps its cloudId and provider association, but automatic cloud sync defaults to OFF: the HTTP restore internally passes enableCloudSync: false and reports enabled: false.

This is an API-specific safety flag, not a request parameter; it does not change the existing shared UI restore behavior. After verifying the restored data and passwords, users may explicitly enable cloud sync later in the client.

Request

POST /api/restoreCloudBackup
api-key: REPLACE_WITH_LOCAL_API_KEY
Content-Type: application/json

Keep the client running and signed in with an active VIP (Pro) membership, with both local_api and cloud-sync access. Copy the actual local base URL and API key from its API screen; do not use the browser CDP port. See Overview and authentication.

JSON body

Parameter	Type	Required	Description
cloudId	string	Yes	ASCII identifier matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$ (1–128 characters). Use an ID from List cloud backups, not a local profile ID.
provider	string	No	Exactly oss or webdav; defaults to the client's global cloud-sync provider.
name	string	No	Local profile name override. Trimmed before use; the trimmed value must contain 1–200 characters. Control characters U+0000–U+001F and U+007F are forbidden. Omit to use the backup name, or a generated name if absent.
password	string	No	Sync encryption password for the separate saved-account envelope, 1–1024 characters. This is not a WebDAV authentication password or the API key.

The body must be a JSON object containing only these fields. Unknown properties, including id, webdav, endpoint, username, enableCloudSync, or enabled, are rejected with HTTP 400. There is no target local ID, overwrite option, or automatic-sync toggle in this request.

For WebDAV, only the server, account, and base directory already saved in the client are used. Configure them there first; do not pass a WebDAV URL, username, or authentication password through this API.

cURL

Replace the base URL, API key, and optional sync-password placeholders before running. The UUID and profile name are fictional. Omit password if you want the client to use its locally saved sync password, if available.

BASE_URL='http://127.0.0.1:REPLACE_WITH_API_PORT'
API_KEY='REPLACE_WITH_LOCAL_API_KEY'
curl --request POST "${BASE_URL}/api/restoreCloudBackup" \
  --header "api-key: ${API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"cloudId":"8f2b6a91-3d74-4c65-9e20-5a1c7d8b9034","provider":"oss","name":"EXAMPLE_RESTORED_PROFILE","password":"REPLACE_WITH_SYNC_ENCRYPTION_PASSWORD"}'

Python

This example omits password and makes one request, without automatic retries.

import requests

base_url = "http://127.0.0.1:REPLACE_WITH_API_PORT"
response = requests.post(
    f"{base_url}/api/restoreCloudBackup",
    headers={"api-key": "REPLACE_WITH_LOCAL_API_KEY"},
    json={
        "cloudId": "8f2b6a91-3d74-4c65-9e20-5a1c7d8b9034",
        "provider": "oss",
        "name": "EXAMPLE_RESTORED_PROFILE",
    },
    timeout=120,
)
result = response.json()
if response.status_code == 409 and result.get("code") == "CLOUD_RESTORE_COMMITTED":
    print("Restore committed; inspect local profile before retrying:", result["data"]["id"])
else:
    response.raise_for_status()
    print(result)

Success response

HTTP 200. This example means that the main profile was restored with automatic cloud sync OFF, but its saved accounts were not restored because no sync password was available.

{
  "success": true,
  "data": {
    "id": 86,
    "cloudId": "8f2b6a91-3d74-4c65-9e20-5a1c7d8b9034",
    "provider": "oss",
    "enabled": false,
    "loginsRestore": {
      "restored": false,
      "reason": "NO_PASSWORD"
    }
  }
}

Field	Type	Meaning
success	boolean	Main profile restoration succeeded.
data.id	integer	Newly allocated, positive local profile ID; not cloudId or an existing target ID.
data.cloudId	string	Cloud backup ID used for the new binding.
data.provider	string	Effective oss or webdav provider.
data.enabled	boolean	Always false on restore: automatic cloud sync is disabled for the new profile, while its cloud association is retained.
data.loginsRestore.restored	boolean	Whether the separate saved accounts were restored.
data.loginsRestore.count	integer, optional	Non-negative restored account count, when reported.
data.loginsRestore.reason	string, optional	Reason when restored is false; not a top-level API error code.

Successful saved-account restoration may return "loginsRestore": {"restored": true, "count": 2}. A failure or skip of this separate step does not invalidate the main restored profile and can still return success: true.

If a later account/session step is interrupted after the main profile has committed, the API instead returns HTTP 409 with CLOUD_RESTORE_COMMITTED and the committed local ID; see below. That error response does not mean the local profile was rolled back.

Saved-account restoration reasons

An explicit password takes precedence; otherwise the client tries its locally saved sync password. If neither is available when an account envelope needs decryption, the non-interactive HTTP flow reports NO_PASSWORD without prompting.

reason	Meaning
NO_PASSWORD	No supplied or locally saved sync password is available.
NOT_FOUND	No saved-account envelope was found; this is not a missing main backup / HTTP 404.
DOWNLOAD_FAILED	Downloading the saved-account envelope failed.
EMPTY	The saved-account envelope contains no accounts to restore.
SKIPPED	Saved-account restoration was skipped.
SYNC_PASSWORD_INVALID	Sync-password validation or envelope decryption failed.
SYNC_PASSWORD_REQUIRED	A sync password is required; this non-interactive route normally uses NO_PASSWORD when none is available.
FAILED	Other saved-account restoration failure.

No automatic retry

Every successful POST creates another local profile, even for the same cloudId. A timeout or lost response does not prove that no profile was created. Do not automatically retry: first check the local profile list and, when available, the backup's localIds in List cloud backups. Confirm the result before deciding whether another restore is needed.

For CLOUD_RESTORE_COMMITTED, inspect the returned data.id first; do not submit another restore just because success is false.

Errors

Errors produced by this endpoint have the form:

{
  "success": false,
  "code": "CLOUD_BACKUP_NOT_FOUND",
  "error": "Cloud backup not found"
}

HTTP	code	Meaning
400	INVALID_PARAMETERS	Invalid JSON body fields, an invalid identifier/name/password, or unknown properties.
400	INVALID_PROVIDER	Provider is not exactly oss or webdav.
400	WEBDAV_CONFIG_REQUIRED	Saved client WebDAV configuration is missing or invalid.
401	AUTH_REQUIRED / LOGIN_REQUIRED	Client sign-in is required. Missing or invalid API keys also return 401, from global middleware.
403	VIP_REQUIRED	Cloud VIP access is missing or expired. Missing local_api authorization also returns 403, from global middleware.
404	CLOUD_BACKUP_NOT_FOUND	The main cloud backup does not exist.
409	CLOUD_SESSION_CHANGED	The account changed before the main profile committed. No new local ID is returned.
409	CLOUD_RESTORE_COMMITTED	The main local profile already committed, but a later account/session step was interrupted. Inspect data.id first; do not blindly retry.
500	CLOUD_BACKUP_RESTORE_FAILED	Main backup restoration failed; generic OSS initialization failures may also surface this way under existing service behavior.
502	WEBDAV_AUTH_FAILED	The saved WebDAV credentials were rejected; correct the client settings.
503	CLOUD_SYNC_UNAVAILABLE	The client's cloud-sync module is unavailable.
504	REQUEST_TIMEOUT	A detected cloud transport timeout; check local profiles before retrying.

504 applies to detected cloud transport timeouts, not every remote initialization failure. Generic OSS initialization failures may still return 500 under the existing service behavior.

Main profile already committed (HTTP 409)

CLOUD_RESTORE_COMMITTED means the main local profile already exists, even though the overall response has success: false. A later account/session step was interrupted. Structural example (error text may differ):

{
  "success": false,
  "code": "CLOUD_RESTORE_COMMITTED",
  "error": "Restore committed; inspect the local profile before retrying",
  "data": {
    "id": 86,
    "committed": true,
    "enabled": false
  }
}

Field	Type	Meaning
data.id	integer	Positive local ID of the profile that already committed; inspect this profile before doing anything else.
data.committed	boolean	true: the main local profile was committed, not rolled back.
data.enabled	boolean	false: automatic cloud sync remains OFF.

Check this local profile's data and passwords before explicitly enabling sync; do not blindly retry the POST. In contrast, ordinary CLOUD_SESSION_CHANGED is only returned before commit and has no new local ID.

Existing global authentication middleware may return success: false and error without code. Always check the HTTP status and body; see Errors and response compatibility.