API

API authorization

You can authorize yourself in the API in two ways.

1. HTTP Basic Authentication - pass username and password in the basic authorization header. This is not preferred method of authorization as it may expose you username and password if, for example, some reads your configuration files.
2. JWT Token - pass an Authorization header with Bearer JWT_TOKEN content where the JWT_TOKEN is a JWT token issued and signed by target SUPLA Scripts instance. THis is the preferred method of authorization.

All of the examples below that need authorization assume that you have a valid JWT Token.

Obtaining JWT authorization token

In GUI

Currently, the only way to obtain a JWT token in the GUI is to generate it for a scene and get it from the exported cURL command.

Programmatic

See the endpoint below.

Tokens

Obtain a JWT token for client

This endpoint creates a client and issues a signed JWT Token that can be used to authorize requests in SUPLA Scripts until the client is disabled or deleted. The token is issues for 5 years.

Attribute	Value
URL	https://supla.fracz.com/api/tokens/client
Method	POST
Body	{"username": "USERNAME", "password": "PASSWORD", "label": "INITIAL_LABEL"}, the label is not mandatory
Requires Authorization header	no
Response	{"token": "JWT_TOKEN"}
cURL request example	curl https://supla.fracz.com/api/voice-commands -X POST -m 10000 --data '{"username": "john", "password": "P4SS"}'
example response	{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ"}

Scenes

Every scene has an identifier which is an UUIDv4 and is being referred to as SCENE_ID in docs. If the scene is set to be publically accessible, it is given another SCENE_PUBLIC_ID which is also an UUIDv4.

Execute a scene with public URL

Attribute	Value
URL	https://supla.fracz.com/api/scenes/pubilc/SCENE_PUBLIC_ID
Method	GET
Requires Authorization header	no
Response	SCENE_FEEDBACK if the scene has feedback cofigured, empty response with 204 HTTP Status otherwise
cURL request example	curl https://supla.fracz.com/api/scenes/public/b4a6b9c3-0c33-41e4-ab89-3a4081e094ab
example response	the bulb has been switched on

Execute a scene with authorized URL

Attribute	Value
URL	https://supla.fracz.com/api/scenes/execute/SCENE_ID
Method	GET
Requires Authorization header	yes
Response	SCENE_FEEDBACK if the scene has feedback cofigured, empty response with 204 HTTP Status otherwise
cURL request example	curl https://supla.fracz.com/api/scenes/execute/108abc97-f91e-4c04-8409-7baab8b38c79 -H "Authorization: Bearer JWT_TOKEN"
example response	the bulb has been switched on

Voice commands

Execute a scene with assigned voice command

This endpoint executes all scenes that have at least one configured voice trigger that matches the given command. The trigger is consired matched if it is a substring of the given comomand.

If multiple commands are matched and all of them provide feedback, each feedback will be concatenated with newline character in the response.

Attribute	Value
URL	https://supla.fracz.com/api/voice-commands
Method	PATCH
Body	{"command": "THE VOICE COMMAND"}
Requires Authorization header	yes
Response	{"matchedActions": X, "feedback": "A FEEDBACK"}, where X is the number of executed scenes
cURL request example	curl https://supla.fracz.com/api/voice-commands -X PATCH -m 10000 -H "Authorization: Bearer JWT_TOKEN" --data '{"command": "switch the bulb on"}'
example response	{"matchedActions": 1, "feedback": "the bulb has been switched on"}