Melody Catalog Service API

Songs

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

Get song by ID

GET

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

/catalog/songs/{id}

Retrieves a song by its unique identifier.

Get song by ID › path Parameters

id

string · uuid · required

Get song by ID › Responses

Song retrieved successfully

Response object representing a song in the catalog

id

string · uuid

Unique identifier of the song

title

string

Song title

durationSeconds

integer · int32

Duration in seconds

explicit

boolean

Indicates explicit content

videoUrl

string

URL of the video associated with the song

storageReference

string

Opaque storage reference or URI to the audio asset

collectionId

string · uuid

Identifier of the parent collection/album

coverUrl

string

Collection cover for song image display

releaseDate

string · date-time

Public release datetime in ISO-8601 UTC

primaryArtistName

string

Primary artist display name

primaryArtistId

string · uuid

Identifier of the primary artist

collaboratorIds

string[] · unique

Identifiers of collaborator artists

genres

string[] · unique

Genre classifications for the song

Enum values:

ROCK

ALTERNATIVE_ROCK

INDIE_ROCK

HARD_ROCK

PUNK_ROCK

POP

INDIE_POP

ELECTROPOP

moods

string[] · unique

Mood classifications that the song evokes

Enum values:

ENERGETIC

CALM

RELAXED

INTENSE

HAPPY

SAD

ROMANTIC

MELANCHOLIC

blockedAdmin

boolean

Indicates if the song is blocked by an administrator

effectiveState

string · enum

Effective availability state

Enum values:

BLOCKED_ADMIN

NOT_AVAILABLE_REGION

DRAFT

SCHEDULED

PUBLISHED

likesCount

integer · int32

Number of likes

createdAt

string · date-time

Creation timestamp in ISO-8601 UTC

updatedAt

string · date-time

Last update timestamp in ISO-8601 UTC

liked

boolean

Whether the current user has liked this song

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)

GET/catalog/songs/{id}

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

shell

Example Responses

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Bohemian Rhapsody",
  "durationSeconds": 354,
  "explicit": false,
  "videoUrl": "https://www.youtube.com/watch?v=fJ9rUzIMcZQ",
  "storageReference": "s3://melody-songs/3fa85f64-5717-4562-b3fc-2c963f66afa6.mp3",
  "collectionId": "9b2f5a9f-1c2b-4f11-8c41-7d2ef6e6c123",
  "coverUrl": "https://example.com/cover.jpg",
  "releaseDate": "1975-10-31T00:00:00Z",
  "primaryArtistName": "Queen",
  "primaryArtistId": "5e1c2a1b-1234-4f67-9abc-0def12345678",
  "collaboratorIds": [
    "a1b2c3d4-1111-2222-3333-444455556666",
    "77778888-9999-aaaa-bbbb-ccccddddeeee"
  ],
  "genres": [
    "ROCK",
    "ALTERNATIVE_ROCK"
  ],
  "moods": [
    "ENERGETIC",
    "NOSTALGIC"
  ],
  "blockedAdmin": false,
  "effectiveState": "AVAILABLE",
  "likesCount": 12345,
  "createdAt": "2025-09-14T12:34:56Z",
  "updatedAt": "2025-09-20T08:15:30Z",
  "liked": true,
  "relevanceScore": 9500,
  "levenshteinDistance": 2
}

json

application/json

Update a song

PUT

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

/catalog/songs/{id}

Updates a song. Only the song's artist can update it.

Update a song › path Parameters

id

string · uuid · required

Update a song › Request Body

Request object for updating an existing song

title

string · required

Song title

durationSeconds

integer · int32

Duration in seconds

explicit

boolean

Indicates explicit content

videoUrl

string

URL of the video associated with the song

storageReference

string

Opaque storage reference or URI to the audio asset

collectionId

string · uuid

Identifier of the parent collection/album

scheduledAt

string · date-time

Scheduled availability datetime in ISO-8601 UTC

collaboratorIds

string[] · unique

genres

string[] · unique

Enum values:

ROCK

ALTERNATIVE_ROCK

INDIE_ROCK

HARD_ROCK

PUNK_ROCK

POP

INDIE_POP

ELECTROPOP

moods

string[] · unique

Enum values:

ENERGETIC

CALM

RELAXED

INTENSE

HAPPY

SAD

ROMANTIC

MELANCHOLIC

Update a song › Responses

Song updated successfully

Response object representing a song in the catalog

id

string · uuid

Unique identifier of the song

title

string

Song title

durationSeconds

integer · int32

Duration in seconds

explicit

boolean

Indicates explicit content

videoUrl

string

URL of the video associated with the song

storageReference

string

Opaque storage reference or URI to the audio asset

collectionId

string · uuid

Identifier of the parent collection/album

coverUrl

string

Collection cover for song image display

releaseDate

string · date-time

Public release datetime in ISO-8601 UTC

primaryArtistName

string

Primary artist display name

primaryArtistId

string · uuid

Identifier of the primary artist

collaboratorIds

string[] · unique

Identifiers of collaborator artists

genres

string[] · unique

Genre classifications for the song

Enum values:

ROCK

ALTERNATIVE_ROCK

INDIE_ROCK

HARD_ROCK

PUNK_ROCK

POP

INDIE_POP

ELECTROPOP

moods

string[] · unique

Mood classifications that the song evokes

Enum values:

ENERGETIC

CALM

RELAXED

INTENSE

HAPPY

SAD

ROMANTIC

MELANCHOLIC

blockedAdmin

boolean

Indicates if the song is blocked by an administrator

effectiveState

string · enum

Effective availability state

Enum values:

BLOCKED_ADMIN

NOT_AVAILABLE_REGION

DRAFT

SCHEDULED

PUBLISHED

likesCount

integer · int32

Number of likes

createdAt

string · date-time

Creation timestamp in ISO-8601 UTC

updatedAt

string · date-time

Last update timestamp in ISO-8601 UTC

liked

boolean

Whether the current user has liked this song

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)

PUT/catalog/songs/{id}

curl --request PUT \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/songs/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Bohemian Rhapsody",
  "durationSeconds": 354,
  "explicit": false,
  "videoUrl": "https://www.youtube.com/watch?v=fJ9rUzIMcZQ",
  "storageReference": "s3://melody-songs/3fa85f64-5717-4562-b3fc-2c963f66afa6.mp3",
  "collectionId": "9b2f5a9f-1c2b-4f11-8c41-7d2ef6e6c123",
  "scheduledAt": "2025-10-20T12:00:00Z",
  "collaboratorIds": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "genres": [
    "ROCK"
  ],
  "moods": [
    "ENERGETIC"
  ]
}
'

shell

Example Request Body

{
  "title": "Bohemian Rhapsody",
  "durationSeconds": 354,
  "explicit": false,
  "videoUrl": "https://www.youtube.com/watch?v=fJ9rUzIMcZQ",
  "storageReference": "s3://melody-songs/3fa85f64-5717-4562-b3fc-2c963f66afa6.mp3",
  "collectionId": "9b2f5a9f-1c2b-4f11-8c41-7d2ef6e6c123",
  "scheduledAt": "2025-10-20T12:00:00Z",
  "collaboratorIds": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "genres": [
    "ROCK"
  ],
  "moods": [
    "ENERGETIC"
  ]
}

json

Example Responses

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Bohemian Rhapsody",
  "durationSeconds": 354,
  "explicit": false,
  "videoUrl": "https://www.youtube.com/watch?v=fJ9rUzIMcZQ",
  "storageReference": "s3://melody-songs/3fa85f64-5717-4562-b3fc-2c963f66afa6.mp3",
  "collectionId": "9b2f5a9f-1c2b-4f11-8c41-7d2ef6e6c123",
  "coverUrl": "https://example.com/cover.jpg",
  "releaseDate": "1975-10-31T00:00:00Z",
  "primaryArtistName": "Queen",
  "primaryArtistId": "5e1c2a1b-1234-4f67-9abc-0def12345678",
  "collaboratorIds": [
    "a1b2c3d4-1111-2222-3333-444455556666",
    "77778888-9999-aaaa-bbbb-ccccddddeeee"
  ],
  "genres": [
    "ROCK",
    "ALTERNATIVE_ROCK"
  ],
  "moods": [
    "ENERGETIC",
    "NOSTALGIC"
  ],
  "blockedAdmin": false,
  "effectiveState": "AVAILABLE",
  "likesCount": 12345,
  "createdAt": "2025-09-14T12:34:56Z",
  "updatedAt": "2025-09-20T08:15:30Z",
  "liked": true,
  "relevanceScore": 9500,
  "levenshteinDistance": 2
}

json

application/json

Delete a song

DELETE

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

/catalog/songs/{id}

Soft deletes a song. Only the song's artist can delete it.

Delete a song › path Parameters

id

string · uuid · required

Delete a song › Responses

Song deleted successfully

No data returned

DELETE/catalog/songs/{id}

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

shell

Example Responses

No example specified for this content type

Partially update a song

PATCH

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

/catalog/songs/{id}

Partially updates a song. Only the fields provided in the request will be updated. Only the song's artist can update it.

Partially update a song › path Parameters

id

string · uuid · required

Partially update a song › Request Body

Request object for partially updating an existing song (PATCH)

title

string

Song title

durationSeconds

integer · int32

Duration in seconds

explicit

boolean

Indicates explicit content

videoUrl

string

URL of the video associated with the song

storageReference

string

Opaque storage reference or URI to the audio asset

scheduledAt

string · date-time

Scheduled availability datetime in ISO-8601 UTC

collaboratorIds

string[] · unique

genres

string[] · unique

Enum values:

ROCK

ALTERNATIVE_ROCK

INDIE_ROCK

HARD_ROCK

PUNK_ROCK

POP

INDIE_POP

ELECTROPOP

moods

string[] · unique

Enum values:

ENERGETIC

CALM

RELAXED

INTENSE

HAPPY

SAD

ROMANTIC

MELANCHOLIC

blockedRegions

string[] · unique

Partially update a song › Responses

Song updated successfully

Response object representing a song in the catalog

id

string · uuid

Unique identifier of the song

title

string

Song title

durationSeconds

integer · int32

Duration in seconds

explicit

boolean

Indicates explicit content

videoUrl

string

URL of the video associated with the song

storageReference

string

Opaque storage reference or URI to the audio asset

collectionId

string · uuid

Identifier of the parent collection/album

coverUrl

string

Collection cover for song image display

releaseDate

string · date-time

Public release datetime in ISO-8601 UTC

primaryArtistName

string

Primary artist display name

primaryArtistId

string · uuid

Identifier of the primary artist

collaboratorIds

string[] · unique

Identifiers of collaborator artists

genres

string[] · unique

Genre classifications for the song

Enum values:

ROCK

ALTERNATIVE_ROCK

INDIE_ROCK

HARD_ROCK

PUNK_ROCK

POP

INDIE_POP

ELECTROPOP

moods

string[] · unique

Mood classifications that the song evokes

Enum values:

ENERGETIC

CALM

RELAXED

INTENSE

HAPPY

SAD

ROMANTIC

MELANCHOLIC

blockedAdmin

boolean

Indicates if the song is blocked by an administrator

effectiveState

string · enum

Effective availability state

Enum values:

BLOCKED_ADMIN

NOT_AVAILABLE_REGION

DRAFT

SCHEDULED

PUBLISHED

likesCount

integer · int32

Number of likes

createdAt

string · date-time

Creation timestamp in ISO-8601 UTC

updatedAt

string · date-time

Last update timestamp in ISO-8601 UTC

liked

boolean

Whether the current user has liked this song

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)

PATCH/catalog/songs/{id}

curl --request PATCH \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/songs/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Bohemian Rhapsody",
  "durationSeconds": 354,
  "explicit": false,
  "videoUrl": "https://www.youtube.com/watch?v=fJ9rUzIMcZQ",
  "storageReference": "s3://melody-songs/3fa85f64-5717-4562-b3fc-2c963f66afa6.mp3",
  "scheduledAt": "2025-10-20T12:00:00Z",
  "collaboratorIds": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "genres": [
    "ROCK"
  ],
  "moods": [
    "ENERGETIC"
  ],
  "blockedRegions": [
    "string"
  ]
}
'

shell

Example Request Body

{
  "title": "Bohemian Rhapsody",
  "durationSeconds": 354,
  "explicit": false,
  "videoUrl": "https://www.youtube.com/watch?v=fJ9rUzIMcZQ",
  "storageReference": "s3://melody-songs/3fa85f64-5717-4562-b3fc-2c963f66afa6.mp3",
  "scheduledAt": "2025-10-20T12:00:00Z",
  "collaboratorIds": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "genres": [
    "ROCK"
  ],
  "moods": [
    "ENERGETIC"
  ],
  "blockedRegions": [
    "string"
  ]
}

json

Example Responses

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Bohemian Rhapsody",
  "durationSeconds": 354,
  "explicit": false,
  "videoUrl": "https://www.youtube.com/watch?v=fJ9rUzIMcZQ",
  "storageReference": "s3://melody-songs/3fa85f64-5717-4562-b3fc-2c963f66afa6.mp3",
  "collectionId": "9b2f5a9f-1c2b-4f11-8c41-7d2ef6e6c123",
  "coverUrl": "https://example.com/cover.jpg",
  "releaseDate": "1975-10-31T00:00:00Z",
  "primaryArtistName": "Queen",
  "primaryArtistId": "5e1c2a1b-1234-4f67-9abc-0def12345678",
  "collaboratorIds": [
    "a1b2c3d4-1111-2222-3333-444455556666",
    "77778888-9999-aaaa-bbbb-ccccddddeeee"
  ],
  "genres": [
    "ROCK",
    "ALTERNATIVE_ROCK"
  ],
  "moods": [
    "ENERGETIC",
    "NOSTALGIC"
  ],
  "blockedAdmin": false,
  "effectiveState": "AVAILABLE",
  "likesCount": 12345,
  "createdAt": "2025-09-14T12:34:56Z",
  "updatedAt": "2025-09-20T08:15:30Z",
  "liked": true,
  "relevanceScore": 9500,
  "levenshteinDistance": 2
}

json

application/json

Get songs

GET

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

/catalog/songs

Retrieves a paginated list of songs. Optionally filter by artist ID or search by query.

Get songs › query Parameters

artistId

string · uuid

query

string

page

integer · int32

Default: 0

size

integer · int32

Default: 20

Get songs › Responses

Songs retrieved successfully

Response object representing a song in the catalog

id

string · uuid

Unique identifier of the song

title

string

Song title

durationSeconds

integer · int32

Duration in seconds

explicit

boolean

Indicates explicit content

videoUrl

string

URL of the video associated with the song

storageReference

string

Opaque storage reference or URI to the audio asset

collectionId

string · uuid

Identifier of the parent collection/album

coverUrl

string

Collection cover for song image display

releaseDate

string · date-time

Public release datetime in ISO-8601 UTC

primaryArtistName

string

Primary artist display name

primaryArtistId

string · uuid

Identifier of the primary artist

collaboratorIds

string[] · unique

Identifiers of collaborator artists

genres

string[] · unique

Genre classifications for the song

Enum values:

ROCK

ALTERNATIVE_ROCK

INDIE_ROCK

HARD_ROCK

PUNK_ROCK

POP

INDIE_POP

ELECTROPOP

moods

string[] · unique

Mood classifications that the song evokes

Enum values:

ENERGETIC

CALM

RELAXED

INTENSE

HAPPY

SAD

ROMANTIC

MELANCHOLIC

blockedAdmin

boolean

Indicates if the song is blocked by an administrator

effectiveState

string · enum

Effective availability state

Enum values:

BLOCKED_ADMIN

NOT_AVAILABLE_REGION

DRAFT

SCHEDULED

PUBLISHED

likesCount

integer · int32

Number of likes

createdAt

string · date-time

Creation timestamp in ISO-8601 UTC

updatedAt

string · date-time

Last update timestamp in ISO-8601 UTC

liked

boolean

Whether the current user has liked this song

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)

GET/catalog/songs

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

shell

Example Responses

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Bohemian Rhapsody",
  "durationSeconds": 354,
  "explicit": false,
  "videoUrl": "https://www.youtube.com/watch?v=fJ9rUzIMcZQ",
  "storageReference": "s3://melody-songs/3fa85f64-5717-4562-b3fc-2c963f66afa6.mp3",
  "collectionId": "9b2f5a9f-1c2b-4f11-8c41-7d2ef6e6c123",
  "coverUrl": "https://example.com/cover.jpg",
  "releaseDate": "1975-10-31T00:00:00Z",
  "primaryArtistName": "Queen",
  "primaryArtistId": "5e1c2a1b-1234-4f67-9abc-0def12345678",
  "collaboratorIds": [
    "a1b2c3d4-1111-2222-3333-444455556666",
    "77778888-9999-aaaa-bbbb-ccccddddeeee"
  ],
  "genres": [
    "ROCK",
    "ALTERNATIVE_ROCK"
  ],
  "moods": [
    "ENERGETIC",
    "NOSTALGIC"
  ],
  "blockedAdmin": false,
  "effectiveState": "AVAILABLE",
  "likesCount": 12345,
  "createdAt": "2025-09-14T12:34:56Z",
  "updatedAt": "2025-09-20T08:15:30Z",
  "liked": true,
  "relevanceScore": 9500,
  "levenshteinDistance": 2
}

json

application/json

Create a new song

POST

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

/catalog/songs

Creates a new song in the catalog. Only artists can create songs.

Create a new song › Request Body

Request payload to create a new song

title

string · required

Song title

durationSeconds

integer · int32

Duration in seconds

explicit

boolean

Indicates explicit content

videoUrl

string

URL of the video associated with the song

storageReference

string

Opaque storage reference or URI to the audio asset

collectionId

string · uuid

Identifier of the parent collection/album (optional)

positionInCollection

integer · int32

Track position within the collection (1-based, optional)

collaboratorIds

string[] · unique

genres

string[] · unique

Enum values:

ROCK

ALTERNATIVE_ROCK

INDIE_ROCK

HARD_ROCK

PUNK_ROCK

POP

INDIE_POP

ELECTROPOP

moods

string[] · unique

Enum values:

ENERGETIC

CALM

RELAXED

INTENSE

HAPPY

SAD

ROMANTIC

MELANCHOLIC

Create a new song › Responses

Song created successfully

Response object representing a song in the catalog

id

string · uuid

Unique identifier of the song

title

string

Song title

durationSeconds

integer · int32

Duration in seconds

explicit

boolean

Indicates explicit content

videoUrl

string

URL of the video associated with the song

storageReference

string

Opaque storage reference or URI to the audio asset

collectionId

string · uuid

Identifier of the parent collection/album

coverUrl

string

Collection cover for song image display

releaseDate

string · date-time

Public release datetime in ISO-8601 UTC

primaryArtistName

string

Primary artist display name

primaryArtistId

string · uuid

Identifier of the primary artist

collaboratorIds

string[] · unique

Identifiers of collaborator artists

genres

string[] · unique

Genre classifications for the song

Enum values:

ROCK

ALTERNATIVE_ROCK

INDIE_ROCK

HARD_ROCK

PUNK_ROCK

POP

INDIE_POP

ELECTROPOP

moods

string[] · unique

Mood classifications that the song evokes

Enum values:

ENERGETIC

CALM

RELAXED

INTENSE

HAPPY

SAD

ROMANTIC

MELANCHOLIC

blockedAdmin

boolean

Indicates if the song is blocked by an administrator

effectiveState

string · enum

Effective availability state

Enum values:

BLOCKED_ADMIN

NOT_AVAILABLE_REGION

DRAFT

SCHEDULED

PUBLISHED

likesCount

integer · int32

Number of likes

createdAt

string · date-time

Creation timestamp in ISO-8601 UTC

updatedAt

string · date-time

Last update timestamp in ISO-8601 UTC

liked

boolean

Whether the current user has liked this song

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)

POST/catalog/songs

curl --request POST \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/catalog/songs \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Bohemian Rhapsody",
  "durationSeconds": 354,
  "explicit": false,
  "videoUrl": "https://www.youtube.com/watch?v=fJ9rUzIMcZQ",
  "storageReference": "s3://melody-songs/3fa85f64-5717-4562-b3fc-2c963f66afa6.mp3",
  "collectionId": "9b2f5a9f-1c2b-4f11-8c41-7d2ef6e6c123",
  "positionInCollection": 3,
  "collaboratorIds": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "genres": [
    "ROCK"
  ],
  "moods": [
    "ENERGETIC"
  ]
}
'

shell

Example Request Body

{
  "title": "Bohemian Rhapsody",
  "durationSeconds": 354,
  "explicit": false,
  "videoUrl": "https://www.youtube.com/watch?v=fJ9rUzIMcZQ",
  "storageReference": "s3://melody-songs/3fa85f64-5717-4562-b3fc-2c963f66afa6.mp3",
  "collectionId": "9b2f5a9f-1c2b-4f11-8c41-7d2ef6e6c123",
  "positionInCollection": 3,
  "collaboratorIds": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "genres": [
    "ROCK"
  ],
  "moods": [
    "ENERGETIC"
  ]
}

json

Example Responses

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Bohemian Rhapsody",
  "durationSeconds": 354,
  "explicit": false,
  "videoUrl": "https://www.youtube.com/watch?v=fJ9rUzIMcZQ",
  "storageReference": "s3://melody-songs/3fa85f64-5717-4562-b3fc-2c963f66afa6.mp3",
  "collectionId": "9b2f5a9f-1c2b-4f11-8c41-7d2ef6e6c123",
  "coverUrl": "https://example.com/cover.jpg",
  "releaseDate": "1975-10-31T00:00:00Z",
  "primaryArtistName": "Queen",
  "primaryArtistId": "5e1c2a1b-1234-4f67-9abc-0def12345678",
  "collaboratorIds": [
    "a1b2c3d4-1111-2222-3333-444455556666",
    "77778888-9999-aaaa-bbbb-ccccddddeeee"
  ],
  "genres": [
    "ROCK",
    "ALTERNATIVE_ROCK"
  ],
  "moods": [
    "ENERGETIC",
    "NOSTALGIC"
  ],
  "blockedAdmin": false,
  "effectiveState": "AVAILABLE",
  "likesCount": 12345,
  "createdAt": "2025-09-14T12:34:56Z",
  "updatedAt": "2025-09-20T08:15:30Z",
  "liked": true,
  "relevanceScore": 9500,
  "levenshteinDistance": 2
}

json

application/json

Advanced search for songs

GET

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

/catalog/songs/search

Performs an advanced search using Levenshtein distance algorithm. Only returns songs that are PUBLISHED or SCHEDULED in the user's region, excluding blocked content.

Advanced search for songs › query Parameters

query

string · required

page

integer · int32

Default: 0

size

integer · int32

Default: 20

Advanced search for songs › Responses

Search results retrieved successfully

Response object representing a song in the catalog

id

string · uuid

Unique identifier of the song

title

string

Song title

durationSeconds

integer · int32

Duration in seconds

explicit

boolean

Indicates explicit content

videoUrl

string

URL of the video associated with the song

storageReference

string

Opaque storage reference or URI to the audio asset

collectionId

string · uuid

Identifier of the parent collection/album

coverUrl

string

Collection cover for song image display

releaseDate

string · date-time

Public release datetime in ISO-8601 UTC

primaryArtistName

string

Primary artist display name

primaryArtistId

string · uuid

Identifier of the primary artist

collaboratorIds

string[] · unique

Identifiers of collaborator artists

genres

string[] · unique

Genre classifications for the song

Enum values:

ROCK

ALTERNATIVE_ROCK

INDIE_ROCK

HARD_ROCK

PUNK_ROCK

POP

INDIE_POP

ELECTROPOP

moods

string[] · unique

Mood classifications that the song evokes

Enum values:

ENERGETIC

CALM

RELAXED

INTENSE

HAPPY

SAD

ROMANTIC

MELANCHOLIC

blockedAdmin

boolean

Indicates if the song is blocked by an administrator

effectiveState

string · enum

Effective availability state

Enum values:

BLOCKED_ADMIN

NOT_AVAILABLE_REGION

DRAFT

SCHEDULED

PUBLISHED

likesCount

integer · int32

Number of likes

createdAt

string · date-time

Creation timestamp in ISO-8601 UTC

updatedAt

string · date-time

Last update timestamp in ISO-8601 UTC

liked

boolean

Whether the current user has liked this song

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)

GET/catalog/songs/search

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

shell

Example Responses

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Bohemian Rhapsody",
  "durationSeconds": 354,
  "explicit": false,
  "videoUrl": "https://www.youtube.com/watch?v=fJ9rUzIMcZQ",
  "storageReference": "s3://melody-songs/3fa85f64-5717-4562-b3fc-2c963f66afa6.mp3",
  "collectionId": "9b2f5a9f-1c2b-4f11-8c41-7d2ef6e6c123",
  "coverUrl": "https://example.com/cover.jpg",
  "releaseDate": "1975-10-31T00:00:00Z",
  "primaryArtistName": "Queen",
  "primaryArtistId": "5e1c2a1b-1234-4f67-9abc-0def12345678",
  "collaboratorIds": [
    "a1b2c3d4-1111-2222-3333-444455556666",
    "77778888-9999-aaaa-bbbb-ccccddddeeee"
  ],
  "genres": [
    "ROCK",
    "ALTERNATIVE_ROCK"
  ],
  "moods": [
    "ENERGETIC",
    "NOSTALGIC"
  ],
  "blockedAdmin": false,
  "effectiveState": "AVAILABLE",
  "likesCount": 12345,
  "createdAt": "2025-09-14T12:34:56Z",
  "updatedAt": "2025-09-20T08:15:30Z",
  "liked": true,
  "relevanceScore": 9500,
  "levenshteinDistance": 2
}

json

application/json

Get song overview with period comparison

GET

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

/metrics/songs/{songId}/overview

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

Get song overview with period comparison › path Parameters

songId

string · uuid · required

Song ID

Get song 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 song overview with period comparison › Responses

Song overview metrics found

Comprehensive metrics overview for a specific song

songId

string · uuid

Song ID

title

string

Song title

artist

string

Artist name

artistId

string · uuid

Artist ID

totalPlays

integer · int64

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

totalLikes

integer · int64

All-time total likes (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/songs/{songId}/overview

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

shell

Example Responses

{
  "songId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Summer Vibes",
  "artist": "Artist Name",
  "artistId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "totalPlays": 5234567,
  "totalLikes": 423890,
  "periodPlays": {
    "current": 1250,
    "previous": 1100,
    "changePercent": 13.64
  },
  "periodLikes": {
    "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": "US"
}

json

application/json

Playback health-controller