مدیریت فایل‌ها

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

Endpoints مدیریت فایل‌ها

مرور، خواندن، نوشتن، آپلود، دانلود، فشرده‌سازی و مدیریت مجوزهای فایل‌های سرور.

GET/api/client/servers/{server}/files/list

محتویات یک پوشه را لیست می‌کند. هر آیتم file_object شامل name، mode، mode_bits، size، is_file، is_symlink، mimetype، created_at و modified_at است.

پارامترنوعالزامتوضیح
?directory=string—مسیر پوشه؛ پیش‌فرض /.
curl "https://pufferland.ir/api/client/servers/1a85a183/files/list?directory=%2F" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"
نمونه پاسخ واقعی:
{
  "object": "list",
  "data": [
    {
      "object": "file_object",
      "attributes": {
        "name": ".cache",
        "mode": "drwxr-xr-x",
        "mode_bits": "755",
        "size": 4096,
        "is_file": false,
        "is_symlink": false,
        "mimetype": "inode/directory",
        "created_at": "2026-09-10T04:34:50+03:30",
        "modified_at": "2026-09-10T04:34:50+03:30"
      }
    },
    {
      "object": "file_object",
      "attributes": {
        "name": ".fabric",
        "mode": "drwxr-xr-x",
        "mode_bits": "755",
        "size": 4096,
        "is_file": false,
        "is_symlink": false,
        "mimetype": "inode/directory",
        "created_at": "2026-09-10T04:34:46+03:30",
        "modified_at": "2026-09-10T04:34:46+03:30"
      }
    }
  ]
}
GET/api/client/servers/{server}/files/contents

محتوای یک فایل را به‌صورت متن خام برمی‌گرداند.

پارامترنوعالزامتوضیح
?file=string✓مسیر فایل.
curl "https://pufferland.ir/api/client/servers/1a85a183/files/contents?file=%2Fserver.properties" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx"
const res = await fetch('https://pufferland.ir/api/client/servers/1a85a183/files/contents?file=%2Fserver.properties', {
  headers: { Authorization: 'Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx' },
});
console.log(await res.text());
import requests

r = requests.get(
    "https://pufferland.ir/api/client/servers/1a85a183/files/contents",
    params={"file": "/server.properties"},
    headers={"Authorization": "Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx"},
)
print(r.text)
$content = file_get_contents('https://pufferland.ir/api/client/servers/1a85a183/files/contents?file=%2Fserver.properties', false, stream_context_create([
    'http' => ['header' => 'Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx'],
]));
نمونه پاسخ واقعی:
#Minecraft server properties
#Thu Sep 10 04:35:17 GMT+03:30
enable-jmx-monitoring=false
level-seed=
gamemode=survival
…
POST/api/client/servers/{server}/files/write

محتوای یک فایل را می‌نویسد (در صورت وجود نداشتن، ساخته می‌شود). پاسخ موفق: 204. بدنه‌ی درخواست باید متن خام با هدر Content-Type: text/plain باشد.

پارامترنوعالزامتوضیح
?file=string✓مسیر فایل مقصد.
curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/files/write?file=%2Fnotes.txt" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: text/plain" \
  --data-binary "متن جدید فایل"
await fetch('https://pufferland.ir/api/client/servers/1a85a183/files/write?file=%2Fnotes.txt', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'text/plain',
  },
  body: 'متن جدید فایل',
});
import requests

requests.post(
    "https://pufferland.ir/api/client/servers/1a85a183/files/write",
    params={"file": "/notes.txt"},
    data="متن جدید فایل",
    headers={"Authorization": "Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx", "Content-Type": "text/plain"},
)
curl_post('https://pufferland.ir/api/client/servers/1a85a183/files/write?file=%2Fnotes.txt', [
    CURLOPT_POSTFIELDS => 'متن جدید فایل',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type: text/plain',
    ],
]);
GET/api/client/servers/{server}/files/upload

مرحله‌ی اول آپلود: یک امضای URL برای آپلود برمی‌گرداند (attributes.url). پارامتر اختیاری ?directory= پوشه‌ی مقصد را تعیین می‌کند (پیش‌فرض /).

curl "https://pufferland.ir/api/client/servers/1a85a183/files/upload?directory=%2F" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"
POST{signed_url}

مرحله‌ی دوم آپلود: فایل‌ها را با multipart/form-data به URL امضاشده‌ی مرحله‌ی قبل ارسال می‌کنید. فیلد files برای هر فایل تکرار می‌شود (حداکثر ۱۰ فایل و ۱۰۰ مگابایت برای هر فایل). پوشه‌ها پشتیبانی نمی‌شوند و فایل‌ها با مجوز 0644 ذخیره می‌شوند.

پارامتر directory در مرحله‌ی دوم باید با مرحله‌ی اول یکسان باشد.
# مرحله ۱: گرفتن URL امضاشده از endpoint قبل
curl "https://pufferland.ir/api/client/servers/1a85a183/files/upload?directory=%2F" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx"
# مرحله ۲: آپلود فایل روی URL امضاشده
curl -X POST "https://uploads.example.com/..." \
  -F "files=@plugin.jar" \
  -F "directory=/"
