API Reference

Parameters

Please note that all methods take the following parameters:

*) Either p or both t and s must be specified.

**) If apiKey is specified, then none of p, t, s, nor u can be specified.

Remember to URL encode the request parameters. All methods (except those that return binary data) returns XML documents conforming to the subsonic-rest-api.xsd schema. The XML documents are encoded with UTF-8.

POST support

OpenSubsonic add official support for application/x-www-form-urlencoded POST to pass the argument.

Check that the server support the HTTP form POST extension before using it.

The arguments can then be passed in the POST body (Do not forget to URL encode both the keys and values), this allows to overcome the URL size limits when passing many parameters for playlists for example.

Authentication

If you are targeting API version 1.12.0 or earlier, authentication is performed by sending the password as clear text or hex-encoded. Examples:

Starting with API version 1.13.0, the recommended authentication scheme is to send an authentication token, calculated as a one-way salted hash of the password.

This involves two steps:

1. For each REST call, generate a random string called the salt. Send this as parameter s. Use a salt length of at least six characters.
2. Calculate the authentication token as follows: token = md5(password + salt). The md5() function takes a string and returns the 32-byte ASCII hexadecimal representation of the MD5 hash, using lower case characters for the hex values. The ‘+’ operator represents concatenation of the two strings. Treat the strings as UTF-8 encoded when calculating the hash. Send the result as parameter t.

For example: if the password is sesame and the random salt is c19b2d, then token = md5(“sesamec19b2d”) = 26719a1196d2a940705a59634eb18eab. The corresponding request URL then becomes:

For servers that implement API Key authentication, the recommended authentication is to use an API key. This is a token generated from the Subsonic server. It must be passed in in as apiKey=<API key>, and the u parameter must not be provided. Note that u/p may still be used by servers which are backed by LDAP/PAM/other authentication.

Subsonic-response

All API endpoint unless noted otherwise returns a subsonic-response that indicate the result of the command and give some information about the server.

• Example:
• OpenSubsonic
• Subsonic

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true
  }
}

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1"
  }
}

See: subsonic-response for the field details.

Error handling

If a method fails it will return an error code and message in an error element. In addition, the status attribute of the subsonic-response root element will be set to failed instead of ok. For example:

• Example:
• OpenSubsonic
• Subsonic

{
  "subsonic-response": {
    "status": "failed",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true,
    "error": {
      "code": 40,
      "message": "Wrong username or password"
    }
  }
}

{
  "subsonic-response": {
    "status": "failed",
    "version": "1.16.1",
    "error": {
      "code": 40,
      "message": "Wrong username or password"
    }
  }
}

The following error codes are defined: