Collection management operations
Get collections
Retrieves collections. By default shows only published collections.
query Parameters
publishedGet collections › Responses
Collections retrieved successfully
idUnique identifier of the collection
titleTitle of the collection
descriptionDescription of the collection
coverUrlURL of the collection's cover image
typeType of the collection
effectiveStateStatus of the collection
primaryArtistIdID of the primary artist
primaryArtistNameName of the primary artist
scheduledReleaseDateScheduled release date of the collection
actualReleaseDateActual release date of the collection
createdAtDate and time when the collection was created
updatedAtDate and time when the collection was last updated
relevanceScoreRelevance score for search results (null if not from search)
levenshteinDistanceLevenshtein distance for search results (null if not from search)
isSavedIndicates whether the current user has saved/bookmarked this collection
Create a new collection
Creates a new collection in the catalog. Only artists can create collections.
Create a new collection › Request Body
titleTitle of the collection
typeType of the collection. SINGLE: 1 song auto-created, ALBUM/EP: multiple songs can be added
descriptionDetailed description of the collection
coverUrlURL of the collection's cover image
Create a new collection › Responses
Collection created successfully
idUnique identifier of the collection
titleTitle of the collection
descriptionDescription of the collection
coverUrlURL of the collection's cover image
typeType of the collection
effectiveStateStatus of the collection
primaryArtistIdID of the primary artist
primaryArtistNameName of the primary artist
durationSecondsTotal duration of the collection in seconds (sum of all songs)
scheduledReleaseDateScheduled release date of the collection
actualReleaseDateActual release date of the collection
List of songs in the collection (ordered)
createdAtDate and time when the collection was created
updatedAtDate and time when the collection was last updated
relevanceScoreRelevance score for search results (null if not from search)
levenshteinDistanceLevenshtein distance for search results (null if not from search)
isSavedIndicates whether the current user has saved/bookmarked this collection
Publish or schedule a collection
Publishes a collection immediately or schedules it for future publication.
Behavior:
- If scheduledAt is null or absent in the request body: publishes immediately
- If scheduledAt is provided: schedules the collection for the specified date/time
Only the collection owner can publish it.
path Parameters
idPublish or schedule a collection › Request Body
scheduledAtScheduled publication time. If null, publishes immediately.
Publish or schedule a collection › Responses
Collection published/scheduled successfully
idUnique identifier of the collection
titleTitle of the collection
descriptionDescription of the collection
coverUrlURL of the collection's cover image
typeType of the collection
effectiveStateStatus of the collection
primaryArtistIdID of the primary artist
primaryArtistNameName of the primary artist
durationSecondsTotal duration of the collection in seconds (sum of all songs)
scheduledReleaseDateScheduled release date of the collection
actualReleaseDateActual release date of the collection
List of songs in the collection (ordered)
createdAtDate and time when the collection was created
updatedAtDate and time when the collection was last updated
relevanceScoreRelevance score for search results (null if not from search)
levenshteinDistanceLevenshtein distance for search results (null if not from search)
isSavedIndicates whether the current user has saved/bookmarked this collection
Get collection by ID
Retrieves a collection by its unique identifier.
path Parameters
idGet collection by ID › Responses
Collection retrieved successfully
idUnique identifier of the collection
titleTitle of the collection
descriptionDescription of the collection
coverUrlURL of the collection's cover image
typeType of the collection
effectiveStateStatus of the collection
primaryArtistIdID of the primary artist
primaryArtistNameName of the primary artist
durationSecondsTotal duration of the collection in seconds (sum of all songs)
scheduledReleaseDateScheduled release date of the collection
actualReleaseDateActual release date of the collection
List of songs in the collection (ordered)
createdAtDate and time when the collection was created
updatedAtDate and time when the collection was last updated
relevanceScoreRelevance score for search results (null if not from search)
levenshteinDistanceLevenshtein distance for search results (null if not from search)
isSavedIndicates whether the current user has saved/bookmarked this collection
Update collection metadata
Updates non-critical metadata of a collection. Only the collection owner can update it.
path Parameters
idUpdate collection metadata › Request Body
titleTitle of the collection
descriptionDetailed description of the collection
coverUrlURL of the collection's cover image
scheduledReleaseDateScheduled release date for the collection (only for DRAFT or SCHEDULED)
blockedRegionsRegions where the collection is not available (blacklist)
Update collection metadata › Responses
Collection updated successfully
idUnique identifier of the collection
titleTitle of the collection
descriptionDescription of the collection
coverUrlURL of the collection's cover image
typeType of the collection
effectiveStateStatus of the collection
primaryArtistIdID of the primary artist
primaryArtistNameName of the primary artist
durationSecondsTotal duration of the collection in seconds (sum of all songs)
scheduledReleaseDateScheduled release date of the collection
actualReleaseDateActual release date of the collection
List of songs in the collection (ordered)
createdAtDate and time when the collection was created
updatedAtDate and time when the collection was last updated
relevanceScoreRelevance score for search results (null if not from search)
levenshteinDistanceLevenshtein distance for search results (null if not from search)
isSavedIndicates whether the current user has saved/bookmarked this collection
Advanced search for collections
Performs an advanced search using Levenshtein distance algorithm. Only returns collections that are PUBLISHED or SCHEDULED in the user's region, excluding blocked content.
query Parameters
querypagesizeAdvanced search for collections › Responses
Search results retrieved successfully
idUnique identifier of the collection
titleTitle of the collection
descriptionDescription of the collection
coverUrlURL of the collection's cover image
typeType of the collection
effectiveStateStatus of the collection
primaryArtistIdID of the primary artist
primaryArtistNameName of the primary artist
scheduledReleaseDateScheduled release date of the collection
actualReleaseDateActual release date of the collection
createdAtDate and time when the collection was created
updatedAtDate and time when the collection was last updated
relevanceScoreRelevance score for search results (null if not from search)
levenshteinDistanceLevenshtein distance for search results (null if not from search)
isSavedIndicates whether the current user has saved/bookmarked this collection
Reorder songs in a collection
Reorders the songs in a collection. Only allowed when the collection is in DRAFT state. Only the collection owner can reorder songs.
path Parameters
idReorder songs in a collection › Responses
Songs reordered successfully
idUnique identifier of the collection
titleTitle of the collection
descriptionDescription of the collection
coverUrlURL of the collection's cover image
typeType of the collection
effectiveStateStatus of the collection
primaryArtistIdID of the primary artist
primaryArtistNameName of the primary artist
durationSecondsTotal duration of the collection in seconds (sum of all songs)
scheduledReleaseDateScheduled release date of the collection
actualReleaseDateActual release date of the collection
List of songs in the collection (ordered)
createdAtDate and time when the collection was created
updatedAtDate and time when the collection was last updated
relevanceScoreRelevance score for search results (null if not from search)
levenshteinDistanceLevenshtein distance for search results (null if not from search)
isSavedIndicates whether the current user has saved/bookmarked this collection
Get collections by artist
Retrieves all collections from a specific artist. By default shows only published collections. Returns collections with their songs included.
path Parameters
artistIdquery Parameters
publishedGet collections by artist › Responses
Collections retrieved successfully
idUnique identifier of the collection
titleTitle of the collection
descriptionDescription of the collection
coverUrlURL of the collection's cover image
typeType of the collection
effectiveStateStatus of the collection
primaryArtistIdID of the primary artist
primaryArtistNameName of the primary artist
scheduledReleaseDateScheduled release date of the collection
actualReleaseDateActual release date of the collection
createdAtDate and time when the collection was created
updatedAtDate and time when the collection was last updated
relevanceScoreRelevance score for search results (null if not from search)
levenshteinDistanceLevenshtein distance for search results (null if not from search)
isSavedIndicates whether the current user has saved/bookmarked this collection
Get collections by mood
Retrieves published collections that contain at least one song with the specified mood. Only non-deleted and non-blocked collections available in the user's region are returned. Results are ordered by release date (newest first). Supports pagination.
query Parameters
moodMood to filter collections by
pagePage number (0-indexed)
sizePage size
Get collections by mood › Responses
Collections retrieved successfully
totalElementstotalPagesnumberOfElementssizenumberfirstlastemptyGet collections by genre
Retrieves published collections that contain at least one song with the specified genre. Only non-deleted and non-blocked collections available in the user's region are returned. Results are ordered by release date (newest first). Supports pagination.
query Parameters
genreGenre to filter collections by
pagePage number (0-indexed)
sizePage size
Get collections by genre › Responses
Collections retrieved successfully
totalElementstotalPagesnumberOfElementssizenumberfirstlastemptyGet top collections by artist
Retrieves the top collections for a specific artist based on popularity.
path Parameters
idGet top collections by artist › Responses
Top collections retrieved successfully
idUnique identifier of the collection
titleTitle of the collection
descriptionDescription of the collection
coverUrlURL of the collection's cover image
typeType of the collection
effectiveStateStatus of the collection
primaryArtistIdID of the primary artist
primaryArtistNameName of the primary artist
scheduledReleaseDateScheduled release date of the collection
actualReleaseDateActual release date of the collection
createdAtDate and time when the collection was created
updatedAtDate and time when the collection was last updated
relevanceScoreRelevance score for search results (null if not from search)
levenshteinDistanceLevenshtein distance for search results (null if not from search)
isSavedIndicates whether the current user has saved/bookmarked this collection
Get collection overview with period comparison
Returns comprehensive metrics overview for a specific collection with all-time totals and period comparison. Requires start_date and end_date.
path Parameters
collectionIdCollection ID
query Parameters
startDateStart date (YYYY-MM-DD)
endDateEnd date (YYYY-MM-DD)
regionRegion to filter (optional)
User Region
Get collection overview with period comparison › Responses
Collection overview metrics found
collectionIdCollection ID
titleCollection title
curatorCurator/Artist name
artistIdArtist ID
totalPlaysAll-time total plays (filtered by region if specified)
totalSavesAll-time total saves (filtered by region if specified)
Metric value with period comparison
Metric value with period comparison
Date range comparison with current and previous periods
regionThe region filter applied (null if not specified)