> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pterodactyl/wings/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Backup

> Create a backup of a server

## Endpoint

```
POST /api/servers/:server/backup
```

## Authentication

Requires Bearer token authentication via the `Authorization` header.

## Path Parameters

<ParamField path="server" type="string" required>
  The UUID of the server
</ParamField>

## Request Body

<ParamField body="adapter" type="string" required>
  Backup storage adapter. Valid values: `wings` (local) or `s3`
</ParamField>

<ParamField body="uuid" type="string" required>
  UUID for the backup (generated by Panel)
</ParamField>

<ParamField body="ignore" type="string">
  Newline-separated list of files/directories to exclude from backup (same format as .pteroignore)
</ParamField>

## Response

Returns `202 Accepted` immediately. The backup process continues asynchronously.

## Example Request

<CodeGroup>
  ```bash cURL - Local Backup theme={null}
  curl -X POST "https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/backup" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "adapter": "wings",
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "ignore": "*.log\ntemp/\ncache/"
    }'
  ```

  ```bash cURL - S3 Backup theme={null}
  curl -X POST "https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/backup" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "adapter": "s3",
      "uuid": "550e8400-e29b-41d4-a716-446655440000"
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch(
    'https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/backup',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        adapter: 'wings',
        uuid: '550e8400-e29b-41d4-a716-446655440000',
        ignore: '*.log\ntemp/\ncache/'
      })
    }
  );
  ```

  ```python Python theme={null}
  import requests

  requests.post(
      'https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/backup',
      headers={'Authorization': 'Bearer YOUR_TOKEN'},
      json={
          'adapter': 'wings',
          'uuid': '550e8400-e29b-41d4-a716-446655440000',
          'ignore': '*.log\ntemp/\ncache/'
      }
  )
  ```
</CodeGroup>

## Backup Process

<Steps>
  <Step title="Backup Initiated">
    Wings accepts the request and returns `202 Accepted` immediately.
  </Step>

  <Step title="Archive Creation">
    Creates a gzip-compressed tar archive (`.tar.gz`) of the server directory.

    * Excludes files matching patterns in the `ignore` parameter
    * Excludes files listed in `.pteroignore` file in server root
    * Calculates SHA1 checksum of the archive
  </Step>

  <Step title="Storage Upload">
    **Local (wings) adapter:**

    * Saves backup to the configured backup directory
    * Default: `/var/lib/pterodactyl/backups/`

    **S3 adapter:**

    * Uploads backup to configured S3 bucket using multipart upload
    * Chunk size: 5 MB per part
    * Uses configured S3 credentials from Wings config
  </Step>

  <Step title="Panel Notification">
    Wings notifies the Panel when the backup is complete with:

    * Backup size
    * SHA1 checksum
    * Success/failure status
  </Step>
</Steps>

## Ignore Patterns

The `ignore` parameter supports glob patterns:

* `*.log` - Ignore all .log files
* `temp/` - Ignore temp directory
* `cache/**` - Ignore cache directory and all contents
* `node_modules/` - Ignore node\_modules
* `*.tmp` - Ignore temporary files

<Info>
  Patterns are matched using the same rules as `.gitignore` files.
</Info>

## WebSocket Events

Backup progress is published via WebSocket:

```json theme={null}
{
  "event": "backup progress",
  "args": ["Creating backup archive..."]
}
```

```json theme={null}
{
  "event": "backup complete",
  "args": ["550e8400-e29b-41d4-a716-446655440000"]
}
```

## Behavior

* Backup runs asynchronously in the background
* Server can remain running during backup
* Disk I/O is rate-limited to prevent performance impact (configured via `system.backup_write_limit`)
* Multiple backups can run concurrently (not recommended)
* Backup filename format: `backup-{uuid}.tar.gz`

<Warning>
  Creating backups of large servers can consume significant disk space and I/O. Monitor disk usage carefully.
</Warning>

## Error Responses

<AccordionGroup>
  <Accordion title="400 Bad Request">
    Invalid adapter type or missing required fields
  </Accordion>

  <Accordion title="401 Unauthorized">
    Missing or invalid Bearer token
  </Accordion>

  <Accordion title="404 Not Found">
    Server does not exist
  </Accordion>

  <Accordion title="409 Conflict">
    A backup with this UUID already exists
  </Accordion>

  <Accordion title="500 Internal Server Error">
    Failed to create backup (disk full, S3 error, etc.)
  </Accordion>
</AccordionGroup>

## Configuration

Backup behavior can be configured in `config.yml`:

```yaml theme={null}
system:
  backup_directory: /var/lib/pterodactyl/backups
  backup_write_limit: 0  # 0 = unlimited, otherwise bytes/second
```

For S3 backups, configure S3 settings in the Panel.

## Source Reference

Implementation: `router/router_server_backup.go:19-57` (postServerBackup function)