API Reference
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.
System.Net.ServicePointManager.Expect100Continue
must be set to false
to stop the header “Expect: 100-Continue” from being sent with the request as SAMMI will not handle it properly.
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}
}
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!"
}
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} |