Backups

List Backups

GET /api/servers/{serverId}/backups
Authorization: Bearer {token}

List all backups for a server.

Path Parameters

serverId

string

required

Server UUID

Authentication

Requires server access (owner, admin, or member with permissions).

Response

backups

array

Array of backup objects

Show Backup Object

string

Backup UUID

name

string

Backup name

size

number

Backup size in bytes

checksum

string

SHA256 checksum

checksumType

string

Checksum algorithm (sha256)

status

string

IN_PROGRESS | COMPLETED | FAILED | RESTORING

isLocked

boolean

Whether backup is locked from deletion

storagePath

string

Storage path or S3 key

serverId

string

Server UUID

ignoredFiles

array

Files/patterns excluded from backup

completedAt

string

ISO 8601 timestamp

createdAt

string

ISO 8601 timestamp

updatedAt

string

ISO 8601 timestamp

[
  {
    "id": "backup-uuid-1",
    "name": "Backup 1/15/2024",
    "size": 1073741824,
    "checksum": "abc123def456...",
    "checksumType": "sha256",
    "status": "COMPLETED",
    "isLocked": false,
    "storagePath": "/backups/server-uuid/backup-uuid-1.tar.gz",
    "serverId": "server-uuid",
    "ignoredFiles": ["*.log", "cache/*"],
    "completedAt": "2024-01-15T12:00:00Z",
    "createdAt": "2024-01-15T11:55:00Z",
    "updatedAt": "2024-01-15T12:00:00Z"
  }
]

Create Backup

POST /api/servers/{serverId}/backups
Authorization: Bearer {token}
Content-Type: application/json

Create a new backup of the server.

Path Parameters

serverId

string

required

Server UUID

Authentication

Requires server access and server must not be suspended.

Request Body

name

string

Backup name (defaults to “Backup ”)

uuid

string

Custom backup UUID (auto-generated if not provided)

ignore

array

File patterns to exclude from backup (e.g., [“.log”, “cache/”])

locked

boolean

default:"false"

Whether to lock the backup from deletion

{
  "name": "Pre-update backup",
  "ignore": ["*.log", "logs/*", "cache/*"],
  "locked": true
}

Response

Returns the created backup object.

{
  "id": "backup-uuid-2",
  "name": "Pre-update backup",
  "size": 524288000,
  "checksum": "def789ghi012...",
  "checksumType": "sha256",
  "status": "COMPLETED",
  "isLocked": true,
  "serverId": "server-uuid",
  "ignoredFiles": ["*.log", "logs/*", "cache/*"],
  "completedAt": "2024-01-15T14:00:00Z",
  "createdAt": "2024-01-15T13:58:00Z",
  "updatedAt": "2024-01-15T14:00:00Z"
}

Errors

400 - Node is offline or server is suspended
500 - Daemon communication error

Restore Backup

POST /api/servers/{serverId}/backups/restore?id={backupId}
Authorization: Bearer {token}

Restore a server from a backup. This will overwrite existing server files.

Path Parameters

serverId

string

required

Server UUID

Query Parameters

string

required

Backup UUID to restore

Authentication

Requires server access and server must not be suspended.

Response

{
  "success": true,
  "message": "Backup restored successfully"
}

Errors

400 - Backup ID required, node offline, cannot restore from failed backup, or backup not ready
404 - Backup not found
409 - Backup is currently in progress or restoring
500 - Daemon communication error

Generate Download Token

POST /api/servers/{serverId}/backups/download-token
Authorization: Bearer {token}
Content-Type: application/json

Generate a signed download token for a backup. Required before downloading.

Path Parameters

serverId

string

required

Server UUID

Request Body

string

required

Backup UUID to download

{
  "id": "backup-uuid-1"
}

Response

token

string

Signed download token (expires in 5 minutes)

expiresAt

number

Unix timestamp when token expires

downloadUrl

string

Complete download URL with token

{
  "token": "base64url-encoded-signed-token",
  "expiresAt": 1705329600,
  "downloadUrl": "/api/servers/server-uuid/backups/download?token=base64url-encoded-signed-token"
}

Errors

400 - Backup ID required

