# Backups

<a id="get-api-v1-accounts-username-backups"></a>
#### `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:**

```bash
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
```

---

<a id="post-api-v1-accounts-username-backups"></a>
#### `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:**

```bash
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
```

---

<a id="get-api-v1-accounts-username-backups-schedules"></a>
#### `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:**

```bash
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
```

---

<a id="post-api-v1-accounts-username-backups-schedules"></a>
#### `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:**

```bash
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
```

---

<a id="delete-api-v1-accounts-username-backups-schedules-schedule-id"></a>
#### `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:**

```bash
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}
```

---

<a id="get-api-v1-accounts-username-backups-schedules-schedule-id"></a>
#### `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:**

```bash
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}
```

---

<a id="put-api-v1-accounts-username-backups-schedules-schedule-id"></a>
#### `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:**

```bash
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}
```

---

<a id="delete-api-v1-accounts-username-backups-backup-id"></a>
#### `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:**

```bash
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}
```

---

<a id="get-api-v1-accounts-username-backups-backup-id-download"></a>
#### `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:**

```bash
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
```

---

<a id="post-api-v1-accounts-username-backups-backup-id-restore"></a>
#### `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:**

```bash
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
```

---