دانلودها

ایجاد دانلود جدید

POSThttps://api.parsget.com/api/v1/downloads

OAuth یا Personal API Key

یک URL با HTTP/HTTPS یا لینک مگنت بفرستید تا پارس‌گت دانلود را ثبت کند. هاست یا سرویس مرتبط با لینک به‌صورت خودکار تشخیص داده می‌شود. برای ارسال فایل .torrent، .nzb یا .xml از POST /downloads/upload استفاده کنید.

ابتدا data.kind را بررسی کنید. پاسخ 201 با kind برابر download یعنی دانلود ایجاد شده و مشخصات آن در data.download است؛ این پاسخ به معنی تکمیل دانلود نیست. وضعیت را با شناسه دانلود پیگیری کنید.

ایجاد دانلود برای بعضی از لینک‌ها به انتخاب کاربر نیاز دارد. برای مثال، پس از ارسال لینک یوتیوب، ابتدا کیفیت‌های موجود نمایش داده می‌شوند و دانلود تا زمان انتخاب کیفیت آغاز نمی‌شود. در این حالت، پاسخ شامل data.kind=selection است و گزینه‌های قابل انتخاب را در data.selection.items برمی‌گرداند. کد وضعیت این پاسخ 200 است. یک item_id قابل انتخاب را به POST /download-selections/{selection}/choices بفرستید. ممکن است پیش از ایجاد دانلود، بیش از یک مرحله انتخاب وجود داشته باشد.

OAuth Scope: downloads:write

گزینه‌ها در data.selection.items داخل یک آرایه قرار دارند. هر گزینه با parent_id مشخص می‌کند زیرمجموعه کدام گزینه است. در هر درخواست، فقط یک گزینه با selectable=true انتخاب کنید و شناسه آن را در item_id بفرستید.

برای دریافت نتیجه دانلود، شامل تکمیل، خطا یا لغو آن، آدرس وب‌هوک برنامه خود را در webhook_url بفرستید.

با client_reference می‌توانید دانلود را به داده‌های برنامه خود، مانند شناسه یک قسمت، مرتبط کنید.

Request body

application/jsonrequired

Field	Type	Description
`url`	`string`required	آدرس اینترنتی معتبر (HTTP/HTTPS) یا لینک مگنت (Magnet)
`directory`	`string`optional	مسیر پوشه مقصد، مانند Movies. نام یا مسیر پوشه را بفرستید؛ این فیلد شناسه پوشه را نمی‌پذیرد.
`client_reference`	`string`optional	برچسب دلخواه برای ارتباط دانلود با داده‌های برنامه شما. چند دانلود می‌توانند برچسب یکسان داشته باشند.
`webhook_url`	`string`optionaluri	آدرس عمومی HTTPS برنامه شما برای دریافت نتیجه دانلود، شامل تکمیل، خطا یا لغو آن. پیش از استفاده، برای Personal API Key یا برنامه OAuth خود webhook secret بسازید.

Response schema

200برای ایجاد دانلود، کاربر باید از فهرست پاسخ، فایل، قسمت یا کیفیت موردنظر را انتخاب کند.

Payloadobject

Field	Type	Description
`kind`	`string` `selection`	—
`selection`	`object`
`id`	`string`	—
`prompt`	`string`	عنوان یا راهنمای مرحله انتخاب برای نمایش به کاربر
`expires_at`	`string`date-time	مهلت انتخاب کاربر. پس از این زمان، شناسه مرحله و گزینه‌های آن معتبر نیستند.
`items`	`object[]`
`id`	`string`	شناسه گزینه در مرحله انتخاب فعلی.
`parent_id`	`string`	شناسه گزینه‌ای که این مورد زیرمجموعه آن است. برای گزینه‌های سطح اول، null است.
`name`	`string`	—
`size_bytes`	`integer`int64 min 0	—
`kind`	`string` `directoryvideoaudioimagedocumentnull`	—
`status`	`string` `nonesubmittedreadynull`	—
`tags`	`Record<string, string>`	—
`thumbnail_url`	`string`uri	—
`selectable`	`boolean`	اگر true باشد، کاربر می‌تواند این گزینه را انتخاب کند.

