HTTP JSON-RPC API

The Mopidy-HTTP extension makes Mopidy’s Core API available using JSON-RPC over HTTP using HTTP POST and WebSockets. We also provide a JavaScript wrapper, called Mopidy.js, around the JSON-RPC over WebSocket API for use both from browsers and Node.js. The Mopidy-API-Explorer extension, can also be used to get you familiarized with HTTP based APIs.

Warning

API stability

Since the HTTP JSON-RPC API exposes our internal core API directly it is to be regarded as experimental. We cannot promise to keep any form of backwards compatibility between releases as we will need to change the core API while working out how to support new use cases. Thus, if you use this API, you must expect to do small adjustments to your client for every release of Mopidy.

From Mopidy 1.0 and onwards, we intend to keep the core API far more stable.

HTTP POST API

The Mopidy web server accepts HTTP requests with the POST method to http://localhost:6680/mopidy/rpc, where the localhost:6680 part will vary with your local setup. The HTTP POST endpoint gives you access to Mopidy’s full core API, but does not give you notification on events. If you need to listen to events, you should probably use the WebSocket API instead.

Example usage from the command line:

$ curl -d '{"jsonrpc": "2.0", "id": 1, "method": "core.playback.get_state"}' http://localhost:6680/mopidy/rpc
{"jsonrpc": "2.0", "id": 1, "result": "stopped"}

For details on the request and response format, see JSON-RPC 2.0 messages.

WebSocket API

The Mopidy web server exposes a WebSocket at http://localhost:6680/mopidy/ws, where the localhost:6680 part will vary with your local setup. The WebSocket gives you access to Mopidy’s full API and enables Mopidy to instantly push events to the client, as they happen.

On the WebSocket we send two different kind of messages: The client can send JSON-RPC 2.0 requests, and the server will respond with JSON-RPC 2.0 responses. In addition, the server will send event messages when something happens on the server. Both message types are encoded as JSON objects.

If you’re using the API from JavaScript, either in the browser or in Node.js, you should use Mopidy.js JavaScript library which wraps the WebSocket API in a nice JavaScript API.

JSON-RPC 2.0 messages

JSON-RPC 2.0 messages can be recognized by checking for the key named jsonrpc with the string value 2.0. For details on the messaging format, please refer to the JSON-RPC 2.0 spec.

All methods (not attributes) in the Core API is made available through JSON-RPC calls over the WebSocket. For example, mopidy.core.PlaybackController.play() is available as the JSON-RPC method core.playback.play.

The core API’s attributes is made available through setters and getters. For example, the attribute mopidy.core.PlaybackController.current_track is available as the JSON-RPC method core.playback.get_current_track.

Example JSON-RPC request:

{"jsonrpc": "2.0", "id": 1, "method": "core.playback.get_current_track"}

Example JSON-RPC response:

{"jsonrpc": "2.0", "id": 1, "result": {"__model__": "Track", "...": "..."}}

The JSON-RPC method core.describe returns a data structure describing all available methods. If you’re unsure how the core API maps to JSON-RPC, having a look at the core.describe response can be helpful.

Event messages

Event objects will always have a key named event whose value is the event type. Depending on the event type, the event may include additional fields for related data. The events maps directly to the mopidy.core.CoreListener API. Refer to the CoreListener method names is the available event types. The CoreListener method’s keyword arguments are all included as extra fields on the event objects. Example event message:

{"event": "track_playback_started", "track": {...}}