Songs
The songs API is used to find and view song information.
Find songs
URL | /api/<auth_token>/songs |
Method | GET |
Version | 1.0 |
Description
Finds and lists songs in your OnSong library.
Path arguments
Name | Type | Description | Required |
---|---|---|---|
auth_token | string | The authentication token used to authenticate the request. | Required |
Query arguments
Options for searching are passed via the query string as follows:
/api/<auth_token>/songs?q=welcome&limit=10&sort=title
Name | Type | Description | Required |
---|---|---|---|
q | string | The keyword query to look up songs. The API searches song title, artist, keywords and lyrics e.g. "love" | Optional |
title | string | The song title (full or partial) of the songs to retrieve e.g. "Rambl" | Optional |
artist | string | The artist (full or partial) of the songs to retrieve e.g. "Beatles" | Optional |
key | string | The key of the songs to retrieve e.g. "Am" | Optional |
topic | string | The topic/keyword of the songs to retrieve e.g. "Country" | Optional |
set | string | The unique identifier of a set for which songs are returned e.g. "41FEEEA9-EA9A-4AA0-9CD2-000E551E3540" | Optional |
book | string | The name of the book used to limit returned songs. Use the special names "all", "bound" or "unbound" to return all songs, songs that are bound to any book, or songs not bound in a book. |
Optional |
sort | string |
The sort method to use when returning songs. Options include:
|
Optional |
descending | boolean | Determines if songs should be returned in descending order. The default order is set by the sort method. | Optional |
limit | number | Limits the number of results returned. Default is 100. | Optional |
start | number | Offsets the start of returned results to be used for paging through results. Default is 0. | Optional |
Response
Returns a list of songs in the OnSong library including the song's unique identifier, title and other basic information.
Name | Type | Description |
---|---|---|
count | int | The total number of results that are returned, independent of limit and start. |
results | array |
Returns a list of song objects which include the song ID, title, artist, key, key, favorite and usefile.
|
attributes | object | Contains the query attributes that were passed. |
Response example
{ "count" : 4, "results" : [ { "ID" : "54AD9D08-69F0-49E7-9086-247B9F70457F", "title" : "How He Loves", "favorite" : 0, "usefile" : false, "key" : "C", "artist" : "David Crowder Band" }, { "ID" : "D3368162-FBC0-4D2F-B2BA-709ADE2DEB9A", "title" : "One Thing Remains", "favorite" : 0, "usefile" : false, "key" : "G", "artist" : "Jesus Culture" } ], "attributes" : { "q" : "love", "start" : "1", "limit" : "2" } }
Create song
URL | /api/<auth_token>/songs |
Method | PUT |
Version | 1.0 |
Description
Updates song information that has been posted.
Path arguments
Name | Type | Description | Required |
---|---|---|---|
auth_token | string | The authentication token used to authenticate the request. | Required |
Body
The body is a valid Songs Object containing detailed information about the song.
Response
Returns an array of status updates for each property that has been updated.
Name | Type | Description |
---|---|---|
success | object | The operation was successful and basic property 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" : { "/songs/new/title" : "New Title" } } ]
The following is an example of a failed operation with a 500 status code:
{ "error" : "Input must be a dictionary object" }
View song
URL | /api/<auth_token>/songs/<song_identifier> |
Method | GET |
Version | 1.0 |
Description
Retrieves song information from the OnSong library.
Path arguments
Name | Type | Description | Required |
---|---|---|---|
auth_token | string | The authentication token used to authenticate the request. | Required |
song_identifier | string | The song identifier of the song information to be retrieved. This can be the identifier of a song, or the term "current" which is the song currently being viewed. | Required |
Query arguments
Name | Type | Description | Required |
---|---|---|---|
with_chord_variations | boolean | Determines if chord variations should be included in the response. If omitted, chord variations are included. | Required |
Response
The response returns a valid Songs Object containing detailed information about the song.
Update song information
URL | /api/<auth_token>/songs/<song_identifier> |
Method | POST |
Version | 1.0 |
Description
Updates song information that has been posted.
Path arguments
Name | Type | Description | Required |
---|---|---|---|
auth_token | string | The authentication token used to authenticate the request. | Required |
song_identifier | string | The song identifier of the song information to be retrieved. This can be the identifier of a song, or the term "current" which is the song currently being viewed. | Required |
Query arguments
Name | Type | Description | Required |
---|---|---|---|
notify | boolean | Determines if a notification is sent to the app to redraw the screen. Default is TRUE. | Optional |
Body
The body is a valid Songs Object containing detailed information about the song.
Response
Returns an array of status updates for each property that has been updated.
Name | Type | Description |
---|---|---|
success | object | The operation was successful and basic property 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" : { "/songs/837BB846-F374-4369-86ED-2A1A08EE131B/title" : "New Title" } } ]
The following is an example of a failed operation with a 500 status code:
{ "error" : "Input must be a dictionary object" }
Delete song
URL | /api/<auth_token>/songs/<song_identifier> |
Method | DELETE |
Version | 1.0 |
Description
Deletes a set from your library.
Path arguments
Name | Type | Description | Required |
---|---|---|---|
auth_token | string | The authentication token used to authenticate the request. | Required |
song_identifier | string | The identifier of the song to be deleted, or the term "current" to delete the currently viewed song. | Required |
Response
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 deletion:
{ "success" : { "ID" : "837BB846-F374-4369-86ED-2A1A08EE131B", "title" : "Deleted Song" } }
The following is an example of a failed operation with a 500 status code:
{ "error" : "No song found" }
Retrieve content
URL | /api/<auth_token>/songs/<song_identifier>/content(.<format>) |
Method | GET |
Version | 1.0 |
Description
Retrieves the content of the song in various formats.
Path arguments
Name | Type | Description | Required |
---|---|---|---|
auth_token | string | The authentication token used to authenticate the request. | Required |
song_identifier | string | The song identifier for which content will be retrieved. | Required |
format | string | The format to use when returning content. Options include:
|
Optional |
Query arguments
Name | Type | Description | Required |
---|---|---|---|
download | boolean | Determines if the file should be forced to download. | Optional |
lyrics_only | boolean | Determines if the chords should be ommited from the output. | Optional |
original_key | boolean | Determines if the song should be outputted in it's original key. | Optional |
translate_chords | boolean | Determines if plain text files should be translated into bracketed chords. | Optional |
Response
Returns the specified content, setting the filename as the title of the song with the appropriate file extension.
Update content
URL | /api/<auth_token>/songs/<song_identifier>/content |
Method | POST |
Version | 1.0 |
Description
Updates the content of the song. This will also update the song information so you will need to retrieve song information after this operation.
Path arguments
Name | Type | Description | Required |
---|---|---|---|
auth_token | string | The authentication token used to authenticate the request. | Required |
song_identifier | string | The song identifier for which content will be retrieved. | Required |
Query arguments
Name | Type | Description | Required |
---|---|---|---|
notify | boolean | Determines if a notification is sent to the app to redraw the screen. Default is TRUE. | Optional |
Body
The body of the POST request must contain the full text of the content of the song in a valid format such as OnSong or ChordPro.
Response
One of two results will be returned:
Name | Type | Description |
---|---|---|
success | object | The operation was successful and basic song 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" : { "ID" : "837BB846-F374-4369-86ED-2A1A08EE131B", "title" : "Oceans (Where Feet May Fail)" } }
The following is an example of a failed update with a 404 status code:
{ "error" : "Song not found" }
Retrieve external file
URL | /api/<auth_token>/songs/<song_identifier>/file |
Method | GET |
Version | 1.0 |
Description
Retrieves the external file associated with the song.
Path arguments
Name | Type | Description | Required |
---|---|---|---|
auth_token | string | The authentication token used to authenticate the request. | Required |
song_identifier | string | The song identifier for which content will be retrieved. | Required |
Response
Returns the external file as an attachment with the file's imported filename. If an error occurs, the API returns an error as a JSON-formatted object with a 404 status code as follows:
{ "error" : "File not found" }
Retrieve sections
URL | /api/<auth_token>/songs/<song_identifier>/sections |
Method | GET |
Version | 1.0 |
Description
Retrieves the external file associated with the song.
Path arguments
Name | Type | Description | Required |
---|---|---|---|
auth_token | string | The authentication token used to authenticate the request. | Required |
song_identifier | string | The song identifier for which content will be retrieved or the term "current" to retrieve the currently viewed song. | Required |
Query arguments
Options for returning song section are passed via the query string as follows:
/api/<auth_token>/songs/<song_identifier>/sections?with_sections=true&with_chords=false
Name | Type | Description | Required |
---|---|---|---|
with_chords | boolean | Includes chords in the section. Chords will be added inline with lyrics surrounded by square brackets. | Optional |
with_transposition | boolean | Determines if chords should be transposed. | Optional |
with_flow | boolean | Determines if the sections should be arranged according to the flow attribute. | Optional |
with_formatting | boolean | Determines if line formatting information should be outputted. | Optional |
with_metadata | boolean | Determines if metadata, the first section of the song, should be outputted. | Optional |
with_sections | boolean | Determines if the sections should be divided by the section labels. | Optional |
Response
Returns a list of the sections in the song. This may be either an array of strings or an array of objects depending if the with_sections is set to true.
[ { "label": "Verse 1:", "sections": [ "to get started with OnSong, tap \"Songs\"\nyou can use this to manage your music\ndon't forget you can swipe left to right\nand simply delete songs you don't like" ] }, { "label": "Chorus:", "sections": [ "tap the gear icon all the way to the right\nand get help on any topic you need\nor tap the sliders icon almost to the right\nand change how your song looks" ] }, { "label": "try out the other menubar options", "sections": [ "and see all that you can do\nlike editing and playing songs\nor sharing music with your band" ] }, { "label": "Verse 2:", "sections": [ "to navigate, just swipe or tap\nleft or right or up or down\nscroll anywhere you want to go\ntap in the middle for full screen" ] } ]
Import songs
URL | /api/<auth_token>/songs/import |
Method | POST |
Version | 1.0 |
Description
Uploads one or more files to the OnSong library to be imported.
Body
Upload one or more files using one or more files in a multipart form data. In HTML you can do this with the following code:
<form action="/api/<auth_token>/songs/import" method="post" enctype="multipart/form-data"> <input type="file" name="file1"/> <input type="file" name="file2"/> <input type="submit" value="Import"/> </form>
Response
Returns an array of songs that have been successfully imported.
Response example
[ { "ID" : "837BB846-F374-4369-86ED-2A1A08EE131C", "title" : @"New Song" }, { "ID" : "837BB846-F374-4369-86ED-2A1A08EE131D", "title" : @"Another Song" } ]
Convert song
URL | /api/<auth_token>/songs/<song_identifier>/convert |
Method | GET |
Version | 1.0 |
Description
Converts the existing imported file into converted text.
Path arguments
Name | Type | Description | Required |
---|---|---|---|
auth_token | string | The authentication token used to authenticate the request. | Required |
song_identifier | string | The song identifier for the song to be converted. Use the value of "current" to convert the currently viewed song. | Required |
Response
Returns success or error to indicate if the conversion process was successfully started. Check the song again or subscribe to changes to the library to determine when the conversion process is completed.
Chord variations
URL | /api/<auth_token>/songs/<song_identifier>/chords |
Method | GET |
Version | 1.0 |
Description
Retrieves chord variations for the specific song.
Path arguments
Name | Type | Description | Required |
---|---|---|---|
auth_token | string | The authentication token used to authenticate the request. | Required |
song_identifier | string | The song identifier of the song for which chords are to be retrieved. This can be the identifier of a song, or the term "current" which is the song currently being viewed. | Required |
Response
The response returns an array of dictionary objects that contain the chord name, variation and optional fingerings.
Response example
[ { "preferred": true, "chord": "D", "variation": "2002" }, { "preferred": true, "chord": "A", "variation": "2245" }, { "preferred": true, "chord": "G", "variation": "0023" }, { "preferred": true, "chord": "Em", "variation": "0223" } ]
Custom chord variations
URL | /api/<auth_token>/songs/<song_identifier>/chords |
Method | POST |
Version | 1.0 |
Description
Retrieves chord variations for the specific song.
Path arguments
Name | Type | Description | Required |
---|---|---|---|
auth_token | string | The authentication token used to authenticate the request. | Required |
song_identifier | string | The song identifier of the song for which chords are to be retrieved. This can be the identifier of a song, or the term "current" which is the song currently being viewed. | Required |
Body arguments
Pass information to this method to customize the instrument and chords to be returned. If either is omitted, the default instrument and list of chords are returned for the song.
Name | Type | Description | Required |
---|---|---|---|
instrument | string | The identifier of the instrument for which chords are to be returned. | Optional |
chords | array | An array of chord names to be returned. | Optional |
Body example
{ instrument:"guitar", chords:["Am", "C", "F", "Em"] }
2.13.5. Response
The response returns the instrument and chords in a dictionary. The chords property is an array of dictionary objects that contain the chord name, variation and optional fingerings.
2.13.6. Response example
{ "instrument": "guitar", "chords": [ { "preferred": true, "chord": "C", "variation": "032010" }, { "preferred": true, "chord": "F", "variation": "x03211" }, { "preferred": true, "chord": "G", "variation": "320003" } ] }