Authentication

The put.io API can only be accessed via OAuth 2.0. This is really important to help us track usage of the API by your applications while keeping our users’ data safe. It’s a standard used by various large API providers, including the Facebook Graph API.

Start by registering your application and obtaining your API credentials. You may want to sign up under a separate account with an extra-secure password to own these credentials. Since each credential is tied to a particular URL, you may want to create a set of development credentials which point to your development server URL, and production credentials which point to your production server URL. For the purposes of OAuth, your “key” from that registration process is your “id” here, and your secret from registering is your secret here.

2. Obtain an access token

There are three general ways to use the new API.

Web server application

(PHP, Perl, Ruby, Python, Java, Scala, etc.)

Redirect users who wish to authenticate to

https://api.put.io/v2/oauth2/authenticate
    ?client_id=YOUR_CLIENT_ID
    &response_type=code
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI

If a user accepts, they will be redirected back to

https://YOUR_REGISTERED_REDIRECT_URI/?code=CODE

Your server will make a request for

https://api.put.io/v2/oauth2/access_token
    ?client_id=YOUR_CLIENT_ID
    &client_secret=YOUR_CLIENT_SECRET
    &grant_type=authorization_code
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
    &code=CODE

The response will be JSON

{ access_token: ACCESS_TOKEN }

Save this access token for this user in your database.

Pure AJAX application

(Javascript)

Redirect users who wish to authenticate to

https://api.put.io/v2/oauth2/authenticate
    ?client_id=CLIENT_ID
    &response_type=token
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI

If a user accepts, they will be redirected back to

http://YOUR_REGISTERED_REDIRECT_URI/#access_token=ACCESS_TOKEN

Phone-based or client-side application

(Android Java, iOS Objective-C, etc.)

If you have no substantive server code, you can embed a web browser and use the token flow, redirecting the user to a dummy page on your domain. You can then grab the token off of the URL and close the browser.
If you have a server as part of your application, you can use the server flow above, possibly in an embedded browser.
An alternative to the above is to use the server flow and an external browser, but redirect to a custom URI handler that brings the user back to our application. You can embed the secret in your application and exchange the provided code for an access token. PLEASE take steps to obfuscate your client secret if you include it in released code, and be prepared to rotate it if needed.

3. Make requests

Once you have an access token. It’s easy to use any of the endpoints, by just adding oauth_token=ACCESS_TOKEN to your GET or POST request. For example, from the command line, you can do

$ curl -H 'Accept: application/json' https://api.put.io/v2/files/list?oauth_token=ACCESS_TOKEN

Pow! That’s all there is to it.

Make sure you are sending the header "Accept: application/json" when making a request.

If you are already logged in to put.io from your browser, you can go to the endpoint and see the response as convenience.

Notes on OAuth

OAuth can pass secrets in the clear without requiring manual signing of requests. The catch is that all requests must be via HTTPS, and you’ll see errors when not using HTTPS.

The examples above use /authenticate instead of /authorize. Following precedent established by Twitter and LinkedIn, /authenticate handles both user authentication and app authorization and will automatically redirect if a user has already authorized the calling page. This is useful if the user is already logged in and has authorized your app and needs to reestablish the OAuth Token bypassing the log-in and authorization process.

Although at this time we do not expire OAuth access tokens, you should be prepared for this possibility in the future. Also remember that a user may revoke access via the put.io settings page at any time. Using /authorize will ask the user to re-authenticate their identity and reauthorize your app while giving the user the option to login under a different account.

Responses & Errors

All successfull responses will look roughly like

        {
          "status": "OK",
          ...response...
        }

All error responses will look roughly like

        {
          "status": "ERROR",
          "error_type": ...,
          "error_message": ...
        }

Errors will usually include an error_type field about what went wrong, intended for the developer. In some cases, the server may include an error_message, which is a string intended for the client to display back to the user directly.

JSONP

You can use JSONP method for making API calls. Example:

https://put.io/v2/files/list?callback=cb

CORS

Cross-origin resource sharing (CORS) is a mechanism that allows a web page to make XMLHttpRequests to another domain. All API responses includes "Access-Control-Allow-Origin" header where the value is the domain part of the callback_url that you give when registering your application.

API Clients

Currently we only have a simple Python client.

putio.py

Files

Sample file looks like this:

{
  "name": "Movies",
  "created_at": "2011-03-26T12:39:38",  // in iso8601 format
  "parent_id": 0,                       // id of the parent folder (0 is root)
  "content_type": "application/x-directory",
  "id": 14747862,
  "size": 0                             // in bytes
}

GET /files/list

Description

Lists files in a folder.

Parameters

