Melody Catalog Service API

Playlists

Endpointhttps://melody-gateway-main-0d30d7f.d2.zuplo.dev

Playlist management operations

Get playlist by ID

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/catalog/playlists/{id}

Retrieves a playlist by its unique identifier. Public playlists can be accessed by anyone, private playlists only by their owners.

Get playlist by ID › path Parameters

id

string · uuid · required

Playlist unique identifier

Get playlist by ID › Responses

Playlist retrieved successfully

id

string · uuid

Unique identifier of the playlist

title

string

Title of the playlist

coverUrl

string

Cover URL of the playlist

userId

string · uuid

Unique identifier of the playlist owner

username

string

Username of the playlist owner

isPublic

boolean

Indicates if the playlist is public

object[]

List of songs in the playlist

songCount

integer · int32

Total number of songs in the playlist

createdAt

string · date-time

Timestamp when the playlist was created

updatedAt

string · date-time

Timestamp when the playlist was last updated

relevanceScore

integer · int32

Relevance score for search results (null if not from search)

levenshteinDistance

integer · int32

Levenshtein distance for search results (null if not from search)

isSaved

boolean

Indicates whether the current user has saved/bookmarked this collection

GET/catalog/playlists/{id}

curl --request GET \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playlists/:id

shell

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "title": "title",
  "coverUrl": "coverUrl",
  "userId": "00000000-0000-0000-0000-000000000000",
  "username": "username",
  "isPublic": true,
  "songs": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "song": {
        "id": "00000000-0000-0000-0000-000000000000",
        "title": "title",
        "durationSeconds": 0,
        "positionInCollection": 0,
        "coverUrl": "coverUrl",
        "primaryArtistName": "primaryArtistName",
        "primaryArtistId": "00000000-0000-0000-0000-000000000000",
        "effectiveState": "BLOCKED_ADMIN",
        "likedByUser": true,
        "explicit": true,
        "videoUrl": "videoUrl",
        "collectionId": "00000000-0000-0000-0000-000000000000",
        "likesCount": 0
      }
    }
  ],
  "songCount": 0,
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z",
  "relevanceScore": 9500,
  "levenshteinDistance": 2,
  "isSaved": true
}

json

application/json

Update playlist

PUT

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/catalog/playlists/{id}

Updates playlist metadata (title, cover, visibility). Only the playlist owner can update it.

Update playlist › path Parameters

id

string · uuid · required

Playlist unique identifier

Update playlist › Request Body

title

string · minLength: 0 · maxLength: 255

coverUrl

string

isPublic

boolean

Update playlist › Responses

Playlist updated successfully

id

string · uuid

Unique identifier of the playlist

title

string

Title of the playlist

coverUrl

string

Cover URL of the playlist

userId

string · uuid

Unique identifier of the playlist owner

username

string

Username of the playlist owner

isPublic

boolean

Indicates if the playlist is public

object[]

List of songs in the playlist

songCount

integer · int32

Total number of songs in the playlist

createdAt

string · date-time

Timestamp when the playlist was created

updatedAt

string · date-time

Timestamp when the playlist was last updated

relevanceScore

integer · int32

Relevance score for search results (null if not from search)

levenshteinDistance

integer · int32

Levenshtein distance for search results (null if not from search)

isSaved

boolean

Indicates whether the current user has saved/bookmarked this collection

PUT/catalog/playlists/{id}

curl --request PUT \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playlists/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "title",
  "coverUrl": "coverUrl",
  "isPublic": true
}
'

shell

Example Request Body

{
  "title": "title",
  "coverUrl": "coverUrl",
  "isPublic": true
}

json

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "title": "title",
  "coverUrl": "coverUrl",
  "userId": "00000000-0000-0000-0000-000000000000",
  "username": "username",
  "isPublic": true,
  "songs": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "song": {
        "id": "00000000-0000-0000-0000-000000000000",
        "title": "title",
        "durationSeconds": 0,
        "positionInCollection": 0,
        "coverUrl": "coverUrl",
        "primaryArtistName": "primaryArtistName",
        "primaryArtistId": "00000000-0000-0000-0000-000000000000",
        "effectiveState": "BLOCKED_ADMIN",
        "likedByUser": true,
        "explicit": true,
        "videoUrl": "videoUrl",
        "collectionId": "00000000-0000-0000-0000-000000000000",
        "likesCount": 0
      }
    }
  ],
  "songCount": 0,
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z",
  "relevanceScore": 9500,
  "levenshteinDistance": 2,
  "isSaved": true
}

