Skip to main content

​
Overview

Volumes are persistent storage units identified by UUIDs. Each volume is automatically mounted to /home/container inside containers.

​
Create Volume

Create a new volume for persistent storage. 
curl -X POST http://localhost:8070/volumes \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json"
Response: 
{
  "volume_id": "d6764075-c5f1-4045-9fb3-85315b85cb0f",
  "path": "/storage/volumes/d6764075-c5f1-4045-9fb3-85315b85cb0f"
}

​
Write File to Volume

Write or overwrite a file in the volume. 
curl -X POST http://localhost:8070/volumes/d6764075/files \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "config/server.properties",
    "content": "server-port=25565\nmax-players=20"
  }'
Request Body:
  • path (required) - Relative path within volume
  • content (required) - File content as string
Response: 
{
  "message": "File written successfully",
  "path": "config/server.properties"
}
Path traversal attempts (e.g., ../../../etc/passwd) are automatically blocked for security.

​
Create Folder

Create a directory in the volume. 
curl -X POST http://localhost:8070/volumes/d6764075/folders \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{"path": "plugins/MyPlugin"}'
Response: 
{
  "message": "Folder created successfully",
  "path": "plugins/MyPlugin"
}

​
Copy File or Folder

Copy files or directories within the volume. 
curl -X POST http://localhost:8070/volumes/d6764075/copy \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "plugins",
    "destination": "backup/plugins"
  }'
Response: 
{
  "message": "Copied successfully",
  "source": "plugins",
  "destination": "backup/plugins"
}

​
List Files

List files and directories in a volume path. 
curl -X GET "http://localhost:8070/volumes/d6764075/files?path=plugins" \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json"
Query Parameters:
  • path (optional) - Subdirectory to list (default: root)
Response: 
{
  "files": [
    {
      "name": "MyPlugin",
      "type": "directory",
      "size": 0
    },
    {
      "name": "config.yml",
      "type": "file",
      "size": 1024
    }
  ]
}

​
Compress Volume

Create an archive from volume contents. 
curl -X POST http://localhost:8070/volumes/d6764075/compress \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "tar.gz",
    "output_name": "backup"
  }'
Supported Formats:
  • zip - ZIP archive
  • tar - TAR archive
  • tar.gz - Gzipped TAR
  • tar.bz2 - Bzip2 compressed TAR
Response: 
{
  "message": "Compression successful",
  "archive_path": "backup.tar.gz",
  "size": 2048576
}

​
Decompress Archive

Extract an archive within the volume. 
curl -X POST http://localhost:8070/volumes/d6764075/decompress \
  -H "Authorization: Bearer lightd_token" \
  -H "Accept: Application/vnd.pkglatv1+json" \
  -H "Content-Type: application/json" \
  -d '{
    "archive_path": "backup.tar.gz",
    "destination": "restored"
  }'
Response: 
{
  "message": "Decompression successful",
  "destination": "restored"
}

​
Volume Path Structure

Volumes are stored at: 
{storage.volumes_path}/{volume_id}/
Example structure: 
/storage/volumes/d6764075-c5f1-4045-9fb3-85315b85cb0f/
├── config/
│   └── server.properties
├── plugins/
│   └── MyPlugin/
└── backup.tar.gz

​
Security Features

All paths are validated to prevent escaping volume boundaries. Patterns like .., absolute paths (/, C:), and empty paths are rejected.
Volumes are automatically mounted to /home/container inside containers.

​
Error Responses

Invalid Path: 
{
  "error": "Invalid path: path traversal detected"
}
Volume Not Found: 
{
  "error": "Volume not found"
}
File Already Exists: 
{
  "error": "File already exists at path: config.yml"
}