مدیریت سرور

مرجع کامل endpointهای بخش «مدیریت سرور» در API کلاینت پافرلند.

Endpoints مدیریت سرور

دریافت لیست سرورها، وضعیت و مصرف منابع، مدیریت پاور، کنسول، تنظیمات و استارتاپ.

در تمام مسیرهای زیر، {server} شناسه‌ی سرور است و می‌تواند UUID کامل یا شناسه‌ی کوتاه (مثل 1a7ce997) باشد.

GET/api/client

فهرست همه‌ی سرورهایی که به آن‌ها دسترسی دارید را برمی‌گرداند. پارامترهای ?page، ?per_page (حداکثر ۱۰۰) و ?include=allocations,variables پشتیبانی می‌شوند.

هر سرور شامل identifier، uuid، name، status، limits، sftp_details و feature_limits است.

# فهرست سرورهای شما
curl https://pufferland.ir/api/client \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

const res = await fetch('https://pufferland.ir/api/client', {
  headers: { Authorization: 'Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx', Accept: 'application/json' },
});
const data = await res.json();
console.log(data.data.map(s => s.attributes.identifier));

import requests

r = requests.get(
    "https://pufferland.ir/api/client",
    headers={"Authorization": "Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx"},
)
for s in r.json()["data"]:
    print(s["attributes"]["identifier"], s["attributes"]["name"])

$ch = curl_init('https://pufferland.ir/api/client');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx',
        'Accept: application/json',
    ],
]);
$data = json_decode(curl_exec($ch), true);

نمونه پاسخ واقعی:

