lb.yaml

openapi: 3.0.3
info:
  title: ListenBrainz Swagger - OpenAPI 3.0
  description: OpenAPI client defintion.
  termsOfService: 'https://listenbrainz.org/terms-of-service/'
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  version: v-2024-07-17.0
servers:
  - url: 'https://api.listenbrainz.org'
tags:
  - name: lbStats
    description: |-
      ListenBrainz has a statistics infrastructure that collects and computes
      statistics from the listen data that has been stored in the database.
      The endpoints in this section offer a way to get this data programmatically.
  - name: lbCore
    description: The ListenBrainz server supports the following end-points for submitting and fetching listens.
  - name: lbPlaylists
    description: The playlists API allows for the creation and editing of lists of recordings.
  - name: lbRecordings
    description: Feedback API and Pinned Recording API.
  - name: lbPopularity
    description: The popularity APIs return the total listen and listeners count for various entities and also a way to query top entities for a given artist.
  - name: lbMetadata
    description: The metadata API looks up MusicBrainz metadata for recordings.
  - name: lbSocial
    description: These api endpoints allow to create and fetch timeline events for a user.
  - name: lbRecommendations
    description: ListenBrainz uses collaborative filtering to generate recording recommendations, which may be further processed to generate playlists for users.
  - name: lbMisc
    description: Various ListenBrainz API endpoints that are not documented elsewhere.
  - name: lbArt
    description: ListenBrainz has a (cover) art infrastructure that creates new cover art from a user's statistics or a user's instructions on how to composite a cover art grid.
