{ "openapi": "3.1.0", "info": { "title": "MusicAPI partner API", "version": "3.0.0", "description": "The partner API of MusicAPI Core (read and write a connected user's library, search and match the catalogue) and MusicAPI Managed Transfers (the hosted transfer flow). Every operation lists the credentials it accepts; any one of them is enough." }, "servers": [ { "url": "https://api.musicapi.com" } ], "tags": [ { "name": "Get started" }, { "name": "Connect your users" }, { "name": "User library" }, { "name": "Catalog" }, { "name": "Managed Transfers" } ], "paths": { "/{slug}": { "servers": [ { "url": "https://app.musicapi.com", "description": "The hosted sign-in pages. Open them in a browser; they are not JSON." } ], "get": { "operationId": "startSignIn", "summary": "Start a sign-in (service picker)", "description": "A page, not a JSON call. Send the user's browser here. The user picks one of the services you turned on, signs in, and comes back to `returnUrl` with the result (see \"Handle the callback\").", "tags": [ "Connect your users" ], "x-docs": { "section": "connect-users", "order": 1, "product": "both", "slug": "start-sign-in", "hostedPage": true }, "security": [], "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "example": "acme" }, "description": "Your account slug (Dashboard, Settings)." }, { "$ref": "#/components/parameters/ReturnUrlQuery" }, { "$ref": "#/components/parameters/RequestOneTimeTokenQuery" }, { "$ref": "#/components/parameters/UniqueIdQuery" }, { "$ref": "#/components/parameters/ForwardFailuresQuery" }, { "$ref": "#/components/parameters/MerchantUserIdQuery" } ], "responses": { "200": { "description": "The service picker page (HTML).", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/{slug}/{integrationType}/auth": { "servers": [ { "url": "https://app.musicapi.com", "description": "The hosted sign-in pages. Open them in a browser; they are not JSON." } ], "get": { "operationId": "startServiceSignIn", "summary": "Start a sign-in with one service", "description": "A page, not a JSON call. Skips the service picker and sends the user straight to the sign-in of one service. This works even for a service that is off in your dashboard.", "tags": [ "Connect your users" ], "x-docs": { "section": "connect-users", "order": 2, "product": "both", "slug": "start-service-sign-in", "hostedPage": true }, "security": [], "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "example": "acme" }, "description": "Your account slug." }, { "in": "path", "name": "integrationType", "required": true, "schema": { "type": "string", "example": "spotify" }, "description": "The service id, for example `spotify`, `appleMusic`, `tidal`." }, { "$ref": "#/components/parameters/ReturnUrlQuery" }, { "$ref": "#/components/parameters/RequestOneTimeTokenQuery" }, { "$ref": "#/components/parameters/UniqueIdQuery" }, { "$ref": "#/components/parameters/ForwardFailuresQuery" }, { "$ref": "#/components/parameters/MerchantUserIdQuery" } ], "responses": { "302": { "description": "A redirect to the service's sign-in page." } } } }, "/app/integrations/byUniqueId/{uniqueId}": { "get": { "operationId": "getSignInStatus", "summary": "Poll the sign-in status", "description": "Poll this while a sign-in that you started with `uniqueId` runs. It needs no credentials: the `uniqueId` you chose is the secret. Send `tokenOnly=1` from a browser, so the answer never holds music-service credentials.", "tags": [ "Connect your users" ], "x-docs": { "section": "connect-users", "order": 3, "product": "both", "slug": "get-sign-in-status" }, "security": [], "parameters": [ { "in": "path", "name": "uniqueId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID v4 that you passed as `uniqueId` when you started the sign-in." }, { "in": "query", "name": "tokenOnly", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Leave `authData` out of the answer." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthByUniqueIdResponse" } } } }, "404": { "description": "No sign-in with this uniqueId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/app/integrations/{authModelUUID}": { "get": { "operationId": "getHostedSignIn", "summary": "Get a hosted sign-in attempt", "description": "The state of one sign-in attempt, as the hosted pages read it. The `authModelUUID` comes back in the callback. It needs no credentials and never returns `authData`.", "tags": [ "Connect your users" ], "x-docs": { "section": "connect-users", "order": 4, "product": "both", "slug": "get-hosted-sign-in" }, "security": [], "parameters": [ { "in": "path", "name": "authModelUUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostedSignInResponse" } } } }, "404": { "description": "No sign-in attempt with this uuid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/public/integrations/auth/{authModelUUID}": { "get": { "operationId": "getSignInResult", "summary": "Get the result of a sign-in", "description": "Reads one sign-in attempt of your account and the user it connected. `authData` is in the answer only for a Client Secret call or with a valid `oneTimeToken` from the callback.", "tags": [ "Connect your users" ], "x-docs": { "section": "connect-users", "order": 5, "product": "both", "slug": "get-sign-in-result" }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "in": "path", "name": "authModelUUID", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "oneTimeToken", "required": false, "schema": { "type": "string" }, "description": "The one-time token from the callback. It must belong to your account and to this sign-in." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthModelResultResponse" } } } }, "403": { "description": "The one-time token belongs to another account or another sign-in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Your account has no sign-in attempt with this uuid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/public/integrations/user/{integrationUserUUID}": { "get": { "operationId": "getIntegrationUser", "summary": "Get a connected user", "description": "Reads one connected user of your account. With Client Secret (Basic) authentication the answer also holds the raw service tokens (`authData`), refreshed when they expire within a minute. Every other credential gets the profile only.", "tags": [ "Connect your users" ], "x-docs": { "section": "connect-users", "order": 6, "product": "both", "slug": "get-integration-user", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationUserResponse" } } } }, "401": { "description": "The tokens could not be refreshed. Send the user to sign in again." }, "404": { "description": "Your account has no connected user with this uuid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteIntegrationUser", "summary": "Delete integration user", "description": "Deletes a connected user, for example when they delete their account in your app. Removes the music service tokens, the user's name, email and profile image, and the copy of their library. Idempotent: deleting a user you already deleted returns 204 again. Requires Client Secret authentication, so call it only from your backend.", "tags": [ "Connect your users" ], "x-docs": { "section": "connect-users", "order": 9, "product": "both", "slug": "delete-integration-user" }, "security": [ { "BasicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" } ], "responses": { "204": { "description": "The user is deleted. The response has no body." }, "400": { "description": "userModelUUID is not a valid UUID." }, "401": { "description": "The request has no credentials." }, "403": { "description": "The request does not use Client Secret authentication." }, "404": { "description": "Your account has no integration user with this UUID." } } } }, "/api/{integrationUserUUID}/users/profile": { "get": { "operationId": "getUserProfile", "summary": "Get the user's service profile (\"Me\")", "description": "[Check which services support returning user information](/docs/get-started/services-and-features)\n\n\nThis endpoint returns information about user that was fetched from Music Service.", "tags": [ "Connect your users" ], "x-docs": { "section": "connect-users", "order": 7, "product": "core", "slug": "get-user-profile", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "404": { "description": "Your account has no connected user with this uuid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/public/integrations/refreshAuthToken": { "post": { "operationId": "refreshIntegrationUserToken", "summary": "Force a token refresh", "description": "Refreshes the music-service tokens of one connected user now. With Client Secret authentication the answer holds the new `authData`.", "tags": [ "Connect your users" ], "x-docs": { "section": "connect-users", "order": 8, "product": "both", "slug": "refresh-integration-user-token" }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshAuthTokenRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshedIntegrationUserResponse" } } } }, "401": { "description": "The refresh failed. Send the user to sign in again." }, "404": { "description": "Your account has no connected user with this uuid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/app/users/{slug}": { "get": { "operationId": "getPartnerProfile", "summary": "Get your public sign-in profile", "description": "What the hosted sign-in pages show for your account: name, logos and the services you turned on. With `returnUrl` it also checks that URL against your Return URLs (400 when it does not match).", "tags": [ "Connect your users" ], "x-docs": { "section": "connect-users", "order": 10, "product": "both", "slug": "get-partner-profile" }, "security": [], "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "type": "string", "example": "acme" } }, { "in": "query", "name": "returnUrl", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerProfileResponse" } } } }, "400": { "description": "`returnUrl` is not one of your Return URLs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No account with this slug.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/{integrationUserUUID}/playlists": { "get": { "operationId": "listPlaylists", "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": [ "User library" ], "x-docs": { "section": "user-library", "order": 1, "product": "core", "slug": "list-playlists", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$ref": "#/components/parameters/NextParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistsResponse" } } } }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createPlaylist", "summary": "Create playlist", "description": "This endpoint creates playlist on Music Service.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 2, "product": "core", "slug": "create-playlist", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistCreationRequest" } } }, "required": true }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Playlist" } } } }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/{integrationUserUUID}/playlists/{playlistId}": { "get": { "operationId": "getPlaylist", "summary": "Get playlist", "description": "This endpoint fetches specified playlist and returns information about it.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 3, "product": "core", "slug": "get-playlist", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$ref": "#/components/parameters/PlaylistId" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Playlist" } } } }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "updatePlaylist", "summary": "Update playlist", "description": "Change a playlist's name, description and public/private state (if available). The user must own the playlist.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 4, "product": "core", "slug": "update-playlist", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$ref": "#/components/parameters/PlaylistId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "ok" }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deletePlaylist", "summary": "Remove playlist", "description": "This endpoint removes a playlist.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 5, "product": "core", "slug": "delete-playlist", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$ref": "#/components/parameters/PlaylistId" } ], "responses": { "200": { "description": "ok" }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/{integrationUserUUID}/playlists/{playlistId}/items": { "get": { "operationId": "listPlaylistItems", "summary": "Get playlist items", "description": "This endpoint fetches playlist items from Music Service.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 6, "product": "core", "slug": "list-playlist-items", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$ref": "#/components/parameters/NextParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/PlaylistId" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TracksResponse" } } } }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "addPlaylistItems", "summary": "Add items to playlist", "description": "Add items to a user's playlist.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 7, "product": "core", "slug": "add-playlist-items", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$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" }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "movePlaylistItems", "summary": "Update playlist items", "description": "[Check which services support updating playlist items](/docs/get-started/services-and-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": [ "User library" ], "x-docs": { "section": "user-library", "order": 8, "product": "core", "slug": "move-playlist-items", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$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" }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "removePlaylistItems", "summary": "Remove playlist items", "description": "[Check which services support removing playlist items](/docs/get-started/services-and-features)\n\n\nRemove items from a user's playlist.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 9, "product": "core", "slug": "remove-playlist-items", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$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" }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/{integrationUserUUID}/liked/tracks": { "get": { "operationId": "listLikedTracks", "summary": "Get liked tracks", "description": "[Check which services support returning ISRC and preview url](/docs/get-started/services-and-features)\n\n\nThis endpoint fetches tracks liked by the user.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 10, "product": "core", "slug": "list-liked-tracks", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$ref": "#/components/parameters/NextParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TracksResponse" } } } }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "addLikedTracks", "summary": "Add tracks to library", "description": "[Check which services support adding tracks to user's library](/docs/get-started/services-and-features)\n\n\nThis endpoint saves tracks to the current user's library on Music Service.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 11, "product": "core", "slug": "add-liked-tracks", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "itemIds": { "$ref": "#/components/schemas/TrackIds" } }, "required": [ "itemIds" ] } } }, "required": true }, "responses": { "200": { "description": "ok" }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "removeLikedTracks", "summary": "Remove tracks from library", "description": "[Check which services support removing tracks from library](/docs/get-started/services-and-features)\n\n\nRemove tracks from a user's library.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 12, "product": "core", "slug": "remove-liked-tracks", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "entryIds": { "$ref": "#/components/schemas/EntryIds" } }, "required": [ "entryIds" ] } } }, "required": true }, "responses": { "200": { "description": "ok" }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/{integrationUserUUID}/albums": { "get": { "operationId": "listAlbums", "summary": "Get user's liked albums", "description": "This endpoint fetches liked albums from Music Service.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 13, "product": "core", "slug": "list-albums", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$ref": "#/components/parameters/NextParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlbumsResponse" } } } }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "saveAlbum", "summary": "Add album to user's library", "description": "This endpoint saves album to the current user's library on Music Service.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 14, "product": "core", "slug": "save-album", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAlbumRequest" } } }, "required": true }, "responses": { "200": { "description": "ok" }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/{integrationUserUUID}/albums/{albumId}": { "get": { "operationId": "getAlbum", "summary": "Get album", "description": "This endpoint fetches specified album and returns information about it.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 15, "product": "core", "slug": "get-album", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$ref": "#/components/parameters/AlbumId" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Album" } } } }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "removeAlbum", "summary": "Remove album from user's library", "description": "This endpoint removes an album from user's library on Music Service.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 16, "product": "core", "slug": "remove-album", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$ref": "#/components/parameters/AlbumId" } ], "responses": { "200": { "description": "ok" }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/{integrationUserUUID}/albums/{albumId}/items": { "get": { "operationId": "listAlbumItems", "summary": "Get album tracks", "description": "This endpoint fetches album's tracks from Music Service.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 17, "product": "core", "slug": "list-album-items", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$ref": "#/components/parameters/NextParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/AlbumId" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TracksResponse" } } } }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/{integrationUserUUID}/artists": { "get": { "operationId": "listArtists", "summary": "Get user's liked artists", "description": "This endpoint fetches liked artists from Music Service.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 18, "product": "core", "slug": "list-artists", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$ref": "#/components/parameters/NextParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtistsResponse" } } } }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "followArtist", "summary": "Add artist to user's library", "description": "This endpoint saves artist to the current user's library on Music Service.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 19, "product": "core", "slug": "follow-artist", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddArtistRequest" } } }, "required": true }, "responses": { "200": { "description": "ok" }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/{integrationUserUUID}/artists/{artistId}": { "get": { "operationId": "getArtist", "summary": "Get artist", "description": "This endpoint fetches specified artist and returns information about it.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 20, "product": "core", "slug": "get-artist", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$ref": "#/components/parameters/ArtistId" } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artist" } } } }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "unfollowArtist", "summary": "Remove artist from user's library", "description": "This endpoint removes an artist from user's library on Music Service.", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 21, "product": "core", "slug": "unfollow-artist", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$ref": "#/components/parameters/ArtistId" } ], "responses": { "200": { "description": "ok" }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/{integrationUserUUID}/search": { "post": { "operationId": "searchUserService", "summary": "Search tracks, albums and artists", "description": "[Check which services support searching by ISRC](/docs/get-started/services-and-features)\n\n\nSearch Endpoint allows you to search for\n\n- tracks\n- albums\n- artists", "tags": [ "User library" ], "x-docs": { "section": "user-library", "order": 22, "product": "core", "slug": "search-user-service", "sandbox": "connectedUser" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IntegrationUserUUIDParam" }, { "$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" } } } }, "404": { "description": "Your account has no connected user with this uuid, or the item does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The user must sign in again (`IntegrationUserNotAuthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Wait for the seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/public/search": { "post": { "operationId": "searchCatalog", "summary": "Search", "description": "Searches the catalogues of one or more services for a track, an album or an artist. Needs no connected user. [Check which services return the ISRC](/docs/get-started/services-and-features).", "tags": [ "Catalog" ], "x-docs": { "section": "catalog", "order": 1, "product": "core", "slug": "search-catalog", "sandbox": "catalog" }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSearchRequest" } } } }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSearchResponse" } } } } } } }, "/public/search/introspection": { "get": { "operationId": "getSearchIntrospection", "summary": "Search Introspection", "description": "Allows you to fetch all different enums needed for sending API requests.", "tags": [ "Catalog" ], "x-docs": { "section": "catalog", "order": 2, "product": "core", "slug": "get-search-introspection", "sandbox": "catalog" }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchIntrospectionResponse" } } } } } } }, "/public/search/match": { "post": { "operationId": "matchCatalogItems", "summary": "Match items into other services", "description": "Finds each track, album or artist that you name in the destination services. Needs no connected user.", "tags": [ "Catalog" ], "x-docs": { "section": "catalog", "order": 3, "product": "core", "slug": "match-catalog-items", "sandbox": "catalog" }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchMatchRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchMatchResponse" } } } }, "400": { "description": "A source or a destination is not a search source.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/public/inspect/url": { "post": { "operationId": "inspectUrl", "summary": "Inspect", "description": "[Check which services support returning ISRC](/docs/get-started/services-and-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.", "tags": [ "Catalog" ], "x-docs": { "section": "catalog", "order": 4, "product": "core", "slug": "inspect-url", "sandbox": "catalog" }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "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" } } } } } } }, "/public/inspect/playlistItems": { "post": { "operationId": "getPublicPlaylistItems", "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 (up to 50 tracks per page). To fetch subsequent pages, pass the `nextParam` value from the response back in the `nextParam` field of the request body. When the response `nextParam` is `null`, there are no more pages.\n\nSupported services: Spotify, Apple Music, Deezer, YouTube, YouTube Music, SoundCloud, Tidal, Amazon Music, Pandora, Qobuz.", "tags": [ "Catalog" ], "x-docs": { "section": "catalog", "order": 5, "product": "core", "slug": "get-public-playlist-items", "sandbox": "catalog" }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, { "DevTokenAuth": [] }, { "DocsSessionAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistItemsRequest" } } }, "required": true }, "responses": { "200": { "description": "ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistItemsResponse" } } } } } } }, "/public/embed/url": { "post": { "operationId": "createEmbedPlayer", "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.", "tags": [ "Catalog" ], "x-docs": { "section": "catalog", "order": 6, "product": "core", "slug": "create-embed-player" }, "security": [], "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" } } } } } } }, "/public/embed/{resourceType}/{resourceId}": { "get": { "operationId": "getEmbedPlayer", "summary": "Embed player page", "description": "The HTML that the iframe of `POST /public/embed/url` loads. You rarely call it yourself: use the `embedUrl` from that answer.", "tags": [ "Catalog" ], "x-docs": { "section": "catalog", "order": 7, "product": "core", "slug": "get-embed-player" }, "security": [], "parameters": [ { "in": "path", "name": "resourceType", "required": true, "schema": { "type": "string", "enum": [ "track", "album", "artist" ] } }, { "in": "path", "name": "resourceId", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "height", "required": true, "schema": { "type": "integer", "example": 152 } } ], "responses": { "200": { "description": "The player (HTML).", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "Unknown resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/public/transfer-sessions": { "post": { "operationId": "createTransferSession", "summary": "Create transfer session", "description": "Creates a pre-authorized session of the hosted transfer wizard. Your backend sends the access token of a user who is already signed in to your destination service in your app. We check the token with the service, store it encrypted, attach the account as the destination and answer with a launchUrl. The user then connects only the source. Requires Client Secret (Basic) or a DevToken without `sub`. See [Pre-authorized Sessions](/docs/managed-transfers/preauthorized-sessions).", "tags": [ "Managed Transfers" ], "x-docs": { "section": "managed-transfers", "order": 1, "product": "managedTransfers", "slug": "create-transfer-session" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransferSessionRequest" } } }, "required": true }, "responses": { "201": { "description": "The session is created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransferSessionResponse" } } } }, "400": { "description": "The body is not valid, no transfer destination is set, or the destination does not support pre-authorized sessions." }, "401": { "description": "The request has no credentials." }, "403": { "description": "The credential is not secret, or the transfer service is not enabled for your account." }, "422": { "description": "The music service refused the access token. Nothing is stored." }, "503": { "description": "The music service could not be reached to check the token. Try again later." } } } }, "/public/transfer-sessions/{sessionUuid}/target-auth": { "put": { "operationId": "pushTransferSessionTargetAuth", "summary": "Push destination token", "description": "Replaces the stored token of the session's destination account. The token must be for the same account. If a transfer of this session waits for the destination (`user.auth_failed` with `preauthorized: true`), it resumes.", "tags": [ "Managed Transfers" ], "x-docs": { "section": "managed-transfers", "order": 2, "product": "managedTransfers", "slug": "push-transfer-session-target-auth" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionUuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "The sessionUuid from Create transfer session" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "authData" ], "properties": { "authData": { "$ref": "#/components/schemas/PreauthorizedAuthData" } } } } }, "required": true }, "responses": { "200": { "description": "The token is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushTargetAuthResponse" } } } }, "400": { "description": "The body is not valid." }, "401": { "description": "The request has no credentials." }, "403": { "description": "The credential is not secret, or the transfer service is not enabled for your account." }, "404": { "description": "Your account has no session with this UUID." }, "409": { "description": "The token is for another account, the session has no pre-authorized destination, or the session ended." }, "422": { "description": "The music service refused the access token." }, "503": { "description": "The music service could not be reached to check the token. Try again later." } } } }, "/public/transfer-sessions/{sessionUuid}": { "delete": { "operationId": "endTransferSession", "summary": "End transfer session", "description": "Ends a session: the wizard stops working for it, a running transfer is cancelled, and the stored token and personal data of a pre-authorized destination account are erased unless another live session or running transfer uses the same account. Calling it again changes nothing.", "tags": [ "Managed Transfers" ], "x-docs": { "section": "managed-transfers", "order": 3, "product": "managedTransfers", "slug": "end-transfer-session" }, "security": [ { "BasicAuth": [] }, { "DevTokenAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionUuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "The sessionUuid from Create transfer session" } ], "responses": { "200": { "description": "The session is ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndTransferSessionResponse" } } } }, "401": { "description": "The request has no credentials." }, "403": { "description": "The credential is not secret." }, "404": { "description": "Your account has no session with this UUID." } } } }, "/public/transfers/{transferUuid}": { "get": { "operationId": "getTransferResult", "summary": "Get transfer summary", "description": "The summary of one transfer of your account: status, counters, source and target service, timestamps, and `resultsUrl`, the address of its unmatched items. Requires Client Secret authentication, so call it only from your backend.", "tags": [ "Managed Transfers" ], "x-docs": { "section": "managed-transfers", "order": 4, "product": "managedTransfers", "slug": "get-transfer-result" }, "security": [ { "BasicAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "in": "path", "name": "transferUuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "The `transferUuid` from a webhook or from the Transfers page of the dashboard." } ], "responses": { "200": { "description": "The transfer summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferSummaryResponse" } } } }, "400": { "description": "transferUuid is not a valid UUID." }, "401": { "description": "The request has no credentials." }, "403": { "description": "The request does not use Client Secret authentication, or the transfer service is not on for your account." }, "404": { "description": "Your account has no transfer with this UUID." } } } }, "/public/transfers/{transferUuid}/unmatched": { "get": { "operationId": "listTransferUnmatchedItems", "summary": "List unmatched items of a transfer", "description": "The unmatched and failed items of one transfer of your account, one page at a time, in a stable order. Send `nextCursor` back as `cursor` until it is `null`. Requires Client Secret authentication. The `match.report_ready` and `transfer.completed` webhooks carry this address as `resultsUrl`.", "tags": [ "Managed Transfers" ], "x-docs": { "section": "managed-transfers", "order": 5, "product": "managedTransfers", "slug": "list-transfer-unmatched-items" }, "security": [ { "BasicAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "in": "path", "name": "transferUuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "The `transferUuid` from a webhook or from the Transfers page of the dashboard." }, { "in": "query", "name": "reason", "schema": { "type": "string", "enum": [ "notFound", "lowConfidence", "regionLocked", "error", "cannotMatch", "limitReached" ] }, "required": false, "description": "Return only the rows with this reason. `error` also returns the failed items." }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "required": false, "description": "Rows per page." }, { "in": "query", "name": "cursor", "schema": { "type": "string" }, "required": false, "description": "The `nextCursor` of the previous page. Leave it out for the first page. Opaque: do not build or change it." } ], "responses": { "200": { "description": "One page of rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchResultsPage" } } } }, "400": { "description": "A parameter or the cursor is not valid." }, "401": { "description": "The request has no credentials." }, "403": { "description": "The request does not use Client Secret authentication, or the transfer service is not on for your account." }, "404": { "description": "Your account has no transfer with this UUID." } } } }, "/public/transfers/unmatched": { "get": { "operationId": "listUnmatchedItems", "summary": "List unmatched items of all transfers", "description": "The unmatched and failed items of every transfer of your account that finished in `[from, to)`, ordered by transfer and then by item. For a daily bulk pull. The window must not be longer than 31 days. A page can hold fewer rows than `limit` and still have a `nextCursor`: continue until `nextCursor` is `null`. Requires Client Secret authentication.", "tags": [ "Managed Transfers" ], "x-docs": { "section": "managed-transfers", "order": 6, "product": "managedTransfers", "slug": "list-unmatched-items" }, "security": [ { "BasicAuth": [] }, { "DocsSessionAuth": [] } ], "parameters": [ { "in": "query", "name": "from", "schema": { "type": "string", "format": "date-time" }, "required": true, "description": "A transfer is in the window when it finished at or after this time." }, { "in": "query", "name": "to", "schema": { "type": "string", "format": "date-time" }, "required": false, "description": "A transfer is in the window when it finished before this time. Default: now." }, { "in": "query", "name": "reason", "schema": { "type": "string", "enum": [ "notFound", "lowConfidence", "regionLocked", "error", "cannotMatch", "limitReached" ] }, "required": false, "description": "Return only the rows with this reason. `error` also returns the failed items." }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "required": false, "description": "Rows per page." }, { "in": "query", "name": "cursor", "schema": { "type": "string" }, "required": false, "description": "The `nextCursor` of the previous page. Leave it out for the first page. Opaque: do not build or change it." } ], "responses": { "200": { "description": "One page of rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchResultsPage" } } } }, "400": { "description": "`from` is missing, `to` is not after `from`, the window is longer than 31 days, or the cursor is not valid." }, "401": { "description": "The request has no credentials." }, "403": { "description": "The request does not use Client Secret authentication, or the transfer service is not on for your account." } } } }, "/public/docs-sessions/exchange": { "post": { "operationId": "exchangeDocsCode", "summary": "Exchange a docs sign-in code", "description": "The docs site calls this after the dashboard sent the browser back with `#code=…`. A code works once and for 2 minutes. The token lives 8 hours. 20 calls per minute per IP.", "tags": [ "Get started" ], "x-docs": { "section": "get-started", "order": 1, "product": "both", "slug": "exchange-docs-code" }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocsSessionExchangeAnswer" } } } }, "400": { "description": "`invalidCode`: the code is used, expired or unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many exchanges from this IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/public/docs-sessions/sandbox": { "post": { "operationId": "createDocsSandboxSession", "summary": "Start a sandbox docs session", "description": "For \"Try it\" without signing in. The token lives 1 hour and acts as the `demo` account, 30 calls per minute. 30 sessions per hour per IP.\n\nWithout a body the token reaches the operations marked `x-docs.sandbox: \"catalog\"`: the catalog reads and its own session routes, with the demo and sample users only.\n\nWith `authModelUUID` the token is bound to the account that the visitor connected through the hosted sign-in of the `demo` account (`authModel.uuid` of `data64`). It then also reaches every operation marked `x-docs.sandbox: \"connectedUser\"`, for that connected user only: another uuid answers 404. The sign-in must have succeeded, must be at most 15 minutes old, and opens one session only. Erasing the user, `refreshAuthToken`, transfers and transfer sessions stay refused.", "tags": [ "Get started" ], "x-docs": { "section": "get-started", "order": 2, "product": "both", "slug": "create-docs-sandbox-session" }, "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocsSandboxAnswer" } } } }, "400": { "description": "`invalidAuthModel`: the sign-in is unknown, failed, of another account, older than 15 minutes, has no connected user, or already opened a session. Connect the account again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many sandbox sessions from this IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "authModelUUID": { "type": "string", "format": "uuid", "description": "The `authModel.uuid` of a hosted sign-in of the `demo` account, at most 15 minutes old. Used once." } } } } } } } }, "/public/docs-sessions/current": { "get": { "operationId": "getDocsSession", "summary": "Get the current docs session", "tags": [ "Get started" ], "x-docs": { "section": "get-started", "order": 3, "product": "both", "slug": "get-docs-session", "sandbox": "catalog" }, "security": [ { "DocsSessionAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocsSessionCurrent" } } } }, "401": { "description": "`docsSessionEnded`: the token expired or was revoked. Sign in again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteDocsSession", "summary": "Sign out of the docs", "tags": [ "Get started" ], "x-docs": { "section": "get-started", "order": 5, "product": "both", "slug": "delete-docs-session", "sandbox": "catalog" }, "security": [ { "DocsSessionAuth": [] } ], "responses": { "204": { "description": "The session is revoked." }, "401": { "description": "`docsSessionEnded`: the session already ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/public/docs-sessions/current/integration-users": { "get": { "operationId": "listDocsIntegrationUsers", "summary": "List your connected users (docs picker)", "description": "The connected users of your account, newest first, 20 per page, without credentials. A sandbox session sees only the demo and sample users. A sandbox session bound to a connected account sees only that account.", "tags": [ "Get started" ], "x-docs": { "section": "get-started", "order": 4, "product": "both", "slug": "list-docs-integration-users", "sandbox": "catalog" }, "security": [ { "DocsSessionAuth": [] } ], "parameters": [ { "in": "query", "name": "integrationType", "required": false, "schema": { "type": "string", "example": "spotify" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocsIntegrationUsersPage" } } } }, "401": { "description": "`docsSessionEnded`: sign in again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "transfer.created": { "post": { "operationId": "webhookTransferCreated", "summary": "transfer.created", "x-docs": { "section": "webhooks", "order": 1, "product": "managedTransfers", "slug": "transfer-created" }, "description": "Sent with the headers `X-MusicAPI-Event: transfer.created` and `X-MusicAPI-Signature: t=,v1=`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "createdAt", "data" ], "properties": { "id": { "type": "string", "example": "evt_3d1f6c0e-8a52-4c1b-9a0e-2f4b7c9d1e33", "description": "The id of this delivery, `evt_`. A retry sends the same id, so dedupe by it. Two endpoints get two different ids for the same event. Deliveries queued before 2026-10-16 have no `id`." }, "event": { "type": "string", "const": "transfer.created" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transferUuid", "sourceIntegrationType", "targetIntegrationType", "totalItems" ], "properties": { "transferUuid": { "type": "string", "format": "uuid" }, "sourceIntegrationType": { "type": "string" }, "targetIntegrationType": { "type": "string" }, "totalItems": { "type": "integer" }, "endUserId": { "type": [ "string", "null" ], "example": "your-user-8841", "description": "Your own id for the person: the `externalUserId` of the session, else the `merchantUserId` of the source login. Null when you sent neither." }, "batch": { "anyOf": [ { "$ref": "#/components/schemas/TransferWebhookBatch" }, { "type": "null" } ], "description": "The batch of the transfer. Null for a transfer that was made alone." } } } } } } } }, "responses": { "200": { "description": "Answer any 2xx within 10 seconds. Any other answer is retried." } } } }, "transfer.progress": { "post": { "operationId": "webhookTransferProgress", "summary": "transfer.progress", "x-docs": { "section": "webhooks", "order": 2, "product": "managedTransfers", "slug": "transfer-progress" }, "description": "Sent with the headers `X-MusicAPI-Event: transfer.progress` and `X-MusicAPI-Signature: t=,v1=`.\n\nSent after a chunk of items was written, at most once every 15 seconds per transfer and only when `processedItems` moved, and at the end of a group run that crossed a 10% step. A small transfer that finishes in one chunk may send none: `transfer.completed` carries the final counts.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "createdAt", "data" ], "properties": { "id": { "type": "string", "example": "evt_3d1f6c0e-8a52-4c1b-9a0e-2f4b7c9d1e33", "description": "The id of this delivery, `evt_`. A retry sends the same id, so dedupe by it. Two endpoints get two different ids for the same event. Deliveries queued before 2026-10-16 have no `id`." }, "event": { "type": "string", "const": "transfer.progress" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transferUuid", "processedItems", "totalItems", "pct" ], "properties": { "transferUuid": { "type": "string", "format": "uuid" }, "processedItems": { "type": "integer" }, "totalItems": { "type": "integer" }, "pct": { "type": "integer", "minimum": 0, "maximum": 100, "description": "0 to 100, rounded down." }, "sourceIntegrationType": { "type": "string", "example": "spotify" }, "targetIntegrationType": { "type": "string", "example": "tidal" }, "endUserId": { "type": [ "string", "null" ], "example": "your-user-8841", "description": "Your own id for the person: the `externalUserId` of the session, else the `merchantUserId` of the source login. Null when you sent neither." }, "batch": { "anyOf": [ { "$ref": "#/components/schemas/TransferWebhookBatch" }, { "type": "null" } ], "description": "The batch of the transfer. Null for a transfer that was made alone." } } } } } } } }, "responses": { "200": { "description": "Answer any 2xx within 10 seconds. Any other answer is retried." } } } }, "transfer.completed": { "post": { "operationId": "webhookTransferCompleted", "summary": "transfer.completed", "x-docs": { "section": "webhooks", "order": 3, "product": "managedTransfers", "slug": "transfer-completed" }, "description": "Sent with the headers `X-MusicAPI-Event: transfer.completed` and `X-MusicAPI-Signature: t=,v1=`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "createdAt", "data" ], "properties": { "id": { "type": "string", "example": "evt_3d1f6c0e-8a52-4c1b-9a0e-2f4b7c9d1e33", "description": "The id of this delivery, `evt_`. A retry sends the same id, so dedupe by it. Two endpoints get two different ids for the same event. Deliveries queued before 2026-10-16 have no `id`." }, "event": { "type": "string", "const": "transfer.completed" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transferUuid", "status", "totalItems", "processedItems", "matchedItems", "unmatchedItems", "skippedItems", "failedItems", "sourceIntegrationType", "targetIntegrationType", "resultsUrl" ], "properties": { "transferUuid": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "completed" }, "totalItems": { "type": "integer" }, "processedItems": { "type": "integer" }, "matchedItems": { "type": "integer" }, "unmatchedItems": { "type": "integer" }, "skippedItems": { "type": "integer" }, "failedItems": { "type": "integer" }, "sourceIntegrationType": { "type": "string", "example": "spotify" }, "targetIntegrationType": { "type": "string", "example": "tidal" }, "resultsUrl": { "type": "string", "format": "uri", "description": "The Match Results API address of the unmatched items." }, "endUserId": { "type": [ "string", "null" ], "example": "your-user-8841", "description": "Your own id for the person: the `externalUserId` of the session, else the `merchantUserId` of the source login. Null when you sent neither." }, "batch": { "anyOf": [ { "$ref": "#/components/schemas/TransferWebhookBatch" }, { "type": "null" } ], "description": "The batch of the transfer. Null for a transfer that was made alone." } } } } } } } }, "responses": { "200": { "description": "Answer any 2xx within 10 seconds. Any other answer is retried." } } } }, "transfer.failed": { "post": { "operationId": "webhookTransferFailed", "summary": "transfer.failed", "x-docs": { "section": "webhooks", "order": 4, "product": "managedTransfers", "slug": "transfer-failed" }, "description": "Sent with the headers `X-MusicAPI-Event: transfer.failed` and `X-MusicAPI-Signature: t=,v1=`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "createdAt", "data" ], "properties": { "id": { "type": "string", "example": "evt_3d1f6c0e-8a52-4c1b-9a0e-2f4b7c9d1e33", "description": "The id of this delivery, `evt_`. A retry sends the same id, so dedupe by it. Two endpoints get two different ids for the same event. Deliveries queued before 2026-10-16 have no `id`." }, "event": { "type": "string", "const": "transfer.failed" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transferUuid" ], "properties": { "transferUuid": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "completed" }, "totalItems": { "type": "integer" }, "processedItems": { "type": "integer" }, "matchedItems": { "type": "integer" }, "unmatchedItems": { "type": "integer" }, "skippedItems": { "type": "integer" }, "failedItems": { "type": "integer" }, "sourceIntegrationType": { "type": "string", "example": "spotify" }, "targetIntegrationType": { "type": "string", "example": "tidal" }, "resultsUrl": { "type": "string", "format": "uri", "description": "The Match Results API address of the unmatched items." }, "stage": { "type": "string", "description": "Only when the transfer failed before it finished: the stage that failed." }, "error": { "type": "string", "description": "Our internal error text. It can change and is not written for end users: show `failureReason` instead." }, "errorType": { "type": [ "string", "null" ] }, "endUserId": { "type": [ "string", "null" ], "example": "your-user-8841", "description": "Your own id for the person: the `externalUserId` of the session, else the `merchantUserId` of the source login. Null when you sent neither." }, "batch": { "anyOf": [ { "$ref": "#/components/schemas/TransferWebhookBatch" }, { "type": "null" } ], "description": "The batch of the transfer. Null for a transfer that was made alone." }, "errorName": { "type": "string", "example": "FetchError", "description": "Only when the transfer failed before it finished: the class name of the error. For a bug report or a dashboard, not for a branch." }, "failureReason": { "type": "string", "enum": [ "notAuthenticated", "rateLimited", "targetRefused", "unknown" ], "description": "Why the transfer failed, in a value you may branch on. `notAuthenticated`: an account was signed out and could not be recovered. `rateLimited`: a music service asked us to slow down too often; the same transfer would work later. `targetRefused`: the transfer ran to the end, but the destination refused its playlists or items. `unknown`: anything else." }, "failureSide": { "type": [ "string", "null" ], "enum": [ "source", "target", null ], "description": "The end of the transfer that failed. Null when we cannot tell." } } } } } } } }, "responses": { "200": { "description": "Answer any 2xx within 10 seconds. Any other answer is retried." } } } }, "transfer.cancelled": { "post": { "operationId": "webhookTransferCancelled", "summary": "transfer.cancelled", "x-docs": { "section": "webhooks", "order": 5, "product": "managedTransfers", "slug": "transfer-cancelled" }, "description": "Sent with the headers `X-MusicAPI-Event: transfer.cancelled` and `X-MusicAPI-Signature: t=,v1=`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "createdAt", "data" ], "properties": { "id": { "type": "string", "example": "evt_3d1f6c0e-8a52-4c1b-9a0e-2f4b7c9d1e33", "description": "The id of this delivery, `evt_`. A retry sends the same id, so dedupe by it. Two endpoints get two different ids for the same event. Deliveries queued before 2026-10-16 have no `id`." }, "event": { "type": "string", "const": "transfer.cancelled" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transferUuid" ], "properties": { "transferUuid": { "type": "string", "format": "uuid" }, "totalItems": { "type": "integer" }, "processedItems": { "type": "integer" }, "matchedItems": { "type": "integer" }, "unmatchedItems": { "type": "integer" }, "skippedItems": { "type": "integer" }, "failedItems": { "type": "integer" }, "sourceIntegrationType": { "type": "string", "example": "spotify" }, "targetIntegrationType": { "type": "string", "example": "tidal" }, "endUserId": { "type": [ "string", "null" ], "example": "your-user-8841", "description": "Your own id for the person: the `externalUserId` of the session, else the `merchantUserId` of the source login. Null when you sent neither." }, "batch": { "anyOf": [ { "$ref": "#/components/schemas/TransferWebhookBatch" }, { "type": "null" } ], "description": "The batch of the transfer. Null for a transfer that was made alone." } } } } } } } }, "responses": { "200": { "description": "Answer any 2xx within 10 seconds. Any other answer is retried." } } } }, "transfer.item_failed": { "post": { "operationId": "webhookTransferItemFailed", "summary": "transfer.item_failed", "x-docs": { "section": "webhooks", "order": 6, "product": "managedTransfers", "slug": "transfer-item-failed" }, "description": "Sent with the headers `X-MusicAPI-Event: transfer.item_failed` and `X-MusicAPI-Signature: t=,v1=`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "createdAt", "data" ], "properties": { "id": { "type": "string", "example": "evt_3d1f6c0e-8a52-4c1b-9a0e-2f4b7c9d1e33", "description": "The id of this delivery, `evt_`. A retry sends the same id, so dedupe by it. Two endpoints get two different ids for the same event. Deliveries queued before 2026-10-16 have no `id`." }, "event": { "type": "string", "const": "transfer.item_failed" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transferUuid", "groupName", "groupType", "newlyFailedCount", "items" ], "properties": { "transferUuid": { "type": "string", "format": "uuid" }, "groupName": { "type": [ "string", "null" ] }, "groupType": { "type": [ "string", "null" ] }, "newlyFailedCount": { "type": "integer" }, "items": { "type": "array", "maxItems": 50, "items": { "type": "object", "properties": { "name": { "type": "string" }, "artist": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] } } } }, "sourceIntegrationType": { "type": "string", "example": "spotify" }, "targetIntegrationType": { "type": "string", "example": "tidal" }, "endUserId": { "type": [ "string", "null" ], "example": "your-user-8841", "description": "Your own id for the person: the `externalUserId` of the session, else the `merchantUserId` of the source login. Null when you sent neither." }, "batch": { "anyOf": [ { "$ref": "#/components/schemas/TransferWebhookBatch" }, { "type": "null" } ], "description": "The batch of the transfer. Null for a transfer that was made alone." } } } } } } } }, "responses": { "200": { "description": "Answer any 2xx within 10 seconds. Any other answer is retried." } } } }, "transfer.synced": { "post": { "operationId": "webhookTransferSynced", "summary": "transfer.synced", "x-docs": { "section": "webhooks", "order": 7, "product": "managedTransfers", "slug": "transfer-synced" }, "description": "Sent with the headers `X-MusicAPI-Event: transfer.synced` and `X-MusicAPI-Signature: t=,v1=`.\n\nSent after a sync run of a synced transfer, when the run has news: every run in `planOnly` mode (the difference is worked out and nothing is written), a `full` run that wrote or failed to write something, and a `full` run that cleared the counts that an earlier `planOnly` run left. A `full` run with nothing to do sends nothing.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "createdAt", "data" ], "properties": { "id": { "type": "string", "example": "evt_3d1f6c0e-8a52-4c1b-9a0e-2f4b7c9d1e33", "description": "The id of this delivery, `evt_`. A retry sends the same id, so dedupe by it. Two endpoints get two different ids for the same event. Deliveries queued before 2026-10-16 have no `id`." }, "event": { "type": "string", "const": "transfer.synced" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transferUuid", "status", "syncMode", "name", "applied", "pending" ], "properties": { "transferUuid": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "completed", "description": "The status of the transfer after the run." }, "syncMode": { "type": "string", "enum": [ "full", "planOnly" ], "description": "`full` writes the difference to the destination. `planOnly` works out the difference and writes nothing." }, "name": { "type": [ "string", "null" ], "example": "Road trip", "description": "The name of the first playlist of the transfer." }, "applied": { "type": "object", "description": "What the run wrote at the destination.", "required": [ "added", "removed", "moved", "failed" ], "properties": { "added": { "type": "integer" }, "removed": { "type": "integer" }, "moved": { "type": "integer" }, "failed": { "type": "integer" } } }, "pending": { "type": "object", "description": "What waits because the run wrote nothing. All zeros in `full` mode.", "required": [ "adds", "removals", "moves" ], "properties": { "adds": { "type": "integer" }, "removals": { "type": "integer" }, "moves": { "type": "integer" } } }, "sourceIntegrationType": { "type": "string", "example": "spotify" }, "targetIntegrationType": { "type": "string", "example": "tidal" }, "endUserId": { "type": [ "string", "null" ], "example": "your-user-8841", "description": "Your own id for the person: the `externalUserId` of the session, else the `merchantUserId` of the source login. Null when you sent neither." }, "batch": { "anyOf": [ { "$ref": "#/components/schemas/TransferWebhookBatch" }, { "type": "null" } ], "description": "The batch of the transfer. Null for a transfer that was made alone." } } } } } } } }, "responses": { "200": { "description": "Answer any 2xx within 10 seconds. Any other answer is retried." } } } }, "user.authorized": { "post": { "operationId": "webhookUserAuthorized", "summary": "user.authorized", "x-docs": { "section": "webhooks", "order": 8, "product": "managedTransfers", "slug": "user-authorized" }, "description": "Sent with the headers `X-MusicAPI-Event: user.authorized` and `X-MusicAPI-Signature: t=,v1=`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "createdAt", "data" ], "properties": { "id": { "type": "string", "example": "evt_3d1f6c0e-8a52-4c1b-9a0e-2f4b7c9d1e33", "description": "The id of this delivery, `evt_`. A retry sends the same id, so dedupe by it. Two endpoints get two different ids for the same event. Deliveries queued before 2026-10-16 have no `id`." }, "event": { "type": "string", "const": "user.authorized" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "sessionUuid", "role", "integrationType", "integrationUserUuid", "preauthorized" ], "properties": { "sessionUuid": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "source", "target" ] }, "integrationType": { "type": [ "string", "null" ] }, "integrationUserUuid": { "type": "string", "format": "uuid" }, "preauthorized": { "type": "boolean" }, "externalUserId": { "type": "string", "description": "Only for a pre-authorized session." } } } } } } } }, "responses": { "200": { "description": "Answer any 2xx within 10 seconds. Any other answer is retried." } } } }, "user.auth_failed": { "post": { "operationId": "webhookUserAuthFailed", "summary": "user.auth_failed", "x-docs": { "section": "webhooks", "order": 9, "product": "managedTransfers", "slug": "user-auth-failed" }, "description": "Sent with the headers `X-MusicAPI-Event: user.auth_failed` and `X-MusicAPI-Signature: t=,v1=`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "createdAt", "data" ], "properties": { "id": { "type": "string", "example": "evt_3d1f6c0e-8a52-4c1b-9a0e-2f4b7c9d1e33", "description": "The id of this delivery, `evt_`. A retry sends the same id, so dedupe by it. Two endpoints get two different ids for the same event. Deliveries queued before 2026-10-16 have no `id`." }, "event": { "type": "string", "const": "user.auth_failed" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transferUuid", "side", "reason", "sessionUuid", "preauthorized" ], "properties": { "transferUuid": { "type": "string", "format": "uuid" }, "side": { "type": "string", "enum": [ "source", "target" ] }, "reason": { "type": "string" }, "sessionUuid": { "type": [ "string", "null" ], "format": "uuid" }, "preauthorized": { "type": "boolean" }, "externalUserId": { "type": [ "string", "null" ] }, "sourceIntegrationType": { "type": "string", "example": "spotify" }, "targetIntegrationType": { "type": "string", "example": "tidal" }, "endUserId": { "type": [ "string", "null" ], "example": "your-user-8841", "description": "Your own id for the person: the `externalUserId` of the session, else the `merchantUserId` of the source login. Null when you sent neither." }, "batch": { "anyOf": [ { "$ref": "#/components/schemas/TransferWebhookBatch" }, { "type": "null" } ], "description": "The batch of the transfer. Null for a transfer that was made alone." } } } } } } } }, "responses": { "200": { "description": "Answer any 2xx within 10 seconds. Any other answer is retried." } } } }, "match.report_ready": { "post": { "operationId": "webhookMatchReportReady", "summary": "match.report_ready", "x-docs": { "section": "webhooks", "order": 10, "product": "managedTransfers", "slug": "match-report-ready" }, "description": "Sent with the headers `X-MusicAPI-Event: match.report_ready` and `X-MusicAPI-Signature: t=,v1=`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "createdAt", "data" ], "properties": { "id": { "type": "string", "example": "evt_3d1f6c0e-8a52-4c1b-9a0e-2f4b7c9d1e33", "description": "The id of this delivery, `evt_`. A retry sends the same id, so dedupe by it. Two endpoints get two different ids for the same event. Deliveries queued before 2026-10-16 have no `id`." }, "event": { "type": "string", "const": "match.report_ready" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "transferUuid", "matchedItems", "unmatchedItems", "failedItems", "resultsUrl" ], "properties": { "transferUuid": { "type": "string", "format": "uuid" }, "matchedItems": { "type": "integer" }, "unmatchedItems": { "type": "integer" }, "failedItems": { "type": "integer" }, "resultsUrl": { "type": "string", "format": "uri" }, "sourceIntegrationType": { "type": "string", "example": "spotify" }, "targetIntegrationType": { "type": "string", "example": "tidal" }, "endUserId": { "type": [ "string", "null" ], "example": "your-user-8841", "description": "Your own id for the person: the `externalUserId` of the session, else the `merchantUserId` of the source login. Null when you sent neither." }, "batch": { "anyOf": [ { "$ref": "#/components/schemas/TransferWebhookBatch" }, { "type": "null" } ], "description": "The batch of the transfer. Null for a transfer that was made alone." } } } } } } } }, "responses": { "200": { "description": "Answer any 2xx within 10 seconds. Any other answer is retried." } } } } }, "components": { "securitySchemes": { "BasicAuth": { "type": "http", "scheme": "basic", "description": "`Authorization: Basic base64(clientId:clientSecret)`. Use it only from your backend." }, "TokenAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "`Authorization: Token ` or `Token `. Works on `/public/*` only." }, "DevTokenAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "`Authorization: DevToken ` signed with a key you uploaded. A token with `sub` works only for that connected user." }, "DocsSessionAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "`Authorization: DocsSession `. The docs site gets it when you sign in there. It acts as your account, but never as your Client Secret." }, "TransferSessionAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "`Authorization: TransferSession `. The hosted transfer wizard uses it. You do not send it yourself." } }, "parameters": { "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" }, "IntegrationUserUUIDParam": { "in": "path", "name": "integrationUserUUID", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The connected user: the `integrationUserUUID` from the sign-in callback." }, "ReturnUrlQuery": { "in": "query", "name": "returnUrl", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Where the user comes back to. It must be one of your Return URLs (Dashboard, Settings)." }, "RequestOneTimeTokenQuery": { "in": "query", "name": "requestOneTimeToken", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Add a one-time token to the callback. With it, your backend or app reads the raw service tokens once." }, "UniqueIdQuery": { "in": "query", "name": "uniqueId", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "A UUID v4 that you make. Poll `GET /app/integrations/byUniqueId/{uniqueId}` with it." }, "ForwardFailuresQuery": { "in": "query", "name": "forwardFailures", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Send the user back to `returnUrl` at once when the sign-in fails." }, "MerchantUserIdQuery": { "in": "query", "name": "merchantUserId", "required": false, "schema": { "type": "string" }, "description": "Your own id for this user. It is stored on the connected user and in the usage data." } }, "schemas": { "PublicSearchRequest": { "type": "object", "required": [ "type", "sources" ], "properties": { "type": { "type": "string", "enum": [ "track", "album", "artist" ], "example": "track" }, "track": { "type": "string", "example": "Bezos I", "description": "Track title." }, "artist": { "type": "string", "example": "Bo Burnham", "description": "Artist name." }, "album": { "type": "string", "example": "INSIDE", "description": "Album title." }, "sources": { "type": "array", "items": { "type": "string", "example": "spotify" }, "description": "At least one search source. `GET /public/search/introspection` lists the valid values." } } }, "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", "null" ], "items": { "type": "string", "example": "Bo Burnham" } }, "albumName": { "type": [ "string", "null" ], "example": "INSIDE" }, "imageUrl": { "type": "string", "example": "https://i.scdn.co/image/ab67616d0000b27388fed14b936c38007a302413" }, "previewUrl": { "type": [ "string", "null" ] }, "isrc": { "type": "string", "example": "" }, "duration": { "type": [ "integer", "null" ], "format": "int32", "example": 58149 }, "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", "null" ], "items": { "type": "string", "example": "Bo Burnham" } }, "albumName": { "type": "string", "example": "INSIDE" }, "imageUrl": { "type": "string", "example": "https://i.scdn.co/image/ab67616d00001e0288fed14b936c38007a302413" }, "previewUrl": { "type": [ "string", "null" ] }, "isrc": { "type": "string", "example": "" }, "duration": { "type": [ "number", "null" ], "example": 58149 }, "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", "youtube", "appleMusic", "amazonMusic", "tidal", "resso", "boomplay", "deezer", "pandora", "soundCloud", "youtubeMusic", "napster", "qobuz", "qqMusic", "yandexMusic", "vkMusic", "zvuk", "gaana", "jiosaavn", "audiomack", "audius" ] }, "nextParam": { "type": "string", "example": "eyJvZmZzZXQiOjEwfQ==", "description": "Pagination cursor. Omit to fetch the first page; to fetch a subsequent page pass the `nextParam` value returned in the previous response." } }, "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": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/TracksResponse" } ], "description": "Paginated playlist track results. Null if the playlist was not found." }, { "type": "null" } ] } } }, "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": "