Loading API Docs
Developer documentation for YourMusic
YourMusic
API docs by Redocly

YourMusic API (0.2.0)

Download OpenAPI specification:

API for YourMusic streaming service. Provides endpoints for user management, music catalog access, and streaming.

Public & Health

Heartbeat and service status endpoints.

Heartbeat

Responses

Response samples

Content type
application/json
{
  • "time": "2025-11-01T09:37:15+00:00"
}

Aggregator status

Responses

Response samples

Content type
application/json
{
  • "status": "up"
}

Edge Operations

Internal operational endpoints for edge reachability reporting.

Store edge reachability observation

Internal endpoint used by blackbox probes to report public reachability for an edge.

Authorizations:
BlackboxProbeToken
Request Body schema: application/json
required
edge_key
required
string

Stable edge node key.

source
required
string <= 128 characters

Unique blackbox probe source name.

source_type
required
string
Value: "blackbox"

Only blackbox observations are accepted by this endpoint.

status
required
string
Enum: "REACHABLE" "UNREACHABLE"
checked_at
required
string <date-time>

Probe timestamp. Must be fresh and not beyond the configured future tolerance.

http_status
integer or null [ 100 .. 599 ]
latency_ms
integer or null >= 0
failure_reason
string or null <= 512 characters
object or null

Responses

Request samples

Content type
application/json
{
  • "edge_key": "edge-eu-central-1-a",
  • "source": "aws-blackbox-eu-central-1",
  • "source_type": "blackbox",
  • "status": "UNREACHABLE",
  • "checked_at": "2026-06-29T22:14:06Z",
  • "latency_ms": 5001,
  • "failure_reason": "timeout",
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "stream_edge_id": "91518389-73aa-4074-b673-10132c50d7b6",
  • "source": "string",
  • "source_type": "blackbox",
  • "status": "REACHABLE",
  • "checked_at": "2019-08-24T14:15:22Z"
}

Authentication

OAuth2 client credentials token issuance.

Issue OAuth2 client token

Client credentials token endpoint accepting JSON (preferred) or form data.

Request Body schema:
required
grant_type
required
string
Value: "client_credentials"
client_id
required
string
client_secret
required
string

Responses

Request samples

Content type
grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret

Response samples

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

Issue user access token

Issues an access token for the specified user/device using client credentials.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>

ID of the end user for whom the access token is issued.

Request Body schema: application/json
required
deviceId
required
string <uuid>

Unique identifier of the device the access token is bound to.

Responses

Request samples

Content type
application/json
{
  • "deviceId": "a9b66a51-3cb6-4e66-bb94-675e83380fe5"
}

Response samples

Content type
application/json
{
  • "token_type": "Bearer",
  • "expires_in": 600,
  • "token": "token-string"
}

Users

Tenant-authenticated (M2M) endpoints for user management.

List users

Returns a paginated list of users. Supports the page query parameter. Page size is server-configured and defaults to 50 when not overridden by deployment configuration.

Authorizations:
OAuth2
query Parameters
page
integer >= 1
Default: 1

Page number (1-based).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": { },
  • "meta": { }
}

Create user

Creates a new user.

Authorizations:
OAuth2
Request Body schema: application/json
required
first_name
required
string
last_name
required
string
email
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "status": "SUBSCRIBED",
  • "linked_providers": [
    ],
  • "has_email_setup": true,
  • "subscription_ends_at": "2019-08-24T14:15:22Z",
  • "pm_type": "string",
  • "pm_last_four": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get user

Returns details of a specific user.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>

ID of the user.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "status": "SUBSCRIBED",
  • "linked_providers": [
    ],
  • "has_email_setup": true,
  • "subscription_ends_at": "2019-08-24T14:15:22Z",
  • "pm_type": "string",
  • "pm_last_four": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update user

Updates details of a specific user.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>

ID of the user.

Request Body schema: application/json
required
first_name
string
last_name
string
email
string <email>

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "status": "SUBSCRIBED",
  • "linked_providers": [
    ],
  • "has_email_setup": true,
  • "subscription_ends_at": "2019-08-24T14:15:22Z",
  • "pm_type": "string",
  • "pm_last_four": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete user