json

application/json

Delete (soft) a playlist

DELETE

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/catalog/playlists/{id}

Soft delete de una playlist. Solo el dueño puede borrar su playlist.

Delete (soft) a playlist › path Parameters

id

string · uuid · required

Playlist unique identifier

Delete (soft) a playlist › Responses

Playlist deleted successfully

No data returned

DELETE/catalog/playlists/{id}

curl --request DELETE \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playlists/:id

shell

Example Responses

No example specified for this content type

Create a new playlist

POST

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/catalog/playlists

Creates a new playlist for the authenticated user. The playlist starts empty and songs can be added later.

Create a new playlist › Request Body

title

string · minLength: 0 · maxLength: 255 · required

coverUrl

string

isPublic

boolean

Create a new playlist › Responses

Playlist created successfully

id

string · uuid

Unique identifier of the playlist

title

string

Title of the playlist

coverUrl

string

Cover URL of the playlist

userId

string · uuid

Unique identifier of the playlist owner

username

string

Username of the playlist owner

isPublic

boolean

Indicates if the playlist is public

object[]

List of songs in the playlist

songCount

integer · int32

Total number of songs in the playlist

createdAt

string · date-time

Timestamp when the playlist was created

updatedAt

string · date-time

Timestamp when the playlist was last updated

relevanceScore

integer · int32

Relevance score for search results (null if not from search)

levenshteinDistance

integer · int32

Levenshtein distance for search results (null if not from search)

isSaved

boolean

Indicates whether the current user has saved/bookmarked this collection

POST/catalog/playlists

curl --request POST \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playlists \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "title",
  "coverUrl": "coverUrl",
  "isPublic": true
}
'

shell

Example Request Body

{
  "title": "title",
  "coverUrl": "coverUrl",
  "isPublic": true
}

json

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "title": "title",
  "coverUrl": "coverUrl",
  "userId": "00000000-0000-0000-0000-000000000000",
  "username": "username",
  "isPublic": true,
  "songs": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "song": {
        "id": "00000000-0000-0000-0000-000000000000",
        "title": "title",
        "durationSeconds": 0,
        "positionInCollection": 0,
        "coverUrl": "coverUrl",
        "primaryArtistName": "primaryArtistName",
        "primaryArtistId": "00000000-0000-0000-0000-000000000000",
        "effectiveState": "BLOCKED_ADMIN",
        "likedByUser": true,
        "explicit": true,
        "videoUrl": "videoUrl",
        "collectionId": "00000000-0000-0000-0000-000000000000",
        "likesCount": 0
      }
    }
  ],
  "songCount": 0,
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z",
  "relevanceScore": 9500,
  "levenshteinDistance": 2,
  "isSaved": true
}

json

application/json

Add song to playlist

POST

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/catalog/playlists/{id}/songs

Adds a song to the end of a playlist. Songs can be added multiple times to the same playlist. Only the playlist owner can add songs.

Add song to playlist › path Parameters

id

string · uuid · required

Playlist unique identifier

Add song to playlist › Request Body

songId

string · uuid · required

Add song to playlist › Responses

Song added successfully

id

string · uuid

Unique identifier of the playlist

title

string

Title of the playlist

coverUrl

string

Cover URL of the playlist

userId

string · uuid

Unique identifier of the playlist owner

username

string

Username of the playlist owner

isPublic

boolean

Indicates if the playlist is public

object[]

List of songs in the playlist

songCount

integer · int32

Total number of songs in the playlist

createdAt

string · date-time

Timestamp when the playlist was created

updatedAt

string · date-time

Timestamp when the playlist was last updated

relevanceScore

integer · int32

Relevance score for search results (null if not from search)

levenshteinDistance

integer · int32

Levenshtein distance for search results (null if not from search)

isSaved

