Set Items
Set contain songs that can be viewed and modified.
List songs
| URL | /api/<auth_token>/sets/<set_identifier>/songs |
| Method | GET |
| Version | 1.0 |
Description
Lists songs contained within the set in the appropriate order.
Path arguments
| Name | Type | Description | Required |
|---|---|---|---|
| auth_token | string | The authentication token used to authenticate the request. | Required |
| set_identifier | string | The identifier of the set. | Required |
Response
Returns a list of songs in the set including the song's unique identifier, title and other basic information.
Response example
[
{
"artist": "Bryan Adams",
"title": "Cuts Like A Knife",
"favorite": 0,
"usefile": false,
"key": "D",
"class": "Song",
"ID": "D3E86FCD-356A-48A1-AC31-B0B6FC12F025"
},
{
"ID": "C43DC77D-68BF-4BFE-8A56-BCB51CF73AC5",
"title": "Time Is On My Side",
"favorite": 0,
"usefile": false,
"class": "Song",
"artist": "Rolling Stones"
},
{
"ID": "63FD467D-EF75-4EA6-B22C-104DB919D3DA",
"title": "Long Hard Road",
"favorite": 0,
"usefile": false,
"class": "Song",
"artist": "Nitty Gritty Dirt Band"
},
{
"ID": "2F0021FE-60DD-41A6-8354-CEBB9B99B95B",
"title": "And We Danced",
"favorite": 0,
"usefile": false,
"class": "Song",
"artist": "Hooters"
}
]
Add songs
| URL | /api/<auth_token>/sets/<set_identifier>/songs |
| Method | PUT |
| Version | 1.0 |
Description
Adds new songs to the set, optionally placing the songs.
Path arguments
| Name | Type | Description | Required |
|---|---|---|---|
| auth_token | string | The authentication token used to authenticate the request. | Required |
| set_identifier | string | The identifier of the set. | Required |
Body arguments
The body can contain a single identifier as a string, an array of identifiers or song objects, or an object containing the following:
| Name | Type | Description | Required |
|---|---|---|---|
| songs | array | The identifiers or song objects of the songs to be added to the set. | Required |
| placement | number | The placement of the songs within the set. If set to zero, the songs are added to the beginning of the set. If set to a number greater than the current number of songs in the set, the songs are added to the end of the set. Otherwise the songs are added in their zero-based index in the set. | Optional |
Response
One of two results will be returned:
| Name | Type | Description |
|---|---|---|
| success | object | The operation was successful and basic set information is returned. |
| error | string | The operation has failed and text indicating the error is returned. |
Response example
The following is an example of a successful update:
[
{
"success": {
"/sets/4246F094-AD81-4EE3-B446-2C48AC88DF87/songs": [
"D3E86FCD-356A-48A1-AC31-B0B6FC12F025"
]
}
}
]
Update songs
| URL | /api/<auth_token>/sets/<set_identifier>/songs |
| Method | POST |
| Version | 1.0 |
Description
Updates the songs in the set list which can be used to reorder, add and remove songs.
Path arguments
| Name | Type | Description | Required |
|---|---|---|---|
| auth_token | string | The authentication token used to authenticate the request. | Required |
| set_identifier | string | The identifier of the set. | Required |
Body arguments
The body can contain a single identifier as a string, an array of identifiers or song objects, or an object containing the following:
| Name | Type | Description | Required |
|---|---|---|---|
| songs | array | The identifiers or song objects of the songs as they should appear within the set. | Required |
Response
One of two results will be returned:
| Name | Type | Description |
|---|---|---|
| success | object | The operation was successful and basic set information is returned. |
| error | string | The operation has failed and text indicating the error is returned. |
Response example
The following is an example of a successful update:
[
{
"success": {
"/sets/4246F094-AD81-4EE3-B446-2C48AC88DF87/songs": [
"D3E86FCD-356A-48A1-AC31-B0B6FC12F025"
]
}
}
]
Delete songs
| URL | /api/<auth_token>/sets/<set_identifier>/songs |
| Method | DELETE |
| Version | 1.0 |
Description
Removes the specified songs from the set if the set already contains the songs.
Path arguments
| Name | Type | Description | Required |
|---|---|---|---|
| auth_token | string | The authentication token used to authenticate the request. | Required |
| set_identifier | string | The identifier of the set. | Required |
Body arguments
The body can contain a single identifier as a string, an array of identifiers or song objects, or an object containing the following:
| Name | Type | Description | Required |
|---|---|---|---|
| songs | array | The identifiers or song objects of the songs as they should appear within the set. | Required |
Response
One of two results will be returned:
| Name | Type | Description |
|---|---|---|
| success | object | The operation was successful and basic set information is returned. |
| error | string | The operation has failed and text indicating the error is returned. |
Response example
The following is an example of a successful update:
[
{
"success": {
"/sets/4246F094-AD81-4EE3-B446-2C48AC88DF87/songs": [
"D3E86FCD-356A-48A1-AC31-B0B6FC12F025"
]
}
}
]