parent_id: The parent folder id of the files to be listed. This defaults to 0 (which means root). If "-1" given it will return the list of all files.

Sample Response

{
  "status": "OK",
  "files": [
    {
      "is_shared": false,
      "name": "Movies",
      "screenshot": null,
      "created_at": "2011-06-28T13:45:08",
      "parent_id": 0,
      "is_mp4_available": false,
      "content_type": "application/x-directory",
      "crc32": null,
      "icon": "http://put.io/images/file_types/folder.png",
      "id": 14747862,
      "size": 0
    },
    {
      "is_shared": true,
      "name": "items shared with you",
      "screenshot": null,
      "created_at": "2011-06-30T14:53:11",
      "parent_id": 0,
      "is_mp4_available": false,
      "content_type": "application/x-directory",
      "crc32": null,
      "icon": "http://put.io/images/file_types/folder.png",
      "id": 14838743,
      "size": 0
    },
    {
      "is_shared": false,
      "name": "Elephants Dream",
      "screenshot": "http://put.io/screenshots/aFZlk2VjXlySh1ZiWWZlZZZfXWVbW2SKZWKTlWCIlFaHloltkJFgXw.jpg",
      "created_at": "2012-01-14T15:15:40",
      "parent_id": 0,
      "is_mp4_available": true,
      "content_type": "video/x-msvideo",
      "crc32": "c01028fc",
      "icon": "http://put.io/thumbnails/aFZlk2VjXlySh1ZiWWZlZZZfXWVbW2SKZWKTlWCIlFaHloltkJFgXw.jpg",
      "id": 270211880,
      "size": 734591856
    },
  ]
}

GET /files/search/<query>/page/<page_no>

Description

Searches your (and shared) files. Returns 50 results at a time. The url for next 50 results is given in the "next" paramater.

Parameters

query: Search parameters. (explained below)

page: Optional. Defaults to 1. If -1 given, returns all results at a time.

Search Syntax

keyword: The keyword to search
from: me, shares, jack or all
type: video, audio, image, iphone or all
ext: mp3, avi, jpg, mp4 or all
time: today, yesterday, thisweek or all

Examples:

jazz from:"me,jack" ext:mp3 time:today
Searches yours and jack's files with the word jazz in its title which has the extension mp3 and created today.

"jazz album" from:"shares" time:thisweek
Searches items shared with you with jazz album which are created thisweek.

jazz type:iphone
Searches your files and items shared with the word jazz in its title which are converted to mp4.

Sample Response

{
  "files": [
    {
      "name": "Documents",
      "created_at": "2011-03-26T12:39:38",
      "parent_id": 0,
      "content_type": "application/x-directory",
      "owner": "SomeUser",
      "icon": "http://put.io/images/file_types/folder.png",
      "id": 147412462,
      "size": 0
    },
    {
      "name": "cat video.avi",
      "created_at": "2011-03-26T12:39:38",
      "parent_id": 0,
      "content_type": "video/x-msvideo",
      "owner": "AnotherUser",
      "icon": "http://put.io/screenshot/ZW3rY1dkZy.jpg",
      "id": 142141211,
      "size": 732491848
    },
    {
      "name": "totally legal song.mp3",
      "created_at": "2011-03-26T12:39:38",
      "parent_id": 0,
      "content_type": "audio/mpeg",
      "owner": "SomeUser",
      "icon": "http://put.io/images/file_types/audio.png",
      "id": 12347862,
      "size": 6426664
    }
  ],
  "status": "OK",
  "next": "http://api.put.io/v2/files/search/YOUR_QUERY/page/2"
}

POST /files/upload

Description

Uploads a file. If the uploaded file is a torrent file, starts it as a transfer.

Parameters

file:Name of the form input.

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://api.put.io/v2/files/upload?oauth_token=KD8D03MF'

Sample Response

{
  "status": "OK",
  "file": {
    "name": "stream.pls",
    "created_at": "2012-02-09T14:52:17",
    "parent_id": 0,
    "content_type": "text/plain",
    "id": 27838620,
    "size": 121
  }
}

If the uploaded file is a torrent, the response is a transfer object:

{
  "status": "OK",
  "transfer": {
    "status": 20,
    "name": "An example movie",
    "down_speed": 0,
    "estimated_time": null,
    "extract": null,
    "created_at": null,
    "up_speed": 0,
    "save_parent_id": 0,
    "percent_done": 0,
    "current_ratio": 0.00,
    "id": 2136998,
    "size": 19563465692
  }
}

POST /files/create-folder

Description

Creates a new folder.

Parameters

name: Name of the new folder.

parent_id: Location of the new folder.

GET /files/<id>

Description

Returns a file's properties.

Sample Response

{
  "status": "OK",
  "file": {
    "is_shared": true,
    "name": "stream.pls",
    "screenshot": null,
    "created_at": "2012-02-09T14:52:17",
    "parent_id": 0,
    "content_type": "text/plain",
    "crc32": "c01028fc",
    "icon": "http://put.io/images/file_types/text.png",
    "id": 27838620,
    "size": 121
  }
}

POST /files/delete

Description

Deletes given files.

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

Sample Response

{
  "status": "OK"
}

POST /files/rename

Description

Renames given file.

file_id: ID of the file to be renamed.

name: New name for the file.

Sample Response

{
  "status": "OK"
}

POST /files/move

Description

Moves files to the given destination.

file_ids: IDs of the files to be moved.

parent_id: Location of the destination folder.

Sample Response

{
  "status": "OK"
}

POST /files/<id>/mp4

Description

Converts the given file to mp4.

id: ID of the files to be converted.

Sample Response

{
  "status": "OK"
}

GET /files/<id>/mp4

Description

Returns the status of the mp4 file.

id: ID of the file.

Sample Response

{
  "status": "OK",
  "mp4": {
    "status": "NOT_AVAILABLE"
  }
}

Sample Response

{
  "status": "OK",
  "mp4": {
    "status": "IN_QUEUE"
  }
}

Sample Response

{
  "status": "OK",
  "mp4": {
    "status": "CONVERTING",
    "percent_done": 37
  }
}

Sample Response

{
  "status": "OK",
  "mp4": {
    "status": "COMPLETED",
    "stream_url": "http://fr04.put.io/stream-mp4/13442/29951780/atk/90492d00782013421e1a8da000c292b0e1f",
    "download_url": "https://put.io/download-file-mp4/12131/24890466",
    "size": 992242885
  }
}

GET /files/<id>/download

Description

Sends the contents of the file.

Sample 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?oauth_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

GET /files/zip

Description

Create zipstream for given files. A redirect to created zipstream will be returned.

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

Transfers

Sample transfer looks like this:

{
      "uploaded": 0,                        // in bytes
      "estimated_time": null,
      "peers_getting_from_us": 0,
      "extract": false,                     // extract after download?
      "current_ratio": 0.0,
      "size": 19563465692,                  // in bytes
      "up_speed": 0,                        // bytes per second
      "is_seeding": false,
      "id": 2136998,
      "subscription_id": null,
      "status_message": "In queue",
      "status": "IN_QUEUE",
      "down_speed": 0,                      // bytes per second
      "peers_connected": 0,
      "downloaded": 0,                      // in bytes
      "file_id": null,
      "peers_sending_to_us": 0,
      "percent_done": 0,
      "tracker_message": null,
      "name": "A video",
      "created_at": "2012-03-23T03:08:58",  // in iso8601 format
      "error_message": null,
      "save_parent_id": 0                   // folder id of the download location
    }

GET /transfers/list

Description

Lists active transfers. If transfer is completed, it is removed from the list.

Sample Response

{
  "status": "OK",
  "transfers": [
    {
      "uploaded": 0,
      "estimated_time": 5,
      "peers_getting_from_us": 0,
      "extract": false,
      "current_ratio": 0.00,
      "size": 9409268,
      "up_speed": 0,
      "id": 2293761,
      "source": "magnet:?xt=urn:btih:194a4c341487fd12d36718054c1e8fef4358b2ab3",
      "subscription_id": null,
      "status_message": "\u2193 1.2 MB/s, \u2191 0.0 bytes/s | connected to 36 peers, sending to 0 peers | dl: 2.9 MB / 9.0 MB, ul: 0.0 bytes",
      "status": "DOWNLOADING",
      "down_speed": 1249337,
      "peers_connected": 36,
      "downloaded": 2999431,
      "file_id": null,
      "peers_sending_to_us": 22,
      "percent_done": 30,
      "tracker_message": null,
      "name": "A video",
      "created_at": "2012-03-28T09:14:17",
      "error_message": null,
      "save_parent_id": 0
    },
    {
      "uploaded": 0,
      "estimated_time": null,
      "peers_getting_from_us": 0,
      "extract": false,
      "current_ratio": 0.00,
      "size": null,
      "up_speed": 0,
      "is_seeding": false,
      "id": 63,
      "subscription_id": null,
      "status_message": "In queue",
      "status": "IN_QUEUE",
      "down_speed": 0,
      "peers_connected": 0,
      "downloaded": 0,
      "file_id": null,
      "peers_sending_to_us": 0,
      "percent_done": 0,
      "tracker_message": null,
      "name": "Another video",
      "created_at": "2012-03-23T05:56:30",
      "error_message": null,
      "save_parent_id": 46
    }
  ]
}