{
  "object": "list",
  "data": [
    {
      "object": "server",
      "attributes": {
        "server_owner": true,
        "identifier": "1a85a183",
        "internal_id": 760,
        "uuid": "1a85a183-227b-4e13-b72e-38c71be75c39",
        "name": "fabric - 20260709234813",
        "node": "Puffer 5",
        "is_node_under_maintenance": false,
        "sftp_details": {
          "ip": "p5.pfmc.ir",
          "port": 2022
        },
        "description": "",
        "limits": {
          "memory": 1536,
          "swap": -1,
          "disk": 5120,
          "io": 500,
          "cpu": 50,
          "threads": null,
          "oom_disabled": true
        },
        "invocation": "java -Xms128M -Xmx1536M -jar server.jar",
        "docker_image": "registry.pufferland.ir/yolks:java_25",
        "egg_features": [
          "eula",
          "java_version"
          // … 1 مورد دیگر
        ],
        "feature_limits": {
          "databases": 0,
          "allocations": 2,
          "backups": 0
        },
        "status": null,
        "is_suspended": false,
        "is_installing": false,
        "is_transferring": false,
        "BlueprintFramework": {
          "egg_id": 41
        },
        "relationships": {
          "allocations": {
            "object": "list",
            "data": [
              {
                "object": "allocation",
                "attributes": {
                  "id": 1146,
                  "ip": "37.32.43.26",
                  "ip_alias": "p5.pfmc.ir",
                  "port": 1038,
                  "notes": null,
                  "is_default": true
                }
              }
            ]
          },
          "variables": {
            "object": "list",
            "data": [
              {
                "object": "egg_variable",
                "attributes": {
                  "name": "Server Jar File",
                  "description": "نام فایل jar سرور که برای اجرای سرور استفاده می‌شود.",
                  "env_variable": "SERVER_JARFILE",
                  "default_value": "server.jar",
                  "server_value": "server.jar",
                  "is_editable": true,
                  "rules": "required|regex:/^([\w\d._-]+)(\.jar)$/"
                }
              },
              {
                "object": "egg_variable",
                "attributes": {
                  "name": "Minecraft Version",
                  "description": "نسخه‌ای از ماینکرفت که نصب می‌شود. برای نصب آخرین نسخه از "latest" و برای نصب آخرین نسخه آزمایشی (اسنپ‌شات) از "snapshot" استفاده کنید.",
                  "env_variable": "MC_VERSION",
                  "default_value": "latest",
                  "server_value": "26.2",
                  "is_editable": true,
                  "rules": "required|string|between:3,15"
                }
              }
              // … 4 مورد دیگر
            ]
          }
        }
      }
    },
    {
      "object": "server",
      "attributes": {
        "server_owner": true,
        "identifier": "851f2843",
        "internal_id": 807,
        "uuid": "851f2843-c4ac-4dc7-82d5-423cac7afa34",
        "name": "pocketmine - 20260719224017",
        "node": "Puffer 6",
        "is_node_under_maintenance": false,
        "sftp_details": {
          "ip": "p6.pfmc.ir",
          "port": 2022
        },
        "description": "",
        "limits": {
          "memory": 1024,
          "swap": -1,
          "disk": 5120,
          "io": 500,
          "cpu": 150,
          "threads": null,
          "oom_disabled": true
        },
        "invocation": "python3 -m endstone -s bedrock_server -y --no-interactive",
        "docker_image": "registry.pufferland.ir/yolks:python_3.12",
        "egg_features": [
          "pid_limit"
        ],
        "feature_limits": {
          "databases": 0,
          "allocations": 1,
          "backups": 0
        },
        "status": null,
        "is_suspended": false,
        "is_installing": false,
        "is_transferring": false,
        "BlueprintFramework": {
          "egg_id": 78
        },
        "relationships": {
          "allocations": {
            "object": "list",
            "data": [
              {
                "object": "allocation",
                "attributes": {
                  "id": 1738,
                  "ip": "81.12.50.10",
                  "ip_alias": "p6.pfmc.ir",
                  "port": 1054,
                  "notes": null,
                  "is_default": true
                }
              }
            ]
          },
          "variables": {
            "object": "list",
            "data": [
              {
                "object": "egg_variable",
                "attributes": {
                  "name": "Endstone Version",
                  "description": "نسخه Endstone (مثال: 0.11.10)

مقدار پیش‌فرض latest است — یعنی آخرین نسخه موجود در آرشیو. نسخه باید دقیقاً با کلیدهای فایل versions.json آرشیو مطابقت داشته باشد.",
                  "env_variable": "ENDSTONE_VERSION",
                  "default_value": "latest",
                  "server_value": "latest",
                  "is_editable": false,
                  "rules": "required|string|max:20"
                }
              },
              {
                "object": "egg_variable",
                "attributes": {
                  "name": "Gamemode",
                  "description": "مقادیر مجاز: "survival", "creative", یا "adventure"",
                  "env_variable": "GAMEMODE",
                  "default_value": "survival",
                  "server_value": "survival",
                  "is_editable": true,
                  "rules": "required|string|in:survival,creative,adventure"
                }
              }
              // … 3 مورد دیگر
            ]
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 3,
      "count": 3,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {}
    }
  }
}

در پاسخ واقعی بالا، مقدار identifier سرور اول 1a85a183 است — همان مقداری که در پارامتر {server} استفاده می‌شود.

GET/api/client/permissions

لیست تمام مجوزهای قابل‌اختصاص را گروه‌بندی‌شده برمی‌گرداند (کنترل، فایل، دیتابیس، بکاپ، زمان‌بندی و…). برای ساخت زیرکاربر با endpoint ساخت زیرکاربر کاربرد دارد.

curl "https://pufferland.ir/api/client/permissions" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

نمونه پاسخ واقعی:

{
  "object": "system_permissions",
  "attributes": {
    "permissions": {
      "websocket": {
        "description": "به کاربر اجازه اتصال به وب‌سوکت سرور را می‌دهد و امکان مشاهده خروجی کنسول و آمار لحظه‌ای سرور را فراهم می‌کند.",
        "keys": {
          "connect": "به کاربر اجازه اتصال به نمونه وب‌سوکت سرور برای پخش کنسول را می‌دهد."
        }
      },
      "control": {
        "description": "دسترسی‌هایی که توانایی کاربر برای کنترل وضعیت روشن/خاموش سرور یا ارسال دستورات را مدیریت می‌کند.",
        "keys": {
          "console": "به کاربر اجازه ارسال دستورات به نمونه سرور از طریق کنسول را می‌دهد.",
          "start": "به کاربر اجازه روشن کردن سرور در صورت خاموش بودن را می‌دهد.",
          "stop": "به کاربر اجازه خاموش کردن سرور در صورت روشن بودن را می‌دهد.",
          "restart": "به کاربر اجازه راه‌اندازی مجدد سرور را می‌دهد. این امکان روشن کردن سرور در صورت آفلاین بودن را فراهم می‌کند، اما سرور را به طور کامل متوقف نمی‌کند."
        }
      },
      "user": {
        "description": "دسترسی‌هایی که به کاربر اجازه مدیریت سایر کاربران فرعی سرور را می‌دهد. آنها هرگز نمی‌توانند اکانت خود را ویرایش کنند یا دسترسی‌هایی که خودشان ندارند را اختصاص دهند.",
        "keys": {
          "create": "به کاربر اجازه ایجاد کاربران فرعی جدید برای سرور را می‌دهد.",
          "read": "به کاربر اجازه مشاهده کاربران فرعی و دسترسی‌های آنها برای سرور را می‌دهد.",
          "update": "به کاربر اجازه ویرایش سایر کاربران فرعی را می‌دهد.",
          "delete": "به کاربر اجازه حذف یک کاربر فرعی از سرور را می‌دهد."
        }
      },
      "file": {
        "description": "دسترسی‌هایی که توانایی کاربر برای تغییر فایل‌سیستم این سرور را مدیریت می‌کند.",
        "keys": {
          "create": "به کاربر اجازه ایجاد فایل‌ها و پوشه‌های جدید از طریق پنل یا آپلود مستقیم را می‌دهد.",
          "read": "به کاربر اجازه مشاهده محتویات یک پوشه را می‌دهد، اما اجازه مشاهده محتویات یا دانلود فایل‌ها را نمی‌دهد.",
          "read-content": "به کاربر اجازه مشاهده محتویات یک فایل مشخص را می‌دهد. همچنین به کاربر اجازه دانلود فایل‌ها را نیز می‌دهد.",
          "update": "به کاربر اجازه به‌روزرسانی محتویات یک فایل یا پوشه موجود را می‌دهد.",
          "delete": "به کاربر اجازه حذف فایل‌ها یا پوشه‌ها را می‌دهد.",
          "archive": "به کاربر اجازه فشرده‌سازی محتویات یک پوشه و همچنین استخراج آرشیوهای موجود روی سیستم را می‌دهد.",
          "sftp": "به کاربر اجازه اتصال به SFTP و مدیریت فایل‌های سرور با استفاده از سایر دسترسی‌های فایل اختصاص داده شده را می‌دهد."
        }
      },
      "backup": {
        "description": "دسترسی‌هایی که توانایی کاربر برای تولید و مدیریت بکاپ‌های سرور را مدیریت می‌کند.",
        "keys": {
          "create": "به کاربر اجازه ایجاد بکاپ‌های جدید برای این سرور را می‌دهد.",
          "read": "به کاربر اجازه مشاهده تمام بکاپ‌های موجود برای این سرور را می‌دهد.",
          "delete": "به کاربر اجازه حذف بکاپ‌ها از سیستم را می‌دهد.",
          "download": "به کاربر اجازه دانلود بکاپ سرور را می‌دهد. هشدار: این امکان به کاربر اجازه دسترسی به تمام فایل‌های سرور در بکاپ را می‌دهد.",
          "restore": "به کاربر اجازه بازیابی بکاپ سرور را می‌دهد. هشدار: این امکان به کاربر اجازه حذف تمام فایل‌های سرور در این فرآیند را می‌دهد."
        }
      },
      "allocation": {
        "description": "دسترسی‌هایی که توانایی کاربر برای تغییر تخصیص پورت‌های این سرور را مدیریت می‌کند.",
        "keys": {
          "read": "به کاربر اجازه مشاهده تمام تخصیص‌های فعلی اختصاص داده شده به این سرور را می‌دهد. کاربران با هر سطح دسترسی به این سرور همیشه می‌توانند تخصیص اصلی را مشاهده کنند.",
          "create": "به کاربر اجازه اختصاص تخصیص‌های اضافی به سرور را می‌دهد.",
          "update": "به کاربر اجازه تغییر تخصیص اصلی سرور و افزودن یادداشت به هر تخصیص را می‌دهد.",
          "delete": "به کاربر اجازه حذف یک تخصیص از سرور را می‌دهد."
        }
      },
      "startup": {
        "description": "دسترسی‌هایی که توانایی کاربر برای مشاهده پارامترهای استارتاپ این سرور را مدیریت می‌کند.",
        "keys": {
          "read": "به کاربر اجازه مشاهده متغیرهای استارتاپ سرور را می‌دهد.",
          "update": "به کاربر اجازه ویرایش متغیرهای استارتاپ سرور را می‌دهد.",
          "docker-image": "به کاربر اجازه تغییر ایمیج Docker مورد استفاده هنگام اجرای سرور را می‌دهد."
        }
      },
      "database": {
        "description": "دسترسی‌هایی که دسترسی کاربر به مدیریت پایگاه داده برای این سرور را مدیریت می‌کند.",
        "keys": {
          "create": "به کاربر اجازه ایجاد یک پایگاه داده جدید برای این سرور را می‌دهد.",
          "read": "به کاربر اجازه مشاهده پایگاه داده مرتبط با این سرور را می‌دهد.",
          "update": "به کاربر اجازه تغییر رمز عبور یک نمونه پایگاه داده را می‌دهد. اگر کاربر دسترسی view_password نداشته باشد، رمز عبور به‌روزرسانی شده را مشاهده نخواهد کرد.",
          "delete": "به کاربر اجازه حذف یک نمونه پایگاه داده از این سرور را می‌دهد.",
          "view_password": "به کاربر اجازه مشاهده رمز عبور مرتبط با یک نمونه پایگاه داده برای این سرور را می‌دهد."
        }
      },
      "schedule": {
        "description": "دسترسی‌هایی که دسترسی کاربر به مدیریت زمان‌بندی برای این سرور را مدیریت می‌کند.",
        "keys": {
          "create": "به کاربر اجازه ایجاد زمان‌بندی‌های جدید برای این سرور را می‌دهد.",
          "read": "به کاربر اجازه مشاهده زمان‌بندی‌ها و وظایف مرتبط با آنها برای این سرور را می‌دهد.",
          "update": "به کاربر اجازه به‌روزرسانی زمان‌بندی‌ها و وظایف زمان‌بندی برای این سرور را می‌دهد.",
          "delete": "به کاربر اجازه حذف زمان‌بندی‌ها برای این سرور را می‌دهد."
        }
      },
      "settings": {
        "description": "دسترسی‌هایی که دسترسی کاربر به تنظیمات این سرور را مدیریت می‌کند.",
        "keys": {
          "rename": "به کاربر اجازه تغییر نام این سرور و تغییر توضیحات آن را می‌دهد.",
          "reinstall": "به کاربر اجازه شروع نصب مجدد این سرور را می‌دهد."
        }
      },
      "activity": {
        "description": "دسترسی‌هایی که دسترسی کاربر به لاگ‌های فعالیت سرور را مدیریت می‌کند.",
        "keys": {
          "read": "به کاربر اجازه مشاهده لاگ‌های فعالیت سرور را می‌دهد."
        }
      }
    }
  }
}

GET/api/client/servers/{server}

جزئیات کامل یک سرور مشخص را برمی‌گرداند: محدودیت‌های منابع، ایمیج داکر، وضعیت، دستور اجرا و… . در بخش meta پاسخ نیز is_server_owner و user_permissions موجود است.

curl "https://pufferland.ir/api/client/servers/1a85a183" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

نمونه پاسخ واقعی:

{
  "object": "server",
  "attributes": {
    "server_owner": true,
    "identifier": "1a85a183",
    "internal_id": 760,
    "uuid": "1a85a183-227b-4e13-b72e-38c71be75c39",
    "name": "fabric - 20260709234813",
    "node": "Puffer 5",
    "is_node_under_maintenance": false,
    "sftp_details": {
      "ip": "p5.pfmc.ir",
      "port": 2022
    },
    "description": "",
    "limits": {
      "memory": 1536,
      "swap": -1,
      "disk": 5120,
      "io": 500,
      "cpu": 50,
      "threads": null,
      "oom_disabled": true
    },
    "invocation": "java -Xms128M -Xmx1536M -jar server.jar",
    "docker_image": "registry.pufferland.ir/yolks:java_25",
    "egg_features": [
      "eula",
      "java_version"
      // … 1 مورد دیگر
    ],
    "feature_limits": {
      "databases": 0,
      "allocations": 2,
      "backups": 0
    },
    "status": null,
    "is_suspended": false,
    "is_installing": false,
    "is_transferring": false,
    "BlueprintFramework": {
      "egg_id": 41
    },
    "relationships": {
      "allocations": {
        "object": "list",
        "data": [
          {
            "object": "allocation",
            "attributes": {
              "id": 1146,
              "ip": "37.32.43.26",
              "ip_alias": "p5.pfmc.ir",
              "port": 1038,
              "notes": null,
              "is_default": true
            }
          }
        ]
      },
      "variables": {
        "object": "list",
        "data": [
          {
            "object": "egg_variable",
            "attributes": {
              "name": "Server Jar File",
              "description": "نام فایل jar سرور که برای اجرای سرور استفاده می‌شود.",
              "env_variable": "SERVER_JARFILE",
              "default_value": "server.jar",
              "server_value": "server.jar",
              "is_editable": true,
              "rules": "required|regex:/^([\w\d._-]+)(\.jar)$/"
            }
          },
          {
            "object": "egg_variable",
            "attributes": {
              "name": "Minecraft Version",
              "description": "نسخه‌ای از ماینکرفت که نصب می‌شود. برای نصب آخرین نسخه از "latest" و برای نصب آخرین نسخه آزمایشی (اسنپ‌شات) از "snapshot" استفاده کنید.",
              "env_variable": "MC_VERSION",
              "default_value": "latest",
              "server_value": "26.2",
              "is_editable": true,
              "rules": "required|string|between:3,15"
            }
          }
          // … 4 مورد دیگر
        ]
      }
    }
  },
  "meta": {
    "is_server_owner": true,
    "user_permissions": [
      "*"
    ]
  }
}

GET/api/client/servers/{server}/resources

مصرف لحظه‌ای منابع سرور را برمی‌گرداند: current_state (مانند running)، is_suspended و resources شامل memory_bytes، cpu_absolute، disk_bytes، network_rx_bytes، network_tx_bytes و uptime (میلی‌ثانیه).

# مصرف لحظه‌ای منابع
curl https://pufferland.ir/api/client/servers/1a85a183/resources \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

const res = await fetch('https://pufferland.ir/api/client/servers/1a85a183/resources', {
  headers: { Authorization: 'Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx', Accept: 'application/json' },
});
const { attributes } = await res.json();
console.log(attributes.current_state, attributes.resources.cpu_absolute);

import requests

r = requests.get(
    "https://pufferland.ir/api/client/servers/1a85a183/resources",
    headers={"Authorization": "Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx"},
)
stats = r.json()["attributes"]
print(stats["current_state"], stats["resources"]["memory_bytes"])

$ch = curl_init('https://pufferland.ir/api/client/servers/1a85a183/resources');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx'],
]);
$stats = json_decode(curl_exec($ch), true)['attributes'];
echo $stats['current_state'];

نمونه پاسخ واقعی:

{
  "object": "stats",
  "attributes": {
    "current_state": "offline",
    "is_suspended": false,
    "resources": {
      "memory_bytes": 0,
      "cpu_absolute": 0,
      "disk_bytes": 459171046,
      "network_rx_bytes": 0,
      "network_tx_bytes": 0,
      "uptime": 0
    }
  }
}

POST/api/client/servers/{server}/power

دستور پاور به سرور ارسال می‌کند. پاسخ موفق: 204 بدون بدنه.

فیلد	نوع	الزام	توضیح
`signal`	string	✓	یکی از مقادیر `start`، `stop`، `restart` یا `kill`.

خطای 400 با کد ConflictingServerStateException در صورت نصب بودن یا اجرای از پیش سرور.

curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/power" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"signal": "restart"}'

await fetch('https://pufferland.ir/api/client/servers/1a85a183/power', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ signal: 'restart' }),
});

