{
    "openapi": "3.0.3",
    "info": {
        "title": "MusicAPI.com",
        "version": "1.0.1"
    },
    "servers": [
        {
            "url": "https://api.musicapi.com"
        }
    ],
    "paths": {
        "/app/integrations/byUniqueId/{uniqueId}": {
            "get": {
                "security": [
                    {
                        "TokenAuth": []
                    },
                    {
                        "BasicAuth": []
                    }
                ],
                "summary": "Get auth flow status",
                "tags": [
                    "User"
                ],
                "description": "Get status of user authentication, useful for polling when authenticating user.",
                "parameters": [
                    {
                        "in": "path",
                        "name": "uniqueId",
                        "schema": {
                            "type": "string"
                        },
                        "required": true,
                        "description": "Unique UUID_V4 that was passed to authentication url"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AuthByUniqueIdResponse"
                                }
                            }
                        }
                    }
                },
                "operationId": "get-auth-flow-status"
            }
        },
        "/public/search": {
            "post": {
                "security": [
                    {
                        "TokenAuth": []
                    },
                    {
                        "BasicAuth": []
                    }
                ],
                "summary": "Search",
                "tags": [
                    "Public"
                ],
                "description": "[Click here to check which services support returning ISRC](/docs/api-basics/supported-features)\n\n\nSearch Endpoint allows you to search for\n\n- tracks\n- albums\n- playlists\n\nin any of the music service we support.",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PublicSearchRequest"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicSearchResponse"
                                }
                            }
                        }
                    }
                },
                "operationId": "search"
            }
        },
        "/public/search/introspection": {
            "get": {
                "security": [
                    {
                        "TokenAuth": []
                    },
                    {
                        "BasicAuth": []
                    }
                ],
                "summary": "Search Introspection",
                "tags": [
                    "Public"
                ],
                "description": "Allows you to fetch all different enums needed for sending API requests.",
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SearchIntrospectionResponse"
                                }
                            }
                        }
                    }
                },
                "operationId": "search-introspection"
            }
        },
        "/public/inspect/url": {
            "post": {
                "security": [
                    {
                        "TokenAuth": []
                    },
                    {
                        "BasicAuth": []
                    }
                ],
                "tags": [
                    "Public"
                ],
                "summary": "Inspect",
                "description": "[Click here to check which services support returning ISRC](/docs/api-basics/supported-features)\n\n\nInspect endpoint allows you fetch the metadata of music service URL.\nYou can pass any URL from music service (eg. `https://tidal.com/browse/track/131696293`) and the API will\nreturn you information about what it points at.\n\nInspect API supports: \n- albums\n- tracks\n- playlists.",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "url": {
                                        "type": "string",
                                        "example": "https://open.spotify.com/track/5aszL9hl6SBzFNsOvw8u8w"
                                    }
                                },
                                "required": [
                                    "url"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/InspectResponse"
                                }
                            }
                        }
                    }
                },
                "operationId": "inspect"
            }
        },
        "/public/inspect/playlistItems": {
            "post": {
                "security": [
                    {
                        "TokenAuth": []
                    },
                    {
                        "BasicAuth": []
                    }
                ],
                "tags": [
                    "Public"
                ],
                "summary": "Inspect Playlist Items",
                "description": "This endpoint allows you to fetch the tracks of a playlist from a music service without user authentication.\nYou need to provide the `playlistId` (which can be extracted from a playlist URL) and the `serviceId` of the music service.\n\nThe response includes paginated track results. To fetch subsequent pages, pass the `nextParam` value from the response as a query parameter in the next request.\n\nSupported services: Spotify, Apple Music, Deezer, YouTube, YouTube Music, SoundCloud, Tidal, Amazon Music, Napster, Pandora, Qobuz.",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PlaylistItemsRequest"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PlaylistItemsResponse"
                                }
                            }
                        }
                    }
                },
                "operationId": "inspect-playlist-items"
            }
        },
        "/public/embed/url": {
            "post": {
                "security": [
                    {
                        "TokenAuth": []
                    },
                    {
                        "BasicAuth": []
                    }
                ],
                "tags": [
                    "Public"
                ],
                "summary": "Embed player",
                "description": "This endpoint allows you to send a request with a share URL to any track, artist, or album from music service, and it will generate an embed player code (an `iframe`) for that resource, enabling easy embedding of the music player on a website or application.\n\nThis endpoint, in addition to the iframe will return available sizes of that music player, so if you would like to change the default size, you need to insert the selected height in two places: into the `height` property of a returned iframe as well as in the URL height param within that iframe `src` property.",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "url": {
                                        "type": "string",
                                        "example": "https://open.spotify.com/track/0pqnGHJpmpxLKifKRmU6WP",
                                        "description": "URL to track, album or artist of music service"
                                    }
                                },
                                "required": [
                                    "url"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EmbedPlayerResponse"
                                }
                            }
                        }
                    }
                },
                "operationId": "embed-player"
            }
        },
        "/api/{userUUID}/users/profile": {
            "get": {
                "summary": "Me",
                "tags": [
                    "User"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    }
                ],
                "description": "[Click here to check which services support returning user information](/docs/api-basics/supported-features)\n\n\nThis endpoint returns information about user that was fetched from Music Service.",
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/UserResponse"
                                }
                            }
                        }
                    }
                },
                "operationId": "me"
            }
        },
        "/api/{userUUID}/playlists": {
            "get": {
                "summary": "Get user's playlists",
                "description": "This endpoint fetches owned & followed playlists from Music Service. As Amazon & Boomplay return data in separate endpoints, we combine the data from 2 sources (owned & liked playlist). So don't expect proper sorting for those.",
                "tags": [
                    "Playlists"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/NextParam"
                    },
                    {
                        "$ref": "#/components/parameters/LimitParam"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PlaylistsResponse"
                                }
                            }
                        }
                    }
                },
                "operationId": "get-users-playlists"
            },
            "post": {
                "summary": "Create playlist",
                "description": "This endpoint creates playlist on Music Service.",
                "tags": [
                    "Playlists"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PlaylistCreationRequest"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Playlist"
                                }
                            }
                        }
                    }
                },
                "operationId": "create-playlist"
            }
        },
        "/api/{userUUID}/playlists/{playlistId}": {
            "get": {
                "summary": "Get playlist",
                "description": "This endpoint fetches specified playlist and returns information about it.",
                "tags": [
                    "Playlists"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/PlaylistId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Playlist"
                                }
                            }
                        }
                    }
                },
                "operationId": "get-playlist"
            },
            "put": {
                "summary": "Update playlist",
                "description": "Change a playlist's name, description and public/private state (if available). The user must own the playlist.",
                "tags": [
                    "Playlists"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/PlaylistId"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PlaylistUpdateRequest"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "ok"
                    }
                },
                "operationId": "update-playlist"
            },
            "delete": {
                "summary": "Remove playlist",
                "description": "This endpoint removes a playlist.",
                "tags": [
                    "Playlists"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/PlaylistId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ok"
                    }
                },
                "operationId": "remove-playlist"
            }
        },
        "/api/{userUUID}/playlists/{playlistId}/items": {
            "get": {
                "summary": "Get playlist items",
                "description": "This endpoint fetches playlist items from Music Service.",
                "tags": [
                    "Playlists"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/NextParam"
                    },
                    {
                        "$ref": "#/components/parameters/LimitParam"
                    },
                    {
                        "$ref": "#/components/parameters/PlaylistId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/TracksResponse"
                                }
                            }
                        }
                    }
                },
                "operationId": "get-playlist-items"
            },
            "post": {
                "summary": "Add items to playlist",
                "description": "Add items to a user's playlist.",
                "tags": [
                    "Playlists"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/PlaylistId"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "itemIds": {
                                        "$ref": "#/components/schemas/TrackIds"
                                    }
                                },
                                "required": [
                                    "itemIds"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "ok"
                    }
                },
                "operationId": "add-items-to-playlist"
            },
            "put": {
                "summary": "Update playlist items",
                "description": "[Click here to check which services support updating playlist items](/docs/api-basics/supported-features)\n\n\nModify the order of items within a user's playlist based on the parameters provided in the request body. The reordering process starts from the position specified by `rangeStart` and encompasses the next `rangeLength` items. The destination for these reordered items is determined by the `insertBefore` property (starts with 0). \n\nExamples: \n- To move the first two items to the end of a playlist containing 10 items, set `rangeStart` as 0, `rangeLength` to 2 and `insertBefore` as 10.\n- To move the last item to the start of the playlist containing 10 items, set `rangeStart` to 9, `rangeLength` to 1  and `insertBefore` to 0.",
                "tags": [
                    "Playlists"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/PlaylistId"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "rangeStart": {
                                        "type": "number",
                                        "example": 1,
                                        "description": "The position of the first item to be reordered"
                                    },
                                    "rangeLength": {
                                        "type": "number",
                                        "example": 3,
                                        "description": "The amount of items to be reordered"
                                    },
                                    "insertBefore": {
                                        "type": "number",
                                        "example": 10,
                                        "description": "The position where the items should be inserted"
                                    }
                                },
                                "required": [
                                    "rangeStart",
                                    "rangeLength",
                                    "insertBefore"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "ok"
                    }
                },
                "operationId": "update-playlist-items"
            },
            "delete": {
                "summary": "Remove playlist items",
                "description": "[Click here to check which services support removing playlist items](/docs/api-basics/supported-features)\n\n\nRemove items from a user's playlist.",
                "tags": [
                    "Playlists"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/PlaylistId"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "entryIds": {
                                        "$ref": "#/components/schemas/EntryIds"
                                    }
                                },
                                "required": [
                                    "entryIds"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "ok"
                    }
                },
                "operationId": "remove-playlist-items"
            }
        },
        "/api/{userUUID}/albums": {
            "get": {
                "summary": "Get user's liked albums",
                "description": "This endpoint fetches liked albums from Music Service.",
                "tags": [
                    "Albums"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/NextParam"
                    },
                    {
                        "$ref": "#/components/parameters/LimitParam"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AlbumsResponse"
                                }
                            }
                        }
                    }
                },
                "operationId": "get-users-liked-albums"
            },
            "post": {
                "summary": "Add album to user's library",
                "description": "This endpoint saves album to the current user's library on Music Service.",
                "tags": [
                    "Albums"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/AddAlbumRequest"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "ok"
                    }
                },
                "operationId": "add-album-to-users-library"
            }
        },
        "/api/{userUUID}/albums/{albumId}": {
            "get": {
                "summary": "Get album",
                "description": "This endpoint fetches specified album and returns information about it.",
                "tags": [
                    "Albums"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/AlbumId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Album"
                                }
                            }
                        }
                    }
                },
                "operationId": "get-album"
            },
            "delete": {
                "summary": "Remove album from user's library",
                "description": "This endpoint removes an album from user's library on Music Service.",
                "tags": [
                    "Albums"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/AlbumId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ok"
                    }
                },
                "operationId": "remove-album-from-users-library"
            }
        },
        "/api/{userUUID}/albums/{albumId}/items": {
            "get": {
                "summary": "Get album tracks",
                "description": "This endpoint fetches album's tracks from Music Service.",
                "tags": [
                    "Albums"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/NextParam"
                    },
                    {
                        "$ref": "#/components/parameters/LimitParam"
                    },
                    {
                        "$ref": "#/components/parameters/AlbumId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/TracksResponse"
                                }
                            }
                        }
                    }
                },
                "operationId": "get-album-tracks"
            }
        },
        "/api/{userUUID}/artists": {
            "get": {
                "summary": "Get user's liked artists",
                "description": "This endpoint fetches liked artists from Music Service.",
                "tags": [
                    "Artists"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/NextParam"
                    },
                    {
                        "$ref": "#/components/parameters/LimitParam"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ArtistsResponse"
                                }
                            }
                        }
                    }
                },
                "operationId": "get-users-liked-artists"
            },
            "post": {
                "summary": "Add artist to user's library",
                "description": "This endpoint saves artist to the current user's library on Music Service.",
                "tags": [
                    "Artists"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/AddArtistRequest"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "ok"
                    }
                },
                "operationId": "add-artist-to-users-library"
            }
        },
        "/api/{userUUID}/artists/{artistId}": {
            "get": {
                "summary": "Get artist",
                "description": "This endpoint fetches specified artist and returns information about it.",
                "tags": [
                    "Artists"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/ArtistId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Artist"
                                }
                            }
                        }
                    }
                },
                "operationId": "get-artist"
            },
            "delete": {
                "summary": "Remove artist from user's library",
                "description": "This endpoint removes an artist from user's library on Music Service.",
                "tags": [
                    "Artists"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/ArtistId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ok"
                    }
                },
                "operationId": "remove-artist-from-users-library"
            }
        },
        "/api/{userUUID}/liked/tracks": {
            "get": {
                "summary": "Get liked tracks",
                "description": "[Click here to check which services support returning ISRC and preview url](/docs/api-basics/supported-features)\n\n\nThis endpoint fetches tracks liked by the user.",
                "tags": [
                    "Liked"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/NextParam"
                    },
                    {
                        "$ref": "#/components/parameters/LimitParam"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/TracksResponse"
                                }
                            }
                        }
                    }
                },
                "operationId": "get-liked-tracks"
            },
            "post": {
                "summary": "Add tracks to library",
                "description": "[Click here to check which services support adding tracks to user's library](/docs/api-basics/supported-features)\n\n\nThis endpoint saves tracks to the current user's library on Music Service.",
                "tags": [
                    "Liked"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "itemIds": {
                                        "$ref": "#/components/schemas/TrackIds"
                                    }
                                },
                                "required": [
                                    "itemIds"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "ok"
                    }
                },
                "operationId": "add-tracks-to-library"
            },
            "delete": {
                "summary": "Remove tracks from library",
                "description": "[Click here to check which services support removing tracks from library](/docs/api-basics/supported-features)\n\n\nRemove tracks from a user's library.",
                "tags": [
                    "Liked"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "entryIds": {
                                        "$ref": "#/components/schemas/EntryIds"
                                    }
                                },
                                "required": [
                                    "entryIds"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "ok"
                    }
                },
                "operationId": "remove-tracks-from-library"
            }
        },
        "/api/{userUUID}/search": {
            "post": {
                "summary": "Search tracks, albums and artists",
                "description": "[Click here to check which services support searching by ISRC](/docs/api-basics/supported-features)\n\n\nSearch Endpoint allows you to search for\n\n- tracks\n- albums\n- artists",
                "tags": [
                    "Search"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/UserUUIDParam"
                    },
                    {
                        "$ref": "#/components/parameters/NextParam"
                    },
                    {
                        "$ref": "#/components/parameters/LimitParam"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "type": {
                                        "type": "string",
                                        "example": "track",
                                        "enum": [
                                            "track",
                                            "album",
                                            "artist"
                                        ]
                                    },
                                    "track": {
                                        "type": "string",
                                        "example": "Numb",
                                        "description": "Track title"
                                    },
                                    "artist": {
                                        "type": "string",
                                        "example": "Linkin Park",
                                        "description": "Artist name"
                                    },
                                    "album": {
                                        "type": "string",
                                        "example": "Meteora",
                                        "description": "Album title"
                                    },
                                    "isrc": {
                                        "type": "string",
                                        "example": "USWB10300474",
                                        "description": "12-digit code assigned to a unique recording of a specific track"
                                    }
                                },
                                "required": [
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "ok",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SearchResponse"
                                }
                            }
                        }
                    }
                },
                "operationId": "search-tracks-albums-and-artists"
            }
        }
    },
    "components": {
        "securitySchemes": {
            "DevTokenAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "Authorization"
            },
            "BasicAuth": {
                "type": "http",
                "scheme": "basic"
            },
            "TokenAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "Authorization"
            }
        },
        "schemas": {
            "PublicSearchRequest": {
                "type": "object",
                "properties": {
                    "track": {
                        "type": "string",
                        "example": "Bezos I"
                    },
                    "artist": {
                        "type": "string",
                        "example": "Bo Burnham"
                    },
                    "type": {
                        "type": "string",
                        "example": "track",
                        "enum": [
                            "track",
                            "playlist",
                            "album"
                        ]
                    },
                    "sources": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "example": "spotify"
                        },
                        "description": "At least one source, no upper limit (check supported music services for list of all available values for this param)"
                    }
                },
                "required": [
                    "track",
                    "sources",
                    "type"
                ]
            },
            "PublicSearchResponse": {
                "type": "object",
                "required": [
                    "tracks"
                ],
                "properties": {
                    "tracks": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "required": [
                                "source",
                                "status",
                                "data",
                                "type"
                            ],
                            "properties": {
                                "source": {
                                    "type": "string",
                                    "example": "spotify"
                                },
                                "status": {
                                    "type": "string",
                                    "example": "success"
                                },
                                "data": {
                                    "type": "object",
                                    "required": [
                                        "externalId",
                                        "name",
                                        "artistNames",
                                        "albumName",
                                        "imageUrl",
                                        "previewUrl",
                                        "isrc",
                                        "duration",
                                        "url"
                                    ],
                                    "properties": {
                                        "externalId": {
                                            "type": "string",
                                            "example": "5aszL9hl6SBzFNsOvw8u8w"
                                        },
                                        "name": {
                                            "type": "string",
                                            "example": "Bezos I"
                                        },
                                        "artistNames": {
                                            "type": "array",
                                            "items": {
                                                "type": "string",
                                                "example": "Bo Burnham"
                                            },
                                            "nullable": true
                                        },
                                        "albumName": {
                                            "type": "string",
                                            "example": "INSIDE",
                                            "nullable": true
                                        },
                                        "imageUrl": {
                                            "type": "string",
                                            "example": "https://i.scdn.co/image/ab67616d0000b27388fed14b936c38007a302413"
                                        },
                                        "previewUrl": {
                                            "type": "string",
                                            "nullable": true
                                        },
                                        "isrc": {
                                            "type": "string",
                                            "example": ""
                                        },
                                        "duration": {
                                            "type": "integer",
                                            "format": "int32",
                                            "example": "58149",
                                            "nullable": true
                                        },
                                        "url": {
                                            "type": "string",
                                            "example": "https://open.spotify.com/track/5aszL9hl6SBzFNsOvw8u8w"
                                        }
                                    }
                                },
                                "type": {
                                    "type": "string",
                                    "example": "track"
                                }
                            }
                        }
                    }
                }
            },
            "SearchIntrospectionResponse": {
                "type": "object",
                "required": [
                    "sources",
                    "authSources",
                    "types"
                ],
                "properties": {
                    "sources": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "example": "amazonMusic"
                        }
                    },
                    "authSources": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "example": "spotify"
                        }
                    },
                    "types": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "example": "track"
                        }
                    }
                }
            },
            "InspectResponse": {
                "type": "object",
                "required": [
                    "status",
                    "source",
                    "type",
                    "data"
                ],
                "properties": {
                    "status": {
                        "type": "string",
                        "example": "success"
                    },
                    "source": {
                        "type": "string",
                        "example": "spotify"
                    },
                    "type": {
                        "type": "string",
                        "example": "track"
                    },
                    "data": {
                        "type": "object",
                        "required": [
                            "externalId",
                            "name",
                            "artistNames",
                            "albumName",
                            "imageUrl",
                            "previewUrl",
                            "isrc",
                            "duration",
                            "url"
                        ],
                        "properties": {
                            "externalId": {
                                "type": "string",
                                "example": "5aszL9hl6SBzFNsOvw8u8w"
                            },
                            "name": {
                                "type": "string",
                                "example": "Bezos I"
                            },
                            "artistNames": {
                                "type": "array",
                                "items": {
                                    "type": "string",
                                    "example": "Bo Burnham"
                                },
                                "nullable": true
                            },
                            "albumName": {
                                "type": "string",
                                "example": "INSIDE"
                            },
                            "imageUrl": {
                                "type": "string",
                                "example": "https://i.scdn.co/image/ab67616d00001e0288fed14b936c38007a302413"
                            },
                            "previewUrl": {
                                "type": "string",
                                "nullable": true
                            },
                            "isrc": {
                                "type": "string",
                                "example": ""
                            },
                            "duration": {
                                "type": "number",
                                "example": "58149",
                                "nullable": true
                            },
                            "url": {
                                "type": "string",
                                "example": "https://open.spotify.com/track/5aszL9hl6SBzFNsOvw8u8w"
                            }
                        }
                    }
                }
            },
            "PlaylistItemsRequest": {
                "type": "object",
                "properties": {
                    "playlistId": {
                        "type": "string",
                        "example": "37i9dQZF1DXcBWIGoYBM5M",
                        "description": "ID of the playlist on the music service. Can be extracted from the playlist URL."
                    },
                    "serviceId": {
                        "type": "string",
                        "example": "spotify",
                        "description": "ID of the music service",
                        "enum": [
                            "spotify",
                            "appleMusic",
                            "deezer",
                            "youtube",
                            "youtubeMusic",
                            "soundCloud",
                            "tidal",
                            "amazonMusic",
                            "napster",
                            "pandora",
                            "qobuz"
                        ]
                    }
                },
                "required": [
                    "playlistId",
                    "serviceId"
                ]
            },
            "PlaylistItemsResponse": {
                "type": "object",
                "required": [
                    "status",
                    "data"
                ],
                "properties": {
                    "status": {
                        "type": "string",
                        "example": "success",
                        "enum": [
                            "success",
                            "not_found",
                            "error"
                        ]
                    },
                    "source": {
                        "type": "string",
                        "example": "spotify",
                        "description": "The music service that provided the data"
                    },
                    "data": {
                        "nullable": true,
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/TracksResponse"
                            }
                        ],
                        "description": "Paginated playlist track results. Null if the playlist was not found."
                    }
                }
            },
            "EmbedPlayerSize": {
                "type": "object",
                "required": [
                    "height",
                    "label"
                ],
                "properties": {
                    "height": {
                        "type": "number",
                        "example": "152"
                    },
                    "label": {
                        "type": "string",
                        "example": "Medium"
                    }
                }
            },
            "EmbedPlayerResponse": {
                "type": "object",
                "required": [
                    "embedCode",
                    "embedUrl",
                    "sizes",
                    "defaultSize"
                ],
                "properties": {
                    "embedCode": {
                        "type": "string",
                        "example": "<iframe title='embed-player' width='100%' height='152' src='http://localhost:4223/embed/track/28?height=152' allow='encrypted-media' style='border:none;position:relative;overflow:hidden;max-width:100%;'/>",
                        "description": "HTML iframe code used to embed music player"
                    },
                    "embedUrl": {
                        "type": "string",
                        "example": "https://api.musicapi.com/embed/track/55754?height=152",
                        "description": "URL used as the source of the iframe"
                    },
                    "sizes": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/EmbedPlayerSize"
                        },
                        "description": "Available sizes for iframe"
                    },
                    "defaultSize": {
                        "$ref": "#/components/schemas/EmbedPlayerSize"
                    }
                }
            },
            "UserResponse": {
                "type": "object",
                "required": [
                    "country",
                    "email",
                    "imageUrl",
                    "integrationUserId",
                    "name"
                ],
                "properties": {
                    "country": {
                        "type": "string",
                        "example": "PL",
                        "nullable": true
                    },
                    "email": {
                        "type": "string",
                        "example": "m@hern.as",
                        "nullable": true
                    },
                    "imageUrl": {
                        "type": "string",
                        "example": "https://scontent-ams4-1.xx.fbcdn.net/v/t1.6435-1/69587629_2638313276187374_2189734242018131968_n.jpg?stp=dst-jpg_p320x320&_nc_cat=111&ccb=1-7&_nc_sid=0c64ff&_nc_ohc=6YFaKfkcgMoAX-dpxQv&_nc_ht=scontent-ams4-1.xx&edm=AP4hL3IEAAAA&oh=00_AfA25N5sgrI6GAjnlESeXr-d362tPDj1z5QsPH8S4HdcCg&oe=6471AC21",
                        "nullable": true
                    },
                    "integrationUserId": {
                        "type": "string",
                        "example": "1176177544"
                    },
                    "name": {
                        "type": "string",
                        "example": "Michał Hernas",
                        "nullable": true
                    }
                }
            },
            "PlaylistCreationRequest": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "Viva Loca New"
                    },
                    "description": {
                        "type": "string",
                        "example": "Description of your playlist"
                    },
                    "visibility": {
                        "type": "string",
                        "example": "public",
                        "enum": [
                            "public",
                            "private"
                        ]
                    }
                },
                "required": [
                    "name"
                ]
            },
            "PlaylistUpdateRequest": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "Viva Loca New"
                    },
                    "description": {
                        "type": "string",
                        "example": "Description of your playlist"
                    },
                    "visibility": {
                        "type": "string",
                        "example": "public",
                        "enum": [
                            "public",
                            "private"
                        ]
                    }
                }
            },
            "Playlist": {
                "type": "object",
                "required": [
                    "name",
                    "id",
                    "totalItems",
                    "imageUrl",
                    "isOwner"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "Viva Playlist"
                    },
                    "id": {
                        "type": "string",
                        "example": "1"
                    },
                    "totalItems": {
                        "type": "number",
                        "example": 25,
                        "nullable": true
                    },
                    "imageUrl": {
                        "type": "string",
                        "example": "https://www.example-image.com/978263478234",
                        "nullable": true
                    },
                    "dateAdded": {
                        "type": "string",
                        "example": "2024-10-16T07:52:07.000Z",
                        "nullable": true
                    },
                    "isOwner": {
                        "type": "boolean",
                        "example": true
                    }
                }
            },
            "PlaylistsResponse": {
                "type": "object",
                "required": [
                    "results",
                    "nextParam",
                    "totalItems"
                ],
                "properties": {
                    "results": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Playlist"
                        }
                    },
                    "nextParam": {
                        "type": "string",
                        "nullable": true,
                        "example": "eyJvZmZzZXQiOjEwfQ=="
                    },
                    "totalItems": {
                        "type": "number",
                        "nullable": true,
                        "example": 25
                    }
                }
            },
            "AlbumsResponse": {
                "type": "object",
                "required": [
                    "results",
                    "nextParam",
                    "totalItems"
                ],
                "properties": {
                    "results": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Album"
                        }
                    },
                    "nextParam": {
                        "type": "string",
                        "nullable": true,
                        "example": "eyJvZmZzZXQiOjEwfQ=="
                    },
                    "totalItems": {
                        "type": "number",
                        "nullable": true,
                        "example": 25
                    }
                }
            },
            "ArtistsResponse": {
                "type": "object",
                "required": [
                    "results",
                    "nextParam",
                    "totalItems"
                ],
                "properties": {
                    "results": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Artist"
                        }
                    },
                    "nextParam": {
                        "type": "string",
                        "nullable": true,
                        "example": "eyJvZmZzZXQiOjEwfQ=="
                    },
                    "totalItems": {
                        "type": "number",
                        "nullable": true,
                        "example": 25
                    }
                }
            },
            "AddAlbumRequest": {
                "type": "object",
                "properties": {
                    "albumId": {
                        "type": "string",
                        "example": "57bgtoPSgt236d8kj"
                    }
                },
                "required": [
                    "albumId"
                ]
            },
            "AddArtistRequest": {
                "type": "object",
                "properties": {
                    "artistId": {
                        "type": "string",
                        "example": "53XhwfbYqKCa1cC15pYq2q"
                    }
                },
                "required": [
                    "artistId"
                ]
            },
            "ArtistSimplified": {
                "type": "object",
                "required": [
                    "id",
                    "entryId",
                    "name",
                    "imageUrl",
                    "followers"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "53XhwfbYqKCa1cC15pYq2q",
                        "nullable": true
                    },
                    "entryId": {
                        "type": "string",
                        "example": "53XhwfbYqKCa1cC15pYq2q",
                        "description": "Identifier associated with an artist within a user's library. Artist entry id can be obtained during fetching artists from user's library.",
                        "nullable": true
                    },
                    "name": {
                        "type": "string",
                        "example": "Imagine Dragons"
                    },
                    "imageUrl": {
                        "type": "string",
                        "example": "https://i.scdn.co/image/ab6761610000e5ebab47d8dae2b24f5afe7f9d38",
                        "nullable": true
                    },
                    "followers": {
                        "type": "number",
                        "example": 53107521,
                        "nullable": true
                    }
                }
            },
            "AlbumSimplified": {
                "type": "object",
                "required": [
                    "name",
                    "id",
                    "totalItems",
                    "artists"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "Meteora"
                    },
                    "id": {
                        "type": "string",
                        "example": "4Gfnly5CzMJQqkUFfoHaP3",
                        "nullable": true
                    },
                    "totalItems": {
                        "type": "number",
                        "example": 13,
                        "nullable": true
                    },
                    "artists": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ArtistSimplified"
                        },
                        "nullable": true
                    }
                }
            },
            "Album": {
                "type": "object",
                "required": [
                    "id",
                    "name",
                    "totalItems",
                    "imageUrl",
                    "artists"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "4Gfnly5CzMJQqkUFfoHaP3"
                    },
                    "name": {
                        "type": "string",
                        "example": "Meteora"
                    },
                    "totalItems": {
                        "type": "number",
                        "example": 13,
                        "nullable": true
                    },
                    "imageUrl": {
                        "type": "string",
                        "example": "https://www.example-image.com/978263478234",
                        "nullable": true
                    },
                    "artists": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ArtistSimplified"
                        },
                        "nullable": true
                    }
                }
            },
            "Artist": {
                "type": "object",
                "required": [
                    "id",
                    "entryId",
                    "name",
                    "imageUrl",
                    "followers"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "53XhwfbYqKCa1cC15pYq2q"
                    },
                    "entryId": {
                        "type": "string",
                        "example": "53XhwfbYqKCa1cC15pYq2q",
                        "description": "Identifier associated with an artist within a user's library. Artist entry id can be obtained during fetching artists from user's library.",
                        "nullable": true
                    },
                    "name": {
                        "type": "string",
                        "example": "Imagine Dragons"
                    },
                    "imageUrl": {
                        "type": "string",
                        "example": "https://i.scdn.co/image/ab6761610000e5ebab47d8dae2b24f5afe7f9d38",
                        "nullable": true
                    },
                    "followers": {
                        "type": "number",
                        "example": 53107521,
                        "nullable": true
                    }
                }
            },
            "Track": {
                "type": "object",
                "required": [
                    "id",
                    "entryId",
                    "name",
                    "isrc",
                    "duration",
                    "imageUrl",
                    "previewUrl",
                    "album",
                    "artists"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "2nLtzopw4rPReszdYBJU6h"
                    },
                    "entryId": {
                        "type": "string",
                        "example": "2nLtzopw4rPReszdYBJU6h",
                        "description": "Identifier associated with a tracks within a specific collection. It is used to identify a particular instance of a track within a playlist or a user's library. Track entry id can be obtained during fetching playlist items or user's library.",
                        "nullable": true
                    },
                    "name": {
                        "type": "string",
                        "example": "Numb"
                    },
                    "isrc": {
                        "type": "string",
                        "example": "USWB10300474",
                        "nullable": true
                    },
                    "duration": {
                        "type": "number",
                        "example": 185586,
                        "nullable": true
                    },
                    "imageUrl": {
                        "type": "string",
                        "example": "https://i.scdn.co/image/ab67616d0000b273b4ad7ebaf4575f120eb3f193",
                        "nullable": true
                    },
                    "previewUrl": {
                        "type": "string",
                        "example": "https://p.scdn.co/mp3-preview/15e1178c9eb7f626ac1112ad8f56eccbec2cd6e5?cid=d3a370919fbb4853a2c037d9d92da680",
                        "nullable": true
                    },
                    "album": {
                        "nullable": true,
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/AlbumSimplified"
                            }
                        ]
                    },
                    "artists": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ArtistSimplified"
                        },
                        "nullable": true
                    },
                    "dateAdded": {
                        "type": "string",
                        "example": "2024-10-16T07:52:07.000Z",
                        "nullable": true
                    }
                }
            },
            "TracksResponse": {
                "type": "object",
                "required": [
                    "results",
                    "nextParam",
                    "totalItems"
                ],
                "properties": {
                    "results": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Track"
                        }
                    },
                    "nextParam": {
                        "type": "string",
                        "nullable": true,
                        "example": "eyJvZmZzZXQiOjEwfQ=="
                    },
                    "totalItems": {
                        "type": "number",
                        "nullable": true,
                        "example": 25
                    }
                }
            },
            "SearchResult": {
                "type": "object",
                "required": [
                    "id",
                    "type",
                    "track",
                    "album",
                    "artist"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "57bgtoPSgt236HzfBOd8kj"
                    },
                    "type": {
                        "type": "string",
                        "example": "track",
                        "enum": [
                            "track",
                            "album",
                            "artist"
                        ]
                    },
                    "track": {
                        "nullable": true,
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/Track"
                            }
                        ]
                    },
                    "album": {
                        "nullable": true,
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/Album"
                            }
                        ]
                    },
                    "artist": {
                        "nullable": true,
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/Artist"
                            }
                        ]
                    }
                }
            },
            "SearchResponse": {
                "type": "object",
                "required": [
                    "results",
                    "nextParam",
                    "totalItems"
                ],
                "properties": {
                    "results": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/SearchResult"
                        }
                    },
                    "nextParam": {
                        "type": "string",
                        "nullable": true,
                        "example": "eyJvZmZzZXQiOjEwfQ=="
                    },
                    "totalItems": {
                        "type": "number",
                        "nullable": true,
                        "example": 0
                    }
                }
            },
            "TrackIds": {
                "type": "array",
                "description": "Track IDs that are retrievable through track searches or when fetching playlist items. A maximum of 20 IDs can be sent in one request.",
                "items": {
                    "type": "string",
                    "example": "42YpD6LQura7bGOtntatQw"
                }
            },
            "EntryIds": {
                "type": "array",
                "description": "Identifiers associated with a tracks within a specific collection. It is used to identify a particular instance of a track within a playlist or a user's library. Track entry id can be obtained during fetching playlist items or user's library. A maximum of 20 IDs can be sent in one request.",
                "items": {
                    "type": "string",
                    "example": "42YpD6LQura7bGOtntatQw"
                }
            },
            "AuthByUniqueIdResponse": {
                "type": "object",
                "required": [
                    "authModel",
                    "integrationUser"
                ],
                "properties": {
                    "authModel": {
                        "type": "object",
                        "required": [
                            "uuid",
                            "status",
                            "error",
                            "errorType"
                        ],
                        "properties": {
                            "uuid": {
                                "type": "string"
                            },
                            "status": {
                                "type": "string",
                                "enum": [
                                    "initialised",
                                    "success",
                                    "error"
                                ]
                            },
                            "error": {
                                "type": "string",
                                "nullable": true
                            },
                            "errorType": {
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                    "accessDenied",
                                    "notAllowedInYourCountry",
                                    "missingScopes",
                                    "deniedSubscriptionTier"
                                ]
                            }
                        }
                    },
                    "integrationUser": {
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/UserResponse"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "required": [
                                    "country",
                                    "email",
                                    "imageUrl",
                                    "integrationUserId",
                                    "name",
                                    "authData",
                                    "authDataExpiresAt"
                                ],
                                "properties": {
                                    "authData": {
                                        "type": "object"
                                    },
                                    "authDataExpiresAt": {
                                        "type": "number"
                                    }
                                }
                            }
                        ]
                    }
                }
            }
        },
        "parameters": {
            "UserUUIDParam": {
                "in": "path",
                "name": "userUUID",
                "schema": {
                    "type": "string"
                },
                "required": true,
                "description": "User UUID `integrationUserUUID` taken from data extracted from successful redirect from authentication"
            },
            "NextParam": {
                "in": "query",
                "name": "nextParam",
                "schema": {
                    "type": "string"
                },
                "required": false,
                "description": "Parameter returned in the response responsible for pagination."
            },
            "LimitParam": {
                "in": "query",
                "name": "limitParam",
                "schema": {
                    "type": "number"
                },
                "required": false,
                "description": "Specifies the maximum number of results per request, adjusted based on the limitations of the respective music service. Ignored if the service doesn't support such a limit."
            },
            "PlaylistId": {
                "in": "path",
                "name": "playlistId",
                "schema": {
                    "type": "string"
                },
                "required": true,
                "description": "ID of the playlist"
            },
            "AlbumId": {
                "in": "path",
                "name": "albumId",
                "schema": {
                    "type": "string"
                },
                "required": true,
                "description": "ID of the album"
            },
            "ArtistId": {
                "in": "path",
                "name": "artistId",
                "schema": {
                    "type": "string"
                },
                "required": true,
                "description": "ID of the artist"
            }
        }
    },
    "security": [
        {
            "BasicAuth": [],
            "DevTokenAuth": []
        }
    ],
    "tags": [
        {
            "name": "Public",
            "description": "Endpoints that do not require user authentication, thus the name public."
        },
        {
            "name": "User",
            "description": "Endpoints related to authenticated user."
        }
    ]
}