Open API
We provide an Open API in Gladys that lets our user send data from outside their network.
Let's imagine I want to send data from my phone: my location, an event when I come home, my battery, an event when my phone is near a NFC tag, an event when I enter a zone, anything is possible with the Open API.
Prerequisites
You need to be a paid Gladys Plus user to use the Open API.
You can subscribe here.
Generate a new API Key
First, you need to create a new API key in Gladys Plus.
Go to https://plus.gladysassistant.com/dashboard/settings/gateway-open-api.
Type a name for the device that will use your API key.
Click on "Generate", then copy-paste the API key and save it somewhere: it'll never be displayed again.
Send a new sensor value
Now, let's send a new sensor value.
Tutorial scenario:
Let's assume you want to send an event when your phone is home, and send another event when your phone has left home.
Let's create a device in Gladys
You can use the "MQTT" integration to create devices, even if you don't use the MQTT integration.
Let's create a device for your phone:
Note: Say that your phone is a motion sensor, because it's a great binary device for this use case. It doesn't really matter here, you'll see how we'll use this here :)
You can keep the feature "external_id" for later, we'll need it in the API.
Send an API request
Now, let's try to send an API request to the Open API to say "my phone is home".
We'll send:
POST https://api.gladysgateway.com/v1/api/device/state/YOUR_OPEN_API_KEY
Body:
{
"device_feature_external_id": "mqtt:my-phone-presence",
"state": 1
}
You can try the API using Insomnia.
If you want to say the opposite (my phone left home), you can send:
POST https://api.gladysgateway.com/v1/api/device/state/YOUR_OPEN_API_KEY
Body:
{
"device_feature_external_id": "mqtt:my-phone-presence",
"state": 0
}
Create a scene in Gladys to put your user as "at home"/"left home"
You can create 2 scenes in Gladys to set your user as "left home" or "at home" when your phone is near home:
Use Tasker or iOS Shortcuts to trigger this API
On Android you can use the Amazing Tasker to send an API request when you enter/leave your house (based on anything: GPS location, NFC trigger, Wi-Fi detection, or anything in your imagination)
On iOS, you can use Shortcuts.
Example with iOS:
First step, install Shortcuts and create a new shortcut
You need to install the "Shortcuts" app on the app store. It's made by Apple and it's free to use.
Then, create a new shortcut, and add a new web action:
Copy the URL of the Gateway, and add the JSON body.
- The "device_feature_external_id" attribute should be a text field
- The "state' attribute should be a number field
You can create another shortcut for the "left home" event by duplicating the previous one, and changing 1 by 0.
Now, we can create an automation to make this shortcut run automatically when you arrive at home:
You can do the same for when you leave home.
You can also add the shortcut to your home screen if you want to trigger it manually:
Send phone location using Owntracks
It's also possible to send your phone location to Gladys using the Open API and Owntracks:
Read the tutorial in the documentation