Social

User Timeline API

These api endpoints allow to create and fetch timeline events for a user.

POST /1/user/(user_name)/timeline-event/create/recording

Make the user recommend a recording to their followers.

The request should post the following data about the recording being recommended:

{
    "metadata": {
        "artist_name": "<The name of the artist, required>",
        "track_name": "<The name of the track, required>",
        "recording_msid": "<The MessyBrainz ID of the recording, required>",
        "release_name": "<The name of the release, optional>",
        "recording_mbid": "<The MusicBrainz ID of the recording, optional>"
    }
}
Parameters

  • user_name (str) – The MusicBrainz ID of the user who is recommending the recording.

Request Headers
Status Codes

  • 200 OK – Successful query, recording has been recommended!

  • 400 Bad Request – Bad request, check response['error'] for more details.

  • 401 Unauthorized – Unauthorized, you do not have permissions to recommend recordings on the behalf of this user

  • 404 Not Found – User not found

Response Headers
POST /1/user/(user_name)/timeline-event/create/notification

Post a message with a link on a user’s timeline. Only approved users are allowed to perform this action.

The request should contain the following data:

{
    "metadata": {
        "message": "<the message to post, required>",
    }
}
Parameters

  • user_name (str) – The MusicBrainz ID of the user on whose timeline the message is to be posted.

Status Codes
Response Headers
POST /1/user/(user_name)/timeline-event/create/review

Creates a CritiqueBrainz review event for the user. This also creates a corresponding review in CritiqueBrainz. Users need to have linked their ListenBrainz account with CritiqueBrainz first to use this endpoint successfully.

The request should contain the following data:

{
    "metadata": {
        "message": "<the message to post, required>",
    }
}
Parameters

  • user_name (str) – The MusicBrainz ID of the user who is creating the review.

Status Codes

  • 200 OK – Successful query, message has been posted!

  • 400 Bad Request – Bad request, check response['error'] for more details.

  • 403 Forbidden – Forbidden, you have not linked with a CritiqueBrainz account.

  • 404 Not Found – User not found

Response Headers
GET /1/user/(user_name)/feed/events

Get feed events for a user’s timeline.

Parameters

  • user_name (str) – The MusicBrainz ID of the user whose timeline is being requested.

  • max_ts – If you specify a max_ts timestamp, events with timestamps less than the value will be returned

  • min_ts – If you specify a min_ts timestamp, events with timestamps greater than the value will be returned

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

Request Headers
Status Codes

  • 200 OK – Successful query, you have feed events!

  • 400 Bad Request – Bad request, check response['error'] for more details.

  • 401 Unauthorized – Unauthorized, you do not have permission to view this user’s feed.

  • 404 Not Found – User not found

Response Headers
POST /1/user/(user_name)/feed/events/delete

Delete those events from user’s feed that belong to them. Supports deletion of recommendation and notification. Along with the authorization token, post the event type and event id. For example:

{
    "event_type": "recording_recommendation",
    "id": "<integer id of the event>"
}

{
    "event_type": "notification",
    "id": "<integer id of the event>"
}
Parameters

  • user_name (str) – The MusicBrainz ID of the user from whose timeline events are being deleted

Request Headers
Status Codes
Response Headers
POST /1/user/(user_name)/feed/events/hide

Hide events from the user feed, only recording_recommendation and recording_pin events that have been generated by the people one is following can be deleted via this endpoint. For example:

{
    "event_type": "recording_recommendation",
    "event_id": "<integer id of the event>"
}

{
    "event_type": "recording_pin",
    "event_id": "<integer id of the event>"
}
Parameters

  • user_name (str) – The MusicBrainz ID of the user from whose timeline events are being deleted

Request Headers
Status Codes
Response Headers
POST /1/user/(user_name)/feed/events/unhide

Delete hidden events from the user feed, aka unhide events. For example:

{
    "event_type": "recording_pin",
    "event_id": "<integer id of the event>"
}
Request Headers
Status Codes
Response Headers
POST /1/user/(user_name)/timeline-event/create/recommend-personal

Make the user recommend a recording to their followers. The request should post the following data about the recording being recommended, and also the list of followers getting recommended:

{
    "metadata": {
        "artist_name": "<The name of the artist, required>",
        "track_name": "<The name of the track, required>",
        "recording_msid": "<The MessyBrainz ID of the recording, required>",
        "release_name": "<The name of the release, optional>",
        "recording_mbid": "<The MusicBrainz ID of the recording, optional>",
        "users": [<usernames of the persons you want to recommend to, required>]
        "blurb_content": "<String containing personalized recommendation>"
    }
}
Request Headers
Status Codes

  • 200 OK – Successful query, recording has been recommended!

  • 400 Bad Request – Bad request, check response['error'] for more

details. :statuscode 401: Unauthorized, you do not have permissions to recommend personal recordings on the behalf of this user :statuscode 404: User not found :resheader Content-Type: application/json

Follow API

These apis allow to interact with follow user feature of ListenBrainz.

GET /1/user/(user_name)/followers

Fetch the list of followers of the user user_name. Returns a JSON with an array of user names like these:

{
    "followers": ["rob", "mr_monkey", "..."],
    "user": "shivam-kapila"
}
Status Codes
GET /1/user/(user_name)/following

Fetch the list of users followed by the user user_name. Returns a JSON with an array of user names like these:

{
    "followers": ["rob", "mr_monkey", "..."],
    "user": "shivam-kapila"
}
Status Codes
POST /1/user/(user_name)/follow

Follow the user user_name. A user token (found on https://listenbrainz.org/profile/ ) must be provided in the Authorization header!

Request Headers
Status Codes

  • 200 OK – Successfully followed the user user_name.

  • 400 Bad Request –

    • Already following the user user_name.

    • Trying to follow yourself.

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

Response Headers
POST /1/user/(user_name)/unfollow

Unfollow the user user_name. A user token (found on https://listenbrainz.org/profile/ ) must be provided in the Authorization header!

Request Headers
Status Codes

  • 200 OK – Successfully unfollowed the user user_name.

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

Response Headers