نمونه پاسخ واقعی:
200 OK
GET/api/client/servers/{server}/files/download

یک URL دانلود برای فایل برمی‌گرداند (پاسخ شامل attributes.url؛ فایل از آن آدرس به‌صورت باینری دریافت می‌شود).

پارامترنوعالزامتوضیح
?file=string✓مسیر فایل.
curl "https://pufferland.ir/api/client/servers/1a85a183/files/download?file=%2Fserver.properties" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"
POST/api/client/servers/{server}/files/create-folder

یک پوشه‌ی جدید می‌سازد. پاسخ موفق: 204.

فیلدنوعالزامتوضیح
rootstring✓مسیر پوشه‌ی والد.
namestring✓نام پوشه‌ی جدید.
curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/files/create-folder" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"root": "/", "name": "plugins"}'
POST/api/client/servers/{server}/files/copy

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

فیلدنوعالزامتوضیح
locationstring✓مسیر فایل مبدأ.
curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/files/copy" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"location": "/plugins/plugin.jar"}'
PUT/api/client/servers/{server}/files/rename

نام یک یا چند فایل/پوشه را همزمان تغییر می‌دهد. پاسخ موفق: 204.

فیلدنوعالزامتوضیح
rootstring✓مسیر پوشه‌ی والد.
filesarray✓آرایه‌ای از { "from": "...", "to": "..." }.
curl -X PUT "https://pufferland.ir/api/client/servers/1a85a183/files/rename" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"root": "/", "files": [{"from": "old.jar", "to": "new.jar"}]}'
POST/api/client/servers/{server}/files/delete

یک یا چند فایل/پوشه را حذف می‌کند. پاسخ موفق: 204. دقت کنید این endpoint با متد POST فراخوانی می‌شود.

فیلدنوعالزامتوضیح
rootstring✓مسیر پوشه‌ی والد.
filesarray✓آرایه‌ای از نام فایل‌ها/پوشه‌ها.
حذف فایل‌ها دائمی و غیرقابل بازگشت است.
curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/files/delete" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"root": "/", "files": ["old.jar"]}'
نمونه پاسخ واقعی:
204 No Content
POST/api/client/servers/{server}/files/compress

فایل‌های مشخص‌شده را در یک آرشیو (مانند .tar.gz) فشرده می‌کند و file_object آرشیو ساخته‌شده را برمی‌گرداند.

فیلدنوعالزامتوضیح
rootstring✓مسیر پوشه‌ی والد.
filesarray✓آرایه‌ای از نام فایل‌ها.
curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/files/compress" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"root": "/", "files": ["logs"]}'
نمونه پاسخ واقعی:
{
  "object": "file_object",
  "attributes": {
    "name": "archive-2026-09-16T035826+0330.tar.gz",
    "mode": "-rw-r--r--",
    "mode_bits": "644",
    "size": 126,
    "is_file": true,
    "is_symlink": false,
    "mimetype": "application/tar+gzip",
    "created_at": "2026-09-16T03:58:26+03:30",
    "modified_at": "2026-09-16T03:58:26+03:30"
  }
}
POST/api/client/servers/{server}/files/decompress

آرشیو را در همان مسیر باز می‌کند. پاسخ موفق: 204. فرمت‌های .zip، .tar، .tar.gz و .tar.bz2 پشتیبانی می‌شوند.

فیلدنوعالزامتوضیح
rootstring✓مسیر پوشه‌ی والد.
filestring✓نام فایل آرشیو.
curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/files/decompress" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"root": "/", "file": "archive.tar.gz"}'
POST/api/client/servers/{server}/files/chmod

مجوز (permission) یک یا چند فایل را تغییر می‌دهد. پاسخ موفق: 204.

فیلدنوعالزامتوضیح
rootstring✓مسیر پوشه‌ی والد.
filesarray✓آرایه‌ای از { "file": "...", "mode": "755" } با مقدار هشت‌هشتی.
curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/files/chmod" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"root": "/", "files": [{"file": "start.sh", "mode": "755"}]}'
نمونه پاسخ واقعی:
204 No Content
POST/api/client/servers/{server}/files/pull

یک فایل از اینترنت روی سرور دانلود می‌کند. حداکثر حجم ۱ گیگابایت، حداکثر زمان ۵ دقیقه و فقط پروتکل HTTP/HTTPS. پاسخ موفق: 204.

فیلدنوعالزامتوضیح
urlstring✓آدرس فایل برای دانلود.
directorystring✓پوشه‌ی مقصد.
filenamestring—نام دلخواه فایل؛ در صورت نبودن از نام اصلی استفاده می‌شود.
curl -X POST "https://pufferland.ir/api/client/servers/1a85a183/files/pull" \
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/mod.jar", "directory": "/"}'