Welcome - Read this first!

Welcome to ScottyBot API documentation

All API requests go to https://api.scottybot.net/api. This is the Base URL.

Almost all responses are in JSON Format.

Any endpoint that states ‘authkey’ refers to the authkey received after authentication or via the GUI. Check authentication on how to get your key.

Any tabs that starting with (WS) are for the control socket.

Response status codes

Success

Successes differ from errors in that their body may not be a simple response object with a code and a message. The headers however are consistent across all calls:

  • GET, PUT, DELETE returns 200 OK on success,
  • POST returns 201 on success,

When retrieving stuff for example:

Status: 200 OK

  "UserID": "21655",
  "status": "Success",
  "username": null,
  "points": 100
}

Error

Error responses are simply returning standard HTTP error codes along with some additional information:

  • The error code is sent back as a status header,
  • The body includes an object describing both the code and message (for debugging and/or display purposes),

For a call with an invalid authentication token for example:

Status: 401 Access Denied

  "status": "Missing or Invalid AuthKey"
}

Authentication

Most methods require authentication. How does one retrieve one?

How to use your authkey

  • Your Authkey is handled as a query parameter, not an authentication header. Any time an authkey is needed, you will see it as a parameter, treat it like others of its kind.

From ScottyGUI

This is a really simple way to get your authkey. Simply head to the GUI, authenticate normally. Head here:

scottty

There’s your Authkey!

GET /settings Get Channel Settings

This method allows you to view all settings for your channel, including donation status, filter status, and more…

Parameters

  • authkey - Your Authkey

Response

Returns all current settings for your channel, including donation status.

Status: 200 OK

{ "pointstowhitelist": 0, "usequotes": 0, "leaveannounce": 0, "usejoin": 0, "channel": "Chew", "subadditionalpoints": 0, "usemaxchars": 0, "usewiki": 0, "timeoutlength": 15, "points": 1, "xqueueremove": 0, "sublistcost": 0, "sjpoints": 0, "raffletime": 60, "joinannounce": 0, "followmsg": "Thank you for the follow (_follower_) we are happy to have you here!", "cooldown": 30, "useclever": 0, "welcomemsg": "Welcome to the stream (_user_)!", "neverclear": 0, "submsg": "(_user_) has subscribed!", "useroulette": 0, "lastone": 0, "usechuck": 0, "useurl": 0, "xqueuecost": 0, "useyoda": 0, "usefollower": 0, "idlepoints": 1, "xqueue": 0, "xqueuesubonly": 0, "sjdonatemsg": "Donation receive: (_donator_) donated $(_amount_) on (_date_) with message: (_message_)", "startpoints": 100, "whitelistthemselfs": 0, "usesublistme": 0, "subalert": 1, "discordaddreg": 0, "chanid": 1581, "usepushbullet": 0, "onlywhenlive": 0, "usewelmsg": 0, "bankheist": "bankheist", "donated": 0, "uselinks": 0, "usegibberish": 0, "notidlepoints": 15, "maxemoji": 5, "timezone": "US/Central", "xqueueusertimeout": 300, "startstopalert": 1, "usebot": 1, "purgecommands": 0, "usesymbols": 0, "repeattimes": 600, "usebankheist": 0, "cappercent": 50, "allowmodtweet": 0, "useleet": 0, "sjannounce": 0, "lfmname": "", "usecapitals": 0, "whisperwarn": 0, "broadcasts": 1, "autotweetmsg": "I have started streaming at https://mixer.com/(_channame_) Let's have some fun!", "subbonus": 0, "roulettename": "roulette", "discordaddsub": 0, "useemoji": 0, "userepeat": 0, "useautotweet": 0, "showhost": 0, "usespin": 1, "usefilter": 0, "spincooldown": 600, "symbolcount": 50, "useme": 0, "whisper": 0, "maxchars": 250, "useraffle": 0, "pointsname": "coins", "useurban": 0 }

POST /settings Change Settings

This method is used to change the value of an individual setting. Boolean values are set via integers: 1 (true) and 0 (false). All available settings can be viewed via calling /settings using GET. Only read only settings are donated, channel, and chanid.

Parameters

  • authkey - Your Authkey
  • setting - Setting to change.
  • value - New value, 0 or 1.

Request

Returns all current settings included the updated setting

Example coming soon!

GET /badwords Get Bad Words

This method returns a JSONObject of all the bad words that are set for the channel. This will be changed to a JSONArray in the future, you may ignore the Keys in the JSONObject.

Parameters

  • authkey - Your Authkey

Response

Returns all current BadWords set for the channel

Status: 200 OK

{ "0": "bagels", "1": "twitch", "2": "garbage", "3": "rood" }

PUT /badwords/add Add a Bad Word

This method allows you to add a bad word to the list, and returns the new list of bad words.

Parameters

  • authkey - Your Authkey.
  • word - Bad word to add.

Response

Returns updated BadWords list.

Status: 200 OK

