Put.io API » API Server Documentation

API Server Documentation (For Library Developers)

If you are looking for how to generate file stream urls, see user>acctoken method and this page.

 

cURL Examples:

for POST
curl -X POST "http://api.put.io/v1/user?method=info" \
    -H "Accept: application/json" \
    -d 'request={"api_key":"YOUR_API_KEY","api_secret":"YOUR_API_SECRET", "params": {}}'

for GET
http://api.put.io/v1/user?method=info&request={"api_key":"YOUR_API_KEY","api_secret":"YOUR_API_SECRET","params":{}}

 

Request Format:

GET/POST request="following JSON String" to the Api Server.

To call any action with authentication, you'll need to send api_key, and api_secret. Parameters are optional depending of the action you are calling. Here is an example:

{
    "api_key": STRING,
    "api_secret": STRING,
    "params": {
                 "param1":"value1",
                 "param2":"value2",
                 .................
              }
}

api_key Api Key of the user. Can be changed by the user.
api_secret A secret string that user determines. Can be changed by the user.

 


Response Format:

Api Server will return the following JSON string.

{
    "user_id": INTEGER,
    "response": {
                    "results": [{
                                   .... data ....
                               }]
                },
    "error": null,
    "error_message": null
}

user_id User who is calling the action.
response A dictionary containing "results" array.
error Null if there is no error.
error_message Error message will be returned unless action is successful.

All strings will be in unicode.


URLs

Files:
http://api.put.io/v1/files?method=list
http://api.put.io/v1/files?method=create_dir
http://api.put.io/v1/files?method=info
http://api.put.io/v1/files?method=rename
http://api.put.io/v1/files?method=move
http://api.put.io/v1/files?method=delete
http://api.put.io/v1/files?method=search
http://api.put.io/v1/files?method=dirmap

Dashboard Messages:
http://api.put.io/v1/messages?method=list
http://api.put.io/v1/messages?method=delete

Active Transfers:
http://api.put.io/v1/transfers?method=list
http://api.put.io/v1/transfers?method=cancel
http://api.put.io/v1/transfers?method=add

URL Handler:
http://api.put.io/v1/urls?method=analyze
http://api.put.io/v1/urls?method=extracturls

User:
http://api.put.io/v1/user?method=info
http://api.put.io/v1/user?method=friends

Subscriptions:
http://api.put.io/v1/subscriptions?method=list
http://api.put.io/v1/subscriptions?method=create
http://api.put.io/v1/subscriptions?method=edit
http://api.put.io/v1/subscriptions?method=delete
http://api.put.io/v1/subscriptions?method=pause
http://api.put.io/v1/subscriptions?method=info

 

 

Classes, Methods and Instance Attributes

 

Classes

  • User
  • Item
  • Message
  • Subscription
  • Transfer
  • UrlBucket
  • Url

 

User

Methods  
info Returns more detailed info about the user.
friends Returns user's friend list.
acctoken Returns a fresh token. Tokens are needed to create stream urls. See this for more info.
   
User Attributes: user.user_id
user.user_name
user.access_token
user.api_key
user.api_secret

 

Item

Methods  
list

Returns the list of items in a folder.

id = STRING or INTEGER
parent_id = STRING or INTEGER
offset = INTEGER (Default:0)
limit = INTEGER (Default: 20)
type = STRING (See Item class for available types)
orderby = STRING (Default: createdat_desc)

Orderby parameters:

id_asc
id_desc
type_asc
type_desc
name_asc
name_desc
extension_asc
extension_desc
createdat_asc
createdat_desc (Default)
create_dir

Creates and returns a new folder.

Parameters:

name
parent_id
info

Returns detailed information about an item.

Parameters:

id
rename

Renames and returns an item

Parameters:

id
name
move

Moves an item from a folder to another, and returns it.

Parameters:

id
parent_id
delete

Deletes an item

Parameters:

id
search

Returns list of found items

Parameters:

query
dirmap Returns a flat list of directory list. Parent_id is the id of a folder the item is in.
   
Item Attributes:

item.id
item.name
item.type
item.size
item.is_dir
item.parent_id
item.screenshot_url
item.thumb_url
item.file_icon_url
item.download_url

Example Folder Item:

"id":"4394",
"name":"ABCDE",
"type":"folder",
"size":"23472048",
"is_dir":true,
"parent_id":"0",
"screenshot_url":"http://put.io/screenshot/b/dgRgraFxlXmNl.jpg",
"thumb_url":"http://put.io/screenshot/dgRgraFxlXmNl.jpg",
"file_icon_url":"http://put.io/images/file_types/folder.png",
"download_url":"http://put.io/download-file/XXXX/4394"}

At the moment, type can be:

filetypes: {
    "folder" : 0,
    "file" : 1,
    "audio" : 2,
    "movie" : 3,
    "image" : 4,
    "compressed" : 5,
    "pdf" : 6,
    "ms_doc" : 7,
    "text" : 8,
    "swf" : 9
}