Download Backup

GET /api/servers/{serverId}/backups/download?token={token}

Download a backup file using a signed token. Token must be generated first.

Path Parameters

serverId

string

required

Server UUID

Query Parameters

token

string

required

Signed download token from download-token endpoint

Authentication

No session authentication required - uses signed token instead.

Response

Returns the backup file as application/gzip with filename {backupId}.tar.gz.

Errors

400 - Invalid token type
401 - Download token required or token expired/invalid
403 - Token not valid for this server
500 - Daemon communication error

Delete Backup

DELETE /api/servers/{serverId}/backups/delete?id={backupId}
Authorization: Bearer {token}

Permanently delete a backup. Cannot delete locked backups.

Path Parameters

serverId

string

required

Server UUID

Query Parameters

string

required

Backup UUID to delete

Authentication

Requires server access and server must not be suspended.

Response

{ "success": true }

Errors

400 - Backup ID required or node offline
403 - Cannot delete locked backup
404 - Backup not found
500 - Daemon communication error

Backup Workflow Example

Here’s a complete workflow for creating and managing backups:

# 1. Create a backup
curl -X POST https://api.stellarstack.io/api/servers/server-uuid/backups \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pre-update backup",
    "ignore": ["*.log", "cache/*"],
    "locked": false
  }'

# Response: { "id": "backup-123", "status": "COMPLETED", ... }

# 2. List all backups
curl https://api.stellarstack.io/api/servers/server-uuid/backups \
  -H "Authorization: Bearer YOUR_TOKEN"

# 3. Generate download token
curl -X POST https://api.stellarstack.io/api/servers/server-uuid/backups/download-token \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "backup-123"}'

# Response: { "token": "abc...", "downloadUrl": "..." }

# 4. Download the backup
curl -O "https://api.stellarstack.io/api/servers/server-uuid/backups/download?token=abc..."

# 5. Restore from backup
curl -X POST "https://api.stellarstack.io/api/servers/server-uuid/backups/restore?id=backup-123" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 6. Delete old backup
curl -X DELETE "https://api.stellarstack.io/api/servers/server-uuid/backups/delete?id=backup-456" \
  -H "Authorization: Bearer YOUR_TOKEN"

Notes

Backups are stored as gzipped tar archives (.tar.gz)
Download tokens expire after 5 minutes for security
Locked backups cannot be deleted until unlocked
Backups in progress or restoring cannot be deleted
Failed backups can be deleted but not restored
Server status is automatically set to RESTORING during restoration

Introduction

Endpoints

List Backups

Path Parameters

Authentication

Response

Create Backup

Path Parameters

Authentication

Request Body

Response

Errors

Restore Backup

Path Parameters

Query Parameters

Authentication

Response

Errors

Generate Download Token

Path Parameters

Request Body

Response

Errors

Download Backup

Path Parameters

Query Parameters

Authentication

Response

Errors

Delete Backup

Path Parameters

Query Parameters

Authentication

Response

Errors

Backup Workflow Example

Notes

Build docs developers (and LLMs) love

Introduction

Endpoints

​List Backups

​Path Parameters

​Authentication

​Response

​Create Backup

​Path Parameters

​Authentication

​Request Body

​Response

​Errors

​Restore Backup

​Path Parameters

​Query Parameters

​Authentication

​Response

​Errors

​Generate Download Token

​Path Parameters

​Request Body

​Response

​Errors

​Download Backup

​Path Parameters

​Query Parameters

​Authentication

​Response

​Errors

​Delete Backup

​Path Parameters

​Query Parameters

​Authentication

​Response

​Errors

​Backup Workflow Example

​Notes

Build docs developers (and LLMs) love

List Backups

Path Parameters

Authentication

Response

Create Backup

Path Parameters

Authentication

Request Body

Response

Errors

Restore Backup

Path Parameters

Query Parameters

Authentication

Response

Errors

Generate Download Token

Path Parameters

Request Body

Response

Errors

Download Backup

Path Parameters

Query Parameters

Authentication

Response

Errors

Delete Backup

Path Parameters

Query Parameters

Authentication

Response

Errors

Backup Workflow Example

Notes