فایل‌ها

دریافت تغییرات فایل‌ها برای همگام‌سازی

GEThttps://api.parsget.com/api/v1/files/changes

OAuth یا Personal API Key

چه زمانی: اگر برنامه شما نسخه‌ای از فایل‌ها و پوشه‌های حساب را نزد خود نگه می‌دارد، مثلاً کتابخانه فیلم یا فهرست جست‌وجو، به‌جای خواندن دوباره همه فایل‌ها از این endpoint استفاده کنید. برای نمایش محتوای یک پوشه، GET /files کافی است.

بار اول: بدون cursor درخواست بدهید تا همه فایل‌ها و پوشه‌های موجود، از همه پوشه‌ها، برگردند. تا وقتی has_more برابر true است، صفحه بعد را با cursor برابر meta.next_cursor بگیرید.

دفعات بعد: آخرین meta.next_cursor را ذخیره کنید و در درخواست بعدی بفرستید. فقط مواردی برمی‌گردند که از آن زمان تغییر کرده‌اند. اگر تغییری نباشد، فهرست خالی است. این درخواست برای سرور سبک است و می‌توانید آن را مرتب، مثلاً هر ۳۰ تا ۶۰ ثانیه، تکرار کنید.

فایل‌های جدید یا تغییرکرده: هر فایل یا پوشه‌ای که ایجاد، تغییرنام، جابه‌جا یا ویرایش شده باشد، با deleted=false و همان فیلدهای GET /files می‌آید. اگر این id را از قبل دارید، اطلاعات قبلی را با این نسخه جایگزین کنید؛ در غیر این صورت آن را اضافه کنید. دانلود شدن فایل تغییر حساب نمی‌شود.

فایل‌هایی که باید حذف شوند: فایل یا پوشه‌ای که حذف شده، در صف حذف است یا دیگر جزو kind ارسالی شما نیست، فقط با id، parent_id و deleted=true می‌آید. آن را از نسخه خودتان حذف کنید؛ اگر این id را ندارید، کاری لازم نیست.

پوشه‌ها: وقتی فایلی به پوشه‌ای اضافه یا از آن خارج شود، خود پوشه هم با updated_at جدید در نتیجه می‌آید.

تکرار: ممکن است یک مورد در چند پاسخ بیاید. خطا نیست؛ همان کار بالا را دوباره انجام دهید تا آخرین وضعیت در نسخه شما بماند.

شروع دوباره: پاسخ 410 با کد cursor_expired یعنی تغییرات پس از cursor شما دیگر قابل گزارش نیست، مثلاً پس از حذف دائمی فایل‌ها. پاسخ 422 برای cursor یعنی مقدار آن تغییر کرده یا ناقص است. در هر دو حالت cursor را کنار بگذارید و بدون cursor از ابتدا شروع کنید.

ثابت نگه‌داشتن درخواست: در همه درخواست‌های یک همگام‌سازی، همان kind، include_media و include_poster را بفرستید.

OAuth Scope: files:read

Parameters

Field	Type	Description
`include_poster`	`boolean · query`optional default `false`	برای دریافت آدرس و مشخصات پوستر ویدیو، مقدار true بفرستید. پیش‌فرض false است و فیلد poster در پاسخ نمی‌آید. اگر پوستر را درخواست کنید اما موجود نباشد، مقدار آن null است.
`include_media`	`boolean · query`optional default `false`	برای دریافت مشخصات صوتی و تصویری ویدیو در فیلد media، مقدار true بفرستید. پیش‌فرض false است و این فیلد در پاسخ نمی‌آید.
`limit`	`integer · query`optional default `100`min 1max 100	تعداد موارد در هر صفحه؛ پیش‌فرض و حداکثر ۱۰۰ مورد.
`cursor`	`string · query`optional	بار اول نفرستید. پس از آن، meta.next_cursor آخرین پاسخ را بدون تغییر بفرستید.
`kind`	`string · query`optional	فقط این نوع‌ها را برگرداند؛ یک یا چند نوع، جداشده با ویرگول، مانند folder,video. با cursor، فایلی که دیگر جزو این نوع‌ها نیست با deleted=true می‌آید.

Response schema

200تغییرات و cursor بعدی.

Payloadobject[]

Metaobject

پاسخ‌های خطاساختار استاندارد error

Example

{
  "data": [
    {
      "id": "01M1BDF0R5C7E9G2K4N6Q8R3TZ",
      "parent_id": null,
      "download_id": null,
      "name": "Movies",
      "type": "folder",
      "kind": "folder",
      "size_bytes": 0,
      "mime_type": null,
      "locked": false,
      "expires_at": null,
      "created_at": "2026-09-20T08:00:00.000000Z",
      "updated_at": "2026-09-25T09:30:00.000000Z",
      "deleted": false
    },
    {
      "id": "01M1BDK9Z0C6E9G2K5N7Q3R4TX",
      "parent_id": "01M1BDF0R5C7E9G2K4N6Q8R3TZ",
      "download_id": "01M1BDA500B4A6D9K3N5R7T8VC",
      "name": "big-buck-bunny.mp4",
      "type": "file",
      "kind": "video",
      "size_bytes": 1073741824,
      "mime_type": "video/mp4",
      "locked": false,
      "expires_at": "2026-09-30T08:05:00.000000Z",
      "created_at": "2026-09-25T09:30:00.000000Z",
      "updated_at": "2026-09-25T09:30:00.000000Z",
      "deleted": false
    }
  ],
  "meta": {
    "next_cursor": "eyJ2IjoxLCJlIjowLCJzIjoiNzU0MzIxIiwiaCI6bnVsbCwiYSI6bnVsbCwieCI6IjcwMDAwMDAwMDAwMDAwMDAwMDAifQ",
    "has_more": false
  }
}