🔨Create a screen

Leverage our simple RESTful endpoints to generate custom screens on your TRMNL device.

Before you begin

Creating screens requires a Private Plugin instance inside your TRMNL account. This is currently available via the web interface only. Simply navigate to Plugins > Private Plugin > New.

Only accounts with the Developer add-on may create private plugins - you may unlock this feature anytime from your Account page for a one-time fee.

Create a screen (webhook strategy)

If your private plugin's "Strategy" is set to Webhook, you can provide data to TRMNL's server at any time.

Simply send a POST request to the instance's Webhook URL, accessible from the configuration form. The below example updates the Plugin with UUID "asdfqwerty1234" using dynamic values inside a "merge_variables" node:

curl "https://usetrmnl.com/api/custom_plugins/asdfqwerty1234" \
  -H "Content-Type: application/json" \
  -d '{"merge_variables": {"text":"You can do it!", "author": "Rob Schneider"}}' \
  -X POST

The Plugin's UUID value (asdfqwerty1234 in the example above) will associate your payload with the Markup you already provided when you created your private plugin.

To retrieve your Plugin's Webook URL / UUID, visit your private plugin instance. Note that you must "save" (create) the private plugin before a UUID and Webhook URL will be generated.

Private Plugin Webhook URL w/ UUID

Create a screen (polling strategy)

If your private plugin's "Strategy" is set to Polling, the TRMNL server will periodically fetch for new data from an endpoint of your choice.

Simply provide a "Polling URL" inside your private webhook instance (web UI), and TRMNL will make a GET request to that URL. To test this quickly, we've prepared an endpoint that responds with text and author key/value pairs, along with a collection array for quick demonstration:

https://usetrmnl.com/custom_plugin_example_data.json

If your desired polling URL contains a collection/array in the root node, TRMNL will nest it inside a key named "data" for accessibility by the Liquid templating engine. Here is an example of that style payload:

https://usetrmnl.com/custom_plugin_example_data.json?collection_only=true

Note: With the Polling strategy, variables do not need to be nested within a "merge_variables" node. That is only a requirement for the Webhook strategy.

Troubleshooting

For more assistance, see our Private Plugin Tutorial or email [e-mail].