Files

File methods in general may be used for gathering information about files or manipulating files. However, there are a few exceptions.

JSON Template

All error-free requests will at least contain the following fields:

{
    "content_type": "application/x-directory",
    "crc32": null,
    "created_at": "2013-09-07T21:32:03",
    "first_accessed_at": null,
    "icon": "https://put.io/images/file_types/folder.png",
    "id": 115932951,
    "is_mp4_available": false,
    "is_shared": false,
    "name": "Breaking.Bad.S05E09.720p.HDTV.x264-IMMERSE [PublicHD]",
    "opensubtitles_hash": null,
    "parent_id": 0,
    "screenshot": null,
    "size": 1155197751
}

Methods

List

GET /files/list

Lists files in a folder.

Parameters

parent_id:ID of the folder you’d like to list. This defaults to the root directory (which has ID number 0).

Example response:

  {
    "files": [
        {
            "content_type": "text/plain",
            "crc32": "66a1512f",
            "created_at": "2013-09-07T21:32:03",
            "first_accessed_at": null,
            "icon": "https://put.io/images/file_types/text.png",
            "id": 6546533,
            "is_mp4_available": false,
            "is_shared": false,
            "name": "MyFile.txt",
            "opensubtitles_hash": null,
            "parent_id": 123,
            "screenshot": null,
            "size": 92
        },
        {
            "content_type": "video/x-matroska",
            "crc32": "cb97ba70",
            "created_at": "2013-09-07T21:32:03",
            "first_accessed_at": "2013-09-07T21:32:13",
            "icon": "https://put.io/thumbnails/aF5rkZVtYV9pV1iWimSOZWJjWWFaXGZdaZBmY2OJY4uJlV5pj5FiXg%3D%3D.jpg",
            "id": 7645645,
            "is_mp4_available": false,
            "is_shared": false,
            "name": "MyVideo.mkv",
            "opensubtitles_hash": "acc2785ffa573c69",
            "parent_id": 123,
            "screenshot": "https://put.io/screenshots/aF5rkZVtYV9pV1iWimSOZWJjWWFaXGZdaZBmY2OJY4uJlV5pj5FiXg%3D%3D.jpg",
            "size": 1155197659
        }
    ],
    "parent": {
            "content_type": "application/x-directory",
            "crc32": null,
            "created_at": "2013-09-07T21:32:03",
            "first_accessed_at": null,
            "icon": "https://put.io/images/file_types/folder.png",
            "id": 123,
            "is_mp4_available": false,
            "is_shared": false,
            "name": "MyFolder",
            "opensubtitles_hash": null,
            "parent_id": 0,
            "screenshot": null,
            "size": 1155197751
            },
    "status": "OK"
}

Upload

POST /files/upload

Uploads a file. If the uploaded file is a torrent file, starts it as a transfer. This endpoint must be used with upload.put.io domain.

Parameters

file:Name of the form input.
filename:The file will be renamed according to this parameter. This defaults to filesystem-secure version of the original filename.
parent_id:Location of the uploaded file. This defaults to 0 (which means root).

Example CURL line

$ curl -i -F file=@/path/to/the/file 'https://upload.put.io/v2/files/upload?oauth_token=KD8D03MF'

If the file is not a torrent file, the result will be as follows:

  {
    "file":
        {
            "content_type": "text/plain",
            "crc32": "66a1512f",
            "created_at": "2013-09-07T21:32:03",
            "first_accessed_at": null,
            "icon": "https://put.io/images/file_types/text.png",
            "id": 6546533,
            "is_mp4_available": false,
            "is_shared": false,
            "name": "MyFile.txt",
            "opensubtitles_hash": null,
            "parent_id": 123,
            "screenshot": null,
            "size": 92
        },
    "status": "OK"
}

If the file is a torrent file, a transfer object is returned

{
    "status": "OK",
    "transfer": {
        "availability": null,
        "callback_url": null,
        "created_at": "2013-09-10T15:40:19",
        "current_ratio": 0.00,
        "down_speed": 0,
        "downloaded": 0,
        "error_message": null,
        "estimated_time": null,
        "extract": false,
        "file_id": null,
        "finished_at": null,
        "id": 9759539,
        "is_private": false,
        "name": "TedVideo",
        "peers_connected": 0,
        "peers_getting_from_us": 0,
        "peers_sending_to_us": 0,
        "percent_done": 0,
        "save_parent_id": 0,
        "seconds_seeding": 0,
        "size": 32810896,
        "source": null,
        "status": "IN_QUEUE",
        "status_message": "In queue...",
        "subscription_id": null,
        "tracker_message": null,
        "type": "TORRENT",
        "up_speed": 0,
        "uploaded": 0
    }
}