POST /transfers/add

Description

Adds a new transfer.

Parameters

url: Location of the file to be downloaded.

save_parent_id: Save location of the transfer. This defaults to 0 (which means root).

extract: Extract after download? (default=False)

callback_url: We POST the transfer's metadata to this URL after the download is finished. (optional)

Sample Response

{
      "uploaded": 0,
      "estimated_time": null,
      "peers_getting_from_us": 0,
      "extract": false,
      "current_ratio": 0.00,
      "size": null,
      "up_speed": 0,
      "id": 63,
      "source": "http://torrent.site.com/legal_video.torrent",
      "subscription_id": null,
      "status_message": "In queue",
      "status": "IN_QUEUE",
      "down_speed": 0,
      "peers_connected": 0,
      "downloaded": 0,
      "file_id": null,
      "peers_sending_to_us": 0,
      "percent_done": 0,
      "tracker_message": null,
      "name": "Another video",
      "created_at": "2012-03-23T05:56:30",
      "error_message": null,
      "save_parent_id": 46
}

GET /transfers/<id>

Description

Returns a transfer's properties.

Sample Response

{
      "uploaded": 0,
      "estimated_time": null,
      "peers_getting_from_us": 0,
      "extract": false,
      "current_ratio": 0.00,
      "size": 5770612938,
      "up_speed": 0,
      "id": 2291767,
      "source": "http://torrent.site.com/legal_video.torrent",
      "subscription_id": null,
      "status_message": "Completed",
      "status": "COMPLETED",
      "down_speed": 0,
      "peers_connected": 0,
      "downloaded": 0,
      "file_id": 29957856,
      "peers_sending_to_us": 0,
      "percent_done": 100,
      "tracker_message": null,
      "name": "Cat video",
      "created_at": "2012-03-27T17:46:22",
      "error_message": null,
      "save_parent_id": 0
}

POST /transfers/cancel

Description

Deletes the given transfers.

transfer_ids: Transfer ids separated by commas. Ex: 1,2,3,4

Sample Response

{
  "status": "OK"
}

POST /transfers/clean

Description

Clean completed transfers from the list.

Sample Response

{
  "status": "OK"
}

Account

GET /account/info

Description

Information about user account.

Sample Response

{
  "info": {
    "username": "cenk",
    "mail": "cenk@gmail.com",
    "disk": {
      "avail": 20849243836,
      "used": 32837847364,
      "size": 53687091200
    }
  },
  "status": "OK"
}

GET /account/settings

Description

User preferences.

Sample Response

{
  "status": "OK",
  "settings": {
    "default_download_folder": 0,
    "is_invisible": false,
    "extraction_default": false
  }
}

Friends

Sample friend looks like this:

{
  "name": "foo"
}

GET /friends/list

Description

Lists friends.

Sample Response

{
  "status": "OK",
  "friends": [
    {
      "name": "foo"
    },
    {
      "name": "bar"
    }
  ]
}

GET /friends/waiting-requests

Description

Lists incoming friend requests.

Sample Response

{
  "status": "OK",
  "friends": [
    {
      "name": "foo"
    },
    {
      "name": "bar"
    }
  ]
}

POST /friends/<username>/request

Description

Sends a friend request to the given username.

Sample Response

{
  "status": "OK"
}

POST /friends/<username>/deny

Description

Denies a friend request from the given username.

Sample Response

{
  "status": "OK"
}

API v2 Documentation

Table of Contents

API Methods

Authentication

1. Sign up

2. Obtain an access token

Web server application

Pure AJAX application

Phone-based or client-side application

3. Make requests

Notes on OAuth

Responses & Errors

JSONP

CORS

API Clients

Files

GET /files/list

Description

Parameters

Sample Response

GET /files/search/<query>/page/<page_no>

Description

Parameters

Search Syntax

Examples:

Sample Response

POST /files/upload

Description

Parameters

Example CURL line:

Sample Response

POST /files/create-folder

Description

Parameters

GET /files/<id>

Description

Sample Response

POST /files/delete

Description

Sample Response

POST /files/rename

Description

Sample Response

POST /files/move

Description

Sample Response

POST /files/<id>/mp4

Description

Sample Response

GET /files/<id>/mp4

Description

Sample Response

Sample Response

Sample Response

Sample Response

GET /files/<id>/download

Description

Sample Response

GET /files/zip

Description

Transfers

GET /transfers/list

Description

Sample Response

POST /transfers/add

Description

Parameters

Sample Response

GET /transfers/<id>

Description

Sample Response

POST /transfers/cancel

Description

Sample Response

POST /transfers/clean

Description

Sample Response

Account

GET /account/info

Description