import requests

requests.post(
    "https://pufferland.ir/api/client/servers/1a85a183/power",
    json={"signal": "restart"},
    headers={"Authorization": "Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx"},
)

curl_post('https://pufferland.ir/api/client/servers/1a85a183/power', [
    CURLOPT_POSTFIELDS => json_encode(['signal' => 'restart']),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
    ],
]);

GET/api/client/servers/{server}/websocket

اعتبارنامه‌ی اتصال به کنسول زنده را برمی‌گرداند: token (JWT یک‌بارمصرف) و socket (آدرس wss://). پس از اتصال، رویداد auth را با توکن ارسال کنید.

رویدادهای قابل ارسال: auth، send command، set state — رویدادهای دریافتی: console output، status، stats.

curl "https://pufferland.ir/api/client/servers/1a85a183/websocket" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

نمونه پاسخ واقعی:

{
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImp0aSI6ImFkMmUwMWZhNWMxM2IwYTVhYmMwMzFhN2Q4ODZhMDc1In0.eyJpc3MiOiJodHRwczovL3BhbmVsLnB1ZmZlcmxhbmQuaXIiLCJhdWQiOlsiaHR0cHM6Ly9wNS5wZm1jLmlyOjgwODAiXSwianRpIjoiYWQyZTAxZmE1YzEzYjBhNWFiYzAzMWE3ZDg4NmEwNzUiLCJpYXQiOjE3ODk1MjQ1MjYsIm5iZiI6MTc4OTUyNDIyNiwiZXhwIjoxNzg5NTI1MTI2LCJzZXJ2ZXJfdXVpZCI6IjFhODVhMTgzLTIyN2ItNGUxMy1iNzJlLTM4YzcxYmU3NWMzOSIsInBlcm1pc3Npb25zIjpbIioiXSwidXNlcl91dWlkIjoiYTQ2MjZlZjktMjYzYS00YzA3LWI1ZTktYzAxYmUwYWJkZGYwIiwidXNlcl9pZCI6Njc2LCJ1bmlxdWVfaWQiOiJpY1ZuRmR5VktPdkpwVGk1In0.apkQWwKaYxpmgJf-wYoHj-hwDlSH7QkNBGRATgRVSi4",
    "socket": "wss://p5.pfmc.ir:8080/api/servers/1a85a183-227b-4e13-b72e-38c71be75c39/ws"
  }
}

POST/api/client/servers/{server}/command

یک دستور به کنسول سرور ارسال می‌کند. پاسخ موفق: 204. سرور باید روشن باشد؛ در غیر این صورت خطای 400. مجوز لازم: control.console.

فیلد	نوع	الزام	توضیح
`command`	string	✓	متن دستور کنسول.

curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/command" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"command": "say Hello"}'

await fetch('https://pufferland.ir/api/client/servers/1a85a183/command', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ command: 'say Hello' }),
});

import requests

requests.post(
    "https://pufferland.ir/api/client/servers/1a85a183/command",
    json={"command": "say Hello"},
    headers={"Authorization": "Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx"},
)

curl_post('https://pufferland.ir/api/client/servers/1a85a183/command', [
    CURLOPT_POSTFIELDS => json_encode(['command' => 'say Hello']),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
    ],
]);

POST/api/client/servers/{server}/settings/rename

نام و توضیحات سرور را تغییر می‌دهد. پاسخ موفق: 204.

فیلد	نوع	الزام	توضیح
`name`	string	✓	نام جدید سرور (۱ تا ۲۵۵ کاراکتر).
`description`	string	—	توضیحات سرور (حداکثر ۵۰۰ کاراکتر).

curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/settings/rename" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Server", "description": "توضیحات سرور"}'

