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

# Pull Remote File

> Download a file from a remote URL directly to the server

## Endpoint

```
POST /api/servers/:server/files/pull
```

## Configuration Requirement

This endpoint must be **explicitly enabled** in the Wings configuration. It is disabled by default for security reasons.

In `config.yml`:

```yaml theme={null}
api:
  disable_remote_download: false  # Must be false to enable remote downloads
```

<Warning>
  Remote file downloads can pose security risks if not properly validated. Only enable this feature if you trust the users who have access to your servers.
</Warning>

## 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="url" type="string" required>
  The remote URL to download from (must be HTTP/HTTPS)
</ParamField>

<ParamField body="directory" type="string" required>
  The destination directory where the file will be saved (relative to server root)
</ParamField>

<ParamField body="filename" type="string">
  Optional custom filename. If not provided, filename is extracted from the URL or Content-Disposition header.
</ParamField>

<ParamField body="use_header" type="boolean" default="false">
  Whether to use the filename from the Content-Disposition header if available
</ParamField>

<ParamField body="foreground" type="boolean" default="false">
  Whether to download in the foreground (blocks until complete) or background
</ParamField>

## Response

Returns `204 No Content` on success (background download) or after completion (foreground download).

## Example Request

<CodeGroup>
  ```bash cURL - Background Download theme={null}
  curl -X POST "https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/files/pull" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/plugins/MyPlugin.jar",
      "directory": "/plugins",
      "foreground": false
    }'
  ```

  ```bash cURL - Foreground with Custom Name theme={null}
  curl -X POST "https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/files/pull" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://cdn.example.com/map.zip",
      "directory": "/downloads",
      "filename": "custom-map.zip",
      "foreground": true
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch(
    'https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/files/pull',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        url: 'https://github.com/user/repo/releases/download/v1.0/plugin.jar',
        directory: '/plugins',
        use_header: true,
        foreground: false
      })
    }
  );
  ```

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

  requests.post(
      'https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/files/pull',
      headers={'Authorization': 'Bearer YOUR_TOKEN'},
      json={
          'url': 'https://example.com/data.zip',
          'directory': '/imports',
          'filename': 'imported-data.zip',
          'foreground': True
      }
  )
  ```
</CodeGroup>

## Behavior

* Downloads are performed asynchronously by default (`foreground: false`)
* Foreground downloads block until complete, background downloads return immediately
* Download progress is published via WebSocket events
* File is written directly to disk (no memory buffering of entire file)
* Supports redirects (follows 3xx responses)
* User-Agent is set to `Pterodactyl Wings`
* Timeout: 15 minutes for the entire download
* Maximum file size: Limited by available disk space
* Existing files with the same name are overwritten
* Path traversal is prevented

<Info>
  Monitor download progress through the server's WebSocket connection. Progress events include download speed and bytes downloaded.
</Info>

## Error Responses

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

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

  <Accordion title="403 Forbidden">
    Remote downloads are disabled in Wings configuration
  </Accordion>

  <Accordion title="404 Not Found">
    Server does not exist or remote file not found
  </Accordion>

  <Accordion title="500 Internal Server Error">
    Failed to download file (network error, disk full, etc.)
  </Accordion>
</AccordionGroup>

## Security Considerations

* **SSRF Prevention**: Wings does not validate remote URLs. Malicious users could potentially download from internal network resources.
* **Disk Usage**: Large downloads can fill up disk space
* **Malware**: Downloaded files are not scanned for malware
* **Rate Limiting**: No built-in rate limiting for remote downloads

<Warning>
  Consider the security implications before enabling remote downloads. Use firewall rules and network policies to restrict access to sensitive internal resources.
</Warning>

## Use Cases

* Download plugins from remote repositories
* Import world maps from CDN
* Fetch configuration files from GitHub
* Download mod packs
* Import database dumps

## Source Reference

Implementation: `router/router_server_files.go` (postServerPullRemoteFile function)