Backups

Updated Oct 4, 2026 Markdown

`GET /api/v1/accounts/{username}/backups`

List account backups

Returns every backup tarball recorded for this account, newest first.

Path parameters:

Name	Type	Required	Notes
`username`	string	yes	—

Responses:

Status	Schema	Description
`200`	`ApiSuccess_list_BackupResponse__`	Successful Response
`422`	`HTTPValidationError`	Validation Error

Response example (200):

JSON

{
  "data": [
    {
      "created_at": "...",
      "filename": "...",
      "id": "...",
      "includes_databases": "...",
      "includes_emails": "...",
      "includes_files": "...",
      "remote_destination_id": "...",
      "remote_upload_error": "...",
      "size_mb": "...",
      "status": "...",
      "username": "..."
    }
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell

curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/backups

`POST /api/v1/accounts/{username}/backups`

Create backup

Snapshot the account's files / databases / mailboxes into a tar.gz tarball. Optionally upload to a configured remote destination. Refused 409 UPDATE_IN_PROGRESS while an update is being installed: the update ends in a restart of the agent that would cut the backup.

Path parameters:

Name	Type	Required	Notes
`username`	string	yes	—

Body fields:

Field	Type	Required	Notes
`include_databases`	boolean	no	default `True`
`include_emails`	boolean	no	default `True`
`include_files`	boolean	no	default `True`
`remote_destination_id`	string	no	—

Request body example:

JSON

{
  "include_databases": true,
  "include_emails": true,
  "include_files": true,
  "remote_destination_id": "string"
}

Responses:

Status	Schema	Description
`200`	`ApiSuccess_BackupResponse_`	Successful Response
`422`	`HTTPValidationError`	Validation Error

Response example (200):

JSON

{
  "data": {
    "created_at": "string",
    "filename": "string",
    "id": "string",
    "includes_databases": true,
    "includes_emails": true,
    "includes_files": true,
    "remote_destination_id": "...",
    "remote_upload_error": "...",
    "size_mb": 0.0,
    "status": "ready",
    "username": "alice"
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell

curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/accounts/{username}/backups

`GET /api/v1/accounts/{username}/backups/schedules`

List backup schedules

Returns every recurring backup schedule for the account.

Path parameters:

Name	Type	Required	Notes
`username`	string	yes	—

Responses:

Status	Schema	Description
`200`	`ApiSuccess_list_BackupScheduleResponse__`	Successful Response
`422`	`HTTPValidationError`	Validation Error

Response example (200):

JSON

{
  "data": [
    {
      "created_at": "...",
      "day_of_month": "...",
      "day_of_week": "...",
      "enabled": "...",
      "frequency": "...",
      "id": "...",
      "include_databases": "...",
      "include_emails": "...",
      "include_files": "...",
      "last_run": "...",
      "next_run": "...",
      "remote_destination_id": "...",
      "retention_count": "...",
      "time": "...",
      "username": "..."
    }
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell

curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/backups/schedules

`POST /api/v1/accounts/{username}/backups/schedules`

Create backup schedule

Define a recurring backup (daily / weekly / monthly + time + retention count). Schedules run via the agent's internal cron loop, not the OS crontab.

Path parameters:

Name	Type	Required	Notes
`username`	string	yes	—

Body fields:

Field	Type	Required	Notes
`day_of_month`	integer	no	—
`day_of_week`	integer	no	—
`enabled`	boolean	no	default `True`
`frequency`	string	yes	enum: `daily`, `weekly`, `monthly`
`include_databases`	boolean	no	default `True`
`include_emails`	boolean	no	default `True`
`include_files`	boolean	no	default `True`
`remote_destination_id`	string	no	—
`retention_count`	integer	no	default `5`; minimum=0.0; maximum=100.0
`time`	string	yes	pattern=`^([01]\d\|2[0-3]):[0-5]\d$`

Request body example:

JSON

{
  "day_of_month": 1.0,
  "day_of_week": 0,
  "enabled": true,
  "frequency": "daily",
  "include_databases": true,
  "include_emails": true,
  "include_files": true,
  "remote_destination_id": "string",
  "retention_count": 5,
  "time": "string"
}

Responses:

Status	Schema	Description
`200`	`ApiSuccess_BackupScheduleResponse_`	Successful Response
`422`	`HTTPValidationError`	Validation Error

Response example (200):

JSON

{
  "data": {
    "created_at": "string",
    "day_of_month": "...",
    "day_of_week": "...",
    "enabled": true,
    "frequency": "string",
    "id": "string",
    "include_databases": true,
    "include_emails": true,
    "include_files": true,
    "last_run": "...",
    "next_run": "...",
    "remote_destination_id": "...",
    "retention_count": 5,
    "time": "string",
    "username": "alice"
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell

curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/accounts/{username}/backups/schedules

`DELETE /api/v1/accounts/{username}/backups/schedules/{schedule_id}`

Delete backup schedule

Remove a recurring backup definition. Existing tarballs are kept.

Path parameters:

Name	Type	Required	Notes
`username`	string	yes	—
`schedule_id`	string	yes	—

Responses:

Status	Schema	Description
`200`	`MessageResponse`	Successful Response
`422`	`HTTPValidationError`	Validation Error

Response example (200):

JSON

{
  "message": "string",
  "status": "success"
}

cURL example:

shell

curl -X DELETE \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/backups/schedules/{schedule_id}

`GET /api/v1/accounts/{username}/backups/schedules/{schedule_id}`

Get backup schedule

Fetch one schedule by id.

Path parameters:

Name	Type	Required	Notes
`username`	string	yes	—
`schedule_id`	string	yes	—

Responses:

Status	Schema	Description
`200`	`ApiSuccess_BackupScheduleResponse_`	Successful Response
`422`	`HTTPValidationError`	Validation Error

Response example (200):

JSON

{
  "data": {
    "created_at": "string",
    "day_of_month": "...",
    "day_of_week": "...",
    "enabled": true,
    "frequency": "string",
    "id": "string",
    "include_databases": true,
    "include_emails": true,
    "include_files": true,
    "last_run": "...",
    "next_run": "...",
    "remote_destination_id": "...",
    "retention_count": 5,
    "time": "string",
    "username": "alice"
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell

curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/backups/schedules/{schedule_id}

`PUT /api/v1/accounts/{username}/backups/schedules/{schedule_id}`

Update backup schedule

Patch frequency / time / retention / enabled flag for an existing schedule.

Path parameters:

Name	Type	Required	Notes
`username`	string	yes	—
`schedule_id`	string	yes	—

Body fields:

Field	Type	Required	Notes
`day_of_month`	integer	no	—
`day_of_week`	integer	no	—
`enabled`	boolean	no	—
`frequency`	string	no	—
`include_databases`	boolean	no	—
`include_emails`	boolean	no	—
`include_files`	boolean	no	—
`remote_destination_id`	string	no	—
`retention_count`	integer	no	—
`time`	string	no	—

Request body example:

JSON

{
  "day_of_month": 1.0,
  "day_of_week": 0,
  "enabled": false,
  "frequency": "daily",
  "include_databases": false,
  "include_emails": false,
  "include_files": false,
  "remote_destination_id": "string",
  "retention_count": 0,
  "time": "string"
}

Responses:

Status	Schema	Description
`200`	`ApiSuccess_BackupScheduleResponse_`	Successful Response
`422`	`HTTPValidationError`	Validation Error

Response example (200):

JSON

{
  "data": {
    "created_at": "string",
    "day_of_month": "...",
    "day_of_week": "...",
    "enabled": true,
    "frequency": "string",
    "id": "string",
    "include_databases": true,
    "include_emails": true,
    "include_files": true,
    "last_run": "...",
    "next_run": "...",
    "remote_destination_id": "...",
    "retention_count": 5,
    "time": "string",
    "username": "alice"
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}

cURL example:

shell

curl -X PUT \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/accounts/{username}/backups/schedules/{schedule_id}

`DELETE /api/v1/accounts/{username}/backups/{backup_id}`

Delete backup

Remove a backup tarball from disk and (if applicable) the remote destination.

Path parameters:

Name	Type	Required	Notes
`username`	string	yes	—
`backup_id`	string	yes	—

Responses:

Status	Schema	Description
`200`	`MessageResponse`	Successful Response
`422`	`HTTPValidationError`	Validation Error

Response example (200):

JSON

{
  "message": "string",
  "status": "success"
}

cURL example:

shell

curl -X DELETE \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/backups/{backup_id}

`GET /api/v1/accounts/{username}/backups/{backup_id}/download`

Download backup tarball

Streams the tar.gz file. Binary response — no JSON envelope.

Path parameters:

Name	Type	Required	Notes
`username`	string	yes	—
`backup_id`	string	yes	—

Responses:

Status	Schema	Description
`200`	—	Successful Response
`422`	`HTTPValidationError`	Validation Error

cURL example:

shell

curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/backups/{backup_id}/download

`POST /api/v1/accounts/{username}/backups/{backup_id}/restore`

Restore backup

Restore account files / databases / mailboxes from the given backup tarball. Overwrites current state — destructive. Refused 409 UPDATE_IN_PROGRESS while an update is being installed: the update ends in a restart of the agent that would cut the restore.

Path parameters:

Name	Type	Required	Notes
`username`	string	yes	—
`backup_id`	string	yes	—

Responses:

Status	Schema	Description
`200`	`MessageResponse`	Successful Response
`422`	`HTTPValidationError`	Validation Error

Response example (200):

JSON

{
  "message": "string",
  "status": "success"
}

cURL example:

shell

curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/backups/{backup_id}/restore

Still Need Help?

Our support team is here around the clock for anything you can't find above.