Engage API Overview

Welcome to the Rockbot Engage API. This API lets you integrate Rockbot engagement functionality into your application. Allow users to see what’s playing, vote and request music via a simple REST API.

All methods require a private API key for your venue that can be found under the Power-Ups section of your venue dashboard. This key must be sent as an Authorization header to the HTTP endpoint specified in the docs below, along with any specified parameters. Do not share your private API key or host in plain text.

If you don’t already manage a Rockbot venue, you can create one at https://rockbot.com/trial. Please contact support@rockbot.com if you have any questions.

Read Methods

Now Playing

curl -H "Authorization: API_KEY"
 "https://api.rockbot.com/v3/engage/now_playing?queue=1"

Successful JSON Response:

{
    "response": {
        "venue": "Rockbot HQ",
        "street": "1625 Clay St #500",
        "city": "Oakland",
        "state": "CA",
        "zip": "94612",
        "current_users": 3,
        "status": "online",
        "now_playing": {
            "pick_id": 1456298284,
            "artist_id": 6597,
            "artist": "DeBarge",
            "song_id": 34242,
            "song": "Rhythm Of The Night",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/150/1/10271.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/500/1/10271.jpg",
            "user": "Rockbot",
            "user_image_small": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-150.png",
            "user_image_large": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-300.png",
            "likes": 0,
            "dislikes": 0,
            "duration": 234,
            "remaining": 104
        },
        "queue": [
            {
                "pick_id": 1456298290,
                "artist_id": 940,
                "artist": "Tamia",
                "song_id": 32340,
                "song": "Beautiful Surprise",
                "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/150/9/26409.jpg",
                "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/500/9/26409.jpg",
                "user": "Rockbot",
                "user_image_small": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-150.png",
                "user_image_large": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-300.png",
                "likes": 0,
                "dislikes": 0
            },
            {
                "pick_id": 1456298291,
                "artist_id": 2801,
                "artist": "Sly & The Family Stone",
                "song_id": 15896,
                "song": "Soul Clappin'",
                "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/150/7/10257.jpg",
                "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/500/7/10257.jpg",
                "user": "Rockbot",
                "user_image_small": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-150.png",
                "user_image_large": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-300.png",
                "likes": 0,
                "dislikes": 0
            },
            {
                "pick_id": 1456298286,
                "artist_id": 807,
                "artist": "Mary J. Blige",
                "song_id": 31549,
                "song": "Just Fine",
                "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/1/25611.jpg",
                "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/1/25611.jpg",
                "user": "Rockbot",
                "user_image_small": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-150.png",
                "user_image_large": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-300.png",
                "likes": 0,
                "dislikes": 0
            }
        ]
    }
}

Returns the current track playing on your player along with related metadata. If the player is offline, an empty JSON object will be returned.

HTTP Endpoint

https://api.rockbot.com/v3/engage/now_playing

GET Parameters

Parameter	Description
queue	Return upcoming songs in response (0 or 1)

Top Artists

curl -H "Authorization: API_KEY"
 "https://api.rockbot.com/v3/engage/top_artists"

Successful JSON Response:

{
    "response": [
        {
            "artist_id": 3,
            "artist": "OutKast",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/4/74.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/4/74.jpg"
        },
        {
            "artist_id": 2,
            "artist": "Radiohead",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/6/177986.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/6/177986.jpg"
        },
        {
            "artist_id": 29,
            "artist": "Kanye West",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/8/177988.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/8/177988.jpg"
        },
        {
            "artist_id": 5523,
            "artist": "Kendrick Lamar",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/1/32361.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/1/32361.jpg"
        },
        {
            "artist_id": 3743,
            "artist": "Frank Ocean",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/7/12557.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/7/12557.jpg"
        },
        {
            "artist_id": 496,
            "artist": "Janet Jackson",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/2/16842.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/2/16842.jpg"
        },
        {
            "artist_id": 27,
            "artist": "Jay-Z",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/7/127.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/7/127.jpg"
        },
        {
            "artist_id": 31,
            "artist": "Arcade Fire",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/1/177781.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/1/177781.jpg"
        },
        {
            "artist_id": 14830,
            "artist": "The War On Drugs",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/0/192650.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/0/192650.jpg"
        },
        {
            "artist_id": 38,
            "artist": "Michael Jackson",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/4/177984.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/4/177984.jpg"
        },
        {
            "artist_id": 135,
            "artist": "Queen",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/4/514.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/4/514.jpg"
        },
        {
            "artist_id": 64,
            "artist": "M.I.A.",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/2/720242.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/2/720242.jpg"
        },
        {
            "artist_id": 4457,
            "artist": "Childish Gambino",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/2/15932.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/2/15932.jpg"
        },
        {
            "artist_id": 819,
            "artist": "Sigur Rós",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/3/49903.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/3/49903.jpg"
        },
        {
            "artist_id": 6,
            "artist": "Weezer",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/9/177989.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/9/177989.jpg"
        },
        ...
    ]
}