boolean

Indicates whether the current user has saved/bookmarked this collection

POST/catalog/playlists/{id}/songs

curl --request POST \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playlists/:id/songs \
  --header 'Content-Type: application/json' \
  --data '
{
  "songId": "00000000-0000-0000-0000-000000000000"
}
'

shell

Example Request Body

{
  "songId": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "title": "title",
  "coverUrl": "coverUrl",
  "userId": "00000000-0000-0000-0000-000000000000",
  "username": "username",
  "isPublic": true,
  "songs": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "song": {
        "id": "00000000-0000-0000-0000-000000000000",
        "title": "title",
        "durationSeconds": 0,
        "positionInCollection": 0,
        "coverUrl": "coverUrl",
        "primaryArtistName": "primaryArtistName",
        "primaryArtistId": "00000000-0000-0000-0000-000000000000",
        "effectiveState": "BLOCKED_ADMIN",
        "likedByUser": true,
        "explicit": true,
        "videoUrl": "videoUrl",
        "collectionId": "00000000-0000-0000-0000-000000000000",
        "likesCount": 0
      }
    }
  ],
  "songCount": 0,
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z",
  "relevanceScore": 9500,
  "levenshteinDistance": 2,
  "isSaved": true
}

json

application/json

Move a single song to a new position

PATCH

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/catalog/playlists/{id}/songs/{playlistSongId}/move

Moves a specific song entry to a new position in the playlist. This is more efficient than reordering the entire playlist when you only need to move one song.

Move a single song to a new position › path Parameters

id

string · uuid · required

Playlist unique identifier

playlistSongId

string · uuid · required

PlaylistSong entry unique identifier

Move a single song to a new position › Request Body

Request to move a song to a new position in the playlist

newPosition

integer · int32 · min: 1 · required

The new position for the song (1-based)

Move a single song to a new position › Responses

Song moved successfully

id

string · uuid

Unique identifier of the playlist

title

string

Title of the playlist

coverUrl

string

Cover URL of the playlist

userId

string · uuid

Unique identifier of the playlist owner

username

string

Username of the playlist owner

isPublic

boolean

Indicates if the playlist is public

object[]

List of songs in the playlist

songCount

integer · int32

Total number of songs in the playlist

createdAt

string · date-time

Timestamp when the playlist was created

updatedAt

string · date-time

Timestamp when the playlist was last updated

relevanceScore

integer · int32

Relevance score for search results (null if not from search)

levenshteinDistance

integer · int32

Levenshtein distance for search results (null if not from search)

isSaved

boolean

Indicates whether the current user has saved/bookmarked this collection

PATCH/catalog/playlists/{id}/songs/{playlistSongId}/move

curl --request PATCH \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playlists/:id/songs/:playlistSongId/move \
  --header 'Content-Type: application/json' \
  --data '
{
  "newPosition": 3
}
'

shell

Example Request Body

{
  "newPosition": 3
}

json

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "title": "title",
  "coverUrl": "coverUrl",
  "userId": "00000000-0000-0000-0000-000000000000",
  "username": "username",
  "isPublic": true,
  "songs": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "song": {
        "id": "00000000-0000-0000-0000-000000000000",
        "title": "title",
        "durationSeconds": 0,
        "positionInCollection": 0,
        "coverUrl": "coverUrl",
        "primaryArtistName": "primaryArtistName",
        "primaryArtistId": "00000000-0000-0000-0000-000000000000",
        "effectiveState": "BLOCKED_ADMIN",
        "likedByUser": true,
        "explicit": true,
        "videoUrl": "videoUrl",
        "collectionId": "00000000-0000-0000-0000-000000000000",
        "likesCount": 0
      }
    }
  ],
  "songCount": 0,
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z",
  "relevanceScore": 9500,
  "levenshteinDistance": 2,
  "isSaved": true
}

json

application/json

Reorder songs in playlist

PATCH

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/catalog/playlists/{id}/songs/reorder

Reorders songs in a playlist by providing the new order of PlaylistSong IDs. This allows precise control over song positioning, including handling repeated songs.

Reorder songs in playlist › path Parameters

id

string · uuid · required

Playlist unique identifier

Reorder songs in playlist › Request Body

playlistSongIds

string[] · required

Reorder songs in playlist › Responses

Songs reordered successfully

id

string · uuid

Unique identifier of the playlist

title

string

Title of the playlist

coverUrl

string

Cover URL of the playlist

userId

string · uuid

Unique identifier of the playlist owner

username

string

Username of the playlist owner

isPublic

boolean

Indicates if the playlist is public

object[]

List of songs in the playlist

songCount

integer · int32

Total number of songs in the playlist

createdAt

string · date-time

Timestamp when the playlist was created

updatedAt

string · date-time

Timestamp when the playlist was last updated

relevanceScore

integer · int32

Relevance score for search results (null if not from search)

levenshteinDistance

integer · int32

Levenshtein distance for search results (null if not from search)

isSaved

boolean

Indicates whether the current user has saved/bookmarked this collection

PATCH/catalog/playlists/{id}/songs/reorder

curl --request PATCH \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playlists/:id/songs/reorder \
  --header 'Content-Type: application/json' \
  --data '
{
  "playlistSongIds": [
    "00000000-0000-0000-0000-000000000000"
  ]
}
'

shell

Example Request Body

{
  "playlistSongIds": [
    "00000000-0000-0000-0000-000000000000"
  ]
}

json

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "title": "title",
  "coverUrl": "coverUrl",
  "userId": "00000000-0000-0000-0000-000000000000",
  "username": "username",
  "isPublic": true,
  "songs": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "song": {
        "id": "00000000-0000-0000-0000-000000000000",
        "title": "title",
        "durationSeconds": 0,
        "positionInCollection": 0,
        "coverUrl": "coverUrl",
        "primaryArtistName": "primaryArtistName",
        "primaryArtistId": "00000000-0000-0000-0000-000000000000",
        "effectiveState": "BLOCKED_ADMIN",
        "likedByUser": true,
        "explicit": true,
        "videoUrl": "videoUrl",
        "collectionId": "00000000-0000-0000-0000-000000000000",
        "likesCount": 0
      }
    }
  ],
  "songCount": 0,
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z",
  "relevanceScore": 9500,
  "levenshteinDistance": 2,
  "isSaved": true
}

json

application/json

Get playlists by user

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/catalog/playlists/users/{userId}

Retrieves all playlists created by a specific user. Only returns public playlists unless the user is requesting their own playlists.

Get playlists by user › path Parameters

userId

string · uuid · required

User unique identifier

Get playlists by user › Responses

Playlists retrieved successfully

id

string · uuid

Unique identifier of the playlist

title

string

Title of the playlist

coverUrl

string

Cover URL of the playlist

userId

string · uuid

Unique identifier of the playlist owner

username

string

Username of the playlist owner

isPublic

boolean

Indicates if the playlist is public

songCount

integer · int32

Total number of songs in the playlist

createdAt

string · date-time

Timestamp when the playlist was created

updatedAt

string · date-time

Timestamp when the playlist was last updated

relevanceScore

integer · int32

Relevance score for search results (null if not from search)

levenshteinDistance

integer · int32

Levenshtein distance for search results (null if not from search)

isSaved

boolean

Indicates whether the current user has saved/bookmarked this collection

GET/catalog/playlists/users/{userId}

curl --request GET \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playlists/users/:userId

shell

Example Responses

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Chill Vibes",
  "coverUrl": "https://example.com/cover.jpg",
  "userId": "987e6543-e21b-12d3-a456-426614174000",
  "username": "music_lover42",
  "isPublic": true,
  "songCount": 25,
  "createdAt": "2023-08-15T10:00:00Z",
  "updatedAt": "2023-09-01T12:30:00Z",
  "relevanceScore": 9500,
  "levenshteinDistance": 2,
  "isSaved": true
}

json

application/json

Remove song from playlist

DELETE

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/catalog/playlists/{id}/songs/{playlistSongId}

Removes a specific song entry from a playlist using its unique PlaylistSong ID. This allows removing specific instances when the same song appears multiple times.

Remove song from playlist › path Parameters

id

string · uuid · required

Playlist unique identifier

playlistSongId

string · uuid · required

PlaylistSong entry unique identifier

Remove song from playlist › Responses

Song removed successfully

id

string · uuid

Unique identifier of the playlist

title

string

Title of the playlist

coverUrl

string

Cover URL of the playlist

userId

string · uuid

Unique identifier of the playlist owner

username

string

Username of the playlist owner

isPublic

boolean

Indicates if the playlist is public

object[]

List of songs in the playlist

songCount

integer · int32

Total number of songs in the playlist

createdAt

string · date-time

Timestamp when the playlist was created

updatedAt

string · date-time

Timestamp when the playlist was last updated

relevanceScore

integer · int32

Relevance score for search results (null if not from search)

levenshteinDistance

integer · int32

Levenshtein distance for search results (null if not from search)

isSaved

boolean

Indicates whether the current user has saved/bookmarked this collection

DELETE/catalog/playlists/{id}/songs/{playlistSongId}

curl --request DELETE \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playlists/:id/songs/:playlistSongId

shell

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "title": "title",
  "coverUrl": "coverUrl",
  "userId": "00000000-0000-0000-0000-000000000000",
  "username": "username",
  "isPublic": true,
  "songs": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "song": {
        "id": "00000000-0000-0000-0000-000000000000",
        "title": "title",
        "durationSeconds": 0,
        "positionInCollection": 0,
        "coverUrl": "coverUrl",
        "primaryArtistName": "primaryArtistName",
        "primaryArtistId": "00000000-0000-0000-0000-000000000000",
        "effectiveState": "BLOCKED_ADMIN",
        "likedByUser": true,
        "explicit": true,
        "videoUrl": "videoUrl",
        "collectionId": "00000000-0000-0000-0000-000000000000",
        "likesCount": 0
      }
    }
  ],
  "songCount": 0,
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z",
  "relevanceScore": 9500,
  "levenshteinDistance": 2,
  "isSaved": true
}

json

application/json

Advanced search for public playlists

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/catalog/playlists/search

Performs an advanced search using Levenshtein distance algorithm on public playlists only. Excludes deleted and blocked playlists. Results are ranked by relevance.

Advanced search for public playlists › query Parameters

query

string · required

page

integer · int32

Default: 0

size

integer · int32

Default: 20

Advanced search for public playlists › Responses

Search results retrieved successfully

id

string · uuid

Unique identifier of the playlist

title

string

Title of the playlist

coverUrl

string

Cover URL of the playlist

userId

string · uuid

Unique identifier of the playlist owner

username

string

Username of the playlist owner

isPublic

boolean

Indicates if the playlist is public

songCount

integer · int32

Total number of songs in the playlist

createdAt

string · date-time

Timestamp when the playlist was created

updatedAt

string · date-time

Timestamp when the playlist was last updated

relevanceScore

integer · int32

Relevance score for search results (null if not from search)

levenshteinDistance

integer · int32

Levenshtein distance for search results (null if not from search)

isSaved

boolean

Indicates whether the current user has saved/bookmarked this collection

GET/catalog/playlists/search

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playlists/search?query=%3Cstring%3E'

shell

Example Responses

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Chill Vibes",
  "coverUrl": "https://example.com/cover.jpg",
  "userId": "987e6543-e21b-12d3-a456-426614174000",
  "username": "music_lover42",
  "isPublic": true,
  "songCount": 25,
  "createdAt": "2023-08-15T10:00:00Z",
  "updatedAt": "2023-09-01T12:30:00Z",
  "relevanceScore": 9500,
  "levenshteinDistance": 2,
  "isSaved": true
}

json

application/json

Get public playlists by mood

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/catalog/playlists/by-mood

Retrieves public playlists that contain at least one song with the specified mood. Only non-deleted and non-blocked playlists are returned. Results are ordered by last update date (most recent first). Supports pagination.

Get public playlists by mood › query Parameters

mood

string · enum · required

Mood to filter playlists by

Enum values:

ENERGETIC

CALM

RELAXED

INTENSE

HAPPY

SAD

ROMANTIC

MELANCHOLIC

page

integer · int32

Page number (0-indexed)

Default: 0

size

integer · int32

Page size

Default: 20