paths:
  # Core
  '/1/search/users':
    $ref: 'paths/core/searchUsers.yaml'
  '/1/submit-listens':
    $ref: 'paths/core/submitListens.yaml'
  '/1/validate-token':
    $ref: 'paths/core/validateToken.yaml'
  '/1/user/{user_name}/listens':
    $ref: 'paths/core/listensForUser.yaml'
  '/1/user/{user_name}/listen-count':
    $ref: 'paths/core/listenCountForUser.yaml'
  '/1/user/{user_name}/playing-now':
    $ref: 'paths/core/playingNowForUser.yaml'
  '/1/user/{user_name}/similar-users':
    $ref: 'paths/core/similarUsersForUser.yaml'
  '/1/user/{user_name}/similar-to/{other_user_name}':
    $ref: 'paths/core/similarityOfUserForUser.yaml'
  '/1/delete-listen':
    $ref: 'paths/core/deleteListen.yaml'
  '/1/latest-import':
    $ref: 'paths/core/latestImport.yaml'
  '/1/user/{user_name}/services':
    $ref: 'paths/core/servicesForUser.yaml'
  '/1/user/{playlist_user_name}/playlists/recommendations':
    $ref: 'paths/core/recommendationPlaylistsForUser.yaml'
  '/1/user/{playlist_user_name}/playlists/search':
    $ref: 'paths/core/searchPlaylistForUser.yaml'
  '/1/lb-radio/artist/{seed_artist_mbid}':
    $ref: 'paths/core/lbRadioRecordingsForArtist.yaml'
  '/1/lb-radio/tags':
    $ref: 'paths/core/lbRadioTags.yaml'
  # Statistics
  '/1/stats/user/{user_name}/artists':
    $ref: 'paths/stats/topArtistsForUser.yaml'
  '/1/stats/user/{user_name}/releases':
    $ref: 'paths/stats/topReleasesForUser.yaml'
  '/1/stats/user/{user_name}/release-groups':
    $ref: 'paths/stats/topReleaseGroupsForUser.yaml'
  '/1/stats/user/{user_name}/recordings':
    $ref: 'paths/stats/topRecordingsForUser.yaml'
  '/1/stats/user/{user_name}/listening-activity':
    $ref: 'paths/stats/listeningActivityForUser.yaml'
  '/1/stats/user/{user_name}/daily-activity':
    $ref: 'paths/stats/dailyActivityForUser.yaml'
  '/1/stats/user/{user_name}/artist-map':
    $ref: 'paths/stats/artistMapForUser.yaml'
  '/1/stats/artist/{artist_mbid}/listeners':
    $ref: 'paths/stats/listenersForArtist.yaml'
  '/1/stats/release-group/{release_group_mbid}/listeners':
    $ref: 'paths/stats/listenersForReleaseGroup.yaml'
  '/1/stats/sitewide/artists':
    $ref: 'paths/stats/sitewideTopArtists.yaml'
  '/1/stats/sitewide/releases':
    $ref: 'paths/stats/sitewideTopReleases.yaml'
  '/1/stats/sitewide/release-groups':
    $ref: 'paths/stats/sitewideTopReleaseGroups.yaml'
  '/1/stats/sitewide/recordings':
    $ref: 'paths/stats/sitewideTopRecordings.yaml'
  '/1/stats/sitewide/listening-activity':
    $ref: 'paths/stats/sitewideListeningActivity.yaml'
  '/1/stats/sitewide/artist-map':
    $ref: 'paths/stats/sitewideArtistMap.yaml'
  '/1/stats/user/{user_name}/year-in-music/{year}':
    $ref: 'paths/stats/yearInMusicForUser.yaml'
  # Playlists
  '/1/user/{playlist_user_name}/playlists':
    $ref: 'paths/playlists/playlistsForUser.yaml'
  '/1/user/{playlist_user_name}/playlists/collaborator':
    $ref: 'paths/playlists/playlistsForUserCollaborator.yaml'
  '/1/user/{playlist_user_name}/playlists/createdfor':
    $ref: 'paths/playlists/playlistsCreatedForUser.yaml'
  '/1/playlist/create':
    $ref: 'paths/playlists/createPlaylist.yaml'
  '/1/playlist/search':
    $ref: 'paths/playlists/searchPlaylists.yaml'
  '/1/playlist/edit/{playlist_mbid}':
    $ref: 'paths/playlists/editPlaylist.yaml'
  '/1/playlist/{playlist_mbid}':
    $ref: 'paths/playlists/fetchPlaylist.yaml'
  '/1/playlist/{playlist_mbid}/item/add/{offset}':
    $ref: 'paths/playlists/appendRecordings.yaml'
  '/1/playlist/{playlist_mbid}/item/move':
    $ref: 'paths/playlists/moveItem.yaml'
  '/1/playlist/{playlist_mbid}/item/delete':
    $ref: 'paths/playlists/itemDelete.yaml'
  '/1/playlist/{playlist_mbid}/delete':
    $ref: 'paths/playlists/deletePlaylist.yaml'
  '/1/playlist/{playlist_mbid}/copy':
    $ref: 'paths/playlists/copyPlaylist.yaml'
  # Recordings
  '/1/feedback/recording-feedback':
    $ref: 'paths/recordings/recordingFeedback.yaml'
  '/1/feedback/user/{user_name}/get-feedback':
    $ref: 'paths/recordings/getFeedback.yaml'
  '/1/feedback/recording/{recording_mbid}/get-feedback-mbid':
    $ref: 'paths/recordings/getFeedbackMbid.yaml'
  '/1/feedback/user/{recording_msid}/get-feedback':
    $ref: 'paths/recordings/getFeedbackMsid.yaml'
  '/1/feedback/user/{user_name}/get-feedback-for-recordings':
    $ref: 'paths/recordings/getFeedbackForRecordings.yaml'
  '/1/pin':
    $ref: 'paths/recordings/pin.yaml'
  '/1/unpin':
    $ref: 'paths/recordings/unpin.yaml'
  '/1/pin/delete/{row_id}':
    $ref: 'paths/recordings/pinDelete.yaml'
  '/1/{user_name}/pins':
    $ref: 'paths/recordings/getPins.yaml'
  '/1/{user_name}/pins/following':
    $ref: 'paths/recordings/getPinsFollowing.yaml'
  '/1/{user_name}/pins/current':
    $ref: 'paths/recordings/getPinsCurrent.yaml'
  '/1/pin/update/{row_id}':
    $ref: 'paths/recordings/updatePin.yaml'
  # Popularity
  '/1/popularity/top-recordings-for-artist/{artist_mbid}':
    $ref: 'paths/popularity/topRecordingsForArtist.yaml'
  '/1/popularity/top-release-groups-for-artist/{artist_mbid}':
    $ref: 'paths/popularity/topReleaseGroupsForArtist.yaml'
  '/1/popularity/recording':
    $ref: 'paths/popularity/recording.yaml'
  '/1/popularity/artist':
    $ref: 'paths/popularity/artist.yaml'
  '/1/popularity/release':
    $ref: 'paths/popularity/release.yaml'
  '/1/popularity/release-group':
    $ref: 'paths/popularity/releaseGroup.yaml'
  # Metadata
  '/1/metadata/recording/':
    $ref: 'paths/metadata/recordingMetadata.yaml'
  '/1/metadata/release_group/':
    $ref: 'paths/metadata/releaseGroupMetadata.yaml'
  '/1/metadata/lookup/':
    $ref: 'paths/metadata/lookup.yaml'
  '/1/metadata/submit_manual_mapping/':
    $ref: 'paths/metadata/submitManualMapping.yaml'
  '/1/metadata/get_manual_mapping/':
    $ref: 'paths/metadata/getManualMapping.yaml'
  '/1/metadata/artist/':
    $ref: 'paths/metadata/artistMetadata.yaml'
  # Social
  '/1/user/{user_name}/timeline-event/create/recording':
    $ref: 'paths/social/recommendRecording.yaml'
  '/1/user/{user_name}/timeline-event/create/notification':
    $ref: 'paths/social/createNotification.yaml'
  '/1/user/{user_name}/timeline-event/create/review':
    $ref: 'paths/social/createReview.yaml'
  '/1/user/{user_name}/feed/events':
    $ref: 'paths/social/feedEvents.yaml'
  '/1/user/{user_name}/feed/events/listens/following':
    $ref: 'paths/social/feedEventsListensFollowing.yaml'
  '/1/user/{user_name}/feed/events/listens/similar':
    $ref: 'paths/social/feedEventsListensSimilar.yaml'
  '/1/user/{user_name}/feed/events/delete':
    $ref: 'paths/social/feedEventsDelete.yaml'
  '/1/user/{user_name}/feed/events/hide':
    $ref: 'paths/social/feedEventsHide.yaml'
  '/1/user/{user_name}/feed/events/unhide':
    $ref: 'paths/social/feedEventsUnhide.yaml'
  '/1/user/{user_name}/timeline-event/create/recommend-personal':
    $ref: 'paths/social/recommendPersonalRecording.yaml'
  '/1/user/{user_name}/followers':
    $ref: 'paths/social/followers.yaml'
  '/1/user/{user_name}/following':
    $ref: 'paths/social/following.yaml'
  '/1/user/{user_name}/follow':
    $ref: 'paths/social/follow.yaml'
  '/1/user/{user_name}/unfollow':
    $ref: 'paths/social/unfollow.yaml'
  # Recommendations
  '/1/cf/recommendation/user/{user_name}/recording':
    $ref: 'paths/recommendations/recordingRecommendations.yaml'
  '/1/recommendation/feedback/submit':
    $ref: 'paths/recommendations/submitFeedback.yaml'
  '/1/recommendations/feedback/delete':
    $ref: 'paths/recommendations/deleteFeedback.yaml'
  '/1/recommendations/feedback/user/{user_name}':
    $ref: 'paths/recommendations/feedbackGivenBy.yaml'
  '/1/recommendations/feedback/user/{user_name}/recordings':
    $ref: 'paths/recommendations/recordingsFeedbackGivenBy.yaml'
  # Miscellaneous
  '/1/explore/fresh-releases/':
    $ref: 'paths/misc/freshReleases.yaml'
  '/1/explore/color/{color}':
    $ref: 'paths/misc/color.yaml'
  '/1/explore/lb-radio':
    $ref: 'paths/misc/lbRadio.yaml'
  '/1/status/get-dump-info':
    $ref: 'paths/misc/getDumpInfo.yaml'
  # Art
  '/1/art/grid/':
    $ref: 'paths/art/createCoverArtGrid.yaml'
  '/1/art/grid-stats/{user_name}/{time_range}/{dimension}/{layout}/{image_size}':
    $ref: 'paths/art/createCoverArtGridForUser.yaml'
  '/1/art/{custom_name}/{user_name}/{time_range}/{image_size}':
    $ref: 'paths/art/createCustomCoverArt.yaml'
  '/1/art/year-in-music/{year}/{user_name}':
    $ref: 'paths/art/yearInMusic.yaml'
components:
  securitySchemes:
    ApiKeyAuth: # arbitrary name for the security scheme
      type: apiKey
      in: header # can be 'header', 'query' or 'cookie'
      name: 'Authorization' # name of the header, query parameter or cookie
  schemas:
    YearInMusicImage:
      type: string
      enum:
        - overview
        - stats
        - artists
        - albums
        - tracks
        - discovery-playlist
        - missed-playlist
    ListenType:
      type: string
      enum:
        - single
        - playing_now
        - import
    Mode:
      description: mode is the LB radio mode to be used for this query
      type: string
      enum:
        - easy
        - medium
        - hard
    AllowedStatisticsRange:
      type: string
      enum:
        - all_time
        - month
        - week
        - year
        - quarter
        - half_yearly
        - this_week
        - this_month
        - this_year
    Operator:
      type: string
      enum:
        - AND
        - OR
    AllowedRatings:
      type: string
      enum:
        - like
        - love
        - dislike
        - hate
        - bad_recommendation
    CoverTypes:
      type: string
      enum:
        - designer-top-5
        - designer-top-10
        - lps-on-the-floor
        - grid-stats
        - grid-stats-special