Returns the top 40 artists enabled at this venue.

HTTP Endpoint

https://api.rockbot.com/v3/engage/top_artists

Browse Artists

curl -H "Authorization: API_KEY"
 "https://api.rockbot.com/v3/engage/browse_artists?letter=J"

Successful JSON Response:

{
    "response": [
        {
            "artist_id": 2909,
            "artist": "Jackie Moore",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/100/4/10074.jpg"
        },
        {
            "artist_id": 1203,
            "artist": "Jagged Edge",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/100/9/553149.jpg"
        },
        {
            "artist_id": 4054,
            "artist": "Jay-Z & Kanye West",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/100/1/13511.jpg"
        },
        {
            "artist_id": 779,
            "artist": "Jazmine Sullivan",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/100/7/2657.jpg"
        },
        {
            "artist_id": 18282,
            "artist": "Jazzy Jeff",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/100/7/299637.jpg"
        },
        {
            "artist_id": 771,
            "artist": "Jennifer Hudson",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/100/2/2632.jpg"
        }
    ]
}

Returns a full list of artists currently selectable at this venue. Passing an optional letter param will limit to artists starting with that letter.

HTTP Endpoint

https://api.rockbot.com/v3/engage/browse_artists

GET Parameters

Parameter	Description
letter	First letter of artists to return (optional)

Search Artists

curl -H "Authorization: API_KEY"
 "https://api.rockbot.com/v3/engage/search_artists?query=80s"

Successful JSON Response:

{
    "response": [
        {
            "artist_id": 38,
            "artist": "Michael Jackson",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/4/177984.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/4/177984.jpg"
        },
        {
            "artist_id": 135,
            "artist": "Queen",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/4/514.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/4/514.jpg"
        },
        {
            "artist_id": 95,
            "artist": "Guns N' Roses",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/3/363.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/3/363.jpg"
        },
        {
            "artist_id": 184,
            "artist": "Aerosmith",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/6/636.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/6/636.jpg"
        },
        {
            "artist_id": 133,
            "artist": "David Bowie",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/8/508.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/8/508.jpg"
        },
        {
            "artist_id": 199,
            "artist": "Van Halen",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/6/716.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/6/716.jpg"
        },
        {
            "artist_id": 362,
            "artist": "Journey",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/0/1330.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/0/1330.jpg"
        }
    ]
}

Returns all selectable artists matching given search query.

HTTP Endpoint

https://api.rockbot.com/v3/engage/search_artists

GET Parameters

Parameter	Description
query	Search string

Write Methods

Vote Up

curl -H "Authorization: API_KEY" -d "pick_id=12345"
 "https://api.rockbot.com/v3/engage/vote_up"

Successful JSON Response:

{
    "response": {
        "venue": "Rockbot HQ",
        "street": "1625 Clay St #500",
        "city": "Oakland",
        "state": "CA",
        "zip": "94612",
        "current_users": 3,
        "status": "online",
        "now_playing": {
            "pick_id": 1456298284,
            "artist_id": 6597,
            "artist": "DeBarge",
            "song_id": 34242,
            "song": "Rhythm Of The Night",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/150/1/10271.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/500/1/10271.jpg",
            "user": "Rockbot",
            "user_image_small": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-150.png",
            "user_image_large": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-300.png",
            "likes": 0,
            "dislikes": 0,
            "duration": 234,
            "remaining": 104
        },
        "queue": [
            {
                "pick_id": 1456298290,
                "artist_id": 940,
                "artist": "Tamia",
                "song_id": 32340,
                "song": "Beautiful Surprise",
                "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/150/9/26409.jpg",
                "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/500/9/26409.jpg",
                "user": "Rockbot",
                "user_image_small": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-150.png",
                "user_image_large": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-300.png",
                "likes": 0,
                "dislikes": 0
            },
            {
                "pick_id": 1456298291,
                "artist_id": 2801,
                "artist": "Sly & The Family Stone",
                "song_id": 15896,
                "song": "Soul Clappin'",
                "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/150/7/10257.jpg",
                "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/500/7/10257.jpg",
                "user": "Rockbot",
                "user_image_small": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-150.png",
                "user_image_large": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-300.png",
                "likes": 0,
                "dislikes": 0
            },
            {
                "pick_id": 1456298286,
                "artist_id": 807,
                "artist": "Mary J. Blige",
                "song_id": 31549,
                "song": "Just Fine",
                "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/1/25611.jpg",
                "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/1/25611.jpg",
                "user": "Rockbot",
                "user_image_small": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-150.png",
                "user_image_large": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-300.png",
                "likes": 0,
                "dislikes": 0
            }
        ]
    }
}

