API Reference

On this page

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}
}

This is not an exhaustive list of all possible response messages.

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}