{ "0": "bagels", "1": "twitch", "2": "garbage", "3": "rood", "4": "hand sanitizer" }

DELETE /badwords/add Delete a Bad Word

This method allows you to remove a bad word from the list, and returns the new list of bad words.

Parameters

  • authkey - Your Authkey.
  • word - Bad word to remove.

Response

Returns updated BadWords list.

Status: 200 OK

{ "0": "bagels", "1": "twitch", "2": "garbage", "3": "rood" }

GET /showquotes Get Quotes

This method receives the list of Quotes for a channel using the Numerical ID of the channel.

Parameters

  • chanid - Numerical ID of the channel

Response

JSONArray of the quotes for a channel.

Status: 200 OK

[ { "quote": "If someone says you're bad at any video game... punch them in the nostril. - @YourMCAdmin - 03/26/2018 (Minecraft)", "id": 0 }, { "quote": "We don't make ugly here. - @YourMCAdmin - 03/26/2018 (Minecraft)", "id": 1 } ]

PUT /quotes/add Add a Quote

This method adds a new quote.

Parameters

  • authkey - Your Authkey.
  • person - Person who said the quote.
  • quote - What the person said.

Response

Returns a JSONArray of the quotes including the new quote

Status: 200 OK

[ { "quote": "If someone says you're bad at any video game... punch them in the nostril. - @YourMCAdmin - 03/26/2018 (Minecraft)", "id": 0 }, { "quote": "We don't make ugly here. - @YourMCAdmin - 03/26/2018 (Minecraft)", "id": 1 }, { "quote": "Hawaii is a planet! - @YourMCAdmin - 06/09/2018 (Minecraft)", "id": 2 } ]

PUT /quotes/edit Edit a Quote

This method edits a quote by ID.

Parameters

  • authkey - Your Authkey.
  • id - ID of quote to edit.
  • quote - Quote to change.

Response

Returns a JSONArray of the quotes including the modified quote

Status: 200 OK

[ { "quote": "If someone says you're bad at any video game... punch them in the nostril. - @YourMCAdmin - 03/26/2018 (Minecraft)", "id": 0 }, { "quote": "We don't make ugly here. - @YourMCAdmin - 03/26/2018 (Minecraft)", "id": 1 }, { "quote": "Hawaii is a country! - @YourMCAdmin - 06/09/2018 (Minecraft)", "id": 2 } ]

DELETE /quotes/delete Delete a Quote

This method deletes a quote by ID.

Parameters

  • authkey - Your Authkey.
  • id - ID of quote to remove.

Response

Returns a JSONArray of the quotes excluding the new quote.

Status: 200 OK

[ { "quote": "If someone says you're bad at any video game... punch them in the nostril. - @YourMCAdmin - 03/26/2018 (Minecraft)", "id": 0 }, { "quote": "We don't make ugly here. - @YourMCAdmin - 03/26/2018 (Minecraft)", "id": 1 } ]

GET /8ball Show 8Ball Responses

This method return a JSONArray of all your custom 8ball messages. If this is empty then the default will be used.

Parameters

  • authkey - Your Authkey.

Response

Returns a JSONArray of custom 8ball messages.

Example coming soon!

PUT /8ball Change 8Ball Responses

This method allows you to set a JSONArray of all your custom 8ball messages. If this is empty then the default will be used.

Parameters

  • authkey - Your Authkey.
  • array - JSONArray of updated 8ball messages.

Response

Returns a JSONArray of custom 8ball messages.

Example coming soon!

PUT /startauction Start an Auction

This method allows you to start an Auction, towhisper is optional, but great for whispering CD Keys or Steam keys or whatnot.

Parameters

  • authkey - Your Authkey.
  • item - The item being auctioned.
  • startingbid - Starting amount for the auction.
  • towhisper - What to whisper to the user.

Response

Returns a JSONObject on if it started or a reason why it could not start.

Example coming soon!

GET /points Get Points

This method returns a JSONObject with information such as the userid, their username, and their current points in the channel.

Parameters

  • authkey - Your Authkey.
  • userid - Numerical ID of the Mixer username.

Response

JSONObject containing information including their current points

{ "UserID": "21655", "status": "Success", "username": null, "points": 500 }

PUT /points Add Points

This method returns a status JSONObject with either success or a failure reason.

Parameters

  • authkey - Your Authkey.
  • userid - Numerical ID of the Mixer username.
  • points - How many points to give.

Response

JSONObject containing success message or failure reason.

{ "status": true }

PUT /points/all Give Everyone Points

This method returns a status JSONObject with either success or a failure reason.

Parameters

  • authkey - Your Authkey.
  • points - How many points to give all users.

Response

JSONObject containing success message or failure reason.

{ "status": true }

DELETE /points Remove Points

This method returns a status JSONObject with either success or a failure reason.

Parameters

  • authkey - Your Authkey.
  • userid - Numerical ID of the Mixer username.
  • points - How many points to remove.

Response

JSONObject containing success message or failure reason.

{ "status": true }

