Songs

The songs API is used to find and view song information.

Find songs

URL/api/<auth_token>/songs
MethodGET
Version1.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:
  • title sorts the songs by song title. Default.
  • artist sorts the songs by the artist.
  • favorite sorts the songs is the song is marked as a favorite. Defaults to descending order.
  • added sorts the songs by the date the song was added. Defaults to descending order.
  • updated sorts the songs by the date the song was updated. Defaults to descending order.
  • number sorts the songs by the song number.
  • random sorts the songs in random order.
  • orderIndex sorts the songs by their order in a set.
  • lastPlayed sorts the songs by date they were last played. Defaults to descending order.
  • mostPopular sorts the songs by how often it has been placed in a set. Defaults to descending order.
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.
  • ID The unique identifier of the song.
  • title The title of the song.
  • artist The artist or byline information of the song.
  • key The current key of the song.
  • favorite Determines if the song has been favorited.
  • usefile Determines if the external file should be used for displaying the song.
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
MethodPUT
Version1.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>
MethodGET
Version1.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>
MethodPOST
Version1.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>
MethodDELETE
Version1.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>)
MethodGET
Version1.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:
  • default when no format is specified, the content is returned straight from the OnSong library.
  • onsong returns the song in the OnSong file format.
  • chordpro returns the song formatted using the ChordPro syntax.
  • txt returns the song as plain text.
  • html returns the song in an HTML format.
  • pdf returns the song as a formatted PDF file.
  • opensong returns the song in the OpenSong XML file format.
  • usr returns the song in the SongSelect USR file format.
  • archive returns the song in the OnSong archive format.
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
MethodPOST
Version1.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
MethodGET
Version1.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
MethodGET
Version1.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
MethodPOST
Version1.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
MethodGET
Version1.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
MethodGET
Version1.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
MethodPOST
Version1.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"
        }
    ]
}