Deletes a specific user.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>

ID of the user.

Responses

Issue user access token

Issues an access token for the specified user/device using client credentials.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>

ID of the end user for whom the access token is issued.

Request Body schema: application/json
required
deviceId
required
string <uuid>

Unique identifier of the device the access token is bound to.

Responses

Request samples

Content type
application/json
{
  • "deviceId": "a9b66a51-3cb6-4e66-bb94-675e83380fe5"
}

Response samples

Content type
application/json
{
  • "token_type": "Bearer",
  • "expires_in": 600,
  • "token": "token-string"
}

Authentication

Request email OTP

Resolves the authentication path for the given tenant/email pair. Standard users receive path: otp; if the address is valid, a code is sent. Accounts that use password authentication receive path: password and no OTP is sent. Invalid tenants return the generic path: otp response and send nothing. The OTP response does not reveal whether a standard user email exists. Rate limits apply per IP (throttle) and per email (min interval between sends, max sends per hour).

Request Body schema: application/json
required
tenant
required
string <= 255 characters

Tenant slug that scopes OTP issuance and verification.

email
required
string <email> <= 255 characters

Email address to send the one-time code to.

locale
string
Enum: "en" "nl" "fr" "de"

Preferred language for the OTP email (en, nl, fr, de). Defaults to en if omitted.

Responses

Request samples

Content type
application/json
{
  • "tenant": "acme",
  • "email": "user@example.com",
  • "locale": "en"
}

Response samples

Content type
application/json
Example
{
  • "path": "otp",
  • "message": "If that email address is valid, a verification code has been sent."
}

Authenticate with email OTP

Verifies an email OTP in a tenant context and returns a user session. Existing users receive access and refresh tokens. If no user exists for that tenant/email, an onboarding token is returned.

Request Body schema: application/json
required
tenant
required
string <= 255 characters
email
required
string <email> <= 255 characters
code
required
string <= 32 characters
device_id
required
string <uuid>
onboarding_token
string

Optional token from social callback when verification is required.

Responses

Request samples

Content type
application/json
{
  • "tenant": "acme",
  • "email": "user@example.com",
  • "code": "12345",
  • "device_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response samples

Content type
application/json
Example
{
  • "token_type": "Bearer",
  • "access_token": "string",
  • "expires_in": 3600,
  • "refresh_token": "string",
  • "refresh_expires_in": 2592000,
  • "user": {
    }
}

Authenticate with password

Authenticates an account that is eligible for password sign-in. On success, returns the same session response shape as OTP login.

Request Body schema: application/json
required
tenant
required
string <= 255 characters
email
required
string <email> <= 255 characters
password
required
string <= 255 characters
device_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "tenant": "acme",
  • "email": "user@example.com",
  • "password": "account-password",
  • "device_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response samples

Content type
application/json
{
  • "token_type": "Bearer",
  • "access_token": "string",
  • "expires_in": 3600,
  • "refresh_token": "string",
  • "refresh_expires_in": 2592000,
  • "user": {
    }
}

Signup

Consumes a one-time onboarding token from email OTP authentication and creates the user (or reuses existing) and issues a session.

Request Body schema: application/json
required
onboarding_token
required
string
first_name
required
string <= 255 characters
last_name
required
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "onboarding_token": "plain-token-from-authenticate-response",
  • "first_name": "Jane",
  • "last_name": "Doe"
}

Response samples

Content type
application/json
{
  • "token_type": "Bearer",
  • "access_token": "string",
  • "expires_in": 3600,
  • "refresh_token": "string",
  • "refresh_expires_in": 2592000,
  • "user": {
    }
}

Refresh passwordless session

Exchanges a valid refresh token for a new access token and a new refresh token. The previous refresh token can no longer be used.

Request Body schema: application/json
required
refresh_token
required
string <= 512 characters

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "plain-refresh-token-from-authenticate-or-previous-refresh"
}

Response samples

Content type
application/json
{
  • "token_type": "Bearer",
  • "access_token": "string",
  • "expires_in": 3600,
  • "refresh_token": "string",
  • "refresh_expires_in": 2592000,
  • "user": {
    }
}

Logout device session

Ends the session for the given refresh token. Returns 204 with no body. Safe to call with an invalid or already-used token.

Request Body schema: application/json
required
refresh_token
required
string <= 512 characters

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "plain-refresh-token-to-revoke"
}

Response samples

Content type
application/json
{
  • "message": "The given data was invalid.",
  • "errors": {
    }
}

Initiate Social OIDC Redirect

Initiates the OIDC authentication flow by redirecting the user to the specified provider (Google, Apple, or Facebook). The client should open this URL in a browser.

path Parameters
provider
required
string
Enum: "google" "apple" "facebook"

The social provider name

query Parameters
tenant
required
string

The tenant slug

device_id
required
string <uuid>

The unique identifier for the user's device

redirect_to
required
string

The deep link URL to redirect back to in the app (e.g., yourapp://auth/callback).

intent_token
string

A short-lived token obtained from /auth/social/link-intent to link the social provider to an already authenticated user.

Responses

Response samples

Content type
application/json
{
  • "message": "The given data was invalid.",
  • "errors": {
    }
}

Social OIDC Callback

Handles the redirect back from the social provider. Processes the user data and redirects back to the mobile app's deep link. Both GET and POST methods are supported to accommodate different provider response modes (e.g., Apple's form_post).

After successful authentication with the provider, the user is redirected back to the redirect_to URL with the following parameters:

  • status: One of success, onboarding_required, verification_required, or failed.
  • action: login or link.
  • onboarding_token: Present if status is onboarding_required or verification_required.
  • email: The email from the social provider.
  • tenant: The slug of the tenant.
  • Optional onboarding profile hints when provided by the social provider:
    • first_name
    • last_name
  • access_token, refresh_token, expires_in: Present if status is success and action is login.
path Parameters
provider
required
string
Enum: "google" "apple" "facebook"
query Parameters
state
required
string

The encoded state payload returned by the provider.

code
string

The authorization code from the provider.

Responses

Response samples

Content type
application/json
{
  • "message": "Unauthenticated."
}

Social OIDC Callback (POST)

Handles the POST redirect back from the social provider (e.g., Apple Sign-In using form_post). Processes the user data and redirects back to the mobile app's deep link.

path Parameters
provider
required
string
Enum: "google" "apple" "facebook"
Request Body schema: application/x-www-form-urlencoded
state
required
string

The encoded state payload returned by the provider.

code
string

The authorization code from the provider.

id_token
string

The OIDC ID token (often sent by Apple).

user
string

The user profile data (sent by Apple on first login).

Responses

Response samples

Content type
application/json
{
  • "message": "Unauthenticated."
}

Create Social Link Intent

Generates a secure, short-lived token that allows an already authenticated user to link a social provider in a browser flow. The user should call this before opening the /redirect endpoint.

Authorizations:
UserSession

Responses

Response samples

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

Unlink Social Provider

Removes a linked social identity from the authenticated user. A user can only unlink a provider if they have another way to log in (email/OTP setup OR another social provider).

Authorizations:
UserSession
path Parameters
provider
required
string
Enum: "google" "apple" "facebook"

Responses

Profile

End-user self-profile endpoints.

Current user profile

Returns profile data for the authenticated caller.

Authorizations:
UserSession

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "status": "SUBSCRIBED",
  • "linked_providers": [
    ],
  • "has_email_setup": true,
  • "subscription_ends_at": "2019-08-24T14:15:22Z",
  • "pm_type": "string",
  • "pm_last_four": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update current user profile

Updates editable profile fields for the authenticated caller.

Authorizations:
UserSession
Request Body schema: application/json
required
first_name
string
last_name
string

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "status": "SUBSCRIBED",
  • "linked_providers": [
    ],
  • "has_email_setup": true,
  • "subscription_ends_at": "2019-08-24T14:15:22Z",
  • "pm_type": "string",
  • "pm_last_four": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete current user account

Confirms an authenticated account deletion request using an account-deletion OTP. The account is immediately disabled and anonymized, sessions are revoked, and remote cleanup plus the deletion receipt email and hard purge are completed asynchronously.

Authorizations:
UserSession
Request Body schema: application/json
required
code
required
string [ 1 .. 10 ] characters
locale
string
Enum: "en" "nl" "fr" "de"

Responses

Request samples

Content type
application/json
{
  • "code": "12345",
  • "locale": "en"
}

Response samples

Content type
application/json
{
  • "message": "Invalid authentication code."
}

Request account deletion confirmation code

Sends an account-deletion OTP to the authenticated user's current email address.

Authorizations:
UserSession
Request Body schema: application/json
optional
locale
string
Enum: "en" "nl" "fr" "de"

Responses

Request samples

Content type
application/json
{
  • "locale": "en"
}

Response samples

Content type
application/json
{
  • "message": "Verification code sent."
}

Request email change confirmation code

Starts an authenticated email-change confirmation flow for the supplied email address.

Authorizations:
UserSession
Request Body schema: application/json
required
email
required
string <email>
locale
string
Enum: "en" "nl" "fr" "de"

Responses

Request samples

Content type
application/json
{
  • "email": "new@example.com"
}

Response samples

Content type
application/json
{
  • "message": "Verification code sent."
}

Confirm email change

Confirms an authenticated email change using a confirmation code.

Authorizations:
UserSession
Request Body schema: application/json
required
email
required
string <email>
code
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "new@example.com",
  • "code": "12345"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "status": "SUBSCRIBED",
  • "linked_providers": [
    ],
  • "has_email_setup": true,
  • "subscription_ends_at": "2019-08-24T14:15:22Z",
  • "pm_type": "string",
  • "pm_last_four": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Checkout

Create checkout session

Creates a hosted checkout session for a subscription product. Optionally accepts custom redirect URLs that must match configured allowed patterns.

Authorizations:
UserSession
Request Body schema: application/json
required
product_slug
required
string

Slug of the subscription product to checkout

success_url
string <uri>

Optional custom redirect URL for successful payment. Must match one of the configured allowed redirect URL patterns. If not provided, the default success_url is used.

cancel_url
string <uri>

Optional custom redirect URL for cancelled payment. Must match one of the configured allowed redirect URL patterns. If not provided, the default cancel_url is used.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Home

Composed home page. Auth optional; guests send X-Tenant (slug), authenticated use user's tenant.

Get home page

Returns the composed home page. Authentication is optional. Authenticated — tenant is derived from the user. Guest — X-Tenant header (tenant slug) is required. If Authorization is present but token is invalid or expired, returns 401 INVALID_AUTH_TOKEN.

header Parameters
X-Tenant
string
Example: acme-records

Tenant slug (e.g. acme-records). Required when unauthenticated; ignored when authenticated.

Responses

Response samples

Content type
application/json
{
  • "page": {
    },
  • "modules": [
    ]
}

Search

Search across artists, releases, tracks, and playlists. Auth optional; playlists only returned when authenticated.

Search

Search across artists, releases, tracks, and playlists from the local database. Authentication is optional — catalog results (artists, releases, tracks) are always returned. Playlists are only included when authenticated (user's own + public within the same tenant).

query Parameters
q
required
string non-empty

Search query string

limit
integer [ 1 .. 20 ]
Default: 5

Maximum number of results per entity type

Responses

Response samples

Content type
application/json
{}

Library

User library — liked tracks, saved releases, followed artists, saved playlists. All endpoints require authentication.

List liked tracks

Returns a cursor-paginated list of tracks the user has liked, ordered by most recently added.

Authorizations:
UserSession
query Parameters
cursor
string

Cursor for pagination

page_size
integer [ 1 .. 50 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Like a track

Adds a track to the user's library. Idempotent — returns 201 on first like, 200 if already liked.

Authorizations:
UserSession
path Parameters
trackId
required
string <uuid>

Responses

Unlike a track

Removes a track from the user's library.

Authorizations:
UserSession
path Parameters
trackId
required
string <uuid>

Responses

List saved releases

Returns a cursor-paginated list of releases the user has saved, ordered by most recently added.

Authorizations:
UserSession
query Parameters
cursor
string
page_size
integer [ 1 .. 50 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Save a release

Authorizations:
UserSession
path Parameters
releaseId
required
string <uuid>

Responses

Unsave a release

Authorizations:
UserSession
path Parameters
releaseId
required
string <uuid>

Responses

List followed artists

Returns a cursor-paginated list of artists the user follows, ordered by most recently added.

Authorizations:
UserSession
query Parameters
cursor
string
page_size
integer [ 1 .. 50 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Follow an artist

Authorizations:
UserSession
path Parameters
artistId
required
string <uuid>

Responses

Unfollow an artist

Authorizations:
UserSession
path Parameters
artistId
required
string <uuid>

Responses

List library playlists

Returns owned playlists and saved public playlists, cursor-paginated and ordered by most recently added.

Authorizations:
UserSession
query Parameters
cursor
string
page_size
integer [ 1 .. 50 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Save a playlist

Saves a public playlist to the user's library. Own playlists are auto-added on creation.

Authorizations:
UserSession
path Parameters
playlistId
required
string <uuid>

Responses

Unsave a playlist

Removes a saved playlist from the user's library. Own playlists cannot be unsaved.

Authorizations:
UserSession
path Parameters
playlistId
required
string <uuid>

Responses

Playlists

Search playlists

Returns a listing of playlists matching the given keyword. Includes owned and public playlists.

Authorizations:
UserSession
query Parameters
keyword
required
string

Keyword to match against playlist name.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

List user playlists

Returns a listing of playlists owned by the user.

Authorizations:
UserSession

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create playlist

Creates a new playlist for the user.

Authorizations:
UserSession
Request Body schema: application/json
required
playlist_name
required
string
public
boolean

Responses

Request samples

Content type
application/json
{
  • "playlist_name": "string",
  • "public": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "playlist_name": "string",
  • "public": true,
  • "track_count": 0,
  • "artwork_url_template": "string",
  • "subtitle": "string"
}

Get playlist

Returns details of a specific playlist.

Authorizations:
UserSession
path Parameters
playlist_id
required
string <uuid>

ID of the playlist.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "playlist_name": "string",
  • "public": true,
  • "track_count": 0,
  • "artwork_url_template": "string",
  • "subtitle": "string"
}

Update playlist

Updates details of an owned playlist.

Authorizations:
UserSession
path Parameters
playlist_id
required
string <uuid>

ID of the playlist.

Request Body schema: application/json
required
playlist_name
string
public
boolean

Responses

Request samples

Content type
application/json
{
  • "playlist_name": "string",
  • "public": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "playlist_name": "string",
  • "public": true,
  • "track_count": 0,
  • "artwork_url_template": "string",
  • "subtitle": "string"
}

Delete playlist

Deletes an owned playlist and its tracks.

Authorizations:
UserSession
path Parameters
playlist_id
required
string <uuid>

ID of the playlist.

Responses

Get playlist tracks

Returns tracks for a specific playlist.

Authorizations:
UserSession
path Parameters
playlist_id
required
string <uuid>

ID of the playlist.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add track to playlist

Adds a single track to the end of the playlist.

Authorizations:
UserSession
path Parameters
playlist_id
required
string <uuid>

ID of the playlist.

Request Body schema: application/json
required
track_id
required
string

ID of the track to add.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "artist_name": "string",
  • "artwork_url_template": "string",
  • "duration_seconds": 0,
  • "explicit": true,
  • "stream_url": "http://example.com",
  • "is_liked": false,
  • "playlist_track_id": "c19f1243-9460-4cce-bd98-3a2a9f77e1b8",
  • "order": 0
}

Update playlist tracks

Replaces all tracks in the playlist with the provided set.

Authorizations:
UserSession
path Parameters
playlist_id
required
string <uuid>

ID of the playlist.

Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

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

Response samples

Content type
application/json
[
  • {
    }
]

Remove track from playlist

Removes a single track and reorders the remaining tracks.

Authorizations:
UserSession
path Parameters
playlist_id
required
string <uuid>
playlistTrackId
required
string <uuid>

Responses

Move track within playlist

Reorders a track and shifts other tracks accordingly.

Authorizations:
UserSession
path Parameters
playlist_id
required
string <uuid>
playlistTrackId
required
string <uuid>
Request Body schema: application/json
required
order
required
integer >= 1

Responses

Request samples

Content type
application/json
{
  • "order": 1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "artist_name": "string",
  • "artwork_url_template": "string",
  • "duration_seconds": 0,
  • "explicit": true,
  • "stream_url": "http://example.com",
  • "is_liked": false,
  • "playlist_track_id": "c19f1243-9460-4cce-bd98-3a2a9f77e1b8",
  • "order": 0
}

Artists

Get artist

Get an artist by ID from the local catalog.

path Parameters
id
required
string <uuid>

Artist UUID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "is_followed": false
}

Get artist releases

Get paginated releases for an artist, ordered by year descending.

path Parameters
id
required
string <uuid>

Artist UUID

query Parameters
page
integer >= 1
Default: 1
page_size
integer [ 1 .. 50 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Search artists Deprecated

Search for artists using the aggregator service.

Authorizations:
OAuth2
query Parameters
q
required
string

Search terms

page
integer >= 1

Page number

pageSize
integer [ 10 .. 50 ]

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "estimatedTotalItems": 0,
  • "page": 0,
  • "expectedPageSize": 0,
  • "results": [
    ]
}

Get artist details Deprecated

Get detailed information about a specific artist.

Authorizations:
OAuth2
path Parameters
artist_id
required
string

ID of the artist

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "version": "string",
  • "artist": {
    }
}

Get artist releases Deprecated

Get releases for a specific artist.

Authorizations:
OAuth2
path Parameters
artist_id
required
string

ID of the artist

query Parameters
usageTypes
string
Enum: "download" "stream"

Usage types (download or stream)

type
string
Enum: "album" "single" "video"

Release type

imageSize
integer
Enum: 33 50 100 180 182 200 350 500 800

Image size

page
integer >= 1

Page number

pageSize
integer [ 10 .. 50 ]

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "version": "string",
  • "releases": {
    }
}

Browse artists Deprecated

Browse artists by letter.

Authorizations:
OAuth2
query Parameters
letter
required
string

Letter to browse by

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "version": "string",
  • "artists": {
    }
}

Releases

Get release

Get a release by ID from the local catalog.

path Parameters
id
required
string <uuid>

Release UUID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "artist_name": "string",
  • "artwork_url_template": "string",
  • "release_type": "string",
  • "year": 0,
  • "explicit": true,
  • "track_count": 0,
  • "is_saved": false
}

Get release tracks

Get paginated tracks for a release, ordered by disc and track number.

path Parameters
id
required
string <uuid>

Release UUID

query Parameters
page
integer >= 1
Default: 1
page_size
integer [ 1 .. 50 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Search releases Deprecated

Search for releases using the aggregator service.

Authorizations:
OAuth2
query Parameters
q
required
string

Search terms

usageTypes
string
Enum: "download" "stream"

Usage types (download or stream)

excludeExplicitContent
boolean

Exclude explicit content

artistId
string

Artist ID

page
integer >= 1

Page number

pageSize
integer [ 10 .. 50 ]

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "estimatedTotalItems": 0,
  • "page": 0,
  • "expectedPageSize": 0,
  • "results": [
    ]
}

Get release details Deprecated

Get detailed information about a specific release.

Authorizations:
OAuth2
path Parameters
release_id
required
string

ID of the release

query Parameters
usageTypes
string
Enum: "download" "stream"

Usage types (download or stream)

imageSize
integer
Enum: 33 50 100 180 182 200 350 500 800

Image size

Responses

Response samples

Content type
application/json
{
  • "release": {
    }
}

Get release tracks Deprecated

Get tracks for a specific release.

Authorizations:
OAuth2
path Parameters
release_id
required
string

ID of the release

query Parameters
usageTypes
string
Enum: "download" "stream"

Usage types (download or stream)

imageSize
integer
Enum: 33 50 100 180 182 200 350 500 800

Image size

Responses

Response samples

Content type
application/json
{
  • "page": 0,
  • "pageSize": 0,
  • "totalItems": 0,
  • "tracks": [
    ]
}

Get batch release details Deprecated

Get detailed information about multiple releases.

Authorizations:
OAuth2
query Parameters
releaseids
required
string

Comma-separated list of release IDs

usageTypes
string
Enum: "download" "stream"

Usage types (download or stream)

showErrors
boolean

Show errors

type
string
Enum: "album" "single" "video"

Release type

imageSize
integer
Enum: 33 50 100 180 182 200 350 500 800

Image size

Responses

Response samples

Content type
application/json
{
  • "items": {
    }
}

Tracks

Get track

Get a track by ID from the local catalog.

path Parameters
id
required
string <uuid>

Track UUID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "artist_name": "string",
  • "artwork_url_template": "string",
  • "duration_seconds": 0,
  • "explicit": true,
  • "stream_url": "http://example.com",
  • "is_liked": false
}

Search tracks Deprecated

Search for tracks using the aggregator service.

Authorizations:
OAuth2
query Parameters
q
required
string

Search terms

usageTypes
string
Enum: "download" "stream"

Usage types (download or stream)

excludeExplicitContent
boolean

Exclude explicit content

artistId
string

Artist ID

page
integer >= 1

Page number

pageSize
integer [ 10 .. 50 ]

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "estimatedTotalItems": 0,
  • "page": 0,
  • "expectedPageSize": 0,
  • "results": [
    ]
}

Get track details Deprecated

Get detailed information about a specific track.

Authorizations:
OAuth2
path Parameters
track_id
required
string

ID of the track

query Parameters
usageTypes
string
Enum: "download" "stream"

Usage types (download or stream)

imageSize
integer
Enum: 33 50 100 180 182 200 350 500 800

Image size

Responses

Response samples

Content type
application/json
{
  • "track": {
    }
}

Get batch track details Deprecated

Get detailed information about multiple tracks.

Authorizations:
OAuth2
query Parameters
trackids
required
string

Comma-separated list of track IDs

usageTypes
string
Enum: "download" "stream"

Usage types (download or stream)

showErrors
boolean

Show errors

imageSize
integer
Enum: 33 50 100 180 182 200 350 500 800

Image size

Responses

Response samples

Content type
application/json
{
  • "items": {
    }
}

Telemetry

Track telemetry endpoints for usage tracking.

Track play event

Registers a 'play' event for a track with start and end positions.

Authorizations:
UserSession
Request Body schema: application/json
required
track_id
required
string <uuid>

ID of the track.

from
required
integer >= 0

The starting second of the play event.

to
required
integer >= 0

The ending second of the play event. Must be greater than 'from'.

reached_end_of_the_track
boolean
Default: false

Whether the track was played until the end.

Responses

Request samples

Content type
application/json
{
  • "track_id": "89443c0f-6172-4ccb-98e3-b20b8a4e4aba",
  • "from": 0,
  • "to": 0,
  • "reached_end_of_the_track": false
}

Track multiple play events in batch

Allows sending multiple play events in a single request, useful for offline sync.

Authorizations:
UserSession
Request Body schema: application/json
required
required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

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

Streaming

Stream track

Returns an HLS manifest from the streaming server using a stream ID.

Authorizations:
UserSession
path Parameters
stream_id
required
string <uuid>

Stream ID used to fetch the HLS manifest.

Responses

Response samples

Content type
application/vnd.apple.mpegurl
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0
#EXTINF:6.000,
segment0.ts
#EXTINF:6.000,
segment1.ts
#EXT-X-ENDLIST