Recordings

Feedback API

These API endpoints allow to submit and retrieve feedback for a user’s recordings

POST /1/feedback/recording-feedback

Submit recording feedback (love/hate) to the server. A user token (found on https://listenbrainz.org/settings/ ) must be provided in the Authorization header! Each request should contain only one feedback in the payload.

For complete details on the format of the JSON to be POSTed to this endpoint, see Feedback JSON Documentation.

Request Headers:
Status Codes:
Response Headers:
GET /1/feedback/user/(user_name)/get-feedback

Get feedback given by user user_name. The format for the JSON returned is defined in our Feedback JSON Documentation.

If the optional argument score is not given, this endpoint will return all the feedback submitted by the user. Otherwise filters the feedback to be returned by score.

Parameters:

  • score (int) – Optional, If 1 then returns the loved recordings, if -1 returns hated recordings.

  • count (int) – Optional, number of feedback items to return, Default: DEFAULT_ITEMS_PER_GET Max: MAX_ITEMS_PER_GET.

  • offset (int) – Optional, number of feedback items to skip from the beginning, for pagination. Ex. An offset of 5 means the top 5 feedback will be skipped, defaults to 0.

  • metadata (str) – Optional, ‘true’ or ‘false’ if this call should return the metadata for the feedback.

Status Codes:

  • 200 OK – Yay, you have data!

Response Headers:
GET /1/feedback/recording/(recording_mbid)/get-feedback-mbid

Get feedback for recording with given recording_mbid. The format for the JSON returned is defined in our Feedback JSON Documentation.

Parameters:

  • score (int) – Optional, If 1 then returns the loved recordings, if -1 returns hated recordings.

  • count (int) – Optional, number of feedback items to return, Default: DEFAULT_ITEMS_PER_GET Max: MAX_ITEMS_PER_GET.

  • offset (int) – Optional, number of feedback items to skip from the beginning, for pagination. Ex. An offset of 5 means the top 5 feedback will be skipped, defaults to 0.

Status Codes:

  • 200 OK – Yay, you have data!

Response Headers:
GET /1/feedback/recording/(recording_msid)/get-feedback

Get feedback for recording with given recording_msid. The format for the JSON returned is defined in our Feedback JSON Documentation.

Parameters:

  • score (int) – Optional, If 1 then returns the loved recordings, if -1 returns hated recordings.

  • count (int) – Optional, number of feedback items to return, Default: DEFAULT_ITEMS_PER_GET Max: MAX_ITEMS_PER_GET.

  • offset (int) – Optional, number of feedback items to skip from the beginning, for pagination. Ex. An offset of 5 means the top 5 feedback will be skipped, defaults to 0.

Status Codes:

  • 200 OK – Yay, you have data!

Response Headers:
POST /1/feedback/user/(user_name)/get-feedback-for-recordings

Get feedback given by user user_name for the list of recordings supplied. The format for the JSON returned is defined in our Feedback JSON Documentation.

If the feedback for given recording MSID doesn’t exist then a score 0 is returned for that recording.

Note

If you get a 502 error while querying this endpoint using a GET request, consider reducing the number of total recordings you are querying in 1 request. As a rule of thumb, requesting maximum ~75 recordings in 1 request will avert the error.

The reason this error occurs is because the recording uuids are query params which are part of the request url. The length of the url is subject to a general limit imposed at the middleware level so requests with long urls never reach the ListenBrainz backend. Due to the same reason, the backend cannot provide a meaningful error.

@GET request :param recordings: comma separated list of recording_msids for which feedback records are to be fetched.

this param is deprecated and will be removed in the future. use recording_msids instead.

Parameters:

  • recording_msids (str) – comma separated list of recording_msids for which feedback records are to be fetched.

  • recording_mbids (str) – comma separated list of recording_mbids for which feedback records are to be fetched.

@POST request The format of the post data should look as follows: .. code-block:: json

{

“recording_msids”: “<msid1>,<msid2>,<msid3>”, “recording_mbids”: “<mbid1>,<mbid2>,<mbid3>”

}

Status Codes:

  • 200 OK – Yay, you have data!

Response Headers:
GET /1/feedback/user/(user_name)/get-feedback-for-recordings

Get feedback given by user user_name for the list of recordings supplied. The format for the JSON returned is defined in our Feedback JSON Documentation.

If the feedback for given recording MSID doesn’t exist then a score 0 is returned for that recording.

Note

If you get a 502 error while querying this endpoint using a GET request, consider reducing the number of total recordings you are querying in 1 request. As a rule of thumb, requesting maximum ~75 recordings in 1 request will avert the error.

The reason this error occurs is because the recording uuids are query params which are part of the request url. The length of the url is subject to a general limit imposed at the middleware level so requests with long urls never reach the ListenBrainz backend. Due to the same reason, the backend cannot provide a meaningful error.

@GET request :param recordings: comma separated list of recording_msids for which feedback records are to be fetched.

this param is deprecated and will be removed in the future. use recording_msids instead.

Parameters:

  • recording_msids (str) – comma separated list of recording_msids for which feedback records are to be fetched.

  • recording_mbids (str) – comma separated list of recording_mbids for which feedback records are to be fetched.

@POST request The format of the post data should look as follows: .. code-block:: json

{

“recording_msids”: “<msid1>,<msid2>,<msid3>”, “recording_mbids”: “<mbid1>,<mbid2>,<mbid3>”

}

Status Codes:

  • 200 OK – Yay, you have data!

Response Headers:
POST /1/feedback/import

Import feedback from external service.

Pinned Recording API

These API endpoints allow submitting, deleting, and retrieving ListenBrainz pinned recordings for users.

POST /1/pin

Pin a recording for user. A user token (found on https://listenbrainz.org/settings/) must be provided in the Authorization header! Each request should contain only one pinned recording item in the payload.

The format of the JSON to be POSTed to this endpoint should look like the following:

{
    "recording_msid": "40ef0ae1-5626-43eb-838f-1b34187519bf",
    "recording_mbid": "<this field is optional>",
    "blurb_content": "Wow..",
    "pinned_until": 1824001816
}
Request Headers:
Status Codes:
Response Headers:
POST /1/pin/unpin

Unpins the currently active pinned recording for the user. A user token (found on https://listenbrainz.org/settings/) must be provided in the Authorization header!

Request Headers:
Status Codes:

  • 200 OK – recording unpinned.

  • 401 Unauthorized – invalid authorization. See error message for details.

  • 404 Not Found – could not find the active recording to unpin for the user. See error message for details.

Response Headers:
POST /1/pin/delete/(row_id)

Deletes the pinned recording with given row_id from the server. A user token (found on https://listenbrainz.org/settings/) must be provided in the Authorization header!

Request Headers:
Parameters:

  • row_id (int) – the row_id of the pinned recording that should be deleted.

Status Codes:
Response Headers:
GET /1/(user_name)/pins

Get a list of all recordings ever pinned by a user with given user_name in descending order of the time they were originally pinned. The JSON returned by the API will look like the following:

{
    "count": 10,
    "offset": 0,
    "pinned_recordings": [
        {
            "blurb_content": "Awesome recording!",
            "created": 1623997168,
            "row_id": 10,
            "pinned_until": 1623997485,
            "recording_mbid": null,
            "recording_msid": "fd7d9162-a284-4a10-906c-faae4f1e166b"
            "track_metadata": {
                "artist_name": "Rick Astley",
                "track_name": "Never Gonna Give You Up"
            }
        },
        "-- more pinned recording items here ---"
    ],
    "total_count": 10,
    "user_name": "-- the MusicBrainz ID of the user --"
}
Parameters:

  • user_name (str) – the MusicBrainz ID of the user whose pin track history requested.

  • count (int) – Optional, number of pinned recording items to return, Default: DEFAULT_ITEMS_PER_GET Max: MAX_ITEMS_PER_GET

  • offset (int) – Optional, number of pinned recording items to skip from the beginning, for pagination. Ex. An offset of 5 means the most recent 5 pinned recordings from the user will be skipped, defaults to 0

Status Codes:
Response Headers:
GET /1/(user_name)/pins/following

Get a list containing the active pinned recordings for all users in a user’s user_name following list. The returned pinned recordings are sorted in descending order of the time they were pinned. The JSON returned by the API will look like the following:

{
    "count": 1,
    "offset": 0,
    "pinned_recordings": [
        {
        "blurb_content": "Spectacular recording!",
        "created": 1624000841,
        "row_id": 1,
        "pinned_until": 1624605641,
        "recording_mbid": null,
        "recording_msid": "40ef0ae1-5626-43eb-838f-1b34187519bf",
        "track_metadata": {
            "artist_name": "Rick Astley",
            "track_name": "Never Gonna Give You Up"
        },
        "user_name": "-- the MusicBrainz ID of the user who pinned this recording --"
        },
        "-- more pinned recordings from different users here ---"
    ],
    "user_name": "-- the MusicBrainz ID of the original user --"
}
Parameters:

  • user_name (str) – the MusicBrainz ID of the user whose followed user’s pinned recordings are being requested.

  • count (int) – Optional, number of pinned recording items to return, Default: DEFAULT_ITEMS_PER_GET Max: MAX_ITEMS_PER_GET

  • offset (int) – Optional, number of pinned recording items to skip from the beginning, for pagination. Ex. An offset of 5 means the most recent pinned recordings from the first 5 users will be skipped, defaults to 0

Status Codes:
Response Headers:
GET /1/(user_name)/pins/current

Get the currently pinned recording by a user with given user_name. The JSON returned by the API will look like the following:

{
    "pinned_recording": {
        "blurb_content": "Awesome recording!",
        "created": 1623997168,
        "row_id": 10,
        "pinned_until": 1623997485,
        "recording_mbid": null,
        "recording_msid": "fd7d9162-a284-4a10-906c-faae4f1e166b"
        "track_metadata": {
            "artist_name": "Rick Astley",
            "track_name": "Never Gonna Give You Up"
        }
    },
    "user_name": "-- the MusicBrainz ID of the user --"
}

If there is no current pin for the user, “pinned_recording” field will be null.

Parameters:

  • user_name (str) – the MusicBrainz ID of the user whose pin track history requested.

Status Codes:
Response Headers: