Documentation for RPC API endpoints accessible by clients external to Cider.
Hostname and Port
All API endpoints are accessible at http://localhost:10767.
We've observed that using 127.0.0.1 when IPv4 is disabled tends to break and not connect. We recommend you do not turn off IPv4, but if you are required to do so, try using [::1]:10767.
Authentication
Unless explicitly disabled within Cider, all API requests require a valid API token. You can generate this token, or turn off authentication, from the menu at Settings -> Connectivity -> Manage External Application Access to Cider within Cider.
The generated token should be passed in the apitoken header of all requests. Do not prefix the token with Bearer or any other string; just pass the token by itself in the header.
This token is not required if disabled within the settings menu.
/api/v1/playback
The API endpoints documented below are all nested under /api/v1/playback.
GET/active
Responds with an empty body and status code 204: No Content. This endpoint can be used to quickly check that the RPC server is still active.
204: No Content
// No response body...
GET/is-playing
Responds with a boolean value indicating whether music is currently playing.
200: OK
{
"status": "ok",
"is_playing": true
}
GET/now-playing
Responds with an Apple Music API response for the currently playing song.
Accepts a url of the item to play. This URL can be found by right-clicking on an item and clicking on Share -> Apple Music in Cider, Share -> Copy Link in the official Apple Music app, or by copying the URL when viewing an item in the Apple Music web app.
Accepts a type of item to play and an id for the item. type should be one of the accepted types in the Apple Music API, such as songs. Note that the ID is required to be a string, not a number.
Request Body (`application/json`)
{
"type": "songs",
"id": "1719861213"
}
200: OK
{
"status": "ok"
}
POST/play-later
Adds an item to the end of the play queue (played after all other items currently in the queue).
Accepts a type of item to play and an id for the item. type should be one of the accepted types in the Apple Music API, such as songs. Note that the ID is required to be a string, not a number.
Request Body (`application/json`)
{
"type": "songs",
"id": "1719861213"
}
200: OK
{
"status": "ok"
}
POST /play-next
Adds an item to the start of the play queue (played next, before all other items in the queue).
Accepts a type of item to play and an id for the item. type should be one of the accepted types in the Apple Music API, such as songs. Note that the ID is required to be a string, not a number.
POST /play
Resumes playback of the current item. If no item is playing, the behavior set under the menu Settings -> Play Button on Stopped Action in Cider will take effect.
POST /pause
Pauses the currently playing item. If no item is playing or if the item is already paused, this will do nothing.
POST /playpause
Toggles the play/pause state of the current item. This has the same behavior as calling /pause if the item is playing, and /play if the item is paused.
POST /stop
Stops the current playback and removes the current item. If items are in the queue, they will be kept.
POST /next
Moves to the next item in the queue, if any. Autoplay enable/disable status will be respected if the queue is empty (infinity button within the queue panel in Cider).
If no item is currently playing but there is one in the queue, it will be started.
POST /previous
Moves to the previously played item, which is the item most recent in the playback history.
If no item is currently playing but there is one in the playback history, it will be started.