POST/api/client/servers/{server}/settings/reinstall

نصب مجدد سرور را آغاز می‌کند (اسکریپت نصب دوباره اجرا می‌شود). پاسخ موفق: 202. فایل‌های موجود سرور حذف نمی‌شوند.

curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/settings/reinstall" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

PUT/api/client/servers/{server}/settings/docker-image

ایمیج داکر سرور را تغییر می‌دهد. پاسخ موفق: 204. خطای 422 برای ایمیج نامعتبر. مجوز لازم: startup.docker-image.

فیلد	نوع	الزام	توضیح
`docker_image`	string	✓	نام ایمیج — ایمیج‌های مجاز در پاسخ endpoint استارتاپ آمده است.

curl -X PUT "https://pufferland.ir/api/client/servers/1a85a183/settings/docker-image" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"docker_image": "ghcr.io/parkervcp/yolks:java_17"}'

GET/api/client/servers/{server}/startup

تنظیمات استارتاپ سرور را برمی‌گرداند: لیست متغیرهای egg_variable (با env_variable، server_value، is_editable و قوانین اعتبارسنجی) به‌علاوه‌ی startup_command و docker_images در بخش meta.

curl "https://pufferland.ir/api/client/servers/1a85a183/startup" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

نمونه پاسخ واقعی:

