API docs by Redocly

tunesynctool web API (0.1.0)

Download OpenAPI specification:

Web API wrapper for the tunesynctool Python package with some extra features.

Users

List all users on the instance

Returns information for all user accounts on the current instance.

Only users with admin rights should call this endpoint, otherwise the request will be rejected.

Authorizations:
OAuth2PasswordBearer

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "item_count": 0
}

Create a new user

Create a new user.

Anyone may create a new account for themselves, assuming their chosen username is not already taken.

The instance owner may disable account creation. In that case, an error will be returned.

Request Body schema: application/json
required
username
required
string (Username) [ 3 .. 255 ] characters

Username must be unique and be at least 3 characters long.

password
required
string (Password) [ 8 .. 255 ] characters

Password must be at least 8 characters long.

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "stringst"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "username": "string",
  • "is_admin": false
}

Get information about the authenticated user

Get the authenticated user.

Authorizations:
OAuth2PasswordBearer

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "username": "string",
  • "is_admin": false
}

Delete a user

Authorizations:
OAuth2PasswordBearer
path Parameters
id
required
integer (Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Authentication

Obtain a JWT token.

Generates a bearer JWT for the user.

Requires the user to provide their username and password. The JWT is returned in the response body.

Request Body schema: application/x-www-form-urlencoded
required
Grant Type (string) or Grant Type (null) (Grant Type)
username
required
string (Username)
password
required
string <password> (Password)
scope
string (Scope)
Default: ""
Client Id (string) or Client Id (null) (Client Id)
Client Secret (string) or Client Secret (null) <password> (Client Secret)

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0
}

Providers

Get the list of all accepted provider names

Returns a list of all accepted provider names that clients can set in the ?provider= query parameter across endpoints.

An example use of this endpoint would be to populate a dropdown list in the client UI in a search field.

Authorizations:
OAuth2PasswordBearer

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "item_count": 0
}

Generate a state for the provider

Generates a signed state to be used for OAuth2 authentication flows.

This is required for providers that users can link by going through an OAuth2 flow.

Authorizations:
OAuth2PasswordBearer
path Parameters
provider_name
required
string (Provider Name)
Request Body schema: application/json
required
redirect_uri
required
string <uri> (Redirect Uri) non-empty

The redirect URI specified by the client.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0
}

Catalog

Search for tracks

Search using the specified provider. This is basically a proxy.

Results are returned in the order they are received from the provider, meaning you should not rely on their order.

Notes:

  • Content other than tracks (e.g. podcasts, albums, etc.) are omitted from the results if this type of filtering is supported by the provider.
  • For YouTube, results are limited to any video that belongs to the "Music" category. This means that the results may include irrelevant content.
  • YouTube results may include results from "Topic" channels, which are not actual artist channels.
Authorizations:
OAuth2PasswordBearer
query Parameters
provider
required
string (Provider)
query
required
string (Query) [ 3 .. 100 ] characters
limit
integer (Limit) [ 1 .. 10 ]
Default: 5

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "query": "string",
  • "item_count": 0
}

Get a track by its ISRC

Search using the specified provider by a specific ISRC identifier. This is basically a proxy.

Notes:

  • Not all providers support direct ISRC search. If this is the case, an error will be returned.
Authorizations:
OAuth2PasswordBearer
path Parameters
isrc
required
string (Isrc)
query Parameters
provider
required
string (Provider)

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "album_name": "string",
  • "duration": 0,
  • "track_number": 0,
  • "release_year": 0,
  • "author": {
    },
  • "identifiers": {
    },
  • "assets": {
    },
  • "meta": {
    }
}

Get a track by its ID

Retrieve a track by its ID from the specified provider. This is basically a proxy.

Notes:

  • Some providers (like Spotify) may support multiple ID formats. In these cases, all formats are supported.
Authorizations:
OAuth2PasswordBearer
path Parameters
provider_id
required
string (Provider Id)
query Parameters
provider
required
string (Provider)

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "album_name": "string",
  • "duration": 0,
  • "track_number": 0,
  • "release_year": 0,
  • "author": {
    },
  • "identifiers": {
    },
  • "assets": {
    },
  • "meta": {
    }
}

Get a playlist by its ID

Retrieve a playlist by its ID from the specified provider. This is basically a proxy.

Notes:

  • Some providers (like Spotify) may support multiple ID formats. In these cases, all formats are supported.
Authorizations:
OAuth2PasswordBearer
path Parameters
provider_id
required
string (Provider Id)
query Parameters
provider
required
string (Provider)

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "is_public": true,
  • "author": {
    },
  • "meta": {
    },
  • "identifiers": {
    },
  • "assets": {
    }
}

