Inner Workings of Put.io

What's an "Item"?

Item stands for a file or folder. For most of the methods files and folders are the same thing. Folders are virtual buckets that hold files or other folders.

How Authtentication Works

To authenticate the user, send the api_key and api_secret string to the api server with every request

To call any actions, include the api_key and api_secret to the request. Use this format: request=FOLLOWINGJSON:

If no user is found the return will be:

{
    "error_message": "Unable to login. Please check your info.",
    "user_id": null,
    "response": {
                    "results": [{
                                    "user_name":null,
                                    "user_id":null
                               }]
                },
    "error":true
}


See the samples for more info.

Building Audio/Video Stream URLs

Stream URLs contain a "user access token" which should be added dynamically by the client application. Here is the format:

URL returned by API : "http://s01.put.io/stream-file/17/4701235/"
User Access Token : "bebe56e6b3455440f90bf9dec14b7c6be814c7c0"

Construct streaming url by adding "/atk/" string and user access token at the end of the returned URL. Final result:

"http://s01.put.io/stream-file/17/4701235/atk/bebe56e6b3455440f90bf9dec14b7c6be814c7c0"

What's Link Analyzation?

By analyzing links, Put.io can report back which links can be fetched, how much disk space or bandwidth quota will be used. We strongly recommend to inform users about the current disk space and data transfer amount.

Also, analyzation report will inform the user about any other Put.io limitations such as single file size limit, compatibility the the source, etc.

Here is a sample report in python dictionary format:

{
    'Current Available Bandwidth'  : 139889066230,              #Bytes
    'Current Available Disk Space' : 180546571528,              #Bytes
    'Your Total Disk Space'        : 191.96000000000001,        #Gigabytes

    'Urls':{
               'url':      [
                               u'ftp://ftp1.mplayerhq.hu/MPlayer/samples/MPEG-4/mp3on4/id5_1.mp4'
                           ],
               'rapid':    [
                               u'http://rapidshare.com/files/121211/jazz.rar'
                           ],
               'multipart':{
                               u'ABCDE':[
                                            u'http://rapidshare.com/files/121212/abcde.part1.rar',
                                            u'http://rapidshare.com/files/121213/abcde.part2.rar'
                                        ]
                           },
               'torrent':  [
                               u'http://legaltorrents.com/1a1112',
                               u'http://legaltorrents.com/1a1100'
                           ]
           }
}

Transfer Status Messages

Waiting
Transfer is added, waiting its turn to be queued. If a user has more transfers than its active transfer limit, transfers will remain in "waiting" status until active ones are complete. See active transfer limit for more info.

In queue
Put.io is preparing to start the transfer. This shouldn't take too long.

Looking for peers
Transfer is initiated, our client is looking for peers to fetch from. If the torrent is well seeded, it shouldn't take too long. Instruct users to add well seeded torrents to reduce waiting time. Applies only to bittorrent transfers.

Downloading
Transfer is in progress and healthy.

Downloading and seeding
Torrent transfer is in progress and healthy.

Seeding
Torrent is downloaded successfully and now its being seeded until the seeding ratio is 1:1. At this point, we remove all the speed limits for the torrent file, to finish seeding and release its slot as soon as possible.

In complete queue
Downloading is finished. It's waiting its turn to be processed and written to your space. This may take some time if the system load is high.

In extraction queue
If the completer discovers any archive files among the files being completed, it sends it to the extraction queue. Archive files will be redirected to the servers which are responsible for doing the extracting. To prevent this and the following stage, you may instruct your users to add transfers without any archive files.

Extracting
Archive files are being extracted. This may take long since extracting is a CPU and harddisk intensive process. Archive size, archive compression algorithm and the archive type may affect the time it takes.

Completing
Files are ready and being saved to users disk space. Transfer size and item count will definitely affect the time it takes.

Completed
Items are ready to be consumed by the user. Notice: Completed status will not be seen via API. Completed transfers are moved from the active transfers list as soon as they are completed.

Error
If a transfer couldn't be completed due to an error, it will remain in the active transfer list unless user cancels it.

Active Transfer Limit

We have an active transfer limit per user. But its only enforced when the system load is high. Current limit is 5, which means a user can have only 5 active transfers at the same time when the system is on fire.

As a design decision, erroneous and "waiting" transfers are not considered as active but seeding torrents are.

Check back later for more info.