{
  "object": "list",
  "data": [
    {
      "object": "egg_variable",
      "attributes": {
        "name": "Server Jar File",
        "description": "نام فایل jar سرور که برای اجرای سرور استفاده می‌شود.",
        "env_variable": "SERVER_JARFILE",
        "default_value": "server.jar",
        "server_value": "server.jar",
        "is_editable": true,
        "rules": "required|regex:/^([\w\d._-]+)(\.jar)$/"
      }
    },
    {
      "object": "egg_variable",
      "attributes": {
        "name": "Minecraft Version",
        "description": "نسخه‌ای از ماینکرفت که نصب می‌شود. برای نصب آخرین نسخه از "latest" و برای نصب آخرین نسخه آزمایشی (اسنپ‌شات) از "snapshot" استفاده کنید.",
        "env_variable": "MC_VERSION",
        "default_value": "latest",
        "server_value": "26.2",
        "is_editable": true,
        "rules": "required|string|between:3,15"
      }
    }
  ],
  "meta": {
    "startup_command": "java -Xms128M -Xmx1536M -jar server.jar",
    "docker_images": {
      "Java 25": "registry.pufferland.ir/yolks:java_25",
      "Java 21": "registry.pufferland.ir/yolks:java_21",
      "Java 17": "registry.pufferland.ir/yolks:java_17",
      "Java 16": "registry.pufferland.ir/yolks:java_16",
      "Java 11": "ghcr.io/pterodactyl/yolks:java_11",
      "Java 8": "registry.pufferland.ir/yolks:java_8"
    },
    "raw_startup_command": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}"
  }
}

