Open API
The API is in beta stage. Contact admin@ if you have any problems or if you need to extend the API.
Also keep in mind that the project was created by people who can easily spend a half of day just renaming wrong named variables.
Introduction
Furk.net - is a cloud file storage service with many unuque features. The purpose of this API is to provide access to its features from third-party tools. Example usage:- media centers plugins such as XMBC
- desktop applications
Limits for non-premium users
Currently only basic bandwidth limits are enforced. The limit vary but in general it should allow a user to download about 500Mb per day. Premiums users limits are much higher (up to 300GB per/month).Other limits
The API is indented to be used only by end-users who use your software (website, plugin or toolbar). So do not try to leach our DB. The requests limit is 60/hour per /24 subnet. If you need more then contact us first. All requests should provide http referer field so we can see where our API is used. Also we can randomly start sending bogus data if you abuse the rules. So do not use the API in production w/o prior approval and do not cheat after.API methods
Common parameters and response keys
- parameters
-
- api_key - required if no login cookies provided. Your API key is: [login to see it]
- jsonp - jsonp callback function. If provided then login cookies are ignored (so no XSS).
- pretty - ex. pretty=1 - turn on json pretty formating.
- format - format of response; supported formats: json(default), xml, dumper; use json whenever possible. Xml format is not well tested and is provided only to make fun on people who got permanent brain damage back in 199x. Dumper format is just for debug and console testing.
- response
-
- status - 'ok' or 'error', test for status=='ok' to check if a request was successfull
- error - error text if status=='error', it's safe to display this error to your users
Downloads
Download files from various sources _to_ the storage./api/dl/add - add a download
- parameters
-
url OR info_hash OR file
- url - url to .torrent file. Some urls to torrent description pages may be automatically converted into urls to .torrent files.
- info_hash - torrent wil be downloaded from a public torrent cache
- file - 'input type=file', the .torrent metafile
- response
-
- dl - download objects, you need only id for futher queries
- file - file object if download is/was already processed
/api/dl/get - get linked downloads
- parameters
-
- id - a single id or arrays of ids (array is muplitpy id params), if omited then all your active and failed downloads are returned
- dl_status - 'active' or 'failed'
- offset, limit
- sort order
- default order is by ctime
- response
- dls - download object
Feeds
Dowloads may be initiated not only by adding individual links/torrents but also by adding an RSS feed in special format./api/feed/get - get user's feed list
- response
- feeds - list of feed objects
/api/feed/add
- parameters
-
- name - just for user reference
- url
- flags - 'notify' or ''
- pubdate - process only feed items published after this date
- episode - process only feed items with episode number greater or equal then this number (S01E02 == 102)
/api/feed/update
- parameters
-
- id
- flags - 'notify' or ''
- pubdate - process only feed items published after this date
- episode - process only feed items with episode number greater or equal then this number (S01E02 == 102)
/api/feed/unlink
- parameters
-
- id - if id is omited then all feeds fill be unlinked
/api/feed/reset - reset and restart a failed feed
- parameters
-
- id
Files
/api/file/info - get files basic info
get names and video info w/o account specific data (labels, feeds etc)- parameters
-
- info_hash - array of info_hash'es.
- response
-
- files - arrays of file objects
- found_files - found_rows()
/api/file/get - get files
- parameters
-
- id - single id or arrays of ids, if used then all params below are ignored, if not used then all linked files are returned
- link_dt_gt - select files linked after this date (mysql date format)
- type - enum('default','audio','video')
- src - source of file, enum('','upload','torrent','http','ed2k'); upload: http upload using html form, torrent: bittorrent proxy service
- tag - optional, select by searching a tag in tags
- offset, limit
-
sort_col - sort by column, valid options are:
- ctime - time when file was linked to user account
- size - size
- name - name
- sort_type - 'asc' or 'desc'
- name_like - filter by substring
- unlinked - if unlinked=1 then only unlinked files will be selected
- response
-
- files - arrays of file objects
- found_files - found_rows()
/api/file/link - link files
- parameters
- id - array of file ids
/api/file/protect - protect/unprotect files
- parameters
- id - array of file ids
- is_protected - 1 or 0
/api/file/unlink - unlink files
- parameters
-
- id - array of file ids, if id is used then all other params are ignored
- do - unlink_all, unlink_by_feed or unlink_by_label
- id_feeds - unlink by feed ids
- id_labels - unlink by label ids
-
/api/file/clear
When /api/file/unlink is called file link object is just moved to another table. To purge file link completely you need to call clear. Unlinked files can be selected by passing unlinked=1 to /api/file/get so a Trash can be implemented.- parameters
- same as for unlink
/api/file/update_link - edit link (file) properties
- parameters
-
- id - file id
- notes
/api/dl/unlink - unlink download
- parameters
- id - array of dl ids
Labels
Labels were inspired by Gmail/Google docs labels and can be used either as tags or directories./api/label/get
- parameters
- [no parameters]
- response
- an array of labels
/api/label/upsert
- parameters
- id, name, id_labels, sorder
- response
- label object
- notes
- if an id is provided or a name is not unique then a record will be updated, otherwise it will be inserted
/api/label/link - link a label with a file
- parameters
- id_files - array of file ids, id_labels - arrays of label ids
/api/label/unlink - unlink a label from a file
- parameters
- id_files - array of file ids, id_labels - arrays of label ids
Login and Registration
API key or login cookies are not required for these methods./api/login/login
- parameters
- login, pwd
- response
- api_key - you can use it for further request if you client doesn't support cookies
/api/login/reg
- parameters
-
- login, pwd, re_pwd, email
- code - invite code, currently an invite code is required to register. In general it's a better if user is registered using website. For ex. facebook registrations can be processed only through website.
- response
- array of errors if any
/api/login/logout
/api/login/recover - send password recovery link
- parameters
- login or email
/api/login/save_pwd - save new password using password recovery link
- parameters
- hash, pwd, re_pwd
/api/login/email_ver - email verification
- parameters
- hash
User profile and settings
/api/account/info - info about account and premium
- response
-
user:
- login, email, ctime, email_is_ver
-
premium:
- bw_{used,limit}_{month,total,extra} - bandwidth counters and limits
- duration - duration of premium in seconds
- time_left
- bw_month_time_left - how long to wait when bw_used_month will be reset back to bw_limit_month
- is_not_last_month - in case of multi months premiums
- name - name of premium
- from_dt
- to_dt
- to_dt_next_max - max(to_dt) of a next premiums if any
/api/account/change_pwd
- parameters
- old_pwd, pwd, re_pwd
/api/account/change_email - change email and send email verification link
- parameters
- email, re_email
/api/account/resend_email_ver - send email verification link
/api/account/save_prefs - save preferences
- parameters
-
- prefs_flags - array of flags, currently only supported is 'moderated_full', ex. prefs=flags=moderated_full
- prefs_json - a simple text field
- dl_uri_scheme - enum('','http','https')
- dl_uri_host - enum('','gcdn.biz')
- dl_uri_port - enum('','30084','30082')
- dl_uri_key - int unsigned not null default 0; used to reset existsing download links
- notes
- Ff a param doesn't exists in query then it will not updated. If params value is '' then a default value will be used if any.
/api/account/txns - list of transactions
- response
- premiums and addons arrays
/api/account/get_invites - get invites
- response
- array of unused invites
Misc.
/api/ping
does nothing, usefull for authentication tests/api/bug_report
send bug report by email to admin.- parameters
- any parameters
Metasearch engine
Agregated search using Google and a dozen of BitTorrent websites./api/plugins/metasearch - search for torrents
- parameters
-
- q - query
- offset - offset, default: 0
- limit - limit, default: 25
- and all other parameters supported by the search /search page.
- response
-
- stats - query stats hash
- files - array of files
- notes
- if a torrent was never been downloaded then only this properties will be provided: name, info_hash, size. Use info_hash to add such torrent to downloads
API objects
file
- either a single file or a zip archive of files. If it's an archive of files then each subfile (t_file) can be downloaded separatetly. Properties:- id - id
- name - name
- ctime - datetime when file was added
- size - size in bytes
- is_ready - '1' if file is http ready. '0' if file was downloaded and deleted later for some reason (ex. no downloads in 90 days).
- is_protected - 1 or 0, if 1 then file will be not automatically deleted if not used
- type - enum('default', 'audio', 'video'), type of file
- status - 'fake' if a fake file was detected (mostly video)
- info_hash - hex(info_hash)
- video_info - video codec info, output of `ffmpeg -i `
- ss_num - number of screenshots, either 0 or 9
- ss_width - screenshot width, always 300
- ss_height - screenshot height, vary
- ss_urls - array of screenshots
- ss_urls_tn - array of screenshots thumbnails
- av_result - enum('ok','warning','infected','error'), 'ok' if no viruses, 'warning' if a password protected archive was found, 'error' if there's was an internal error while checking (ex. Kaspersky segfaults often)
- av_info - last line output of Kaspersky scan
- av_time - aintivirus check time
- url_page - url to page with detailed info
- url_dl - the main direct download link. Link will contain your id and you sub user id. Each your user should get personal links. Don't use one link for more the one user.
- url_pls - VLC playlist url with direct links inside the playlist
- t_files - array of t_files objects, will be included only if 't_files=1' was specified in query and only if id/info_hash params is not an array (i.e. single), don't use if not required, if there's more then 1k of t_files then only first 1k will be included
- id_labels - array of labels ids
- is_linked
- notes - created by user a text note about the file
- bitrate - average bitrate of t_files
- files_num_{audio,video,image} - number of t_files with specific content type
- files_num_{audio,video}_player - number of t_files with specific content type and which are supported by Flash/HTML5 player. flv/mp4/mp3 and some other files
- del_reason - if unlinked=1 was used then this text filed will be set
-
t_file
- a file from an archive of files. Properties:- name - name
- path - relative file path
- size - size
- ct - content type
- url_dl - direct download link for single file
- url_player - url for flash video player
- url_pls - single entry playlist
- player - enum('', 'video', 'audio', 'image'); inline player, only for files supported by flash/html5 and images
- width - for video and images
- height - for video and images
- url_tn - url of 9 thumbnails in row
- tn_height - height of url_tn image
- length - length of video/audio file in seconds
- bitrate - for video and audio files (kb/s); actually it's a datarate calculated as size/length*8/1024
-
dl
- a download object (http/ftp or torrent). The purpose of this object is only for quering download states. Once a download is finished a new file object is created but the download object will be keeped untill download is finalized. I.e. a download and a file pointing to the same data may appear in /api/file/get and /api/dl/get. Properties:- id - id
- name - name
- size - size
- dl_status - enum('active','finished','failed'); state of downloading
- active_status - enum('adding','starting','leeching','seeding'); sub status of dl_status='active'; To check if a download is ready check for dl_status='finished'
- fail_reason - if dl_status='failed' then this property will contain error message. It's safe to shows this error to your user.
- info_hash - hex(info_hash)
- speed - speed of leeching
- bytes - how many bytes has been downloaded (might be higher then actual size)
- up_speed - speed of seeding
- up_bytes - how many bytes has been uploaded
- have - how many % of torrent has been downloaded
- avail - how many % of torrent is available in swarm. If less then 100% then the torrent may stuck. If now bytes is downloaded in 24h a torrent is auto deleted, if it doesn't start in 12h (i.e. have=0) then it's deleted. This field is not used by current BT engine.
- start_dt - when torrent was added/started
- finish_dt - when torrent was finished
- url_page - url to torrent/file info page (optional, returned only by /api/dl/get)
- is_linked
-
label
- id
- name
- id_labels - (optional) id of parent label
- sorder - sort order, signed integer
-
feed
- id
- name
- url
- mtime
- ctime
- status - set('enqueue','active','disabled','failed')
- fail_cnt - feed failed downloads counter
- err_msg - last error message
- notify
- cnt_items_enqueue - number of feed items with status="enqueue"
- cnt_items_failed
- cnt_items_active
- cnt_finished - number of finished and linked downloads
- cnt_failed - number of failed downloads
- failed_items - array of failed items errors { err_msg: '', cnt: 0 }
- pubdate
- episode