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/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/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.
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)/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
Status Codes:
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
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:
 

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)/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:
 
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: