Melody Catalog Service API

Playback

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

Endpoints for recording playback events and managing history

Update playback history configuration

PUT

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

/catalog/playback/config

Updates the user's playback history configuration (e.g., pause/resume history).

Update playback history configuration › Request Body

Request to update playback history configuration

pauseHistory

boolean · required

Whether to pause history tracking

Update playback history configuration › Responses

Playback configuration updated successfully

No data returned

PUT/catalog/playback/config

curl --request PUT \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playback/config \
  --header 'Content-Type: application/json' \
  --data '
{
  "pauseHistory": false
}
'

shell

Example Request Body

{
  "pauseHistory": false
}

json

Example Responses

No example specified for this content type

Record a playback event

POST

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

/catalog/playback

Records or updates a playback session in the user's history. Uses UPSERT logic: updates existing session or creates new one for user+song combination.

Record a playback event › Request Body

Request to log a playback event

songId

string · uuid · required

The ID of the song being played

durationSeconds

integer · int32 · min: 1 · required

The total duration of the song in seconds

contextType

string · enum

The type of resource being played (PLAYLIST, COLLECTION) if applicable

Enum values:

PLAYLIST

COLLECTION

contextId

string · uuid

The ID of the context resource (e.g., playlist or collection) if applicable

contextName

string

The name of the context resource (e.g., playlist or collection) if applicable

contextOwnerId

string · uuid

Indicates if the playback is a preview (e.g., 30-second clip)

positionSeconds

integer · int32 · min: 0

The position in seconds where playback is starting

Record a playback event › Responses

Playback recorded successfully

No data returned

POST/catalog/playback

curl --request POST \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playback \
  --header 'Content-Type: application/json' \
  --data '
{
  "songId": "550e8400-e29b-41d4-a716-446655440000",
  "contextType": "PLAYLIST",
  "contextId": "00000000-0000-0000-0000-000000000000",
  "contextName": "contextName",
  "contextOwnerId": false,
  "positionSeconds": 120,
  "durationSeconds": 210
}
'

shell

Example Request Body

{
  "songId": "550e8400-e29b-41d4-a716-446655440000",
  "contextType": "PLAYLIST",
  "contextId": "00000000-0000-0000-0000-000000000000",
  "contextName": "contextName",
  "contextOwnerId": false,
  "positionSeconds": 120,
  "durationSeconds": 210
}

json

Example Responses

No example specified for this content type

Get playback history

GET

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

/catalog/playback/history

Retrieves the user's playback history with pagination, ordered by most recent first

Get playback history › query Parameters

object · required

page

string

Page number (0-based)

size

string

Page size

sort

string

Sort by field

Get playback history › Responses

Playback history retrieved successfully

Response containing pageable playback history and tracking status

paused

boolean

Whether the playback history tracking is paused

object

GET/catalog/playback/history

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playback/history?pageable=%3Cvalue%3E'

shell

Example Responses

{
  "paused": false,
  "history": {
    "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": [
      {
        "songSummary": {
          "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
        },
        "contextType": "PLAYLIST",
        "contextId": "550e8400-e29b-41d4-a716-446655440000",
        "contextName": "My Awesome Playlist",
        "playedAt": "2025-10-31T19:12:00Z"
      }
    ],
    "number": 0,
    "sort": {
      "sorted": true,
      "unsorted": true,
      "empty": true
    },
    "first": true,
    "last": true,
    "empty": true
  }
}

json

application/json

Clear playback history

DELETE

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

/catalog/playback/history

Clears the user's entire playback history.

Clear playback history › Responses

Playback history cleared successfully

No data returned

DELETE/catalog/playback/history

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

shell

Example Responses

No example specified for this content type

Search playback history

GET

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

/catalog/playback/history/search

Search the user's playback history by song title or artist name

Search playback history › query Parameters

query

string · required

Search query (song title or artist name)

object · required

page

string

Page number (0-based)

size

string

Page size

sort

string

Sort by field

Search playback history › Responses

Search results retrieved successfully

Response containing pageable playback history and tracking status

paused

boolean

Whether the playback history tracking is paused

object

GET/catalog/playback/history/search

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

shell

Example Responses

{
  "paused": false,
  "history": {
    "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": [
      {
        "songSummary": {
          "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
        },
        "contextType": "PLAYLIST",
        "contextId": "550e8400-e29b-41d4-a716-446655440000",
        "contextName": "My Awesome Playlist",
        "playedAt": "2025-10-31T19:12:00Z"
      }
    ],
    "number": 0,
    "sort": {
      "sorted": true,
      "unsorted": true,
      "empty": true
    },
    "first": true,
    "last": true,
    "empty": true
  }
}

json

application/json

Artist Pick Songs

