Skip to content

GetSongs

Jump to bottom
Walter Lara edited this page Jul 16, 2024 · 28 revisions

Get Songs

Allows to get Songs. This endpoint supports pagination and filtering.

Request

URL: /v1/songs

Method: GET

Path Parameters: None

Query Parameters:

Parameter Type Description Requirement Type
offset integer Start offset of paginated results to retrieve. Default is 0. Optional
limit integer Maximum number of paginated results to retrieve. Default is 25. Optional
archived boolean Indicates if only archived songs should be included. Default is false. Optional
sortOrder string Sort order of the results based on createdAt field. Valid values are desc (newest first) and asc (oldest first). Default is asc. Optional
phrase string Case-insensitive phrase to filter out songs by searching the Song title, description, album and nftName fields as well as the Song Owner nickname if set, otherwise firstName and lastName. If the parameter is missing, defaults to no filtering out. Optional
ids string list Comma-separated list of song UUID's for filtering results. Prefix each value with - to exclude and + (optional) to include. Defaults to inclusion if no prefix is specified. Optional
ownerIds string list Comma-separated list of owner UUID's for filtering results. A value of "me" can be used instead of the caller's UUID. Prefix each value with - to exclude and + (optional) to include. Defaults to inclusion if no prefix is specified. Optional
genres string list Comma-separated list of song genres for filtering results. Prefix each value with - to exclude and + (optional) to include. Defaults to inclusion if no prefix is specified. Optional
moods string list Comma-separated list of song moods to for filtering results. Prefix each value with - to exclude and + (optional) to include. Defaults to inclusion if no prefix is specified. Optional
mintingStatuses string list Comma-separated list of song Song minting statuses for filtering results. Prefix each value with - to exclude and + (optional) to include. Defaults to inclusion if no prefix is specified. Optional
olderThan string ISO-8601 formated oldest (maximum) timestamp to filter-out results. If missing, defaults to no filtering out. Optional
newerThan string ISO-8601 formated newest (minimum) timestamp to filter-out results. If missing, defaults to no filtering out. Optional

Headers:

Authorization: Bearer {accessToken}

Accept: application/json

✅ Success Response

Code: 200 OK

Headers:

Content-Type: application/json

Content:

Field Type Description Condition
id string UUID of the Song. Always
archived boolean Song archive indicator. Always
ownerId string UUID of the Song owner (creator). Always
createdAt string Date and time when the Song was created (ISO-8601 format). Always
title string Song title. Always
genres string array Song genres. Always
moods string array Song moods. Only if available
coverArtUrl string Valid URL of cover art picture file. Only if available
lyricsUrl string Valid URL of song lyrics file. Only if available
description string Song description. Only if available
album string Song album. Only if available
track integer Song track. Only if available
language string Song language. Only if available
coverRemixSample boolean Indicates if the Song is a Cover, Remix or Sample. Always
compositionCopyrightOwner string Song composition copyright owner. Only if available
compositionCopyrightYear integer Song composition copyright year. Only if available
phonographicCopyrightOwner string Song phonographic copyright owner. Only if available
phonographicCopyrightYear integer Song phonographic copyright year. Only if available
parentalAdvisory string Song parental advisory. Only if available
barcodeType string Song barcode type. Valid values are: Upc, Ean and Jan. Only if available
barcodeNumber string Song barcode number. Only if available
isrc string International Standard Recording Code (ISRC). Only if available
iswc string International Standard Musical Work Code (ISWC). Only if available
ipis string array Interested Party Information (IPIS) Numbers. Only if available
releaseDate string Song release date (ISO-8601 format) Only if available
publicationDate string Song publication date (ISO-8601 format) Only if available
duration integer Song duration in milliseconds. Only if available
streamUrl string Song streaming URL. Only if available
nftPolicyId string Song NFT Policy ID. Only if available
nftName string Song NFT Name. Only if available
audioEncodingStatus string Song audio encoding status. Valid values are: NotStarted, Started, Completed & Failed Always
mintingStatus string Song minting status. Valid values are: Undistributed, StreamTokenAgreementApproved, MintingPaymentRequested, MintingPaymentReceived, AwaitingAudioEncoding, AwaitingCollaboratorApproval, ReadyToDistribute, SubmittedForDistribution, Distributed, Declined, Pending & Minted Always
marketplaceStatus string Song marketplace status. Valid valid values are: NotSelling & Selling. Always

Content example:

[
    {
        "id": "7bd2862f-8deb-4814-8943-156d9dab80dd",
        "archived": false,
        "ownerId": "842f5460-76f8-41d8-add9-d043a7a381de",
        "createdAt": "2022-04-22T20:47:55.738918",
        "title": "Blinding Lights",
        "genres": ["Synthwave", "Synthpop"],
        "moods": ["Cool", "Upbeat"],
        "coverArtUrl": "https://www.example.com/bindinglights/cover.png",
        "lyricsUrl": "https://www.example.com/bindinglights/lyrics.txt",
        "description": "Song by The Weeknd",
        "coverRemixSample": false,
        "compositionCopyrightOwner": "© The Weeknd",
        "compositionCopyrightYear": 2022
        "duration": 132202,
        "streamUrl": "https://www.example.com/bindinglights/blinding_lights.m4a",
        "nftPolicyId": "11123344555",
        "nftPolicyName": "Blinding Lights NFT",
        "audioEncodingStatus": "Completed",
        "mintingStatus": "Minted",
        "marketplaceStatus": "Selling"
    },
    {
        "id": "5cd11788-4cc1-4768-b4fa-4c0f519a94c5",
        "archived": false,
        "ownerId": "842f5460-76f8-41d8-add9-d043a7a381de",
        "createdAt": "2022-05-22T20:46:46.738741",
        "title": "Save Your Tears",
        "genres": ["Synthwave", "Synthpop"],
        "moods": ["Sentimental", "Sophisticated"],
        "coverArtUrl": "https://www.example.com/saveyourtears/cover.png",
        "lyricsUrl": "https://www.example.com/saveyourtears/lyrics.txt",
        "description": "Song by The Weeknd",
        "coverRemixSample": false,
        "compositionCopyrightOwner": "© The Weeknd",
        "compositionCopyrightYear": 2023
        "duration": 143200,
        "streamUrl": "https://www.example.com/saveyourtears/save_your_tears.m4a",
        "nftPolicyId": "4444555666",
        "nftPolicyName": "Save Your Tears NFT",
        "audioEncodingStatus": "Completed",
        "mintingStatus": "Minted",
        "marketplaceStatus": "NotSelling"
    }
]

❌ Error Responses

1. Unauthorized

Code: 401 UNAUTHORIZED

Condition: If {accessToken} is invalid or expired.

2. Unprocessable Entity

Code: 422 UNPROCESSABLE ENTITY

Condition: If any of the UUID query parameters is malformed.

Headers:

Content-Type: application/json

Content example:

{
    "code": 422,
    "description": "Unprocessable Entity",
    "cause": "Invalid UUID string: 123456789"
}

See Also

Post Song (Add New Song)

Patch Song (Update Song)

Get Song Count

Get Song

Delete Song

Upload Song Audio

Process Song Stream Token Agreement

Get Song Genres

Get Song Genre Count

Clone this wiki locally