API Reference

Edit

General #

The default URI is localhost:9450/api for all GET and POST requests.
You must pass an Authorization header supplying the password if it’s enabled in the SAMMI Settings.
For GET requests supply parameters in the URL query, for POST requests supply parameters in the request body.

Available requests #

Request Method Description
getVariable GET Get a global or button variable
getDeckStatus GET Get the current deck status
setVariable POST Set a global or button variable
deleteVariable POST Delete a variable
insertArray POST Insert a value into an existing array
deleteArray POST Delete a value in an existing array
changeDeckStatus POST Enable, disable or toggle Deck status
triggerButton POST Trigger a button
releaseButton POST Release a button
modifyButton POST Modify button’s text, color, border or image
alertMessage POST Send a yellow alert message
popupMessage POST Send a popup message
notificationMessage POST Send a bubble notification message

Request formats #

Every request must supply request parameter either in the URL query for GET methods or JSON body for POST methods.

Example getVariable request:
URI: localhost:9450/api?request=getVariable&name=Architecture

Example setVariable request:
URI: localhost:9450/api
Request body:

{
    "request": "setVariable",
    "name": "myVariable",
    "value": "Hello World",
    "buttonID": "ID19"
}

Successful response formats #

For successful GET requests, SAMMI replies with:

{
    "data": {REQUESTED DATA}
}

For successful POST requests, SAMMI replies with:

{
    "data": "Ok."
}

Error response formats #

If anything goes wrong, SAMMI repplies with the appropriate HTTP status and the following message:

{
    "Error": {Short Error Code}, 
    "Description": {More detailed information about the error}
}


Edit

Requests #

Get Variable #

Request a variable and return its value.
Method: GET
Request: getVariable

Parameter Name Required Type Description
name yes String Name of the variable to retrieve
buttonID no String Button ID. Defaults to global variable if none supplied.

Example
Request URI: localhost:9450/api?request=getVariable&name=Architecture
Response:

{
    "data": "x64"
}

Get Deck Status #

Request a deck status.
Method: GET
Request: getDeckStatus

Parameter Name Required Type Description
deckID yes String ID of the deck (Deck name not supported)

Example
Request URI: localhost:9450/api?request=getDeckStatus&deckID=20221014032126860893584
Response:

{
    "data": true
}

Set Variable #

Set a global or button variable.
Method: POST
Request: setVariable

Parameter Name Required Type Description
name yes String Name of the variable
value yes Int/String/Array/Object Value to set the variable to
buttonID no String Button ID. Defaults to global variable if none supplied.

Example
Request URI: localhost:9450/api
Request Body:

{
"request": "setVariable",
"name": "myVariable",
"value": "Hello World",
"buttonID": "ID19"
}

Delete a variable #

Deletes a variable.
Method: POST
Request: deleteVariable

Parameter Name Required Type Description
name yes String Variable name to delete
buttonID no String Button ID. Defaults to global variable if none supplied.

Example
Request URI: localhost:9450/api
Request Body:

{
    "request": "deleteVariable",
    "name": "myVariable",
    "buttonID": "ID19"
}

Insert an array value #

Inserts a value into an existing array at a specified position.
Method: POST
Request: insertArray

Parameter Name Required Type Description
name yes String Name of the array
index yes Int Array index to insert the value to
value yes Int/String/Object The value to insert
buttonID no String Button ID. Defaults to global variable if none supplied.

Example
Request URI: localhost:9450/api
Request Body:

{
	"request": "insertArray",
	"name": "myArray",
	"index": 0,
	"buttonID": "ID19",
	"value": {
		"key": "Hello",
		"key2": "Hello World"
	}
}

Delete an array value #

Deletes an array value at a specified position.
Method: POST
Request: deleteArray

Parameter Name Required Type Description
name yes String Name of the array
index yes Int Array index to delete the value at
buttonID no String Button ID. Defaults to global variable if none supplied.

Example
Request URI: localhost:9450/api
Request Body:

{
	"request": "deleteArray",
	"name": "myArray",
	"index": 0,
	"buttonID": "ID19"
}

Change deck status #

Enable or disable a deck.
Method: POST
Request: changeDeckStatus

Parameter Name Required Type Description
deckID yes String ID of the deck (Deck name not supported)
status yes Int Status - 1 to enable, 0 to disable, 2 to toggle

Example
Request URI: localhost:9450/api
Request Body:

{
    "request": "changeDeckStatus",
    "deckID": "20211224163143633002232",
    "status": 1
}

Trigger a button #

Trigger a deck button.
Method: POST
Request: triggerButton

Parameter Name Required Type Description
buttonID yes String Button ID to be triggered

Example
Request URI: localhost:9450/api
Request Body:

{
    "request": "triggerButton",
    "buttonID": "ID19"
}

Release a button #

Release a deck button.
Method: POST
Request: releaseButton

Parameter Name Required Type Description
buttonID yes String Button ID to be released

Example
Request URI: localhost:9450/api
Request Body:

{
    "request": "releaseButton",
    "buttonID": "ID19"
}

Modify a button #

Modify an existing button. Do not supply any parameters to reset the button to its original state.
Method: POST
Request: modifyButton

Parameter Name Required Type Description
buttonID yes String Button ID to be modified
text no String Button text
color no Int Decimal button color (BGR)
image no String Button image file name
border no Int 0-7 border size

Example
Request URI: localhost:9450/api
Request Body:

{
    "request": "modifyButton",
    "buttonID": "ID19",
    "text": "Hello World",
    "color": 16744576 ,
    "image": "myimage.png",
    "border": 2
}

Popup message #

Display a popup message.
Method: POST
Request: popupMessage

Parameter Name Required Type Description
message yes String Message to show

Example
Request URI: localhost:9450/api
Request Body:

{
    "request": "popupMessage",
    "message": "Hello World!"
}

Alert message #

Display a yellow alert message.
Method: POST
Request: alertMessage

Parameter Name Required Type Description
message yes String Message to show

Example
Request URI: localhost:9450/api
Request Body:

{
    "request": "alertMessage",
    "message": "Hello World!"
}

Notification message #

Display a bubble notification message.
Method: POST
Request: notificationMessage

Parameter Name Required Type Description
title yes String Title to show
message yes String Message to show

Example
Request URI: localhost:9450/api
Request Body:

{
    "request": "notificationMessage",
    "message": "Hello World!"
}


Edit

Errors #

If there’s any issue with your request, SAMMI will reply with the appropriate HTTP status, error code and description.

Error response format:

{
    Error: {Short Error Code}, 
    Description: {More detailed information about the error}
}

400 Bad Request

Error Description
Malformed request body Malformed request body. The provided JSON string is invalid.
Request is missing. No request key in the request body was found.
Required parameter is missing. Request body is missing the following required parameters: {requiredParams}
Incorrect parameter type. Request body supplied an incorrect parameter type for {requestType}

401 Unauthorized

Error Description
Authorization failed. No authorization header was found or wrong value was provided. Please verify your Authorization header matches your API Password in SAMMI Settings.

404 Not Found

Error Description
Endpoint not found. Hello from SAMMI! Endpoint {endpoint} was not found :( Available endpoints: {endpoints}.
Unsupported request. Not found. Method {reqMethod} only supports the following requests: {requests}
Button ID not found. You’re trying to trigger a button that does not exist, or is not persistent.
Variable not found. Variable with the name {varName} does not exist.

405 Method Not Allowed

Error Description
Method not supported. Hello from SAMMI! Endpoint {endpoint} accepts only the following methods: {methods}