Get public playlists by mood › Responses

Playlists retrieved successfully

totalElements

integer · int64

totalPages

integer · int32

object

numberOfElements

integer · int32

size

integer · int32

object[]

number

integer · int32

object

first

boolean

last

boolean

empty

boolean

GET/catalog/playlists/by-mood

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playlists/by-mood?mood=%3Cstring%3E'

shell

Example Responses

{
  "totalElements": 0,
  "totalPages": 0,
  "pageable": {
    "paged": true,
    "pageSize": 0,
    "unpaged": true,
    "pageNumber": 0,
    "offset": 0,
    "sort": {
      "sorted": true,
      "unsorted": true,
      "empty": true
    }
  },
  "numberOfElements": 0,
  "size": 0,
  "content": [
    {}
  ],
  "number": 0,
  "sort": {
    "sorted": true,
    "unsorted": true,
    "empty": true
  },
  "first": true,
  "last": true,
  "empty": true
}

json

application/json

Get public playlists by genre

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/catalog/playlists/by-genre

Retrieves public playlists that contain at least one song with the specified genre. Only non-deleted and non-blocked playlists are returned. Results are ordered by last update date (most recent first). Supports pagination.

Get public playlists by genre › query Parameters

genre

string · enum · required

Genre to filter playlists by

Enum values:

ROCK

ALTERNATIVE_ROCK

INDIE_ROCK

HARD_ROCK

PUNK_ROCK

POP

INDIE_POP

ELECTROPOP

page

integer · int32

Page number (0-indexed)

Default: 0

size

integer · int32

Page size

Default: 20

Get public playlists by genre › Responses

Playlists retrieved successfully

totalElements

integer · int64

totalPages

integer · int32

object

numberOfElements

integer · int32

size

integer · int32

object[]

number

integer · int32

object

first

boolean

last

boolean

empty

boolean

GET/catalog/playlists/by-genre

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playlists/by-genre?genre=%3Cstring%3E'

shell

Example Responses

{
  "totalElements": 0,
  "totalPages": 0,
  "pageable": {
    "paged": true,
    "pageSize": 0,
    "unpaged": true,
    "pageNumber": 0,
    "offset": 0,
    "sort": {
      "sorted": true,
      "unsorted": true,
      "empty": true
    }
  },
  "numberOfElements": 0,
  "size": 0,
  "content": [
    {}
  ],
  "number": 0,
  "sort": {
    "sorted": true,
    "unsorted": true,
    "empty": true
  },
  "first": true,
  "last": true,
  "empty": true
}

json

application/json

Get playlist overview with period comparison

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/playlists/{playlistId}/overview

Returns comprehensive metrics overview for a specific playlist with all-time totals and period comparison. Requires start_date and end_date.

Get playlist overview with period comparison › path Parameters

playlistId

string · uuid · required

Playlist ID

Get playlist overview with period comparison › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

region

string

Region to filter (optional)

User Region

Get playlist overview with period comparison › Responses

Playlist overview metrics found

Comprehensive metrics overview for a specific playlist

playlistId

string · uuid

Playlist ID

title

string

Playlist title

curator

string

Curator/Username

totalPlays

integer · int64

All-time total plays (filtered by region if specified)

totalSaves

integer · int64

All-time total saves (filtered by region if specified)

object

Metric value with period comparison

object

Metric value with period comparison

object

Date range comparison with current and previous periods

region

string

The region filter applied (null if not specified)

GET/metrics/playlists/{playlistId}/overview

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/playlists/:playlistId/overview?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "playlistId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Top Hits 2024",
  "curator": "Official Charts",
  "totalPlays": 15678900,
  "totalSaves": 567890,
  "periodPlays": {
    "current": 1250,
    "previous": 1100,
    "changePercent": 13.64
  },
  "periodSaves": {
    "current": 1250,
    "previous": 1100,
    "changePercent": 13.64
  },
  "dateRange": {
    "current": {
      "start": "2024-08-01",
      "end": "2024-08-31"
    },
    "previous": {
      "start": "2024-08-01",
      "end": "2024-08-31"
    }
  },
  "region": "MX"
}

json

application/json

Collections