{"openapi":"3.1.0","info":{"title":"Multi-Scrobbler API","version":"0.1.0","description":"The Multi-Scrobbler server API is documented in **OpenAPI format** and includes\nendpoints useful for programatically interacting with your `Play` data and the various **Sources**/**Clients**\nyou have configured.\n\nAdditionally, the **Ingress** category endpoints document the body/query shape required to make a successful api call for [Ingress-based Sources.](/configuration/sources/?sourceComm=ingress#by-communication-method)\n\n:::tip\n\nIf you not using Ingress-based Sources or trying to write an application to use the MS API, you do not\nnot need to use this docs section.\n\n:::\n\n:::important\n\nThe endpoints documented here, other than those in Ingress categories, are **subject to change until a release declares them stable.**\n\n:::"},"paths":{"/api/logs":{"get":{"summary":"Get Logs","tags":["Events"],"parameters":[],"responses":{"200":{"description":"Success"}}},"put":{"summary":"Update Log Settings","tags":["Events"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"level":{"type":"string","enum":["debug","error","verbose","info","silly","silent","log","trace","warn","fatal"]},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":500}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success"}}}},"/api/events":{"get":{"summary":"SSE Events","tags":["Events"],"parameters":[{"name":"tab","in":"query","required":false,"schema":{"description":"Client-generated connection id. Required to opt in to log events via PUT /api/events/:tab/logs","type":"string"}}],"responses":{"200":{"description":"Success"}}}},"/api/webscrobbler":{"post":{"summary":"Accepts a Webscrobbler native scrobble","tags":["WebScrobbler Ingress"],"parameters":[],"description":"Use the default path `/api/webscrobbler` for standard configs or append a suffix if using a slug EX `/api/webscrobbler/mySlug`","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"eventName":{"anyOf":[{"type":"string","enum":["scrobble","paused","resumedplaying","nowplaying"]},{"type":"string"}]},"time":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"data":{"type":"object","properties":{"song":{"type":"object","properties":{"controllerTabId":{"anyOf":[{"type":"string"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}]},"connector":{"type":"object","properties":{"id":{"type":"string"},"js":{"type":"string"},"label":{"type":"string"}},"required":["id","js","label"],"additionalProperties":false},"parsed":{"type":"object","properties":{"artist":{"type":["string","null"]},"album":{"type":["string","null"]},"albumArtist":{"type":["string","null"]},"track":{"type":["string","null"]},"duration":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"trackArt":{"type":["string","null"]},"uniqueID":{"type":["string","null"]},"originUrl":{"type":["string","null"]},"isPodcast":{"type":["boolean","null"]},"isPlaying":{"type":["boolean","null"]},"currentTime":{"type":["number","null"]},"isScrobblingAllowed":{"type":["boolean","null"]}},"additionalProperties":false},"processed":{"type":"object","properties":{"artist":{"type":["string","null"]},"album":{"type":["string","null"]},"albumArtist":{"type":["string","null"]},"track":{"type":["string","null"]},"duration":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]}},"additionalProperties":false},"noRegex":{"type":"object","properties":{"artist":{"type":["string","null"]},"album":{"type":["string","null"]},"albumArtist":{"type":["string","null"]},"track":{"type":["string","null"]},"duration":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]}},"additionalProperties":false},"flags":{"type":"object","properties":{"isScrobbled":{"type":"boolean"},"isCorrectedByUser":{"type":"boolean"},"isRegexEditedByUser":{"type":"object","properties":{"track":{"type":"boolean"},"artist":{"type":"boolean"},"album":{"type":"boolean"},"albumArtist":{"type":"boolean"}},"required":["track","artist","album","albumArtist"],"additionalProperties":false},"isAlbumFetched":{"type":"boolean"},"isValid":{"type":"boolean"},"isMarkedAsPlaying":{"type":"boolean"},"isSkipped":{"type":"boolean"},"isReplaying":{"type":"boolean"}},"required":["isScrobbled","isCorrectedByUser","isRegexEditedByUser","isAlbumFetched","isValid","isMarkedAsPlaying","isSkipped","isReplaying"],"additionalProperties":{}},"metadata":{"type":"object","properties":{"label":{"type":"string"},"startTimestamp":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"albumMbId":{"type":"string"},"albumUrl":{"type":"string"},"artistUrl":{"type":"string"},"notificationId":{"type":"string"},"trackArtUrl":{"type":"string"},"trackUrl":{"type":"string"},"userPlayCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"userloved":{"type":"boolean"}},"required":["label","startTimestamp"],"additionalProperties":{}},"connectorLabel":{"type":"string"}},"required":["controllerTabId","connector","parsed","processed","noRegex","flags","metadata"],"additionalProperties":false},"songs":{"type":"array","items":{"type":"object","properties":{"controllerTabId":{"anyOf":[{"type":"string"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}]},"connector":{"type":"object","properties":{"id":{"type":"string"},"js":{"type":"string"},"label":{"type":"string"}},"required":["id","js","label"],"additionalProperties":false},"parsed":{"type":"object","properties":{"artist":{"type":["string","null"]},"album":{"type":["string","null"]},"albumArtist":{"type":["string","null"]},"track":{"type":["string","null"]},"duration":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]},"trackArt":{"type":["string","null"]},"uniqueID":{"type":["string","null"]},"originUrl":{"type":["string","null"]},"isPodcast":{"type":["boolean","null"]},"isPlaying":{"type":["boolean","null"]},"currentTime":{"type":["number","null"]},"isScrobblingAllowed":{"type":["boolean","null"]}},"additionalProperties":false},"processed":{"type":"object","properties":{"artist":{"type":["string","null"]},"album":{"type":["string","null"]},"albumArtist":{"type":["string","null"]},"track":{"type":["string","null"]},"duration":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]}},"additionalProperties":false},"noRegex":{"type":"object","properties":{"artist":{"type":["string","null"]},"album":{"type":["string","null"]},"albumArtist":{"type":["string","null"]},"track":{"type":["string","null"]},"duration":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}]}},"additionalProperties":false},"flags":{"type":"object","properties":{"isScrobbled":{"type":"boolean"},"isCorrectedByUser":{"type":"boolean"},"isRegexEditedByUser":{"type":"object","properties":{"track":{"type":"boolean"},"artist":{"type":"boolean"},"album":{"type":"boolean"},"albumArtist":{"type":"boolean"}},"required":["track","artist","album","albumArtist"],"additionalProperties":false},"isAlbumFetched":{"type":"boolean"},"isValid":{"type":"boolean"},"isMarkedAsPlaying":{"type":"boolean"},"isSkipped":{"type":"boolean"},"isReplaying":{"type":"boolean"}},"required":["isScrobbled","isCorrectedByUser","isRegexEditedByUser","isAlbumFetched","isValid","isMarkedAsPlaying","isSkipped","isReplaying"],"additionalProperties":{}},"metadata":{"type":"object","properties":{"label":{"type":"string"},"startTimestamp":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"albumMbId":{"type":"string"},"albumUrl":{"type":"string"},"artistUrl":{"type":"string"},"notificationId":{"type":"string"},"trackArtUrl":{"type":"string"},"trackUrl":{"type":"string"},"userPlayCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"userloved":{"type":"boolean"}},"required":["label","startTimestamp"],"additionalProperties":{}},"connectorLabel":{"type":"string"}},"required":["controllerTabId","connector","parsed","processed","noRegex","flags","metadata"],"additionalProperties":false}},"currentlyPlaying":{"type":"boolean"}},"required":["song"],"additionalProperties":false}},"required":["eventName","data"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success"}}}},"/api/listenbrainz":{"post":{"summary":"Accept a Listenbrainz Scrobble (Slug)","tags":["Listenbrainz Ingress"],"parameters":[],"description":"Accepts the standard Listenbrainz `submit-listens` payload using a custom`slug`\n\nEX `slug=myCoolSlug` => `submit-listens` payload to `/api/listenbrainz/myCoolSlug`","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"listen_type":{"type":"string","enum":["single","playing_now","import"]},"payload":{"type":"array","items":{"type":"object","properties":{"listened_at":{"type":"number"},"track_metadata":{"type":"object","properties":{"artist_name":{"type":"string"},"track_name":{"type":"string"},"release_name":{"type":"string"},"additional_info":{"type":"object","properties":{"artist_mbids":{"type":"array","items":{"type":"string"}},"release_mbid":{"type":"string"},"release_group_mbid":{"type":"string"},"recording_mbid":{"type":"string"},"submission_client":{"type":"string"},"submission_client_version":{"type":"string"},"spotify_id":{"type":"string"},"isrc":{"type":"string"},"media_player":{"type":"string"},"media_player_version":{"type":"string"},"music_service":{"type":"string"},"music_service_name":{"type":"string"},"origin_url":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"duration":{"type":"number"},"duration_ms":{"type":"number"},"duration_played":{"type":"number"},"track_mbid":{"type":"string"},"work_mbids":{"type":"array","items":{"type":"string"}},"release_artist_name":{"type":"string"},"release_artist_names":{"type":"array","items":{"type":"string"}},"spotify_album_id":{"type":"string"},"spotify_album_artist_ids":{"type":"array","items":{"type":"string"}},"spotify_artist_ids":{"type":"array","items":{"type":"string"}},"artist_names":{"type":"array","items":{"type":"string"}},"albumartist":{"type":"string"},"tracknumber":{"type":"number"},"position_ms":{"description":"The millisecond position of the Player reporting Now Playing information.\n\n(Currently) custom field not officially supported by LZ. Name is subject to change if/when standardized.","type":"number"}},"additionalProperties":false},"mbid_mapping":{"type":"object","properties":{"recording_name":{"type":"string"},"artist_mbids":{"type":"array","items":{"type":"string"}},"artists":{"type":"array","items":{"type":"object","properties":{"artist_credit_name":{"type":"string"},"artist_mbid":{"type":"string"},"join_phrase":{"type":"string"}},"required":["artist_credit_name","artist_mbid","join_phrase"],"additionalProperties":false}},"caa_id":{"type":"number"},"caa_release_mbid":{"type":"string"},"recording_mbid":{"type":"string"},"release_mbid":{"type":"string"}},"additionalProperties":false}},"required":["artist_name","track_name"],"additionalProperties":false}},"required":["track_metadata"],"additionalProperties":false}}},"required":["listen_type","payload"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success"}}}},"/1/submit-listens":{"post":{"summary":"Accept a Listenbrainz Scrobble (Standard)","tags":["Listenbrainz Ingress"],"parameters":[],"description":"Accepts the standard Listenbrainz `submit-listens` payload at this endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"listen_type":{"type":"string","enum":["single","playing_now","import"]},"payload":{"type":"array","items":{"type":"object","properties":{"listened_at":{"type":"number"},"track_metadata":{"type":"object","properties":{"artist_name":{"type":"string"},"track_name":{"type":"string"},"release_name":{"type":"string"},"additional_info":{"type":"object","properties":{"artist_mbids":{"type":"array","items":{"type":"string"}},"release_mbid":{"type":"string"},"release_group_mbid":{"type":"string"},"recording_mbid":{"type":"string"},"submission_client":{"type":"string"},"submission_client_version":{"type":"string"},"spotify_id":{"type":"string"},"isrc":{"type":"string"},"media_player":{"type":"string"},"media_player_version":{"type":"string"},"music_service":{"type":"string"},"music_service_name":{"type":"string"},"origin_url":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"duration":{"type":"number"},"duration_ms":{"type":"number"},"duration_played":{"type":"number"},"track_mbid":{"type":"string"},"work_mbids":{"type":"array","items":{"type":"string"}},"release_artist_name":{"type":"string"},"release_artist_names":{"type":"array","items":{"type":"string"}},"spotify_album_id":{"type":"string"},"spotify_album_artist_ids":{"type":"array","items":{"type":"string"}},"spotify_artist_ids":{"type":"array","items":{"type":"string"}},"artist_names":{"type":"array","items":{"type":"string"}},"albumartist":{"type":"string"},"tracknumber":{"type":"number"},"position_ms":{"description":"The millisecond position of the Player reporting Now Playing information.\n\n(Currently) custom field not officially supported by LZ. Name is subject to change if/when standardized.","type":"number"}},"additionalProperties":false},"mbid_mapping":{"type":"object","properties":{"recording_name":{"type":"string"},"artist_mbids":{"type":"array","items":{"type":"string"}},"artists":{"type":"array","items":{"type":"object","properties":{"artist_credit_name":{"type":"string"},"artist_mbid":{"type":"string"},"join_phrase":{"type":"string"}},"required":["artist_credit_name","artist_mbid","join_phrase"],"additionalProperties":false}},"caa_id":{"type":"number"},"caa_release_mbid":{"type":"string"},"recording_mbid":{"type":"string"},"release_mbid":{"type":"string"}},"additionalProperties":false}},"required":["artist_name","track_name"],"additionalProperties":false}},"required":["track_metadata"],"additionalProperties":false}}},"required":["listen_type","payload"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success"}}}},"/1/user/{username}/playing-now":{"get":{"summary":"Get Playing Now","tags":["Listenbrainz Ingress"],"parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"}}],"description":"Tries to match username with the username set in the config of an LZ Endpoint Source.\n\nIf no match then returns Playing Now for the first LZ Endpoint configured.","responses":{"200":{"description":"Success"}}}},"/1/validate-token":{"get":{"summary":"Validate Token","tags":["Listenbrainz Ingress"],"parameters":[],"description":"Always returns valid as long as any endpointlz source is configured.\n\nFor `username` in the response it will return the Source `config.data.username` or fallback to the Source's `name` or fallback to `Multi-Scrobbler` if no valid Sources.","responses":{"200":{"description":"Success"}}}},"/api/lastfm":{"post":{"summary":"Accept a Last.fm Scrobble (Slug)","tags":["Lastfm Ingress"],"parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string"}}],"description":"Accepts a standard Last.fm `track.scrobble` payload using a custom `slug`\n        \n        EX `slug=myCoolSlug` => `track.scrobble` to `/api/lastfm/myCoolSlug`","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"anyOf":[{"type":"object","properties":{"method":{"type":"string","const":"track.scrobble"},"artist":{"type":"string"},"track":{"type":"string"},"album":{"type":"string"},"albumArtist":{"type":"string"},"mbid":{"type":"string"},"duration":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"sk":{"type":"string"},"api_key":{"type":"string"},"timestamp":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["method","artist","track","timestamp"],"additionalProperties":false,"title":"Single Scrobble"},{"type":"object","properties":{"method":{"type":"string","const":"track.scrobble"},"artist":{"type":"array","items":{"type":"string"}},"track":{"type":"array","items":{"type":"string"}},"album":{"type":"array","items":{"type":"string"}},"albumArtist":{"type":"array","items":{"type":"string"}},"mbid":{"type":"array","items":{"type":"string"}},"duration":{"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"sk":{"type":"string"},"api_key":{"type":"string"},"timestamp":{"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}},"required":["method","artist","track","timestamp"],"additionalProperties":false,"title":"Bulk Scrobbles"}],"title":"Single or Bulk Scrobble"},{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"track.updateNowPlaying"},"artist":{"type":"string"},"track":{"type":"string"},"album":{"type":"string"},"albumArtist":{"type":"string"},"mbid":{"type":"string"},"duration":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"sk":{"type":"string"},"api_key":{"type":"string"}},"required":["method","artist","track"],"additionalProperties":false,"title":"Update Now Playing"},{"type":"object","properties":{"method":{"type":"string","const":"auth.getMobileSession"},"username":{"type":"string"},"password":{"type":"string"},"api_key":{"type":"string"}},"required":["method"],"additionalProperties":false,"title":"Get Mobile Auth Session"}],"title":"Update Now Playing or Mobile Auth Session"}]}}}},"responses":{"200":{"description":"Success"}}}},"/2.0/":{"post":{"summary":"Accept a Last.fm Scrobble (Standard)","tags":["Lastfm Ingress"],"parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string"}}],"description":"Accepts the standard Last.fm `track.scrobble` payload at this endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"anyOf":[{"type":"object","properties":{"method":{"type":"string","const":"track.scrobble"},"artist":{"type":"string"},"track":{"type":"string"},"album":{"type":"string"},"albumArtist":{"type":"string"},"mbid":{"type":"string"},"duration":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"sk":{"type":"string"},"api_key":{"type":"string"},"timestamp":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["method","artist","track","timestamp"],"additionalProperties":false,"title":"Single Scrobble"},{"type":"object","properties":{"method":{"type":"string","const":"track.scrobble"},"artist":{"type":"array","items":{"type":"string"}},"track":{"type":"array","items":{"type":"string"}},"album":{"type":"array","items":{"type":"string"}},"albumArtist":{"type":"array","items":{"type":"string"}},"mbid":{"type":"array","items":{"type":"string"}},"duration":{"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"sk":{"type":"string"},"api_key":{"type":"string"},"timestamp":{"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}},"required":["method","artist","track","timestamp"],"additionalProperties":false,"title":"Bulk Scrobbles"}],"title":"Single or Bulk Scrobble"},{"oneOf":[{"type":"object","properties":{"method":{"type":"string","const":"track.updateNowPlaying"},"artist":{"type":"string"},"track":{"type":"string"},"album":{"type":"string"},"albumArtist":{"type":"string"},"mbid":{"type":"string"},"duration":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"sk":{"type":"string"},"api_key":{"type":"string"}},"required":["method","artist","track"],"additionalProperties":false,"title":"Update Now Playing"},{"type":"object","properties":{"method":{"type":"string","const":"auth.getMobileSession"},"username":{"type":"string"},"password":{"type":"string"},"api_key":{"type":"string"}},"required":["method"],"additionalProperties":false,"title":"Get Mobile Auth Session"}],"title":"Update Now Playing or Mobile Auth Session"}]}}}},"responses":{"200":{"description":"Success"}}}},"/api/components/{id}/auth":{"get":{"summary":"Get Source/Client Auth URL","tags":["Source/Client"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"}}},"post":{"summary":"Test Source/Client Authentication","tags":["Source/Client"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"}}}},".{callback}":{"get":{"summary":"Get resource","tags":["default"],"parameters":[],"responses":{"200":{"description":"Success"}}}},"/api/components":{"get":{"summary":"Get All Sources/Clients","tags":["Source/Client"],"parameters":[],"responses":{"200":{"description":"Success"}}}},"/api/components/{id}/players":{"get":{"summary":"Get Source/Client Players","tags":["Source/Client"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"}}}},"/api/components/{id}/players/{platformId}":{"get":{"summary":"Get Specific Source/Client Player","tags":["Source/Client"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"platformId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"}}}},"/api/components/{id}":{"get":{"summary":"Get Source/Client","tags":["Source/Client"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"}}}},"/api/components/{id}/state":{"post":{"summary":"Update Source/Client State","tags":["Source/Client"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"state":{"type":"string","enum":["stop","start","restart","ignore","monitor"]},"reason":{"type":"string"}},"required":["state"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success"}}}},"/api/components/{id}/art":{"get":{"summary":"Get External Art","tags":["Source/Client"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Fetches and returns art from the upstream/downstream external service\nNote: this is only supported by some components.","responses":{"200":{"description":"Success"}}}},"/api/components/{id}/plays":{"get":{"summary":"Get Paginated Plays","tags":["Plays"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"}}}},"/api/components/{id}/plays/{uid}":{"get":{"summary":"Get Play","tags":["Plays"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"}}},"delete":{"summary":"Delete Play","tags":["Plays"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"uid","in":"path","required":true,"schema":{"type":"string"}},{"name":"children","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Success"}}}},"/api/components/{id}/plays/{uid}/play":{"put":{"summary":"Update Play","tags":["Plays"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"track":{"type":"object","properties":{"name":{"type":"string","minLength":1},"metadata":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"name":{"type":"string","const":"musicbrainz"},"image":{"type":"string"},"id":{"type":"string"},"idType":{"type":"string","enum":["recording","release","track","artist","release-group"]}},"required":["name","id"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","enum":["spotify","youtube","jellyfin","plex","listenbrainz","rocksky","isrc"]},"image":{"type":"string"},"id":{"type":"string"},"idType":{"type":"string"}},"required":["name","id"],"additionalProperties":false}]}},"image":{"type":"string"}},"required":["name"],"additionalProperties":false},"artists":{"minItems":1,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"metadata":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"name":{"type":"string","const":"musicbrainz"},"image":{"type":"string"},"id":{"type":"string"},"idType":{"type":"string","enum":["recording","release","track","artist","release-group"]}},"required":["name","id"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","enum":["spotify","youtube","jellyfin","plex","listenbrainz","rocksky","isrc"]},"image":{"type":"string"},"id":{"type":"string"},"idType":{"type":"string"}},"required":["name","id"],"additionalProperties":false}]}},"image":{"type":"string"}},"required":["name"],"additionalProperties":false}},"albumArtists":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"metadata":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"name":{"type":"string","const":"musicbrainz"},"image":{"type":"string"},"id":{"type":"string"},"idType":{"type":"string","enum":["recording","release","track","artist","release-group"]}},"required":["name","id"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","enum":["spotify","youtube","jellyfin","plex","listenbrainz","rocksky","isrc"]},"image":{"type":"string"},"id":{"type":"string"},"idType":{"type":"string"}},"required":["name","id"],"additionalProperties":false}]}},"image":{"type":"string"}},"required":["name"],"additionalProperties":false}},"album":{"type":"object","properties":{"name":{"type":"string"},"metadata":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"name":{"type":"string","const":"musicbrainz"},"image":{"type":"string"},"id":{"type":"string"},"idType":{"type":"string","enum":["recording","release","track","artist","release-group"]}},"required":["name","id"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","enum":["spotify","youtube","jellyfin","plex","listenbrainz","rocksky","isrc"]},"image":{"type":"string"},"id":{"type":"string"},"idType":{"type":"string"}},"required":["name","id"],"additionalProperties":false}]}},"image":{"type":"string"}},"required":["name"],"additionalProperties":false},"duration":{"type":"number","minimum":0},"isrc":{"type":"string"},"meta":{"type":"object","properties":{"brainz":{"type":"object","properties":{"trackNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"additionalProperties":false}},"additionalProperties":false},"playDate":{"type":"string"},"listenedFor":{"type":"number","minimum":0}},"required":["track","artists"],"additionalProperties":false},"meta":{"type":"object","properties":{"source":{"type":"string"},"musicService":{"type":"string"},"trackId":{"type":"string"},"parsedFrom":{"type":"string","enum":["backlog","now playing","player","history","ingress"]},"url":{"type":"object","properties":{"web":{"type":"string"},"origin":{"type":"string"}},"additionalProperties":{}}},"additionalProperties":{}}},"required":["data","meta"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success"}}}},"/api/components/{id}/plays/queue":{"post":{"summary":"Requeue Bulk Plays","tags":["Plays"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"context":{"type":"object","properties":{"transform":{"type":"boolean"},"dupeCheck":{"type":"boolean"},"useCache":{"type":"boolean"},"reason":{"type":"string"},"isRetry":{"type":"boolean"}},"additionalProperties":false},"filters":{"type":"object","properties":{},"additionalProperties":{}}},"required":["filters"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success"}}}},"/api/components/{id}/plays/{uid}/queue":{"post":{"summary":"Requeue a Play","tags":["Plays"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"transform":{"type":"boolean"},"dupeCheck":{"type":"boolean"},"useCache":{"type":"boolean"},"reason":{"type":"string"},"isRetry":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success"}}},"delete":{"summary":"Dequeue a Play","tags":["Plays"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"}}}},"/api/components/{id}/plays/{uid}/state":{"post":{"summary":"Mark Play as Done","tags":["Plays"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"state":{"type":"string","enum":["discarded"]},"reason":{"type":"string"}},"required":["state"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success"}}}},"/api/cache/{cacheType}":{"delete":{"summary":"Delete Cache By Type","tags":["Cache"],"parameters":[{"name":"cacheType","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"}}}},"/api/components/{id}/plays/historical":{"post":{"summary":"Hydrate Historical Plays","tags":["Plays"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"If the Source/Client supports Historical Play capabilities, this route requests a manual hydration of historical Plays","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"description":"Use `full` to initiate a complete sync of all history or `recent` to sync the last ~100 plays.","type":"string","enum":["full","recent"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success"}}}},"/api/metadata/search/tracks":{"get":{"summary":"Get Track Metadata from Providers","tags":["Metadata"],"parameters":[{"name":"track","in":"query","required":true,"schema":{"anyOf":[{"type":"string","pattern":"^(reid|tid|mbid|isrc|spotify):[\\s\\S]{0,}$"},{"type":"string"}],"description":"the track name or prefix:id to search for"}},{"name":"artists","in":"query","required":false,"schema":{"description":"a list of plain artist strings associated with the track","type":"array","items":{"type":"string"}}},{"name":"album","in":"query","required":false,"schema":{"description":"a plain album name string associated with the track","type":"string"}}],"description":"Gets track results from all metadata providers. Send the header `Accept: application/x-ndjson` to get results as newline-delimited JSON, one line per provider as soon as it finishes: `{\"type\":\"result\",\"service\":\"...\",\"data\":[...]}` or `{\"type\":\"error\",\"service\":\"...\",\"error\":{...}}`, followed by a final `{\"type\":\"done\"}` line.","responses":{"200":{"description":"Success"}}},"post":{"summary":"Get Track Metadata from Providers (Advanced)","tags":["Metadata"],"parameters":[],"description":"Gets track results from all metadata providers using Credits with metadata. Send the header `Accept: application/x-ndjson` to get results as newline-delimited JSON, one line per provider as soon as it finishes: `{\"type\":\"result\",\"service\":\"...\",\"data\":[...]}` or `{\"type\":\"error\",\"service\":\"...\",\"error\":{...}}`, followed by a final `{\"type\":\"done\"}` line.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"track":{"description":"a track credit to search by","type":"object","properties":{"name":{"type":"string"},"metadata":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"name":{"type":"string","const":"musicbrainz"},"id":{"type":"string"},"idType":{"type":"string","enum":["recording","release","track","artist","release-group"]}},"required":["name","id"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","enum":["spotify","youtube","jellyfin","plex","listenbrainz","rocksky","isrc"]},"id":{"type":"string"},"idType":{"type":"string"}},"required":["name","id"],"additionalProperties":false}]}}},"required":["name"],"additionalProperties":false},"artists":{"description":"a list of artist Credits","type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"metadata":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"name":{"type":"string","const":"musicbrainz"},"id":{"type":"string"},"idType":{"type":"string","enum":["recording","release","track","artist","release-group"]}},"required":["name","id"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","enum":["spotify","youtube","jellyfin","plex","listenbrainz","rocksky","isrc"]},"id":{"type":"string"},"idType":{"type":"string"}},"required":["name","id"],"additionalProperties":false}]}}},"required":["name"],"additionalProperties":false}},"album":{"description":"an album credit","type":"object","properties":{"name":{"type":"string"},"metadata":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"name":{"type":"string","const":"musicbrainz"},"id":{"type":"string"},"idType":{"type":"string","enum":["recording","release","track","artist","release-group"]}},"required":["name","id"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","enum":["spotify","youtube","jellyfin","plex","listenbrainz","rocksky","isrc"]},"id":{"type":"string"},"idType":{"type":"string"}},"required":["name","id"],"additionalProperties":false}]}}},"required":["name"],"additionalProperties":false}},"required":["track"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success"}}}},"/api/metadata/search/albums":{"get":{"summary":"Get Album Metadata from Providers","tags":["Metadata"],"parameters":[{"name":"album","in":"query","required":true,"schema":{"anyOf":[{"type":"string","pattern":"^(rid|rgid|mbid|spotify):[\\s\\S]{0,}$"},{"type":"string"}],"description":"the album name or prefix:id to search for"}},{"name":"artists","in":"query","required":false,"schema":{"description":"a list of plain artist strings associated with the album","type":"array","items":{"type":"string"}}}],"description":"Gets album results from all metadata providers. Send the header `Accept: application/x-ndjson` to get results as newline-delimited JSON, one line per provider as soon as it finishes: `{\"type\":\"result\",\"service\":\"...\",\"data\":[...]}` or `{\"type\":\"error\",\"service\":\"...\",\"error\":{...}}`, followed by a final `{\"type\":\"done\"}` line.","responses":{"200":{"description":"Success"}}},"post":{"summary":"Get Album Metadata from Providers (Advanced)","tags":["Metadata"],"parameters":[],"description":"Gets album results from all metadata providers using Credits with metadata. Send the header `Accept: application/x-ndjson` to get results as newline-delimited JSON, one line per provider as soon as it finishes: `{\"type\":\"result\",\"service\":\"...\",\"data\":[...]}` or `{\"type\":\"error\",\"service\":\"...\",\"error\":{...}}`, followed by a final `{\"type\":\"done\"}` line.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"artists":{"description":"a list of artist Credits","type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"metadata":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"name":{"type":"string","const":"musicbrainz"},"id":{"type":"string"},"idType":{"type":"string","enum":["recording","release","track","artist","release-group"]}},"required":["name","id"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","enum":["spotify","youtube","jellyfin","plex","listenbrainz","rocksky","isrc"]},"id":{"type":"string"},"idType":{"type":"string"}},"required":["name","id"],"additionalProperties":false}]}}},"required":["name"],"additionalProperties":false}},"album":{"description":"an album credit","type":"object","properties":{"name":{"type":"string"},"metadata":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"name":{"type":"string","const":"musicbrainz"},"id":{"type":"string"},"idType":{"type":"string","enum":["recording","release","track","artist","release-group"]}},"required":["name","id"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","enum":["spotify","youtube","jellyfin","plex","listenbrainz","rocksky","isrc"]},"id":{"type":"string"},"idType":{"type":"string"}},"required":["name","id"],"additionalProperties":false}]}}},"required":["name"],"additionalProperties":false}},"required":["album"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success"}}}},"/api/metadata/search/artists":{"get":{"summary":"Get Artist Metadata from Providers","tags":["Metadata"],"parameters":[{"name":"artist","in":"query","required":true,"schema":{"anyOf":[{"type":"string","pattern":"^(arid|spotify):[\\s\\S]{0,}$"},{"type":"string"}],"description":"a plain artist name or prefix:id to search for"}}],"description":"Gets artist results from all metadata providers. Send the header `Accept: application/x-ndjson` to get results as newline-delimited JSON, one line per provider as soon as it finishes: `{\"type\":\"result\",\"service\":\"...\",\"data\":[...]}` or `{\"type\":\"error\",\"service\":\"...\",\"error\":{...}}`, followed by a final `{\"type\":\"done\"}` line.","responses":{"200":{"description":"Success"}}},"post":{"summary":"Get Artist Metadata from Providers (Advanced)","tags":["Metadata"],"parameters":[],"description":"Gets artist results from all metadata providers using Credits with metadata. Send the header `Accept: application/x-ndjson` to get results as newline-delimited JSON, one line per provider as soon as it finishes: `{\"type\":\"result\",\"service\":\"...\",\"data\":[...]}` or `{\"type\":\"error\",\"service\":\"...\",\"error\":{...}}`, followed by a final `{\"type\":\"done\"}` line.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"artists":{"description":"a list of artist Credits","type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"metadata":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"name":{"type":"string","const":"musicbrainz"},"id":{"type":"string"},"idType":{"type":"string","enum":["recording","release","track","artist","release-group"]}},"required":["name","id"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","enum":["spotify","youtube","jellyfin","plex","listenbrainz","rocksky","isrc"]},"id":{"type":"string"},"idType":{"type":"string"}},"required":["name","id"],"additionalProperties":false}]}}},"required":["name"],"additionalProperties":false}}},"required":["artists"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success"}}}},"/api/health":{"get":{"summary":"Get health","tags":["App Meta"],"parameters":[{"name":"type","in":"query","required":false,"schema":{"description":"Only report status for components of this type","type":"string"}},{"name":"name","in":"query","required":false,"schema":{"description":"Only report status for the component with this name","type":"string"}}],"responses":{"200":{"description":"Success"}}}},"/api/metrics":{"get":{"summary":"Get metrics","tags":["App Meta"],"parameters":[],"responses":{"200":{"description":"Success"}}}},"/api/version":{"get":{"summary":"Get version","tags":["App Meta"],"parameters":[],"responses":{"200":{"description":"Success"}}}}}}