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>",
    }
}

Response Headers:
Parameters:	user_name (`str`) – The MusicBrainz ID of the user on whose timeline the message is to be posted.
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 are not an approved user. 404 Not Found – User not found
	Content-Type – application/json

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>"
    }
}

Response Headers:
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
	Content-Type – application/json

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>"
}

Response Headers:
Parameters:	user_name (`str`) – The MusicBrainz ID of the user from whose timeline events are being deleted
Status Codes:	200 OK – Successful deletion 400 Bad Request – Bad request, check `response['error']` for more details. 401 Unauthorized – Unauthorized 404 Not Found – User not found 500 Internal Server Error – API Internal Server Error
	Content-Type – application/json

GET /1/user/(user_name)/feed/events¶

Get feed events for a user’s timeline.

Response Headers:
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
	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:	200 OK – Yay, you have data! 404 Not Found – User not found

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:	200 OK – Yay, you have data! 404 Not Found – User not found

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:
	Authorization – Token <user token> Content-Type – application/json
Status Codes:	200 OK – Successfully unfollowed the user `user_name`. 401 Unauthorized – invalid authorization. See error message for details.
Response Headers:
	Content-Type – application/json

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:
	Authorization – Token <user token> Content-Type – application/json
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:
	Content-Type – application/json