> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dbhost.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Restore backup (limited rollout)

> Exact-target restore contract for operator-approved rollouts; not generally available.

Queues a staged restore from an existing backup. DBHost validates the artifact,
creates and verifies a pre-restore backup, restores into an isolated database,
then performs an operation-bound swap. The previous database is retained in
isolation for 24 hours for operator-controlled rollback.

<Warning>
  Limited availability: this is not a normal customer or published CLI workflow.
  Every restore requires an approved per-database rollout binding,
  managed-registry/OID match, operation ID and agent capability. Other databases
  receive `FEATURE_NOT_AVAILABLE`.
</Warning>

## Path parameters

| Parameter  | Type   | Description                                        |
| ---------- | ------ | -------------------------------------------------- |
| `id`       | uuid   | Database ID                                        |
| `filename` | string | Backup filename (format: `YYYYMMDD_HHMMSS.sql.gz`) |

## Example

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer dbh_your_api_key_here" \
  https://dbhost.app/api/v1/databases/550e8400-e29b-41d4-a716-446655440000/backups/20260326_222551.sql.gz
```

## Response

```json 202 Accepted theme={null}
{
  "message": "Staged restore accepted.",
  "operation": {
    "id": "op_01J...",
    "type": "restore",
    "status": "queued",
    "stage": "pre_restore_backup",
    "progress": 0
  }
}
```

Poll `GET /api/v1/operations/{id}` for validation, staging, swap, health-check,
rollback, and completion status.

## Errors

| Status | Code                           | Description                                                                      |
| ------ | ------------------------------ | -------------------------------------------------------------------------------- |
| 400    | `INVALID_BACKUP_FILENAME`      | Filename doesn't match the expected `YYYYMMDD_HHMMSS.sql.gz` format              |
| 401    | `UNAUTHORIZED`                 | Missing or invalid API key                                                       |
| 403    | `FORBIDDEN`                    | The caller can view backups but cannot manage them                               |
| 404    | `DATABASE_NOT_FOUND`           | Database doesn't exist, isn't owned by this user, or isn't in scope for this key |
| 404    | `FEATURE_NOT_AVAILABLE`        | The database has no exact staged-restore rollout binding                         |
| 404    | `BACKUP_NOT_FOUND`             | Backup file not found                                                            |
| 409    | `OPERATION_CONFLICT`           | Another destructive operation is active for the database                         |
| 503    | `AGENT_CAPABILITY_UNAVAILABLE` | The staged-restore agent capability is unavailable                               |
| 500    | `AGENT_ERROR`                  | The VPS agent failed to restore the backup                                       |