فایل‌ها

فهرست فایل‌ها و پوشه‌ها

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

OAuth یا Personal API Key

فایل‌ها و پوشه‌های حساب را دریافت کنید. بدون فیلتر پوشه یا دانلود، مواردی را می‌بینید که داخل هیچ پوشه‌ای نیستند. با parent_id محتوای یک پوشه و با download_id فایل‌های یک دانلود را بگیرید. برای محدود کردن فهرست به ویدیوها، kind=video بفرستید.

برای دریافت فایل‌ها و پوشه‌های سراسر حساب در یک فهرست، flatten=true بفرستید. با این گزینه، محتوای پوشه‌ها و زیرپوشه‌ها هم در فهرست می‌آید. مثلاً با flatten=true&kind=video می‌توانید همه ویدیوهای حساب را نمایش دهید. هنگام استفاده از flatten=true، شناسه پوشه در parent_id نفرستید؛ ترکیب این دو پاسخ 422 دارد. برای دریافت فقط فایل‌های یک دانلود، می‌توانید download_id بفرستید. parent_id هر نتیجه نشان می‌دهد آن فایل یا پوشه داخل کدام پوشه قرار دارد.

بدون updated_after، موارد بر اساس شناسه از بزرگ به کوچک مرتب می‌شوند. با updated_after، فقط مواردی برمی‌گردند که پس از زمان ارسالی تغییر کرده‌اند. در این حالت، ترتیب بر اساس updated_at از قدیمی به جدید است و برای زمان‌های برابر، id از کوچک به بزرگ مرتب می‌شود. این فیلتر حذف فایل‌ها را گزارش نمی‌کند؛ برای همگام‌سازی کامل، به‌تنهایی کافی نیست.

با include_media=true، خلاصه مشخصات صوتی و تصویری ویدیو هم در پاسخ می‌آید. برای جزئیات کامل، ترک‌های صوتی و زیرنویس‌های داخل فایل، GET /files/{file} را با همین گزینه فراخوانی کنید.

OAuth Scope: files:read

Parameters

