Diode API Docs

Enabling the Diode API

This API runs on every Diode app instance, and is disabled by default.

The API is device-wide. To enable the API on your device:

  1. Open the Diode app (version 1.9.3 or later)
  2. Navigate to any Zone and any Channel, it doesn't matter which Channel
  3. Send the following chat command to the Channel: /sysconfig remote-api enable.
Messages that start with "/" are chat commands. Chat commands and the automated responses to them don't send any data to the channel members, only the sender can see them, and they disappear after leaving the page.
  1. Next, a token will need generated. To generate a token, send this chat command: /sysconfig remote-api generate-token
  2. To view the newly generated token, use this command: /sysconfig remote-api view-token
WARNING: When your API is enabled, anyone with this token can perform API functions on your behalf. Keep it a secret.
  1. The API is now enabled device-wide and a token has been obtained. The device is now ready to accept API requests by whoever has the token. Here are some other helpful commands:
    1. Regenerate Token (Note: This will replace the previous token):
      /sysconfig remote-api generate-token
    2. Disable API:
      /sysconfig remote-api disable
    3. API Status:
      /sysconfig remote-api status
    4. API Version:
      /sysconfig remote-api version

Calling the API

A valid request is an HTTP POST request containing the following two headers and a JSON-RPC 2.0 payload.

There are two ways to reach the API endpoint:

  • Via the Diode Web2 Gateway (most convenient, use anywhere):
    https://<device_address>.diode.link/api/json_rpc
  • Direct via Web3 (most secure, requires web3 pipe between caller and device where the API is enabled):
    http://<device_address>.diode/api/json_rpc
The "device_address" can be found on the "About" page in Diode Drive, or by sending the /info chat command to any Channel.

Headers:

Content-Type: application/json

Authorization: Bearer <bearer_token>

JSON-RPC 2.0 Payload Format:

{"jsonrpc":"2.0","method":"<method>","params":["<param1>", "<param2>", ..., <paramN>], "id":N}

Curl Example:
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <bearer_token>" -d '{"jsonrpc":"2.0","method":"<method>","params":["<param1>", "<param2>", ..., <paramN>], "id":N}' https://<device_address>.diode.link/api/json_rpc
You can use the following chat commands to get curl templates for the "send_message" method. Please note that the second command will auto-populate the "zone_id" and "channel_id" for the specific channel the command is sent to; the "device_address" will also be auto-populated.

/sysconfig remote-api template
/sysconfig remote-api example

API Methods

"ping"

{"jsonrpc":"2.0","method":"ping","id":1}

"send_message"

{"jsonrpc":"2.0","method":"send_message","params":["<zone_id>", "<channel_id>", "<message_text>"], "id":1}
To obtain the "zone_id" and "channel_id", navigate to the target Channel and send the /info chat command to that Channel. The "zone_id" and "channel_id" will be printed out, amongst other helpful information.


How did we do?


Powered by HelpDocs (opens in a new tab)

Powered by HelpDocs (opens in a new tab)