Billing & API

Off-site storage can be sold as an add-on. Each server has an allowance — on or off, a maximum number of copies and a maximum size — that your billing system can change when an invoice is paid or cancelled.

Two ways to set it: on the server's admin page, or through the Application API described here.

Authentication

Use the panel's normal Application API key:

Authorization: Bearer <application-api-key>
Accept: application/json
Content-Type: application/json

Base URL:

https://your-panel/api/application/extensions/offsite-backups

{server} is the panel's numeric server id, not the UUID.

Get a server's allowance

GET /servers/{server}/quota

{
  "object": "offsite_quota",
  "attributes": {
    "server_id": 42,
    "offsite_enabled": true,
    "offsite_max_copies": 14,
    "offsite_max_gb": 50,
    "backup_storage": "node"
  }
}

Field	Type	Meaning
offsite_enabled	boolean	Whether this server may store copies off-site
offsite_max_copies	number	Maximum off-site copies kept; 0 means no per-server limit
offsite_max_gb	number	Maximum off-site storage in GB; 0 means unlimited
backup_storage	node, s3 or null	Where the server's own backups go; null follows the panel default

Set a server's allowance

PUT /servers/{server}/quota

{
  "offsite_enabled": true,
  "offsite_max_copies": 30,
  "offsite_max_gb": 100,
  "backup_storage": "s3"
}

Every field is optional; send only what changes. The response has the same shape as GET.

Typical billing use

Event in your billing panel	Call
Customer buys the "S3 backups" add-on	PUT with backup_storage: "s3" and the allowance
Customer cancels it	PUT with offsite_enabled: false
Customer upgrades storage	PUT with a larger offsite_max_gb

List a server's copies

GET /servers/{server}/copies

{
  "object": "list",
  "data": [
    {
      "object": "offsite_copy",
      "attributes": {
        "uuid": "0f7c…",
        "status": "completed",
        "bytes": 2804492,
        "verification": "sha1",
        "encrypted": false,
        "destination": "Backups bucket",
        "created_at": "2026-10-20T12:02:24Z"
      }
    }
  ]
}

Copy one backup now

POST /servers/{server}/backups/{backup}/offload

{backup} is the backup's UUID. The response is 202 with the copy record. Useful when a customer clicks "back up now" in your billing panel, or to re-copy one specific backup.

Through the panel's own server endpoints

You can also set the allowance while creating or updating a server, without calling the extension directly. Send an extensions object on the panel's normal endpoints:

POST /api/application/servers

{
  "name": "Customer server",
  "user": 1,
  "egg": 1,
  "docker_image": "ghcr.io/pterodactyl/yolks:java_17",
  "startup": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar server.jar",
  "environment": {},
  "limits": { "memory": 1024, "swap": 0, "disk": 5120, "io": 500, "cpu": 100 },
  "feature_limits": { "databases": 0, "allocations": 1, "backups": 5 },
  "extensions": {
    "offsite-backups": {
      "offsite_enabled": true,
      "offsite_max_copies": 14,
      "offsite_max_gb": 50,
      "backup_storage": "node"
    }
  }
}

The same object works on PATCH /api/application/servers/{server}.

Errors

Status	Meaning
401	Missing or invalid API key
403	The key lacks permission
404	Wrong server id, or the extension is disabled
422	Validation — check the field types
429	Panel rate limit; back off and retry

Notes

• backup_storage: "s3" needs an S3 destination that exists and is enabled. Otherwise new backups fall back to the node, and the server's Off-site tab explains why.
• Changing backup_storage does not move existing backups. It only affects new ones.
• offsite_enabled: false stops new copies but does not delete existing ones. Remove them from Copies, or let retention handle it.
• Allowances are enforced when a copy is made, not when a backup is created, so a customer can always take a local backup even when their off-site allowance is full.