Melody Catalog Service API

Playback

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

Endpoints for recording playback events and managing history

Update playback history configuration

PUT

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

/catalog/playback/config

Updates the user's playback history configuration (e.g., pause/resume history).

Update playback history configuration › Request Body

Request to update playback history configuration

pauseHistory

boolean · required

Whether to pause history tracking

Update playback history configuration › Responses

Playback configuration updated successfully

No data returned

PUT/catalog/playback/config

curl --request PUT \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playback/config \
  --header 'Content-Type: application/json' \
  --data '
{
  "pauseHistory": false
}
'

shell

Example Request Body

{
  "pauseHistory": false
}

json

Example Responses

No example specified for this content type

Record a playback event

POST

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

/catalog/playback

Records or updates a playback session in the user's history. Uses UPSERT logic: updates existing session or creates new one for user+song combination.

Record a playback event › Request Body

Request to log a playback event

songId

string · uuid · required

The ID of the song being played

durationSeconds

integer · int32 · min: 1 · required

The total duration of the song in seconds

contextType

string · enum

The type of resource being played (PLAYLIST, COLLECTION) if applicable

Enum values:

PLAYLIST

COLLECTION

contextId

string · uuid

The ID of the context resource (e.g., playlist or collection) if applicable

contextName

string

The name of the context resource (e.g., playlist or collection) if applicable

contextOwnerId

string · uuid

Indicates if the playback is a preview (e.g., 30-second clip)

positionSeconds

integer · int32 · min: 0

The position in seconds where playback is starting

Record a playback event › Responses

Playback recorded successfully

No data returned

POST/catalog/playback

curl --request POST \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playback \
  --header 'Content-Type: application/json' \
  --data '
{
  "songId": "550e8400-e29b-41d4-a716-446655440000",
  "contextType": "PLAYLIST",
  "contextId": "00000000-0000-0000-0000-000000000000",
  "contextName": "contextName",
  "contextOwnerId": false,
  "positionSeconds": 120,
  "durationSeconds": 210
}
'

shell

Example Request Body

{
  "songId": "550e8400-e29b-41d4-a716-446655440000",
  "contextType": "PLAYLIST",
  "contextId": "00000000-0000-0000-0000-000000000000",
  "contextName": "contextName",
  "contextOwnerId": false,
  "positionSeconds": 120,
  "durationSeconds": 210
}

json

Example Responses

No example specified for this content type

Get playback history

GET

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

/catalog/playback/history

Retrieves the user's playback history with pagination, ordered by most recent first

Get playback history › query Parameters

object · required

page

string

Page number (0-based)

size

string

Page size

sort

string

Sort by field

Get playback history › Responses

Playback history retrieved successfully

Response containing pageable playback history and tracking status

paused

boolean

Whether the playback history tracking is paused

object

GET/catalog/playback/history

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/playback/history?pageable=%3Cvalue%3E'

shell

Example Responses

{
  "paused": false,
  "history": {
    "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": [
      {
        "songSummary": {
          "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
        },
        "contextType": "PLAYLIST",
        "contextId": "550e8400-e29b-41d4-a716-446655440000",
        "contextName": "My Awesome Playlist",
        "playedAt": "2025-10-31T19:12:00Z"
      }
    ],
    "number": 0,
    "sort": {
      "sorted": true,
      "unsorted": true,
      "empty": true
    },
    "first": true,
    "last": true,
    "empty": true
  }
}

json

application/json

Clear playback history

DELETE

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

/catalog/playback/history

Clears the user's entire playback history.

Clear playback history › Responses

Playback history cleared successfully

No data returned

DELETE/catalog/playback/history

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

shell

Example Responses

No example specified for this content type

Search playback history

GET

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

/catalog/playback/history/search

Search the user's playback history by song title or artist name

Search playback history › query Parameters

query

string · required

Search query (song title or artist name)

object · required

page

string

Page number (0-based)

size

string

Page size

sort

string

Sort by field

Search playback history › Responses

Search results retrieved successfully

Response containing pageable playback history and tracking status

paused

boolean

Whether the playback history tracking is paused

object

GET/catalog/playback/history/search

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

shell

Example Responses

{
  "paused": false,
  "history": {
    "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": [
      {
        "songSummary": {
          "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
        },
        "contextType": "PLAYLIST",
        "contextId": "550e8400-e29b-41d4-a716-446655440000",
        "contextName": "My Awesome Playlist",
        "playedAt": "2025-10-31T19:12:00Z"
      }
    ],
    "number": 0,
    "sort": {
      "sorted": true,
      "unsorted": true,
      "empty": true
    },
    "first": true,
    "last": true,
    "empty": true
  }
}

json

application/json

Artist Pick Songs