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 (either one of recording_msid or recording_mbid is sufficient):

{
    "metadata": {
        "recording_msid": "<The MessyBrainz ID of the recording, optional>",
        "recording_mbid": "<The MusicBrainz ID of the recording>"
    }
}
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

  • 403 Forbidden – Forbidden, you are not an approved 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": {
        "entity_name": "<entity name, required>",
        "entity_id": "<entity id, required>",
        "entity_type": "<entity type, required>",
        "text": "<the message to post, required>",
        "language": "<language code, required>",
        "rating": <rating, int>,
    },
}
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 (int) – If you specify a max_ts timestamp, events with timestamps less than the value will be returned.

  • min_ts (int) – 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.

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

  • 404 Not Found – User not found

Response Headers:
GET /1/user/(user_name)/feed/events/listens/following

Get feed’s listen events for followed users.

Parameters:

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

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

  • min_ts (int) – 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 listen-events!

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

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

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

  • 404 Not Found – User not found

Response Headers:
GET /1/user/(user_name)/feed/events/listens/similar

Get feed’s listen events for similar users.

Parameters:

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

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

  • min_ts (int) – 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 listen-events!

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

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

  • 403 Forbidden – Forbidden, 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 (either one of recording_msid or recording_mbid is sufficient), and also the list of followers getting recommended:

{
    "metadata": {
        "recording_msid": "<The MessyBrainz ID of the recording, optional>",
        "recording_mbid": "<The MusicBrainz ID of the recording>",
        "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.

  • 401 Unauthorized – Unauthorized, you do not have permissions to recommend

personal recordings on the behalf of this user :statuscode 403: Forbidden, you do not have permissions to recommend :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:

{
    "following": ["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/settings/ ) 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/settings/ ) 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: