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"
}

Authentication

OAuth2 client credentials token issuance and User Delegation Token minting.

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
}

Mint a User Delegation Token

Issues a UDT 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 UDT is issued.

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

Unique identifier of the device the UDT 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.

Authorizations:
OAuth2

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>
date_of_birth
required
string <date>

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "date_of_birth": "2019-08-24",
  • "status": "SUBSCRIBED",
  • "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",
  • "date_of_birth": "2019-08-24",
  • "status": "SUBSCRIBED",
  • "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>
date_of_birth
string <date>

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "date_of_birth": "2019-08-24",
  • "status": "SUBSCRIBED",
  • "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

Mint a User Delegation Token

Issues a UDT 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 UDT is issued.

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

Unique identifier of the device the UDT 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

Sends a one-time verification code to the given email address. If the address is valid, a code is sent; the response does not reveal whether the address 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"

Preferred language for the OTP email (en, nl, fr). 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
{
  • "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>

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": {
    }
}

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
date_of_birth
required
string <date>

Responses

Request samples

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

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": {
    }
}

Profile

End-user self-profile endpoints (UDT-authenticated).

Current user profile

Returns profile data for the caller authenticated with a UDT.

Authorizations:
UDT

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "date_of_birth": "2019-08-24",
  • "status": "SUBSCRIBED",
  • "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 caller authenticated with a UDT.

Authorizations:
UDT
Request Body schema: application/json
required
first_name
string
last_name
string
date_of_birth
string <date>

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "date_of_birth": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "date_of_birth": "2019-08-24",
  • "status": "SUBSCRIBED",
  • "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 Stripe Checkout session

Creates a new Stripe Checkout session for a subscription product. Optionally accepts custom redirect URLs that must match configured allowed patterns.

Authorizations:
UDT
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": [
    ]
}

Playlists

Search playlists

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

Authorizations:
UDT
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:
UDT

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create playlist

Creates a new playlist for the user.

Authorizations:
UDT
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",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "playlist_name": "string",
  • "public": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get playlist

Returns details of a specific playlist.

Authorizations:
UDT
path Parameters
playlist_id
required
string <uuid>

ID of the playlist.

query Parameters
with
string
Value: "tracks"

Relationships to include in the response.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "playlist_name": "string",
  • "public": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update playlist

Updates details of an owned playlist.

Authorizations:
UDT
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",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "playlist_name": "string",
  • "public": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete playlist

Deletes an owned playlist and its tracks.

Authorizations:
UDT
path Parameters
playlist_id
required
string <uuid>

ID of the playlist.

Responses

Get playlist tracks

Returns tracks for a specific playlist.

Authorizations:
UDT
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:
UDT
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",
  • "playlist_id": "4a089bd6-aad8-455a-b371-0f37773c35d2",
  • "track_id": "string",
  • "order": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update playlist tracks

Replaces all tracks in the playlist with the provided set.

Authorizations:
UDT
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:
UDT
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:
UDT
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",
  • "playlist_id": "4a089bd6-aad8-455a-b371-0f37773c35d2",
  • "track_id": "string",
  • "order": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Artists

Search artists

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

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

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

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

Search releases

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

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

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

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

Search tracks

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

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

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": {
    }
}

Streaming

Stream track

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

Authorizations:
UDT
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