JDownloader Premium API 1. General 1.1 Request Method The API Uses POST HTTP Requests 1.2 Data Format Please use JSON as response format. All Examples here use formated JSON for readability. However,you can ignore whitespace, newlines and other prettyprinting. 1.3 "Challenge" Parameter To detect "Men in the middle", each request has to send a &challenge= parameter. The response has to be surrounded by this value. A normal, "error-free" response thus looks like this: ----------------------------------------------------------------------- | | | ----------------------------------------------------------------------- 1.4 Errors In case of Errors, the API has to return an error Object, and an ERROR marker before the json response. ----------------------------------------------------------------------- | | ERROR{"code":,"msg":""} | ----------------------------------------------------------------------- 1.5 Encoding Please make sure that all parameters are send and handled in UTF-8 Encoding. Please assure that your API is able to handle special chars correctly 1.6 Login Login can be done by &user and &pass parameter in each request, or by sending the &session parameter (see "getAccountDetails") 2. Commands 2.1 getAccountDetails 2.1.1 Responsedata ----------------------------------------------------------------------- | | { | "type" : "Premium", | "expireTime" : 130129841400, | "traffic" : 36774829453, | "autoRefill" : true, | "concurrentDownloads" : 20, | "maxChunks" : 10, | "concurrentConnections" : 50, | "resume" : true, | "session" : "47dhd829degd9" | } | ----------------------------------------------------------------------- type [String] Free String that describes in short the accounttype (free, premium, gold, platin,...) expireTime [long]in milliseconds Expire Time of this account in milliseconds unixtimestamp -1 = unlimited traffic [long] in bytes Free traffic available for download. autoRefill [boolean] True if this account autorefills without user interaction. For example if the account has a daily limit, and auto refills the next day concurrentDownloads [long] How many concurrent downloads can we start? -1 = unlimited maxChunks [long] By loading one file with several connections, we can boost the users downloadspeed. The server has to support several connections, and http Range-Headers. We call this "chunkload" -1 = unlimited concurrentConnections [long] If we use Chunkload, we have several connections per file. If there is a concurrent connection limit, please set this here. -1 = unlimited resume [boolean] Is Resuming broken downloads allowed? This Feature requires Serverside enabled range Headers session [String] OPTIONAL To use auth protected API Features, we need to login. We use either &user and &pass parameters, or a &session parameter. If you want us to use the session parameter as often as possible, please return this parameter here. We will renew the session if we get a session invalid error. 2.1.2 Possible Errors (Please see the Error Section to get a better description of each error) 1 user unknown 2 password wrong 3 logins wrong 4 session invalid 5 IP blocked 0 API Error 6 Custom 2.1.3 Example Request 2.1.3.1 Success ----------------------------------------------------------------------- | | ----------------Request------------------ | POST /api.php HTTP/1.1 | Host: yourhost.com | Connection: close | | cmd=getAccountDetails&challenge=dfhsds73hf&user=testuser&pass=testpassword | ----------------Response------------------ | HTTP/1.1 200 OK | Connection: close | | dfhsds73hf{ | "type" : "Premium", | "expireTime" : 130129841400, | "traffic" : 36774829453, | "autoRefill" : true, | "concurrentDownloads" : 20, | "maxChunks" : 10, | "concurrentConnections" : 50, | "resume" : true, | "session" : "47dhd829degd9" | }dfhsds73hf | ----------------------------------------------------------------------- 2.1.3.2 Error ----------------------------------------------------------------------- | | ----------------Request------------------ | POST /api.php HTTP/1.1 | Host: yourhost.com | Connection: close | | cmd=getAccountDetails&challenge=dfhsds73hf&user=testuser&pass=testpassword | ----------------Response------------------ | HTTP/1.1 200 OK | Connection: close | | dfhsds73hfERROR{ | "code" : 2, | "msg" : "Password is wrong" | }dfhsds73hf | ----------------------------------------------------------------------- 2.2 getLinkStatus 2.2.1 Parameters (This command does not require logins!) 2.2.1.1 links A newline (\r\n) separated list of all links(linkids). We do not have to use full links here, but can use link-IDs instead. 2.2.2 Response The response is a map. Each linkid is mapped to a statusobject ----------------------------------------------------------------------- | | { | "linkid1" : { | "status" : "online", | "filename" : "myFile.zip", | "filesize" : 134654654, | "md5" : "2fcab58712467eab4004583eb8fb7f89", | "sha1" : "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12", | "custom" : "any additional fileinfos", | "password" : "true" | }, | "linkid2" : { | "status" : "online", | "filename" : "myFile2.zip", | "filesize" : 13465454654, | "md5" : "4004583eb2fcab58712467eab8fb7f89", | "sha1" : "e1bb76e73912fd4e1c67a2d28fced849eb93eb12", | "custom" : "any additional fileinfos", | "password" : "false" | }, … | } | ----------------------------------------------------------------------- status [String] "online"|"offline"|"tempUnavailable"|"Invalid" Possible values: online File is online and can be downloaded offline File is offline, and cannot be downloaded any more tempUnavailable File is online, but not available atm. Invalid LinkID is not valid. filename [String] Full filename of this file filesize [long] in bytes Exact filesize md5 [String] OPTIONAL Md5 checksum of this file. We use this to find download errors sha1 [String] OPTIONAL Alternative to MD5 custom [String] OPTIONAL If you have any further information about this file, let us know here. Password [String] null|"true"|"false" OPTIONAL If downloading this file is password protected, set this to "true", else to "false" 2.2.3 Possible Errors 13 – Invalid Links 2.2.4 Example Request 2.2.4.1 Success ----------------------------------------------------------------------- | | ----------------Request------------------ | POST /api.php HTTP/1.1 | Host: yourhost.com | Connection: close | | cmd=getLinkStatus&challenge=dfhsds73hf&user=testuser&pass=testpassword&links=http://yourhost.com/file/123432 | http://yourhost.com/file/123433 | http://yourhost.com/file/123434 | | ----------------Response------------------ | HTTP/1.1 200 OK | Connection: close | | dfhsds73hf{ | "http://yourhost.com/file/123432" : { | "status" : "online", | "filename" : "myFile2.zip", | "filesize" : 13465454654, | "md5" : "4004583eb2fcab58712467eab8fb7f89", | "sha1" : "e1bb76e73912fd4e1c67a2d28fced849eb93eb12", | "custom" : "any additional fileinfos", | "password" : "false" | } | "http://yourhost.com/file/123433" : { | "status" : "offline" | } | "http://yourhost.com/file/123434" : { | "status" : "offline", | "filename" : "myFile3.zip", | "filesize" : 13465454654, | "md5" : "400eb2fcab58712467eab45838fb7f89", | "sha1" : "6e73912fd4e1c67a2d28fced849eb93ee1bb7b12", | "custom" : "any additional fileinfos", | "password" : "false" | } | }dfhsds73hf | ----------------------------------------------------------------------- 2.2.4.2 Error ----------------------------------------------------------------------- | | ----------------Request------------------ | POST /api.php HTTP/1.1 | Host: yourhost.com | Connection: close | | cmd=getLinkStatus&challenge=dfhsds73hf&user=testuser&pass=testpassword&links=http://yourhost.com/file/123432 | http://yourhost.com/file/123433 | http://yourhost.com/file/123434 | | ----------------Response------------------ | HTTP/1.1 200 OK | Connection: close | | dfhsds73hfERROR{ | "code" : 13, | "msg" : "Invalid File Id(s)" | }dfhsds73hf | ----------------------------------------------------------------------- 2.3 download 2.3.1 Parameters 2.3.1.1 downloadPass OPTIONAL If the download is passwordprotected 2.3.1.2 linkid Same linkid we use for linkcheck. This can be the whole http link, or only a part of it. 2.3.2 Response In errorcase, please do NOT send Content-Disposition, but a normal error response. If everything is fine, we get the filedata as response. Please send these headers 2.3.2.1 Content-Disposition see RFC2231, http://greenbytes.de/tech/tc2231/ Content-Disposition: attachment; filename*=UTF-8''test.html 2.3.2.2 Content-Length Exact size of the file in bytes Content-Length: 35678463 2.3.2.3 Content-MD5 (Optional) Md5 checksum of this file. We use this to find download errors Content-MD5: 4004583eb2fcab58712467eab8fb7f89 2.3.2.4 Content-SHA1 (Optional) Alternative to MD5 Header Content-SHA1: e1bb76e73912fd4e1c67a2d28fced849eb93eb12 2.3.3 Possible Errors 0 API Error 1 user unknown 2 password wrong 3 logins wrong 4 session invalid 5 IP blocked 6 Custom 7 Download Password wrong 8 Traffic limit reached 9 account type invalid 10 link offline 11 link temp unavailable 12 connection limit reached 2.3.4 Example Request 2.3.4.1 Success ----------------------------------------------------------------------- | | ----------------Request------------------ | POST /api.php HTTP/1.1 | Host: yourhost.com | Connection: close | | cmd=download&challenge=dfhsds73hf&user=testuser&pass=testpassword&linkid=http://yourhost.com/file/123432 | | | ----------------Response------------------ | HTTP/1.1 200 OK | Content-Disposition: attachment; filename*=UTF-8'' | Content-Length: 35678463 | Content-MD5: 4004583eb2fcab58712467eab8fb7f89 | Connection: close | | ...... | ----------------------------------------------------------------------- 2.3.4.2 Error ----------------------------------------------------------------------- | | ----------------Request------------------ | POST /api.php HTTP/1.1 | Host: yourhost.com | Connection: close | | cmd=download&challenge=dfhsds73hf&user=testuser&pass=testpassword&linkid=http://yourhost.com/file/123432 | | ----------------Response------------------ | HTTP/1.1 200 OK | Connection: close | | dfhsds73hfERROR{ | "code" : 8, | "msg" : "Traffic Limit reached. Try again in 3 hours" | }dfhsds73hf | ----------------------------------------------------------------------- 3. Errors ----------------------------------------------------------------------- | { | "code" : 5 | "msg" : "IP Blocked. To many failed logins!" | } ----------------------------------------------------------------------- Code 0 Technical API Error If we use wrong parameters, or any other technical error occures Code 1 User Unknown Login Error: The user is unknown Code 2 Password wrong Login Error: The user is known, but password is wrong Code 3 Logins wrong If you cannot differ between 1 and 2, use this code Code 4 Session Invalid Login Error: The given Session is invalid. We will try to get a new one Code 5 IP Blocked If you want to prevent hacking attemps, you can block the user's ip if he does too many wrong requests. If you do this, please provide an option to unblock the user. For example by solving a captcha request. Code 6 Custom For errors not matching the other codes. Please provide a description in the error msg Code 7 Download password wrong If download is password protected, and we have no, or a wrong password parameter Code 8 traffic limit reached Cannot download because the users traffic limit is reached Code 9 account type not supported For example if a user tries to download a file which cannot be downloaded with his accounttype Code 10 link offline Link is offline and cannot be downloaded (see link status) Code 11 link temp. Unavailable Link cannot be downloaded right now. (see link status) Code 12 Connection Limit Cannot download, because user reached his connection limit Code 13 Invalid Links Linkcheck failed, because there is one or more invalid links in the given list. Please avoid throwing this error. However some hosters want to avoid brutforce linkgrabbing, and this let the whole request fail of at least one invalid link is in the list.