201دانلود با موفقیت ایجاد شد

Payloadobject

Field	Type	Description
`kind`	`string` `download`	—
`download`	`object`
`id`	`string`	—
`client_reference`	`string`	برچسب دلخواه برای ارتباط دانلود با داده‌های برنامه شما، مثلاً شناسه قسمت یک مجموعه. چند دانلود می‌توانند برچسب یکسان داشته باشند.
`name`	`string`	—
`status`	`string` `queuedprocessingdownloadingfinalizingcompletedblockedfailedcanceled`	وضعیت دانلود. queued یعنی در صف، processing یعنی در حال بررسی و آماده‌سازی دانلود، downloading یعنی دریافت فایل و finalizing یعنی آماده‌سازی نهایی. completed یعنی تکمیل شده، blocked یعنی نیازمند پرداخت، failed یعنی ناموفق و canceled یعنی لغوشده.
`activity`	`string` `seedingnull`	پس از تکمیل تورنت، ممکن است ارسال فایل به دیگر کاربران تورنت ادامه داشته باشد. در این حالت، activity برابر seeding و status برابر completed است.
`source`	`object`
`type`	`string` `urltorrentusenet`	—
`hash`	`string`	هش تورنت (فقط برای دانلودهای تورنت مقدار دارد)
`host`	`string`	کد سرویس دانلود؛ برای اطلاعات سرویس آن را با code در GET /services تطبیق دهید.
`file_id`	`string`	شناسه فایل ایجادشده پس از تکمیل موفق دانلود
`mime_type`	`string`	—
`size_bytes`	`integer`int64	—
`progress`	`object`
`percent`	`number`float min 0max 100	درصد پیشرفت دانلود از ۰ تا ۱۰۰.
`bytes_completed`	`integer`int64 min 0	حجم دریافت‌شده بر حسب بایت.
`speed_bytes_per_second`	`number` min 0	سرعت دریافت بر حسب بایت بر ثانیه؛ اگر مشخص نباشد null است.
`eta_seconds`	`number` min 0	زمان تخمینی باقی‌مانده بر حسب ثانیه؛ اگر مشخص نباشد null است.
`can_cancel`	`boolean`	اگر true باشد، می‌توانید دانلود را لغو کنید. دکمه لغو را بر اساس این مقدار نمایش دهید.
`can_retry`	`boolean`	اگر true باشد، می‌توانید دانلود را دوباره شروع کنید. دکمه تلاش مجدد را بر اساس این مقدار نمایش دهید.
`error`	`object \| null`
`code`	`string` `source_unavailabledownload_expiredquota_exceededdownload_failed`	—
`message`	`string`	—
`created_at`	`string`date-time	—
`updated_at`	`string`date-time	—
`completed_at`	`string`date-time	—
`attempt`	`integer` min 1	شماره تلاش دانلود، از ۱. با شروع موفق یک تلاش جدید از طریق endpoint retry افزایش می‌یابد.

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

Example

{
  "data": {
    "kind": "selection",
    "selection": {
      "id": "dls_01M1BDA500E8G2K4N6Q7R9TVWX",
      "prompt": "Choose a file",
      "expires_at": "2026-08-31T20:00:00.000000Z",
      "items": [
        {
          "id": "dli_01M1BDA500F9H3M5P7S8T2VWXY",
          "parent_id": null,
          "name": "big-buck-bunny.mp4",
          "size_bytes": 734003200,
          "kind": "video",
          "status": "ready",
          "tags": {
            "season": "1",
            "episode": "1"
          },
          "thumbnail_url": "https://images.parsget.com/selections/big-buck-bunny.webp",
          "selectable": true
        }
      ]
    }
  }
}