Create Folder

POST /files/create-folder

Creates a new folder.

Parameters

name:Name of the new folder.
parent_id:Location of the new folder.

Get

GET /files/<id>

Returns a file’s properties.

Parameters

parent_id:ID of the folder you’d like to list. This defaults to the root directory (which has ID number 0).

Example response:

  {
    "file":
        {
            "content_type": "text/plain",
            "crc32": "66a1512f",
            "created_at": "2013-09-07T21:32:03",
            "first_accessed_at": null,
            "icon": "https://put.io/images/file_types/text.png",
            "id": 6546533,
            "is_mp4_available": false,
            "is_shared": false,
            "name": "MyFile.txt",
            "opensubtitles_hash": null,
            "parent_id": 123,
            "screenshot": null,
            "size": 92
        }
    "status": "OK"
}

Delete

POST /files/delete

Deletes given files.

Parameters

file_ids:File ids separated by commas. Ex: 1,2,3,4

Example response:

{
  "status": "OK"
}

Rename

POST /files/rename

Renames given file.

Parameters

file_id:ID of the file to be renamed.
name:Name of the new file.

Example response:

{
  "status": "OK"
}

Move

POST /files/move

Moves files to the given destination.

Parameters

file_ids:File ids separated by commas. Ex: 1,2,3,4
parent_id:Location of the destination folder.

Example response:

{
  "status": "OK"
}

Convert to MP4

POST /files/<id>/mp4

Starts the conversion of the given file to mp4.

Parameters

id:ID of the files to be converted.

Example response:

{
  "status": "OK"
}

Get MP4 Status

GET /files/<id>/mp4

Returns the status of mp4 conversion of the given file.

Parameters

id:ID of the files to be converted.

Example responses:

{
    "status": "OK",
    "mp4": {
     "status": "NOT_AVAILABLE"
    }
}
{
    "status": "OK",
    "mp4": {
     "status": "IN_QUEUE"
    }
}
{
    "status": "OK",
    "mp4": {
     "status": "PREPARING",
     "percent_done": 0
    }
}
{
    "status": "OK",
    "mp4": {
     "status": "CONVERTING",
     "percent_done": 37
    }
}
{
    "status": "OK",
    "mp4": {
     "status": "FINISHING",
     "percent_done": 100
    }
}
{
    "status": "OK",
    "mp4": {
     "status": "COMPLETED",
     "percent_done": 100,
     "size": 992242885
    }
}

Download

GET /files/<id>/download

Sends the contents of the file.

Example response:

First response is always a redirect. Location of the file is in ‘Location’ header. The client must send a new GET request to the new location. Only headers are shown.

HTTP/1.1 302 FOUND
Server: nginx
Date: Thu, 09 Feb 2012 15:58:53 GMT
Content-Type: text/html; charset=utf-8
Connection: keep-alive
Keep-Alive: timeout=60
Content-Length: 385
Location: http://s01.put.io/v2/files/26205116/download?token=4a63387841ce11e1a047001018321b64
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 09 Feb 2012 15:58:53 GMT
Content-Type: application/x-rar
Content-Length: 3190802
Last-Modified: Fri, 16 Sep 2011 11:42:13 GMT
Connection: keep-alive
Keep-Alive: timeout=60
Content-Disposition: attachment; filename="file.rar"
Accept-Ranges: bytes

This method can’t be used for downloading folders, see Zips endpoint instead.

Sharing

POST /files/share

Shares given files with given friends or all friends.

Parameters

file_ids:String. File ids separated by commas. Ex: ‘1,2,3,4’
friends:String. ‘everyone’ or user names of friends separated by commas. Ex: ‘johndoe,janedoe’

Example response:

{
    "status": "OK"
}
GET /files/shared

Returns list of shared files and share information.

“shared_with” value in response may be “everyone” or an integer indicating number of people file is shared with (EX: “everyone” or 2)

Example response:

{
    "shared": [
        {
            "id": 115932951,
            "name": "Breaking.Bad.S05E09.720p.HDTV.x264-IMMERSE [PublicHD]",
            "shared_with": "everyone"
        },
        {
            "id": 115231234,
            "name": "MyVideo.mkv",
            "shared_with": 3
        }
    ],
    "status": "OK"
}
GET /files/<id>/shared-with

Returns list of users file is shared with. Each result item contains a share id which can be used for unsharing.

Example response:

{
    "shared-with": [
        {
            "user_name": "John Doe",
            "user_avatar_url": "/avatars/johndoe.png",
            "share_id": 3913572317
        },
        {
            "user_name": "Jane Doe",
            "user_avatar_url": "/avatars/janedoe.png",
            "share_id": 3913572318
        }
    ],
    "status": "OK"
}
POST /files/<id>/unshare

Unshares given file from given friends or from everyone.

Parameters

shares:String. ‘everyone’ or share ids separated by commas. Ex: ‘1,2,3,4’

Example response:

{
    "status": "OK"
}

Subtitles

GET /files/<id>/subtitles

Lists available subtitles for user’s preferred language. User must select “Default Subtitle Language” from settings page. See: Account Info

Example response:

{
    "default": "V7mVadfvq34erarjy9tqj0435hgare",
    "status": "OK",
    "subtitles": [
        {
            "key": "V7mVadfvq34erarjy9tqj0435hgare",
            "language": null,
            "name": "MySubtitle1.srt",
            "source": "folder"
        },
        {
            "key": "V7mVafQ73r9902cjgbdfkvj2094css",
            "language": "English",
            "name": "MySubtitle2.srt",
            "source": "mkv"
        },
        {
            "key": "V7mVafQ7LC_B7FKcG3pELfos2URzh8I",
            "language": "English",
            "name": "MySubtitle3.srt",
            "source": "opensubtitles"
        },
        {
            "key": "V7mVafQ7LC_B7FKcG3pELfos2URzh8IO1kvjZHNY=",
            "language": "English",
            "name": "MySubtitle4.srt",
            "source": "opensubtitles"
        }
    ]
}

Fields

key:This is the key used for Download Subtitle.
language:Language name in English. This may be null. We are working on improving it.
name:Subtitle files name.
source:Where we got this subtitle from. More details below.

Sources

folder:Putio has it. A srt file that has identical parent folder and name with the video.
mkv:Extracted from MKV video file.
opensubtitles:From opensubtitles.

Download Subtitle

GET /files/<id>/subtitles/<key>

Sends the contents of the subtitle file. There is a powerful built in key called default. If you use it, putio searches for a subtitle in the following order and returns the first match:

  1. A subtitle file that has identical parent folder and name with the video.
  2. Subtitle file extracted from video if the format is MKV.
  3. First match from opensubtitles.

Parameters

format:Subtitle file format. Default is srt, webvtt can be requested.

HLS Playlist

GET /files/<id>/hls/media.m3u8

Serves a HLS playlist for a video file.

Parameters

subtitle_key:Subtitle key for the file. Use “all” as key to get available subtitles for user’s preferred languages.

Events

GET /events/list

List of dashboard events. Includes download and share events.

Example response:

{
    "status": "OK",
    "events": [
        {
            "transfer_name": "4th Rock from The Sun",
            "created_at": "2014-12-09 22:31:42",
            "transfer_size": 14872103214,
            "file_id": 257901855,
            "type": "transfer_completed"
        },
        {
             "file_name": "Managing Scale and Complexity.mp4",
             "created_at": "2014-10-22 15:23:10",
             "sharing_user_name": "johndoe",
             "file_id": 117645943,
             "file_size": 73454320,
             "type": "file_shared"
        }
    ],

}

First event entry indicates a completed transfer, second entry indicates a shared file from the friend ‘johndoe’.

POST /events/delete

Clear all dashboard events. User’s home screen (dashboard) which uses same data will also be cleared at Put.io website.

Example response:

{
    "status": "OK"
}

Set Video Position

POST /files/<id>/start-from

Sets default video position for a video file.

Parameters:

time:Video position in seconds.

Example response:

{
    "status": OK
}

Delete Video Position

POST /files/<id>/start-from/delete

Delete video position for a video file.

Example response:

{
    "status": OK
}