-
Notifications
You must be signed in to change notification settings - Fork 5
GetSongs
Walter Lara edited this page Jul 16, 2024
·
28 revisions
Allows to get Songs. This endpoint supports pagination and filtering.
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
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"
}
]
Code: 401 UNAUTHORIZED
Condition: If {accessToken}
is invalid or expired.
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"
}