Basics

Introduction

This document specifies the development state of the MyJDownloader API. As the API changes regularly, changes in this document will happen every so often. The API is designed to offer a secure communication between the JDownloader client and the request client, and to prevent any man in the middle listeners. For this approach the API is using AES128CBC and HMAC-SHA256. To be able to communicate with the API we would suggest to make sure you understand the procedure as this can get somewhat complicated for beginners. The API is REST based, but currently only GET and POST routes are offered.

Communication

API Endpoint: https://api.jdownloader.org
To avoid problems with NAT and Portforwarding, the communication between the frontends and JDownloader is routed through our Connection-Server. IF available, the frontend will try to establish a direct connection between the frontend and JDownloader after validating the account credentials and initializing the encryption tokens.
Pro Tip: It's possible to access the JDownloader API directly (Bypass our server) by enabling the so called 'Deprecated API' in the Advanced Options.

Common Mistakes

If things do not work as expected, please check the common mistakes section first.

Parameter Order

The parameter in GET/POST requests are important. Use the documented order or you won't get a positive response.

Content-Type Header & JSON Syntax

Make sure to use the correct Content-Type. For most calls, this is application/json; charset=utf-8, see call description

The API expects JSON Input and will return JSON output. Make sure that you send valid JSON formatted text.
We highly recommend, that you use a JSON Library to create proper JSON, and parse the results. The results syntax of existing methods MAY CHANGE, but the content structure and field names will remain. (e.g. we might add a field, or shuffle fields, but we will not rename or remove an existing field. This way, the API will stay compatible)

Always provide a new RequestID

The RequestID is required in almost every request. It's a number that has to increase from one call to another. You can either use a millisecond precise timestamp, or a self incrementing number. The API will return the RequestID in the response. You should validate the response to make sure the answer is valid.

Field names

Make sure that you use the correct field names.

WRONG!
	/downloadsV2/queryLinks?{"packageUUID":[1468427395088]}
	
CORRECT!
	/downloadsV2/queryLinks?{"packageUUIDs":[1468427395088]}
	

URL-Encoding

Make sure all url parameters are correctly urlencoded.

Signature

Most calls require a signature that validates the call against our server and your JDownloader. The API will only accept calls with a proper signature.
Create the Signature:

  1. build the full queryString (incl. RequestID)
  2. hmac the queryString. The used Key depends. Some calls use serverEncryptionToken, others have to ask the user for email and password, create the loginSecret and use the loginsecret as key. email needs to be lower case!
  3. hexformat the result
  4. append the signature to the queryString &signature=.
Example:
queryString = "/my/connect?email=foo@bar.com&rid=1361982773157";
queryString += "&signature=" + HmacSha256(utf8bytes(queryString), ServerEncryptionToken);

Errors & Exceptions

All HTTP Response codes except 200 are errors or exceptions. The response content contains an ErrorObject in this case. Errors can have different origins. Depending on the call, the Connection Server or the JDownloader installation might throw an error. Check the 'src' field to get the origin.

{
"src":"MYJD"|"DEVICE"  
"type":<see errortypes below>
"data":<Optional Data Object>
}

Device Error Types

Device Errors' origin is a JDownloader installation.

"src":"DEVICE"

Server Error Types

Server Errors' origin is the Connection Server

"src":"MYJD"

Account Management

Create/Register an account

1. Get Captcha Challenge

Response Content

{ 
"captchaChallenge" :	"13650058317(...)8299d97cf5",
"image" : 		"data:image/png;base64,iVBORw0KGgoCAYAA(...)"
}

2. Register

3. Finish Registration

Methods