Parties


What is this I don't even

A Party on the Guitarparty.com platform is essentially a real-time channel which can be used to sync lyrics and chords to multiple users. While this is still a highly experimental feature we are most excited about this part of our system.

Users can join channels if they know the public URL for the party, which is available through our API. Right now, it is only possible to view ongoing parties in our web based client, but our native apps for Android and iOs are in development, launch TBA.

Parties support GET, POST, PUT and DELETE requests as explained below.


Create a Party

To create a new party, send a POST request to http://api.guitarparty.com/v2/parties/. The following parameters are supported:

  • title: Title of party (required)
  • description: Description if you like (optional)
  • current_song: This is the song that users who just logged on to the party see initially (optional)
  • songbook_seed: This is an id of a songbook that can be used to seed the party (optional)
  • song_seed: A JSON array of song ID's that can be used to seed the party (optional)

Consider this JSON file called postdata.json:

{
    "title": "Awesome party",
    "description": "Awesome party is awesome",
    "current_song": 5,
    "song_seed": 5
}

In this case we want to create a new party called Awesome party with a description of Awesome party is awesome and seed it with a single song which happens to be Jolene.

curl -H 'Guitarparty-Api-Key: {API_KEY}' http://api.guitarparty.com/v2/parties/ -d @postdata.json

{
    "current_song": null, 
    "description": "Awesome party is awesome", 
    "human_uri": "http://www.guitarparty.com/party/xyz12/", 
    "short_code": "xyz12", 
    "song_count": 0, 
    "title": "Awesome party", 
    "uri": "/v2/parties/xyz12/"    
}

Update party

The same parameters apply when updating and creating parties, with the only exception that there is no required parameter when updating.

The current_song parameter should be an ID of a song in our database as you get it from our API. When you change the song, an event will be triggered in the channel associated with the party, and each client listening will receive an update.

Example:

curl -X PUT -H 'Guitarparty-Api-Key: {API_KEY}' http://api.guitarparty.com/v2/parties/xyz12/ -d "{\"current_song\": 5}"

This will return a full update on the current state of the party as well as trigger the push event on the party channel:

{
    "current_song": "/v2/songs/5/", 
    "description": "Awesome party is awesome", 
    "human_uri": "http://www.guitarparty.com/party/xyz12/", 
    "short_code": "xyz12", 
    "song_count": 0, 
    "title": "Awesome party", 
    "uri": "/v2/parties/xyz12/"
}

Songs in party

To get a list of parties, send a GET request to http://api.guitarparty.com/v2/parties/{PARTY_ID}/songs/

To add a song to a party, send a POST request to http://api.guitarparty.com/v2/parties/{PARTY_ID}/songs/ with a single song_id parameter containing a comma-separated list of song id's.

To do actions on the songs for a given party, send a GET, PUT or DELETE request to http://api.guitarparty.com/v2/parties/{PARTY_ID}/songs/{PARTYSONG_ID} using the ID given in the song list or when the song was added.


Party messages

You can send a message to the party channel by sending a POST request to http://api.guitarparty.com/v2/parties/{PARTY_ID}/messages/

There are only two parameters:

  • title: The title of the message (required)
  • content: The message content (required)

Example:

curl -X POST -H 'Guitarparty-Api-Key: {API_KEY}' http://api.guitarparty.com/v2/parties/xyz12/messages/ -d "{\"title\": \"Title\",\"content\":\"Content\"}"

You get back a copy of your message for confirmation, but since messages are a one-time event in our system, they are considered volatile and you do not get a reference to the message you created.

{
    "content": "Content", 
    "title": "Title"
}