Message

Methods  
list Returns a list of messages
delete

Deletes a message

Parameters:

id
   
Message Attributes:

message.id (Integer)
message.user_id (Integer)
message.title (String)
message.description (None)
messages.importance (Integer)
message.file_name (String)
message.file_type (String)
message.user_file_id (Integer)
message.from_user_id (Integer. If None, message is from Put.io)
message.channel (Integer)
message.hidden (Integer, 1 or 0)

Sample:

user_file_id = 4
user_id = 666666666
description = None
title = '<a rel="userfile" href="/file/4">abcd.mp4</a> <span class="dash-gray">(89.86K) downloaded</span>'
importance = 0
file_name = 'abcd.mp4'
id = 3773
file_type = 'audio'
hidden = 0
from_user_id = None
channel = 2

 

Subscription

Methods  
list Returns a list of subscriptions
create

Creates a subscription and returns it.

Parameters:

title
url
do_filters
dont_filters
parent_folder_id
paused
edit

Updates a subscription and returns it.

Parameters:

id
title
url

do_filters
dont_filters
parent_folder_id
paused
delete

Deletes a subscription.

Parameters:

id
pause

Toggles the activity of a subscription. Use it to pause or resume.

Parameters:

id
info

Returns detailed information of a subscription

Parameters:

id
   
Subscription Attributes:

subsitem.id (Integer)
subsitem.url (String)
subsitem.name (String)
subsitem.do_filters (Strings, seperated by commas)
subsitem.dont_filters (Strings, seperated by commas)
subsitem.parent_folder_id (Integer)
subsitem.last_update_time (String)
subsitem.next_update_time (String)
subsitem.paused (Boolean)

Sample Values:

subsitem.id = 860
subsitem.url = "http://legaltorrents.com/music/rss.xml"
subsitem.name = "Jazz Radio"
subsitem.do_filters = "jazz, mp3"
subsitem.dont_filters = "smooth, wav"
subsitem.parent_folder_id = 234
subsitem.last_update_time = "2010-01-01 00:00"
subsitem.next_update_time = "2010-01-01 00:00"
subsitem.paused = False


Transfer

Methods  
list Returns a list of active transfers.
cancel

Cancels a transfer.

Parameters:

id
add

Adds urls to fetch and returns a list of active transfers.

Parameters:

links
   
Transfer Attributes:

instance.id (String)
instance.name (String)
instance.status (String)
instance.percent_done (String)

Samples:

instance.id = '45'
instance.name = 'A video file.avi'
instance.status = 'Completed'
instance.percent_done = '100'

instance.id : '47'
instance.name : 'abcde.mp4'
instance.status : 'Waiting'
instance.percent_done : '0'

If has error:

instance.id = Null
instance.name = 'A file.avi'
instance.status = 'Error: Not enough disk space'
instance.percent_done = Null

instance.id : '47'
instance.name : 'abcde.mp4'
instance.status : 'Waiting'
instance.percent_done : '0'

 

Url

Methods  
analyze

Returns an array of urls that Put.io can fetch

Parameters:

urls
extracturls

Returns an array of urls

Parameters:

txt
   
Url Attributes:

instance.dl_handler = 'Single Url'
instance.name = 'name_of_the_file.mp4'
instance.file_type = 'file'
instance.error = None
instance.url = 'ftp://a.b.c/name_of_the_file.mp4'
instance.paid_bw = 0
instance.file_size = '92014'
instance.type_name = 'file'
instance.dltype = 3
instance.human_size = '89.86K'

SingleRapid Url Attributes:

instance.dl_handler = 'Rapid'
instance.name = 'ABCDE.rar'
instance.file_type = 'file'
instance.error = None
instance.url = 'http://rapidshare.com/files/abcde.rar'
instance.paid_bw = '104961263'
instance.file_size = '104961263'
instance.type_name = 'file'
instance.dltype = 1
instance.human_size = '100.10M'

Torrent Attributes:

instance.dl_handler = 'Torrent'
instance.name = 'ABCDE.avi'
instance.file_type = 'file'
instance.file_size = 244091464
instance.url = 'http://a.b/c.torrent'
instance.paid_bw = 0
instance.error = None
instance.type_name = 'file'
instance.dltype = 2
instance.human_size = '232.78M'

Multipart Attributes:

instance.dltype = 4
instance.dl_handler = 'Multipart'
instance.name = 'ABCDE'
instance.file_size = 366500388
instance.paid_bw = 366500388
instance.urls = ['http://rapidshare.com/files/ab.part1.rar',
'http://rapidshare.com/files/ab.part2.rar']
instance.error = None

 

dl_handler = {
     "1" : "Torrent",
     "2" : "Rapid",
     "3" : "Single Url",
     "4" : "Upload",
     "5" : "Multipart"
}

dltype = {
    "1" : "Paid",
    "2" : "Torrent",
    "3" : "Url",
    "4" : "Paid Multipart"
}