Open API

Introduction

• media centers plugins such as XMBC
• desktop applications

Limits for non-premium users

Other limits

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

• /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

• /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

  1. files - arrays of file objects
  2. 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

  1. files - arrays of file objects
  2. 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

  1. id - array of file ids, if id is used then all other params are ignored
  2. do - unlink_all, unlink_by_feed or unlink_by_label
  3. id_feeds - unlink by feed ids
  4. 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

• /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/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

• /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:
  1. id - id
  2. name - name
  3. ctime - datetime when file was added
  4. size - size in bytes
  5. 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).
  6. is_protected - 1 or 0, if 1 then file will be not automatically deleted if not used
  7. type - enum('default', 'audio', 'video'), type of file
  8. status - 'fake' if a fake file was detected (mostly video)
  9. info_hash - hex(info_hash)
  10. video_info - video codec info, output of `ffmpeg -i `
  11. ss_num - number of screenshots, either 0 or 9
  12. ss_width - screenshot width, always 300
  13. ss_height - screenshot height, vary
  14. ss_urls - array of screenshots
  15. ss_urls_tn - array of screenshots thumbnails
  16. 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)
  17. av_info - last line output of Kaspersky scan
  18. av_time - aintivirus check time
  19. url_page - url to page with detailed info
  20. 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.
  21. url_pls - VLC playlist url with direct links inside the playlist
  22. 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
  23. id_labels - array of labels ids
  24. is_linked
  25. notes - created by user a text note about the file
  26. bitrate - average bitrate of t_files
  27. files_num_{audio,video,image} - number of t_files with specific content type
  28. 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
  29. del_reason - if unlinked=1 was used then this text filed will be set

• t_file

  - a file from an archive of files. Properties:
  1. name - name
  2. path - relative file path
  3. size - size
  4. ct - content type
  5. url_dl - direct download link for single file
  6. url_player - url for flash video player
  7. url_pls - single entry playlist
  8. player - enum('', 'video', 'audio', 'image'); inline player, only for files supported by flash/html5 and images
  9. width - for video and images
  10. height - for video and images
  11. url_tn - url of 9 thumbnails in row
  12. tn_height - height of url_tn image
  13. length - length of video/audio file in seconds
  14. 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:
  1. id - id
  2. name - name
  3. size - size
  4. dl_status - enum('active','finished','failed'); state of downloading
  5. 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'
  6. fail_reason - if dl_status='failed' then this property will contain error message. It's safe to shows this error to your user.
  7. info_hash - hex(info_hash)
  8. speed - speed of leeching
  9. bytes - how many bytes has been downloaded (might be higher then actual size)
  10. up_speed - speed of seeding
  11. up_bytes - how many bytes has been uploaded
  12. have - how many % of torrent has been downloaded
  13. 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.
  14. start_dt - when torrent was added/started
  15. finish_dt - when torrent was finished
  16. url_page - url to torrent/file info page (optional, returned only by /api/dl/get)
  17. is_linked

• label

  1. id
  2. name
  3. id_labels - (optional) id of parent label
  4. sorder - sort order, signed integer

• feed

  1. id
  2. name
  3. url
  4. mtime
  5. ctime
  6. status - set('enqueue','active','disabled','failed')
  7. fail_cnt - feed failed downloads counter
  8. err_msg - last error message
  9. notify
  10. cnt_items_enqueue - number of feed items with status="enqueue"
  11. cnt_items_failed
  12. cnt_items_active
  13. cnt_finished - number of finished and linked downloads
  14. cnt_failed - number of failed downloads
  15. failed_items - array of failed items errors { err_msg: '', cnt: 0 }
  16. pubdate
  17. episode