Field	Type	Description
`include_state`	`boolean · query`optional default `false`	برای دریافت داده‌هایی که برنامه شما برای این فایل یا پوشه ذخیره کرده، مقدار true بفرستید. این داده‌ها در app_state می‌آیند. به توکن OAuth با دسترسی‌های files:read و storage:read نیاز دارید. پیش‌فرض false است و این فیلد در پاسخ نمی‌آید.
`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 `50`min 1max 100	تعداد موارد در هر صفحه؛ پیش‌فرض ۵۰ و حداکثر ۱۰۰ مورد.
`cursor`	`string · query`optional	برای صفحه اول نفرستید. برای صفحه بعد، مقدار meta.next_cursor پاسخ قبلی را بدون تغییر بفرستید.
`flatten`	`boolean · query`optional default `false`	برای دریافت فایل‌ها و پوشه‌ها از سراسر حساب، مقدار true بفرستید. پیش‌فرض false است. برای دریافت فقط ویدیوها، kind=video را هم بفرستید. با مقدار true، نباید شناسه پوشه در parent_id بفرستید.
`parent_id`	`string · query`optional	شناسه پوشه برای دریافت محتویات آن
`download_id`	`string · query`optional	شناسه دانلود برای فیلتر فایل‌های آن
`kind`	`string · query`optional `foldervideoaudioimagedocumentarchivesubtitleother`	برای فیلتر نوع محتوا، مانند video برای ویدیوها.
`updated_after`	`string · query`optionaldate-time	فقط موارد تغییرکرده پس از این زمان را برمی‌گرداند. زمان کامل RFC 3339 با منطقه زمانی بفرستید، مانند 2026-08-26T12:00:00Z. این فیلتر حذف‌ها را گزارش نمی‌کند و محتوای همه زیرپوشه‌ها را خودکار فهرست نمی‌کند.

Response schema

200فهرست فایل‌ها و پوشه‌ها و اطلاعات صفحه بعد.

Payloadobject[]

Field	Type	Description
`id`	`string`	—
`parent_id`	`string`	شناسه پوشه‌ای که فایل یا پوشه فعلی داخل آن قرار دارد. برای مواردی که داخل هیچ پوشه‌ای نیستند، null است.
`download_id`	`string`	شناسه دانلود مرتبط با فایل یا پوشه؛ اگر دانلود مرتبطی نداشته باشد null است.
`name`	`string`	—
`type`	`string` `filefolder`	—
`kind`	`string` `foldervideoaudioimagedocumentarchivesubtitleother`	—
`media`	`object \| null`	مشخصات صوتی و تصویری ویدیو؛ فقط با include_media=true در پاسخ می‌آید و برای فایل‌های غیر ویدیویی null است. GET /files خلاصه مشخصات و GET /files/{file} جزئیات کامل را برمی‌گرداند.
`status`	`string` `pendingreadyunavailable`	وضعیت آماده‌سازی مشخصات رسانه: pending یعنی در انتظار آماده‌سازی، ready یعنی آماده و unavailable یعنی در دسترس نیست. وضعیت دانلود را جداگانه از status دانلود بخوانید.
`title`	`string`	عنوان ثبت‌شده در متادیتای فایل رسانه.
`description`	`string`	—
`creation_time`	`string`	زمان ایجاد رسانه که در متادیتای فایل ثبت شده است.
`format_names`	`string[]`	—
`duration_ms`	`integer`int64	مدت پخش بر حسب میلی‌ثانیه.
`bitrate`	`integer`int64	—
`width`	`integer`	—
`height`	`integer`	—
`chapters`	`object[]`
`start_ms`	`integer`int64 min 0	—
`end_ms`	`integer`int64 min 1	—
`title`	`string`	—
`video_streams`	`object[]`
`index`	`integer`	—
`codec`	`string`	—
`codec_tag`	`string`	—
`profile`	`string`	—
`level`	`integer`	—
`width`	`integer`	—
`height`	`integer`	—
`display_aspect_ratio`	`string`	—
`sample_aspect_ratio`	`string`	—
`pixel_format`	`string`	—
`frame_rate`	`string`	—
`bitrate`	`integer`	—
`color_range`	`string`	—
`color_space`	`string`	—
`color_transfer`	`string`	—
`color_primaries`	`string`	—
`hdr`	`boolean`	اگر true باشد، ویدیو HDR است.
`rotation`	`integer`	—
`default`	`boolean`	—
`audio_streams`	`object[]`
`index`	`integer`	—
`codec`	`string`	—
`profile`	`string`	—
`channels`	`integer`	—
`channel_layout`	`string`	—
`sample_rate`	`integer`	—
`bitrate`	`integer`	—
`language`	`string`	—
`title`	`string`	—
`default`	`boolean`	—
`original`	`boolean`	—
`commentary`	`boolean`	—
`hearing_impaired`	`boolean`	—
`visual_impaired`	`boolean`	—
`subtitle_streams`	`object[]`	مشخصات زیرنویس‌های داخل فایل ویدیو.
`index`	`integer`	—
`codec`	`string`	—
`language`	`string`	—
`title`	`string`	—
`default`	`boolean`	—
`forced`	`boolean`	—
`original`	`boolean`	—
`commentary`	`boolean`	—
`hearing_impaired`	`boolean`	—
`poster`	`object \| null`	آدرس و مشخصات پوستر برای نمایش پیش‌نمایش ویدیو؛ فقط با include_poster=true در پاسخ می‌آید. اگر پوستر در دسترس نباشد، مقدار آن null است.
`url`	`string`uri	—
`expires_at`	`null`	پوستر انقضای زمانی ندارد
`width`	`integer` max 640	—
`height`	`integer`	—
`mime_type`	`string` `image/webp`	—
`dominant_color`	`string`	رنگ غالب پوستر به‌صورت کد Hex، برای مثال برای رنگ پس‌زمینه پیش‌نمایش.
`size_bytes`	`integer`int64 min 0	—
`mime_type`	`string`	—
`locked`	`boolean`	اگر true باشد، فایل قفل است و نمی‌توانید برای آن لینک دانلود یا پخش بگیرید.
`expires_at`	`string`date-time	زمان انقضای فایل در حساب؛ با زمان انقضای لینک دانلود متفاوت است.
`created_at`	`string`date-time	—
`updated_at`	`string`date-time	—
`app_state`	`object \| null`	داده‌هایی که برنامه شما برای این کاربر و فایل یا پوشه ذخیره کرده است، مانند موقعیت پخش ویدیو. فقط با include_state=true در پاسخ می‌آید. اگر هنوز داده‌ای ذخیره نکرده باشید، مقدار آن null است.
`value`	`Record<string, any>`	داده‌های دلخواه برنامه در قالب یک شیء JSON با حداکثر حجم ۶۴ KiB. فیلدهای داخل این شیء را خودتان تعیین می‌کنید.
`version`	`integer` min 1	—
`etag`	`string`	برای ارسال If-Match، این مقدار را کامل و همراه با علامت نقل‌قول کپی کنید. ETag را از روی version نسازید.
`created_at`	`string`date-time	—
`updated_at`	`string`date-time	—

Metaobject

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

Example

{
  "data": [
    {
      "id": "01M1BDK9Z0C6E9G2K5N7Q3R4TX",
      "parent_id": null,
      "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-08-31T08:05:00.000000Z",
      "updated_at": "2026-08-31T08:05:00.000000Z",
      "media": {
        "status": "ready",
        "title": "Big Buck Bunny",
        "description": null,
        "creation_time": null,
        "format_names": [
          "mov",
          "mp4",
          "m4a",
          "3gp",
          "3g2",
          "mj2"
        ],
        "duration_ms": 596000,
        "bitrate": 14400000,
        "width": 1920,
        "height": 1080,
        "chapters": [],
        "video_streams": [],
        "audio_streams": [],
        "subtitle_streams": []
      },
      "poster": {
        "url": "https://api.parsget.com/images/posters/01K3W2G9K3Z6J7K8N9P0Q1R2S3/bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb/poster-lg.webp",
        "expires_at": null,
        "width": 640,
        "height": 360,
        "mime_type": "image/webp",
        "dominant_color": "#6b7280"
      }
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6IjAxTTFCREE1MDBCNEE2RDlLM041UjdUOFZDIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ",
    "has_more": true
  }
}