Get all tracks from a playlist

Retrieve a playlist by its ID from the specified provider. This is basically a proxy.

Notes:

  • Some providers (like Spotify) may support multiple ID formats. In these cases, all formats are supported.
  • This endpoint is not suitable to retrieve the user's saved tracks. Use the appropriate endpoint for that.
Authorizations:
OAuth2PasswordBearer
path Parameters
provider_id
required
string (Provider Id)
query Parameters
provider
required
string (Provider)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "item_count": 0
}

Add tracks to a playlist

Add a track to a playlist on the specified provider.

Authorizations:
OAuth2PasswordBearer
path Parameters
provider_id
required
string (Provider Id)
query Parameters
provider
required
string (Provider)
Request Body schema: application/json
required
provider_ids
required
Array of strings (Provider Ids)

ID of the track to be inserted. Cannot be an empty string.

Responses

Request samples

Content type
application/json
{
  • "provider_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "item_count": 0
}

Get playlists owned (and saved) by the user

Returns all playlists the user owns or has saved to their library on the specified provider. Keep in mind that results may not be exhaustive. Some providers may not return all playlists like those that are automatically generated.

Notes:

  • YouTube does not support retrieving playlists that are saved but not owned by the linked account.
  • YouTube results are not filtered to only contain music related playlists (e.g. any owned playlist will be returned).
  • This endpoint doesn't return the "liked music" playlist for all providers. Use the appropriate endpoint for that.
Authorizations:
OAuth2PasswordBearer
query Parameters
provider
required
string (Provider)
limit
integer (Limit) >= 0
Default: 0

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "item_count": 0
}

Create a new playlist

Create a new playlist on the specified provider.

To keep things uniform, you cannot add initial tracks to the playlist because not all providers support this.

Authorizations:
OAuth2PasswordBearer
query Parameters
provider
required
string (Provider)
Request Body schema: application/json
required
title
required
string (Title)

Title of the playlist. Cannot be an empty string.

Responses

Request samples

Content type
application/json
{
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "is_public": true,
  • "author": {
    },
  • "meta": {
    },
  • "identifiers": {
    },
  • "assets": {
    }
}

Get the user's saved (liked) tracks at a provider

Returns the user's saved tracks (aka. liked music) on the specified provider.

Authorizations:
OAuth2PasswordBearer
query Parameters
provider
required
string (Provider)
limit
integer (Limit) >= 0
Default: 0

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "item_count": 0
}

Tasks

Find the equivalent track on another provider

Matches a track based on the provided metadata. Finding a match is not 100% guaranteed.

This can take anywhere from a few seconds to up to half a minute in extreme cases.

Notes:

  • The metadata provided is not used to populate the returned data.
  • The returned data is the closest match found by an automated search algorithm, not 100% guaranteed to be the same track.
  • The returned data may be a different version of the same track (e.g. live version, remix, etc.).
  • Do your own client-side validation to ensure the returned track is what you or your users expect.
Authorizations:
OAuth2PasswordBearer
query Parameters
provider
required
string (Provider)

Name of the provider to search with.

Request Body schema: application/json
required
title
required
string (Title)

Title of the track.

required
Album Name (string) or Album Name (null) (Album Name)

Name of the album (if available).

Duration (integer) or Duration (null) (Duration)

Duration of the track in seconds (if available).

Track Number (integer) or Track Number (null) (Track Number)

Track number in the album (if available).

Release Year (integer) or Release Year (null) (Release Year)

Release year of the track (if available).

required
object (EntityMultiAuthorRead)

Authors of the track.

required
object (TrackIdentifiersThirdPartyBase)

Identifiers of the track.

required
object (EntityAssetsBase)

Assets of the track.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "album_name": "string",
  • "duration": 0,
  • "track_number": 0,
  • "release_year": 0,
  • "author": {
    },
  • "identifiers": {
    },
  • "assets": {
    }
}

Response samples

Content type
application/json
{
  • "title": "string",
  • "album_name": "string",
  • "duration": 0,
  • "track_number": 0,
  • "release_year": 0,
  • "author": {
    },
  • "identifiers": {
    },
  • "assets": {
    },
  • "meta": {
    }
}

Transfer a playlist to another provider

Attempts to transfer the specified playlist from the source provider to the target provider. Replication is not guaranteed to be 100% successful.

This starts a long running task. Clients can poll for the progress of the transfer.

Authorizations:
OAuth2PasswordBearer
Request Body schema: application/json
required
from_provider
required
string (From Provider)

Origin provider for the playlist.

to_provider
required
string (To Provider)

Target provider to replicate the playlist on.

kind
required
string (TaskKind)
Value: "playlist_transfer"

The type of the task.

is_dry_run
required
boolean (Is Dry Run)

If True, write operations will be avoided where possible.

from_playlist
required
string (From Playlist)

Source playlist you wish to replicate.

Responses

Request samples

Content type
application/json
{
  • "from_provider": "string",
  • "to_provider": "string",
  • "kind": "playlist_transfer",
  • "is_dry_run": true,
  • "from_playlist": "string"
}

Response samples

Content type
application/json
{
  • "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  • "status": "running",
  • "status_reason": "string",
  • "queued_at": 0,
  • "started_at": 0,
  • "done_at": 0,
  • "worker_id": "string",
  • "last_heartbeat": 0,
  • "arguments": {
    },
  • "progress": {
    }
}

List all tasks

Returns all tasks belonging to the authenticated user, regardless of if they are running, in queue, or finished. The only exception is deleted tasks, for obvious reasons.

Authorizations:
OAuth2PasswordBearer

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "item_count": 0
}

Manually cancel a task

Cancels the specified task. Users can only cancel their own tasks. It may take a few seconds for the background workers to honor this request.

Only tasks that are still active (queued, running, or on hold) are cancelled. Tasks that have already reached a terminal state (finished, failed, or cancelled) are left untouched and remain in the user's history.

Authorizations:
OAuth2PasswordBearer
path Parameters
task_id
required
string <uuid> (Task Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Manually delete a task

Deletes the specified task. Users can only delete their own tasks. It may take a few seconds for the background workers to honor this request.

Both active and inactive tasks can be deleted. The difference between this endpoint and the cancellation endpoint is that this removes the task from the task history.

Authorizations:
OAuth2PasswordBearer
path Parameters
task_id
required
string <uuid> (Task Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Library

Get the user's playlists across all providers

Compiles a list of playlists the user owns and has saved to their library across all of their linked providers.

Please note that this endpoint may not return up-to-date data because it relies on caching to prevent excessive API calls.

Notes:

  • Some providers do not return all playlists (e.g. Spotify's automatically generated playlists).
  • Some providers do not support retrieving playlists that are saved but not owned by the linked account (e.g. YouTube).
  • This endpoint returns all playlists it finds. Checking wether 2 playlists are the same but synced is up to the client.
Authorizations:
OAuth2PasswordBearer

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "item_count": 0
}

Spotify

Start the Spotify Authorization Code Flow

Starts the Spotify Authorization Code Flow. Redirects the user to the Spotify authorization page. The user will be asked to log in and authorize the application.

Details: https://developer.spotify.com/documentation/web-api/tutorials/code-flow

Takes a state parameter that includes metadata about the client.

query Parameters
state
required
string (State)

Responses

Response samples

Content type
application/json
null

Unlink Spotify

Unlinks the Spotify account associated with the user.

Authorizations:
OAuth2PasswordBearer
query Parameters
provider
required
string (Provider)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Deezer

Set the Deezer ARL cookie

Allows the user to set their Deezer ARL cookie.

Authorizations:
OAuth2PasswordBearer
Request Body schema: application/json
required
arl
required
string (Arl)

The ARL cookie's value.

Responses

Request samples

Content type
application/json
{
  • "arl": "string"
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Unlink Deezer

Unlinks the Deezer account associated with the user.

Authorizations:
OAuth2PasswordBearer
query Parameters
provider
required
string (Provider)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Subsonic

Set the Subsonic credentials

Allows the user to set their Subsonic credentials.

Authorizations:
OAuth2PasswordBearer
Request Body schema: application/json
required
username
required
string (Username)

The Subsonic username.

password
required
string (Password)

The Subsonic password.

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Unlink Subsonic

Unlinks the Subsonic account associated with the user.

Authorizations:
OAuth2PasswordBearer
query Parameters
provider
required
string (Provider)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

YouTube

Start the YouTube Authorization Code Flow

Starts the YouTube Authorization Code Flow. Redirects the user to the YouTube authorization page. The user will be asked to log in and authorize the application.

Details: https://developers.google.com/identity/protocols/oauth2

Takes a state parameter that includes metadata about the client.

query Parameters
state
required
string (State)

Responses

Response samples

Content type
application/json
null

Unlink YouTube

Unlinks the Google account associated with the user.

Authorizations:
OAuth2PasswordBearer
query Parameters
provider
required
string (Provider)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}