Submits a positive vote on given pick_id.

HTTP Endpoint

https://api.rockbot.com/v3/engage/vote_up

POST Parameters

Parameter	Description
pick_id	Pick ID to vote up

Vote Down

curl -H "Authorization: API_KEY" -d "pick_id=12345"
 "https://api.rockbot.com/v3/engage/vote_down"

Successful JSON Response:

{
    "response": {
        "venue": "Rockbot HQ",
        "street": "1625 Clay St #500",
        "city": "Oakland",
        "state": "CA",
        "zip": "94612",
        "current_users": 3,
        "status": "online",
        "now_playing": {
            "pick_id": 1456298284,
            "artist_id": 6597,
            "artist": "DeBarge",
            "song_id": 34242,
            "song": "Rhythm Of The Night",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/150/1/10271.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/500/1/10271.jpg",
            "user": "Rockbot",
            "user_image_small": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-150.png",
            "user_image_large": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-300.png",
            "likes": 0,
            "dislikes": 0,
            "duration": 234,
            "remaining": 104
        },
        "queue": [
            {
                "pick_id": 1456298290,
                "artist_id": 940,
                "artist": "Tamia",
                "song_id": 32340,
                "song": "Beautiful Surprise",
                "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/150/9/26409.jpg",
                "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/500/9/26409.jpg",
                "user": "Rockbot",
                "user_image_small": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-150.png",
                "user_image_large": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-300.png",
                "likes": 0,
                "dislikes": 0
            },
            {
                "pick_id": 1456298291,
                "artist_id": 2801,
                "artist": "Sly & The Family Stone",
                "song_id": 15896,
                "song": "Soul Clappin'",
                "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/150/7/10257.jpg",
                "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/500/7/10257.jpg",
                "user": "Rockbot",
                "user_image_small": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-150.png",
                "user_image_large": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-300.png",
                "likes": 0,
                "dislikes": 0
            },
            {
                "pick_id": 1456298286,
                "artist_id": 807,
                "artist": "Mary J. Blige",
                "song_id": 31549,
                "song": "Just Fine",
                "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/150/1/25611.jpg",
                "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/artists/500/1/25611.jpg",
                "user": "Rockbot",
                "user_image_small": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-150.png",
                "user_image_large": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-300.png",
                "likes": 0,
                "dislikes": 0
            }
        ]
    }
}

Submits a negative vote on given pick_id.

HTTP Endpoint

https://api.rockbot.com/v3/engage/vote_down

POST Parameters

Parameter	Description
pick_id	Pick ID to vote down

Request Artist

curl -H "Authorization: API_KEY" -d "artist_id=123"
 "https://api.rockbot.com/v3/engage/request_artist"

Successful JSON Response:

{
    "response": {
        "venue": "Rockbot HQ",
        "street": "1625 Clay St #500",
        "city": "Oakland",
        "state": "CA",
        "zip": "94612",
        "current_users": 3,
        "status": "online",
        "now_playing": {
            "pick_id": 1456298284,
            "artist_id": 6597,
            "artist": "DeBarge",
            "song_id": 34242,
            "song": "Rhythm Of The Night",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/150/1/10271.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/500/1/10271.jpg",
            "user": "Rockbot",
            "user_image_small": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-150.png",
            "user_image_large": "https://d2x3f3hu3pbot6.cloudfront.net/static/assets/logos/square-300.png",
            "likes": 0,
            "dislikes": 0,
            "duration": 234,
            "remaining": 104
        },
        "queue": [
            {
                "pick_id": 1456298292,
                "artist_id": 371,
                "artist": "Al Green",
                "song_id": 43130,
                "song": "Everything's Gonna Be Alright",
                "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/150/7/48877.jpg",
                "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/500/7/48877.jpg",
                "user": "kiosktest",
                "user_image_small": "https://d2x3f3hu3pbot6.cloudfront.net/static/img/common/no-image/noimage-gray-150.jpg",
                "user_image_large": "https://d2x3f3hu3pbot6.cloudfront.net/static/img/common/no-image/noimage-gray-300.jpg",
                "likes": 0,
                "dislikes": 0
            }
        ],
        "new_pick": {
            "artist_id": 371,
            "artist": "Al Green",
            "song_id": 43130,
            "song": "Everything's Gonna Be Alright",
            "artwork_small": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/100/7/48877.jpg",
            "artwork_large": "https://d2x3f3hu3pbot6.cloudfront.net/upload/live/albums/500/7/48877.jpg",
            "pick_id": 1456298292
        }
    }
}

Adds a track by given artist_id to the queue for playback at venue.

HTTP Endpoint

https://api.rockbot.com/v3/engage/request_artist

POST Parameters

Parameter	Description
artist_id	Artist ID to add to venue queue