> ## 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.

# Trigger backup

> Start an asynchronous database backup/export.

Triggers an asynchronous `pg_dump` backup/export. The request returns immediately while the backup runs in the background.

## Path parameters

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `id`      | uuid | Database ID |

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

## Response

```json 202 Accepted theme={null}
{
  "message": "Backup queued",
  "operation": {
    "id": "op_01J...",
    "type": "backup",
    "status": "queued",
    "stage": "queued",
    "progress": 0
  }
}
```

Poll `GET /api/v1/operations/{id}` for status. The operation ID is also used by
the resulting backup artifact, audit event, and any customer webhook delivery.

## Errors

| Status | Code                 | Description                                                                      |
| ------ | -------------------- | -------------------------------------------------------------------------------- |
| 401    | `UNAUTHORIZED`       | Missing or invalid API key                                                       |
| 403    | `FORBIDDEN`          | 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 |
| 500    | `AGENT_ERROR`        | The VPS agent failed to start the backup                                         |