Lyrical Systems Karaoke Cloud API
These are the resources available to view and manipulate the songs, queues, lights, and other features of the Lyrical Karaoke Cloud package.
These features are available for Voicebox, as well as our partner organizations with the Lyrical Karaoke Cloud features enabled. Note that each API request will require an organization parameter to disambiguate.
See the overview documentation for details about response codes, error handling, organizations, etc.
Resource Overview
Login
Profile
Songs
- GET /api/version/songs.format
- GET /api/version/songs/id.format
- GET /api/version/songs/search.format
- GET /api/version/songs/roulette.format
- GET /api/version/songs/languages.format
- GET /api/version/songs/tags.format
- GET /api/version/songs/stats.format
- POST /api/version/songs/request.format
Song Favorites
- GET /api/version/songs/favorites.format
- POST /api/version/songs/favorites.format
- DELETE /api/version/songs/favorites.format
Room
Queue
- GET /api/version/queue.format
- POST /api/version/queue.format
- DELETE /api/version/queue.format
- POST /api/version/queue/reorder.format
Current Song
- POST /api/version/current_song/skip.format
- POST /api/version/current_song/restart.format
- POST /api/version/current_song/pause.format
- POST /api/version/current_song/resume.format
Audio
Lights
Popups
Service Call
Play History
POST /api/version/login.format
Login to the Lyrical Systems API by email, which will or find or create a new profile if it does not already exist, and associate the current session with the profile. This is necessary for some features, such as keeping favorite songs, playlists, and more as we grow.
Parameters
-
session (optional)
This is normally generated by the client, and should be specified
When unspecified, returns a new session to be used
See overview documentation for more information about sessions and login -
email (required)
A valid email address
Examples
To login a user, letting the server generate a new session ID
POST /api/v1/login?email=test@email.com
To login a user, where the client chooses a random session ID
POST /api/v1/login?email=test@email.com&session=12345678-1234-1234-1234-123456abcdef
Example Response
{
"session": "12345678-1234-1234-1234-123456abcdef",
"email": "test@email.com",
"handle": "test",
"color": "#00BCB5",
"hide_handle_in_queue": false
}
GET /api/version/profile.format
Get the profile for the currently logged-in user.
Parameters
- session (required)
The user must be logged-in
Examples
To get a logged-in user’s profile, given their session ID
GET /api/v1/profile?session=12345678-1234-1234-1234-123456abcdef
Example Response
{
"session": "12345678-1234-1234-1234-123456abcdef",
"email": "test@email.com",
"handle": "test",
"color": "#00BCB5",
"hide_handle_in_queue": false,
"birth_year": 1975,
"birth_month": 11,
"birth_day": 22
}
PUT /api/version/profile.format
Set values for the currently logged-in user. Any unspecified values are left unchanged.
Parameters
-
session (required)
The user must be logged-in -
handle (optional)
This is used to identify the user in the queue and when posting popups -
color (optional)
This is used to identify the user in the queue and when posting popups
Must be a valid hexadecimal color value like #4455FF (the # is optional) -
hide_handle_in_queue (optional)
When set, any songs added to the queue by this user are anonymous - birth_year (optional)
- birth_month (optional)
- birth_day (optional)
Be a member of the birthday club!
This is optional, but if set, bothbirth_month
andbirth_day
must be present.
birth_year
is always optional. We won’t pry.
Examples
To set a logged-in user’s handle, to be shown on-screen
PUT /api/v1/profile?session=12345678-1234-1234-1234-123456abcdef&handle=rickroller
Example Response
{
"session": "12345678-1234-1234-1234-123456abcdef",
"email": "test@email.com",
"handle": "rickroller",
"color": "#00BCB5",
"hide_handle_in_queue": false,
"birth_year": null,
"birth_month": null,
"birth_day": null
}
GET /api/version/songs.format
Access the songs available at a location.
The intended usage is to page through songs by artist, title, popularity, or recent additions, much as you would browse songs in a printed song book.
Parameters
-
by (optional)
one of artist, title, popularity, or recently_added
defaults to artist -
prefix (optional)
when unspecified, returns results across all songs
use character ‘$’ to browse all songs that begin with a non-alphabetic character -
language (optional)
when unspecified, returns all languages -
tag (optional)
return songs with a specific tag, e.g. to filter by genre
see the song tags resource below for a list of available tags
when unspecified, returns results unfiltered by tag -
page (optional)
defaults to 1 -
per_page (optional)
defaults to 50
maximum is 1000
Examples
To get the first page of the English song book by title, use
GET /api/v1/songs?by=title&language=English
To get the second page, in JSON format, use
GET /api/v1/songs.json?by=title&language=English&page=2
To get just songs by title that start with ‘d’, use
GET /api/v1/songs?by=title&language=English&prefix=d
To get the list of most popular songs, use
GET /api/v1/songs?by=popularity
To get the most popular duets, use
GET /api/v1/songs?tag=Duet&by=popularity
To get the third page of songs by artist that start with ‘depeche’, with a page size of 2, use
GET /api/v1/songs?by=artist&language=English&prefix=depeche&page=3&per_page=2
Example response
{
"by": "artist",
"prefix": "depeche",
"language": "English",
"page": 3,
"per_page": 2,
"total_pages": 10,
"total_entries": 20,
"songs": [
{
"id": 56831,
"title": "Everything Counts",
"artist": "Depeche Mode",
"language": "English",
"popularity": 880,
"play_count": 107,
"added_on": "2009-06-16",
"tags": [
"80s"
]
},
{
"id": 56830,
"title": "Home",
"artist": "Depeche Mode",
"language": "English",
"popularity": 197,
"play_count": 28,
"added_on": "2009-06-16",
"tags": [
"90s"
]
}
]
}
GET /api/version/songs/id.format
Access information about a single song by ID.
Parameters
None
Examples
To get the JSON information for Don’t Stop Believin’, use
GET /api/v1/songs/67277.json
To get the same information using a cross-domain JSONP call, use
GET /api/v1/songs/67277.json?callback=mycallback
Example Response
{
"song": {
"id": 67277,
"title": "Don't Stop Believin'",
"artist": "Journey",
"language": "English",
"popularity": 130563,
"play_count": 8145,
"added_on": "2013-11-04",
"tags": [
"80s",
"Fan Videos"
]
}
}
GET /api/version/songs/search.format
Search songs by title or artist.
Parameters
-
query (required)
Search terms to find in the title or artist of a song
Returns all matches, across artist and title
Putting quotes the query will do an exact match (but case-insensitive) on artist or title -
language (optional)
when unspecified, returns all languages -
page (optional)
defaults to 1 -
per_page (optional)
defaults to 50
maximum is 1000
Examples
To get the first page of results searching for ‘Elvis’, use
GET /api/v1/songs/search?query=Elvis
To get the second page, use
GET /api/v1/songs/search?query=Elvis&page=2
To get only English language songs with the term ‘Elvis’, use
GET /api/v1/songs/search?query=Elvis&language=English
Example Response
{
"query": "journey",
"language": null,
"tag": null,
"tag_notes": null,
"page": 1,
"per_page": 2,
"total_pages": 13,
"total_entries": 26,
"songs": [
{
"id": 71885,
"title": "Journey To The Past",
"artist": "Anastasia",
"language": "English",
"popularity": 172,
"play_count": 26,
"added_on": "2014-05-06"
},
{
"id": 638,
"title": "Sentimental Journey",
"artist": "Day, Doris",
"language": "English",
"popularity": 87,
"play_count": 43,
"added_on": "2008-10-31"
}
]
}
GET /api/version/songs/roulette.format
Get a random selection of songs, weighted toward the most popular.
Parameters
-
language (optional)
when unspecified, returns all languages -
tag (optional)
return songs with a specific tag, e.g. to filter by genre
see the song tags resource below for a list of available tags
when unspecified, returns results unfiltered by tag -
from_top (optional)
return songs from the top N most popular songs
defaults to 3000 -
per_page (optional)
defaults to 10
maximum is 1000
Examples
To get a random page of results, use
GET /api/v1/songs/roulette
To get a random page of results from the top 100, use
GET /api/v1/songs/roulette?from_top=100
To get random Rap songs, use
GET /api/v1/songs/roulette?tag=Rap
Example Response
{
"tag": "Rap",
"tag_notes": "Rap and Hip-Hop",
"per_page": 2,
"total_entries": 539,
"songs": [
{
"id": 72246,
"title": "I'm Out",
"artist": "Ciara & Nicki Minaj",
"language": "English",
"play_count": 48,
"popularity": 164,
"added_on": "2014-11-25",
"tags": [
"Pop",
"Rap",
"Divas"
]
},
{
"id": 69399,
"title": "Look At Her Go",
"artist": "T-Pain feat Chris Brown",
"language": "English",
"popularity": 19,
"play_count": 3,
"added_on": "2012-03-12",
"tags": [
"Rap"
]
}
]
}
GET /api/version/songs/languages.format
Get available languages, and information about how many songs are available in each language.
Parameters
None
Examples
To get all available languages
GET /api/v1/songs/languages
Example Response
{
"languages": [
{
"language": "English",
"song_count": 15030,
"artist_count": 4410
},
{
"language": "Spanish",
"song_count": 2516,
"artist_count": 606
}
]
}
GET /api/version/songs/tags.format
Get available tags for songs, grouped by category. Tags are how we indicate genre, duets, etc.
Parameters
None
Examples
To get song tags
GET /api/v1/songs/tags
Example Response
{
"categories": [
{
"category_name": "Genres",
"tags": [
{
"name": "Country",
"song_count": 522,
"notes": "Some tags have some extra notes to describe it"
},
{
"name": "Disco",
"song_count": 76
}
]
},
{
"category_name": "Decades",
"tags": [
{
"name": "90s",
"song_count": 392
},
{
"name": "80s",
"song_count": 401
}
]
}
]
}
GET /api/version/songs/stats.format
Get statistics for songs, such as the top played songs and artists.
Also includes information about recently played songs, with breakdowns by day and week.
Parameters
None
Examples
To get song statistics
GET /api/v1/songs/stats
Example Response
{
"total_songs_played": 1326100,
"total_songs_available": 67251,
"top_songs": [
{
"id": 67277,
"title": "Don't Stop Believin'",
"artist": "Journey",
"language": "English",
"popularity": 130563,
"play_count": 6273
}
],
"top_artists": [
{
"artist": "Beatles, The",
"popularity": 384885,
"play_count": 14829
}
],
"top_songs_today": [],
"total_songs_today": 0,
"top_songs_this_week": [
{
"id": 67277,
"title": "Don't Stop Believin'",
"artist": "Journey",
"language": "English",
"popularity": 130563,
"play_count": 46
}
],
"total_songs_this_week": 6727,
"latest_song_additions": [
{
"id": 72525,
"title": "Invincible",
"artist": "Clarkson, Kelly",
"language": "English",
"popularity": 177,
"added_on": "2015-06-12"
}
],
"updated_at": "2015-06-24T03:55:36.185Z"
}
POST /api/version/songs/request.format
Post a request for a song. We use these requests to prioritze which songs we can get.
Parameters
-
artist (required)
the artist that made this song famous -
title (required)
the title of the song. please try to be as exact as possible -
notes (optional)
any additional notes you’d like to specify to our song librarian
Examples
To request Don’t Stop Believin’ by Journey
POST /api/v1/songs/request?session=12345678-1234-1234-1234-123456abcdef&title=Don't%20Stop%20Believin'&artist=Journey
GET /api/version/songs/favorites.format
Get songs that have been favorited by a logged-in user.
Parameters
-
session (required)
The user must be logged-in -
page (optional)
defaults to 1 -
per_page (optional)
defaults to 50
maximum is 1000
Examples
To get a logged-in user’s favorite songs
GET /api/v1/songs/favorites?session=12345678-1234-1234-1234-123456abcdef
Example Response
{
"page": 1,
"per_page": 50,
"total_pages": 1,
"total_entries": 2,
"songs": [
{
"id": 68250,
"title": "Beautiful, Dirty, Rich",
"artist": "Lady Gaga",
"language": "English",
"popularity": 821,
"play_count": 9,
"added_on": "2014-01-07",
"favorite": true
},
{
"id": 56746,
"title": "Just Can't Get Enough",
"artist": "Depeche Mode",
"language": "English",
"popularity": 1444,
"play_count": 7,
"added_on": "2015-05-23",
"favorite": true,
"tags": [
"80s"
]
}
]
}
POST /api/version/songs/favorites.format
Add a song to save as a favorite.
If the song already a favorite for the user, no changes will be made, and the added
property in the response will be false
.
Parameters
-
session (required)
The user must be logged-in -
song_id (required)
The song you love to sing!
Examples
Add Don’t Stop Believin’ as a favorite song
POST /api/v1/songs/favorites?session=12345678-1234-1234-1234-123456abcdef&song_id=67277
Example Response
{
"song_id": 67277,
"added": true
}
DELETE /api/version/songs/favorites.format
Remove a song from your favorites.
If the song is not a favorite for the user, no changes will be made, and the removed
property in the response will be false
.
Parameters
-
session (required)
The user must be logged-in -
song_id (required)
The song you used to love, and now it’s just been overplayed!
Examples
Remove Don’t Stop Believin’ from a user’s favorites
DELETE /api/v1/songs/favorites?session=12345678-1234-1234-1234-123456abcdef&song_id=67277
Example Response
{
"song_id": 67277,
"removed": true
}
GET /api/version/room.format
Validate a room_code, and get information about the room, such as location, room_number, and whether certain features are enabled for that room.
Parameters
- room_code (required)
The 4-letter code displayed on the TV in each karaoke suite
Examples
To validate a room code, and get information about the room.
GET /api/v1/room?room_code=CQFW
Example Response
{
"room_code": "CQFW",
"room_number": 1,
"location_id": 5,
"location": "Southeast",
"location_full_name": "Southeast Portland",
"region": "Portland",
"has_service_call": true
}
GET /api/version/queue.format
Get the song queue for a room.
Returns information about all queued songs, as well as the currently playing song.
Parameters
- room_code (required)
The 4-letter code displayed on the TV in each karaoke suite
Without this code, clients are not able to access the queue
Examples
To get the queue for a room, given that you know the 4-letter code, use
GET /api/v1/queue?room_code=CQFW
Example Response
{
"room_code": "CQFW",
"current_song": {
"song_id": 68250,
"play_id": "G-Test-6c4008b3e6c4-1435717763903-2",
"title": "Beautiful, Dirty, Rich",
"artist": "Lady Gaga",
"duration": 170000,
"position": 30000,
"paused": false,
"pitch_shift": 0,
"audio_channels": "stereo",
"message": "jenny",
"message_color": "#00BCB5"
},
"volume": 75,
"songs_queued": 1,
"queue": [
{
"index": 0,
"song_id": 69001,
"play_id": "G-Test-6c4008b3e6c4-1435717770940-3",
"title": "Summerboy",
"artist": "Lady Gaga",
"duration": 242865,
"message": null,
"message_color": null
}
]
}
POST /api/version/queue.format
Add one or more songs to the queue for a room.
Parameters
-
room_code (required)
The 4-letter code displayed on the TV in each karaoke suite
Without this code, clients are not able to access the queue -
song_id (required)
The numeric song id, typically found by browsing or searching for songs
This may be a comma-separated list of song ids, to add multiple songs at once -
to (optional)
Either a play_id or an index, indicating the new destination in the queue
If a play_id is used, then the song will be moved to the position of the given play_id
The index may be negative, indicating a relative position from the end
defaults to -1, adding the song to the end of the queue -
allow_duplicate (optional)
A boolean value, indicating whether adding a song should be checked
against the songs already in the queue, to prevent consecutive songs with the same song_id.
Adding the same song in a non-consecutive position is always allowed.
defaults to false, which prevents adding back-to-back songs -
message (optional)
A message that will be displayed in the queue next to the song.
Note that when a logged-in user adds a song, they will have theirhandle
displayed,
and providing an explicitmessage
will override thehandle
in that case. -
message_color (optional)
Set the color for themessage
.
Should be a standard web format like#1122FF
.
Defaults to#999999
(gray)
Examples
To add Don’t Stop Believin’ to the queue, use
POST /api/v1/queue?room_code=CQFW&song_id=67277
To add 3 songs at once to the queue, use
POST /api/v1/queue?room_code=CQFW&song_id=101,102,103
To add a song to the top of the queue, to be played next after any currently playing song, use
POST /api/v1/queue?room_code=CQFW&song_id=101&to=0
Using curl, from the command-line, this can be accomplished with
curl -X POST -d "" "https://app.lyricalsystems.com/api/v1/queue.json?room_code=CQFW&song_id=67277"
Example Response
{
"index": 3,
"song_id": 67277,
"play_id": "G-Southeast-6c4008b3e6c4-1435717896331-4",
"title": "Don't Stop Believin'",
"artist": "Journey",
"duration": 268128
}
The index
in the response indicates the position the song was added to the queue.
A value of -1 means that it will immediately begin playing as the current song.
Values greater than or equal to 0 correspond to positions in the queue.
DELETE /api/version/queue.format
Delete either a specific song, or all songs, from the queue for a room.
Note, this does not stop the currently-playing song. It only removes upcoming songs.
Parameters
-
room_code (required)
The 4-letter code displayed on the TV in each karaoke suite
Without this code, clients are not able to access the queue -
from (optional)
Either a play_id or an index, indicating a specific entry from the queue to delete
If not supplied, deletes the entire queue
The index may be negative, indicating a relative position from the end
If from is a play_id that refers to the current song, it will skip the current song
Examples
To delete just a specific song, using a play_id, use
DELETE /api/v1/queue?room_code=CQFW&from=G-Test-28cfe91dc4e7-1415156264149-1
To delete the song that is next in the queue, but keep all of the others, use
DELETE /api/v1/queue?room_code=CQFW&from=0
To delete the song that was most recently added to the queue, use
DELETE /api/v1/queue?room_code=CQFW&from=-1
To clear the entire queue, use
DELETE /api/v1/queue?room_code=CQFW
POST /api/version/queue/reorder.format
Reorder songs in the queue for a room.
Parameters
-
room_code (required)
The 4-letter code displayed on the TV in each karaoke suite
Without this code, clients are not able to access the queue -
from (required)
Either a play_id or an index, indicating a specific entry from the queue to move
The index may be negative, indicating a relative position from the end -
to (optional)
Either a play_id or an index, indicating the new destination in the queue
If a play_id is used, then the song will be moved to the position of the given play_id
The index may be negative, indicating a relative position from the end
defaults to 0, moving the song to the top of the queue
Examples
Each example assumes a queue with play_ids: G-XXX-1, G-XXX-2, G-XXX-3, G-XXX-4
To move a song to the top of the queue, using a play_id of G-XXX-3,
resulting in: G-XXX-3, G-XXX-1, G-XXX-2, G-XXX-4
POST /api/v1/queue/reorder?room_code=CQFW&from=G-XXX-3
To move a song to the second position in the queue, using a play_id of G-XXX-3,
resulting in: G-XXX-1, G-XXX-3, G-XXX-2, G-XXX-4
POST /api/v1/queue/reorder?room_code=CQFW&from=G-XXX-3&to=1
To move the most recently added song to the top of the queue,
resulting in: G-XXX-4, G-XXX-1, G-XXX-2, G-XXX-3
POST /api/v1/queue/reorder?room_code=CQFW&from=-1
To swap the top two songs in the queue,
resulting in: G-XXX-2, G-XXX-1, G-XXX-3, G-XXX-4
POST /api/v1/queue/reorder?room_code=CQFW&from=0&to=1
POST /api/version/current_song/skip.format
Skip the currently playing song in a room.
Parameters
- room_code (required)
The 4-letter code displayed on the TV in each karaoke suite
Without this code, clients are not able to access the current song
Example
POST /api/v1/current_song/skip?room_code=CQFW
POST /api/version/current_song/restart.format
Rewinds and starts playing the currently playing song from the beginning.
Parameters
- room_code (required)
The 4-letter code displayed on the TV in each karaoke suite
Without this code, clients are not able to access the current song
Example
POST /api/v1/current_song/restart?room_code=CQFW
POST /api/version/current_song/pause.format
Pauses the currently playing song in a room.
Parameters
- room_code (required)
The 4-letter code displayed on the TV in each karaoke suite
Without this code, clients are not able to access the current song
Example
POST /api/v1/current_song/pause?room_code=CQFW
POST /api/version/current_song/resume.format
Resumes playing the currently playing song in a room, if it was previously paused.
Parameters
- room_code (required)
The 4-letter code displayed on the TV in each karaoke suite
Without this code, clients are not able to access the current song
Example
POST /api/v1/current_song/resume?room_code=CQFW
PUT /api/version/audio.format
Controls the audio for the currently playing song in a room.
Setting the volume
is persistent, but pitch_shift
and channels
will be reset when the current song ends.
Note, the audio information is returned as part of the queue response.
Parameters
-
room_code (required)
The 4-letter code displayed on the TV in each karaoke suite
Without this code, clients are not able to access the current song -
volume (optional)
An integer value from 0 to 100 -
pitch_shift (optional)
An integer value from -12 to 12
The number of semitones to adjust the pitch
1 shifts up by a semitone, -1 down by a semitone, 12 by an octave, etc.
A value of 0 turns off pitch adjustment -
channels (optional)
One of:stereo
,left
, orright
Some karaoke videos encode the voice on either the left or right channels
Setting toleft
will play only the left channel through both speakers
Setting tostereo
will play normally
Examples
To set the volume to the max, use
PUT /api/v1/audio?room_code=CQFW&volume=100
To mute the audio, use
PUT /api/v1/audio?room_code=CQFW&volume=0
To adjust the pitch down a whole step, and play only the right channel through both speakers, use
PUT /api/v1/audio?room_code=CQFW&pitch_shift=-2&channels=right
To return the pitch shift and audio channels to their default, use
PUT /api/v1/audio?room_code=CQFW&pitch_shift=0&channels=stereo
PUT /api/version/lights.format
Set the lighting levels and effects in a room.
Note, the lighting information is returned as part of the queue response.
Parameters
-
room_code (required)
The 4-letter code displayed on the TV in each karaoke suite
Without this code, clients are not able to access the lights -
mode (optional)
An integer value
0 - Bright lights
1 - Medium lights
2 - Low lights -
effects (optional)
A boolean value, indicating whether the lighting effects should be turned on or off
In most rooms, this controls the mirror ball
Examples
To turn on the mirror ball, given that you know the 4-letter code, use
PUT /api/v1/lights?room_code=CQFW&effects=1
To set a low lighting level, use
PUT /api/v1/lights?room_code=CQFW&mode=2
To turn off the mirror ball, and raise the lights to a bright level, use
PUT /api/v1/lights?room_code=CQFW&mode=0&effects=0
POST /api/version/popups.format
Show a popup message on-screen in a room. This requires a logged-in session.
Each popup will be shown with the logged-in user’s handle
.
The handle
defaults to the first part of the email address for the user’s profile.
Note, there is currently no way to get the displayed popups.
Parameters
-
session (required)
See the description above about sessions
This session must be logged-in -
room_code (required)
The 4-letter code displayed on the TV in each karaoke suite
Without this code, clients are not able to access popups -
text (required)
A text message to display. Have fun!
Limited to 90 characters
Examples
To show “You rock!” on screen, use (replacing the session as appropriate, of course)
POST /api/v1/popups?session=12345678-1234-1234-1234-123456abcdef&room_code=CQFW&text=You%20rock!
GET /api/version/service_call.format
Get the current status of the service-call feature for a room.
Note that only some organizations have this feature. Please contact us for more information.
Parameters
- room_code (required)
The 4-letter code displayed on the TV in each karaoke suite
Without this code, clients are not able to access the service-call status
Examples
To get the service-call status of a room
GET /api/v1/service_call?room_code=CQFW
Example Response
{
"room_code": "HSCL",
"state": "requested",
"requested_at": "2020-06-17T21:23:32.523Z",
"requested_by": "guest",
"acknowledged_at": null,
"served_at": null,
"cancelled_at": null,
"cancelled_by": null,
"rerequested_at": null
}
In the response, the state
can be one of the following values:
State | Active | Description |
---|---|---|
reset | false | Reset at beginning of party. |
served | false | Staff has served the guest. |
cancelled | false | Either a guest or our staff has explicitly cancelled a requested service-call. |
requested | true | A guest has requested service from our staff. |
acknowledged | true | Our staff has seen the request, and will come to the room ASAP. |
rerequested | true | If our staff has already been to the room, but the guest would like additional service, this can be used to explicitly re-request that the staff come back. |
The requested_by
and cancelled_by
values will one of "guest"
or "staff"
, indicating who performed the action.
PUT /api/version/service_call.format
Get the current status of the service-call feature for a room.
Note that only some organizations have this feature. Please contact us for more information.
Parameters
-
session (required)
See the description above about sessions -
room_code (required)
The 4-letter code displayed on the TV in each karaoke suite
Without this code, clients are not able to access the service-call status -
state (required)
One ofrequested
,cancelled
, orrerequested
Examples
To request service in a room
PUT /api/v1/service_call?room_code=CQFW&state=requested&session=12345678-1234-1234-1234-123456abcdef
To cancel a service-call that is currently in progress
PUT /api/v1/service_call?room_code=CQFW&state=cancelled&session=12345678-1234-1234-1234-123456abcdef
To re-request service, after the staff has been to the room, but hasn’t yet marked the service-call complete
PUT /api/v1/service_call?room_code=CQFW&state=rerequested&session=12345678-1234-1234-1234-123456abcdef
Example Response
{
"room_code": "HSCL",
"state": "requested",
"requested_at": "2020-06-17T21:23:32.523Z",
"requested_by": "guest",
"acknowledged_at": null,
"served_at": null,
"cancelled_at": null,
"cancelled_by": null,
"rerequested_at": null
}
See above for details about the response.
GET /api/version/plays/history.format
Get the play history for the current user. This does not require a logged-in session. However, with a login, your history will be persistent across visits.
Parameters
-
session (required)
See overview documentation for more information about sessions and login -
page (optional)
defaults to 1 -
per_page (optional)
defaults to 50
maximum is 1000
Examples
To get the play history for a logged-in user
GET /api/v1/plays/history?session=12345678-1234-1234-1234-123456abcdef
Example Response
{
"session": "12345678-1234-1234-1234-123456abcdef",
"page": 1,
"per_page": 50,
"total_pages": 1,
"total_entries": 2,
"plays": [
{
"song_id": 6834,
"play_id": "G-Southeast-00259086cd54-1415213795446-616",
"title": "While My Guitar Gently Weeps",
"artist": "Beatles, The",
"location": "Southeast",
"business_date": "2014-11-05",
"enqueue_time": "2014-11-05T18:56:35.446Z",
"start_time": null,
"end_time": null,
"duration": 303077,
"position": 0,
"room": 1,
"favorite": false
},
{
"song_id": 67519,
"play_id": "G-Southeast-00259086cd54-1414190084090-11078",
"title": "Start It Up",
"artist": "Banks, Lloyd ft. Kanye West, Swizz Beatz, Ryan Leslie & Fabolous",
"location": "Southeast",
"business_date": "2014-10-24",
"enqueue_time": "2014-10-24T22:34:44.090Z",
"start_time": "2014-10-24T22:37:54.058Z",
"end_time": "2014-10-24T22:37:54.788Z",
"duration": 302680,
"position": 118,
"room": 2,
"favorite": true,
"tags": [
"Rap"
]
}
]
}