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.
2. JWT Token - pass an Authorization header with Bearer JWT_TOKEN content where the JWT_TOKEN is a JWT token issues by SUPLA Scripts instance.

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

Clients

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

Execute a scene with public URL

Execute a scene with authorized URL

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