PUT/api/client/servers/{server}/startup/variable

مقدار یک متغیر استارتاپ را به‌روزرسانی می‌کند و متغیر به‌روزشده را برمی‌گرداند. خطای 422 اگر مقدار قوانین اعتبارسنجی را نقض کند یا کلید نامعتبر باشد؛ خطای 400 اگر متغیر قابل ویرایش نباشد.

فیلد	نوع	الزام	توضیح
`key`	string	✓	نام متغیر محیطی (`env_variable`).
`value`	string	✓	مقدار جدید متغیر.

curl -X PUT "https://pufferland.ir/api/client/servers/1a85a183/startup/variable" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"key": "SERVER_JARFILE", "value": "server.jar"}'

GET/api/client/servers/{server}/activity

لاگ فعالیت‌های سرور (مانند server:power.start) را به‌صورت صفحه‌بندی‌شده برمی‌گرداند.

curl "https://pufferland.ir/api/client/servers/1a85a183/activity?page=1" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

نمونه پاسخ واقعی:

{
  "object": "list",
  "data": [
    {
      "object": "activity_log",
      "attributes": {
        "id": "331bcd47e778042a41bd9e085880cef9953fadd6",
        "batch": null,
        "event": "server:power.start",
        "is_api": false,
        "ip": "86.57.47.17",
        "description": null,
        "properties": {},
        "has_additional_metadata": false,
        "timestamp": "2026-07-27T19:57:21+03:30"
      }
    },
    {
      "object": "activity_log",
      "attributes": {
        "id": "385e74c358cf406ac901635fcb5f5037c1db088a",
        "batch": null,
        "event": "server:power.kill",
        "is_api": false,
        "ip": "86.57.47.17",
        "description": null,
        "properties": {},
        "has_additional_metadata": false,
        "timestamp": "2026-07-27T19:57:26+03:30"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 95,
      "count": 25,
      "per_page": 25,
      "current_page": 1,
      "total_pages": 4,
      "links": {
        "next": "https://panel.pufferland.ir/api/client/servers/1a85a183/activity?page=2"
      }
    }
  }
}