GET /reglist Get the Regular List

This method returns a status JSONObject with either success or a failure reason.

Parameters

  • chanid - Name or ID of Mixer channel.

Response

JSONObject containing success message or failure reason.

Example coming soon!

GET /rankscheme Get Channel Rank

Return a JSONObject with the hours required as the key and the rank name as the value.

Parameters

  • chanid - Numerical ID of Mixer channel.

Response

JSONObject with rank hours and name.

“hour”: “Rank”

{ "0": "Noob with (_hours_) watched!", "8": "Seasoned with (_hours_) watched!", "2": "Noobish with (_hours_) watched!", "4": "New Viewer with (_hours_) watched!", "16": "Friend with (_hours_) watched!" }

DELETE /rankscheme/reset Reset Channel Rank

Return a JSONObject with the hours required as the key and the rank name as the value.

Parameters

  • authkey - Your Authkey.

Response

Resets ranks to the bot default. Returns the ranks afterwards.

{ "192": "Sergeant - Grade 2 with (_hours_) watched!", "2052": "Brigadier General with (_hours_) watched!", "8450": "General - Grade 1 with (_hours_) watched!", "375": "Gunnery Sergeant - Grade 2 with (_hours_) watched!", "1259": "Captain - Grade 1 with (_hours_) watched!", "1114": "First Lieutenant with (_hours_) watched!", "732": "Lieutenant - Grade 1 with (_hours_) watched!", "5039": "Colonel - Grade 3 with (_hours_) watched!", "6525": "Brigadier - Grade 2 with (_hours_) watched!", "4623": "Colonel - Grade 2 with (_hours_) watched!", "1816": "Staff Captain with (_hours_) watched!", "2529": "Major - Grade 3 with (_hours_) watched!", "32": "Corporal - Grade 1 with (_hours_) watched!", "5492": "Force Colonel with (_hours_) watched!", "7112": "Brigadier - Grade 3 with (_hours_) watched!", "9211": "General - Grade 2 with (_hours_) watched!", "4241": "Colonel - Grade 1 with (_hours_) watched!", "10040": "General - Grade 3 with (_hours_) watched!", "7752": "Brigadier General with (_hours_) watched!", "3891": "Strike Commander with (_hours_) watched!", "16": "Private - Grade 2 with (_hours_) watched!", "3275": "Commander - Grade 2 with (_hours_) watched!", "240": "Sergeant - Grade 3 with (_hours_) watched!", "10943": "5 Star General with (_hours_) watched!", "0": "Recruit with (_hours_) watched!", "2756": "Field Major with (_hours_) watched!", "2": "Apprentice - Grade 1 with (_hours_) watched!", "586": "Master Gunnery Sergeant with (_hours_) watched!", "300": "Gunnery Sergeant - Grade 1 with (_hours_) watched!", "1422": "Captain - Grade 2 with (_hours_) watched!", "4": "Apprentice - Grade 2 with (_hours_) watched!", "3004": "Commander - Grade 1 with (_hours_) watched!", "2278": "Major - Grade 2 with (_hours_) watched!", "842": "Lieutenant - Grade 2 with (_hours_) watched!", "469": "Gunnery Sergeant - Grade 3 with (_hours_) watched!", "128": "Sergeant - Grade 1 with (_hours_) watched!", "8": "Private - Grade 1 with (_hours_) watched!", "5986": "Brigadier - Grade 1 with (_hours_) watched!", "1607": "Captain - Grade 3 with (_hours_) watched!", "969": "Lieutenant - Grade 3 with (_hours_) watched!", "64": "Corporal - Grade 2 with (_hours_) watched!" }

PUT /rankscheme/set Set Channel Ranks

Set the ranks to your custom choices, with the hours as the key and the rank name as the value

Parameters

  • authkey - Your Authkey.
  • jsonranks - JSONObject of your ranks.

Response

Set your custom ranks to the JSONObject you sent

{ "5": "Bagel with (_hours_) watched!" }

GET /hours Get User Watch Hours

Return a JSONObject with the hours and rank of the user.

Parameters

  • authkey - Your Authkey.
  • userid - User ID of user.

Response

Set your custom ranks to the JSONObject you sent

{ "status": "User has no hours in this channel yet." }

GET /botstats Get Scottybot Status

Returns the raw JSONObject of bot status, the same info you see at https://scottybot.net/status.php.

Parameters

None!

Response

JSONObject of bot info

{ "channels": 14785, "curlivecount": 557, "controlsockets": 168, "lastrestart": "Tue Jun 12 04:31:43 BST 2018", "chanreconcount": 0, "uptime": "1 day 12 hours 0 minutes 13 seconds" }

PUT /speak Make Scottybot Talk

Allows you to easily get the bot to speak on behalf of a script or program. Returns a success or failure. This endpoint does not know if the bot has lost connection or not.

Parameters

  • authkey - Your authkey
  • say - What the bot will say.

Response

JSONObject of success.

{ "status": "success" }