> ## 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 on-demand pg_dump backup of a DBHost database through the API. The request returns an operation that you can poll until it finishes.

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 |

## Headers

| Header | Required | Description |
| - | - | - |
| `Idempotency-Key` | No | Replaying the same key returns the same backup operation instead of starting another. A key whose backup failed or was canceled answers `409 BACKUP_OPERATION_TERMINAL`; send a new key to request another backup. |

## 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 |
| 409 | `BACKUP_OPERATION_TERMINAL` | The `Idempotency-Key` names a backup that already failed or was canceled; send a new key |
| 500 | `AGENT_ERROR` | The VPS agent failed to start the backup |
| 503 | `DATABASE_VERIFICATION_UNAVAILABLE` | DBHost could not verify the database right now. No database data was changed; retry after `Retry-After`. If you sent an `Idempotency-Key` and the backup operation had already been created, retry with a new key |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.