### Get Devices - JavaScript Example Source: https://github.com/usetrmnl/api-docs/blob/master/private-api/account.md This example demonstrates how to retrieve a list of devices associated with your account using the Account API. It shows the expected JSON response structure, including device ID, name, MAC address, and battery status. No specific dependencies are required beyond making an HTTP GET request. ```javascript GET https://trmnl.com/api/devices { "data": [ { "id": 123456, "name": "My TRMNL", "friendly_id": "A1B2C3", "mac_address": "AB:CD:EF:12:34:56", "battery_voltage": 3.9, "rssi": -41 } ] } ``` -------------------------------- ### Setup BYOS API Endpoint (Shell) Source: https://github.com/usetrmnl/api-docs/blob/master/diy/byos.md Initiates the setup process for a BYOS device. Requires the device's MAC address as an 'ID' header and specifies JSON content type. ```shell curl "https://byos.local/api/setup" \ -H 'ID: ' \ -H 'Content-Type: application/json' ``` -------------------------------- ### Success Webhook Notification Payload (JSON) Source: https://github.com/usetrmnl/api-docs/blob/master/plugin-marketplace/plugin-installation-flow.md This is an example of the JSON payload received by your server when a user successfully installs a plugin. It includes user details and plugin setting information, which can be used for further actions or redirects. ```json { "user": { "name":"Ronak J", "email":"ronak@trmnl.com", "first_name":"Ronak", "last_name":"J", "locale":"en", "time_zone":"Pacific Time (US & Canada)", "time_zone_iana":"America/Los_Angeles", "utc_offset":-28800, "plugin_setting_id":1234, "uuid": "674c9d99-cea1-4e52-9025-9efbe0e30901" } } ``` -------------------------------- ### Setup API Source: https://github.com/usetrmnl/api-docs/blob/master/diy/byos.md This endpoint is used to set up a BYOS device. It requires the device's MAC address in the 'ID' header. ```APIDOC ## POST /api/setup ### Description Sets up a BYOS device. Requires the device's MAC address in the 'ID' header. ### Method POST ### Endpoint /api/setup ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```shell curl "https://byos.local/api/setup" \ -H 'ID: ' \ -H 'Content-Type: application/json' ``` ### Response #### Success Response (200) Details of the success response are not provided in the source text. #### Response Example None provided in the source text. ``` -------------------------------- ### OAuth Plugin Installation Flow Source: https://context7.com/usetrmnl/api-docs/llms.txt Third-party plugins use OAuth2 for user authentication. After receiving the installation request, exchange the token for an access token. ```APIDOC ## POST /oauth/token ### Description Exchange an authorization code for an access token during the OAuth2 plugin installation flow. ### Method POST ### Endpoint /oauth/token ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **code** (string) - Required - The authorization code received from the installation request. - **client_id** (string) - Required - Your plugin's client ID. - **client_secret** (string) - Required - Your plugin's client secret. - **grant_type** (string) - Required - Must be set to "authorization_code". ### Request Example ```json { "code": "authorization-code-from-installation", "client_id": "your-plugin-client-id", "client_secret": "your-plugin-secret", "grant_type": "authorization_code" } ``` ### Response #### Success Response (200) - **access_token** (string) - The user-specific access token for the plugin. #### Response Example ```json {"access_token": "user-specific-access-token"} ``` ``` -------------------------------- ### Installation Success Webhook Source: https://github.com/usetrmnl/api-docs/blob/master/plugin-marketplace/plugin-installation-flow.md TRMNL sends a POST notification to your specified webhook URL upon successful plugin installation by a user. ```APIDOC ## POST /installation_success_webhook_url ### Description Receives a notification from TRMNL when a user successfully installs a plugin. ### Method POST ### Endpoint [installation_success_webhook_url provided during installation request] ### Parameters #### Request Body - **user** (object) - Required - Information about the user who installed the plugin. - **name** (string) - The full name of the user. - **email** (string) - The email address of the user. - **first_name** (string) - The first name of the user. - **last_name** (string) - The last name of the user. - **locale** (string) - The user's locale setting. - **time_zone** (string) - The user's time zone description. - **time_zone_iana** (string) - The user's IANA time zone identifier. - **utc_offset** (integer) - The user's UTC offset in seconds. - **plugin_setting_id** (integer) - The unique identifier for this plugin setting. - **uuid** (string) - The unique identifier for the user. ### Request Example ```json { "user": { "name": "Ronak J", "email": "ronak@trmnl.com", "first_name": "Ronak", "last_name": "J", "locale": "en", "time_zone": "Pacific Time (US & Canada)", "time_zone_iana": "America/Los_Angeles", "utc_offset": -28800, "plugin_setting_id": 1234, "uuid": "674c9d99-cea1-4e52-9025-9efbe0e30901" } } ``` ### Response #### Success Response (200) - **message** (string) - Confirmation message. #### Response Example ```json { "message": "Installation processed successfully." } ``` ``` -------------------------------- ### API Setup Endpoint Source: https://github.com/usetrmnl/api-docs/blob/master/diy/byod-s.md This endpoint is part of the server setup process required for TRMNL firmware compatibility. Specific details are available in the firmware README. ```APIDOC ## POST /api/setup ### Description This endpoint is part of the server setup process required for TRMNL firmware compatibility. Refer to the firmware README for detailed specifications. ### Method POST ### Endpoint /api/setup ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body * **(Details to be provided based on firmware README)** ### Request Example ```json { "example": "request body" } ``` ### Response #### Success Response (200) * **(Details to be provided based on firmware README)** #### Response Example ```json { "example": "response body" } ``` ``` -------------------------------- ### OAuth Token Exchange Source: https://github.com/usetrmnl/api-docs/blob/master/plugin-marketplace/plugin-installation-flow.md After receiving an installation request, your server exchanges the provided token with TRMNL to obtain an access token. ```APIDOC ## POST /oauth/token ### Description Exchanges an authorization code for an access token. ### Method POST ### Endpoint https://trmnl.com/oauth/token ### Parameters #### Request Body - **code** (string) - Required - The authorization code received during the installation request. - **client_id** (string) - Required - Your plugin's client ID. - **client_secret** (string) - Required - Your plugin's client secret. - **grant_type** (string) - Required - Must be set to 'authorization_code'. ### Request Example ```json { "code": "code-from-step-1", "client_id": "your-plugin-client-id", "client_secret": "your-plugin-secret", "grant_type": "authorization_code" } ``` ### Response #### Success Response (200) - **access_token** (string) - The access token for authenticating subsequent API requests. #### Response Example ```json { "access_token": "your_access_token" } ``` ``` -------------------------------- ### Define and Render Reusable Liquid Templates Source: https://github.com/usetrmnl/api-docs/blob/master/reusing-markup.md This example shows how to define a reusable Liquid template named 'say_hello' using the `{% template %}` tag and then render it within a view layout using the `{% render %}` tag, passing a variable 'name'. ```liquid {% template say_hello %} Hello there, {{ name }}. {% endtemplate %} {% render "say_hello", name: "General Kenobi" %} ``` -------------------------------- ### TRMNL Metadata Object Example (JSON) Source: https://github.com/usetrmnl/api-docs/blob/master/plugin-marketplace/plugin-screen-generation-flow.md An example of the metadata object that TRMNL sends in the POST request payload. This object contains user, device, system, and plugin settings information, which may be useful for the plugin. ```json { "user": { "name": "Jim Bob", "first_name": "Jim", "last_name": "Bob", "locale": "en", "time_zone": "Eastern Time (US & Canada)", "time_zone_iana": "America/New_York", "utc_offset": -14400 }, "device": { "friendly_id": "XXXXXX", "percent_charged": 74.17, "wifi_strength": 50, "height": 480, "width": 800 }, "system": { "timestamp_utc": 1747596567 }, "plugin_settings": { "instance_name": "Upcoming Assignments" } } ``` -------------------------------- ### Fetch Access Token using HTTParty (Ruby) Source: https://github.com/usetrmnl/api-docs/blob/master/plugin-marketplace/plugin-installation-flow.md This snippet demonstrates how to request an access token from TRMNL using the provided client ID, client secret, and installation token. It utilizes the HTTParty gem for making the POST request to the TRMNL OAuth token endpoint. ```ruby body = { code: 'code-from-step-1', client_id: 'your-plugin-client-id', client_secret: 'your-plugin-secret', grant_type: 'authorization_code' } response = HTTParty.post("https://trmnl.com/oauth/token", body: body) response['access_token'] ``` -------------------------------- ### TRMNL Server JSON Response Example Source: https://github.com/usetrmnl/api-docs/blob/master/diy/byod-s.md This is an example of the JSON response generated by the TRMNL web server when a device pings the Display API. It contains an absolute URL to the next image in the queue. ```json { "image_url":"https://trmnl.s3.us-east-2.amazonaws.com/path-to-img.png" } ``` -------------------------------- ### POST /api/partners - Provision Device and Discount Code Source: https://github.com/usetrmnl/api-docs/blob/master/partners-api/provisioning-devices.md This endpoint allows partners to request a coupon code and provision a device with custom data. The custom data will be saved to the user's pre-loaded plugin upon device setup. ```APIDOC ## POST /api/partners ### Description Stub a device + discount code with the Partners API. To preload a custom plugin on a device for your customer, you can generate a coupon code and share the customer's relevant credentials in a single API request. ### Method POST ### Endpoint /api/partners ### Parameters #### Headers - **Client-ID** (string) - Required - Provided by TRMNL team - **Access-Token** (string) - Required - Provided by TRMNL team #### Request Body - **partner** (object) - Required - **action** (string) - Required - Must be "provision_discount" - **data** (object) - Optional - Custom data to be saved to the user's pre-loaded plugin. Key/values should match the merge variables required by the plugin setting instance. - **user-data** (string) - Example data - **more-data** (string) - Example data - **meta** (object) - Optional - Metadata for the provision request - **expires_at** (string) - Optional - The date the coupon will expire (e.g., "2025-03-20"). Defaults to 23:59 EST on this date. ### Request Example ```json { "partner": { "action": "provision_discount", "data": { "user-data": "goes here", "more-data": "also ok" }, "meta": { "expires_at": "2025-03-20" } } } ``` ### Response #### Success Response (200) - **status** (integer) - The status code of the response. - **data** (object) - Contains the generated coupon code. - **code** (string) - The generated coupon code (e.g., "acme-123456789"). This value will be `nil` if a quota is breached. #### Response Example ```json { "status": 200, "data": { "code": "acme-123456789" } } ``` ### Notes - If a quota is preferred (e.g., 50 provisions per month), this endpoint will return a `nil` code value when the quota is breached. - The generated coupon code should be provided to the customer to use at checkout on trmnl.com. - Contact [partners@trmnl.com](mailto:partners@trmnl.com) with questions or requests. ``` -------------------------------- ### GET /recipes/{id}.json Source: https://github.com/usetrmnl/api-docs/blob/master/public-api/recipes-api.md Retrieves details for a specific recipe using its unique identifier. ```APIDOC ## GET /recipes/{id}.json ### Description Retrieves details for a specific recipe using its unique identifier. ### Method GET ### Endpoint `/recipes/{id}.json` #### Path Parameters - **id** (integer) - Required - The unique identifier of the recipe. ### Response #### Success Response (200) - **data** (object) - Contains the recipe details. - **id** (integer) - The recipe's unique identifier. - **user_id** (integer) - The ID of the user who created the recipe. - **name** (string) - The name of the recipe. - **published_at** (string) - The date and time the recipe was published (ISO 8601 format). - **icon_url** (string) - URL of the recipe's icon. - **screenshot_url** (string) - URL of the recipe's screenshot. - **author_bio** (object) - Information about the author. - **keyname** (string) - **name** (string) - **field_type** (string) - **description** (string) - **category** (string) - **custom_fields** (array) - An array of custom fields associated with the recipe. - **keyname** (string) - **name** (string) - **field_type** (string) - **default** (string) - Optional - Default value for the custom field. - **help_text** (string) - Optional - Help text for the custom field. - **stats** (object) - Statistics related to the recipe. - **installs** (integer) - Number of installs. - **forks** (integer) - Number of forks. #### Response Example ```json { "data": { "id": 16382, "user_id": 934, "name": "Matrix", "published_at":"2025-02-10T11:33:00.000Z", "icon_url": "https://trmnl-public.s3.us-east-2.amazonaws.com/mtpxyr22spnwjheeh5kv1p7tpk6n", "screenshot_url": "https://trmnl.s3.us-east-2.amazonaws.com/jly9u094jtsc2bwmnhlnmwjnsokk?response-content-disposition=inline%3B%20filename%3D%22plugin-2025-04-10T12-47-23Z-776f51%22%3B%20filename%2A%3DUTF-8%27%27plugin-2025-04-10T12-47-23Z-776f51&response-content-type=image%2Fbmp&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA47CRUQUU4VKBBMOF%2F20251024%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20251024T210933Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=828e75fc333464c3ba13654c70434d307a8ca48053cd102f4a10a55e953c3ce2", "author_bio": { "keyname": "doesnt_matter", "name": "About This Plugin", "field_type": "author_bio", "description": "Matrix brings the iconic digital rain from the movies to your screen. By default, it displays the current date in the classic style, but you can also customize it to show any message you want.", "category": "calendar,life" }, "custom_fields": [ { "keyname": "doesnt_matter", "name": "About This Plugin", "field_type": "author_bio", "description": "Matrix brings the iconic digital rain from the movies to your screen. By default, it displays the current date in the classic style, but you can also customize it to show any message you want.", "category": "calendar,life" }, { "keyname": "message", "field_type": "string", "name": "Message", "default": "%date", "help_text": "%date to display current date" } ], "stats": { "installs": 25, "forks": 176 } } } ``` ``` -------------------------------- ### Send POST Request to Plugin Markup URL (Bash) Source: https://github.com/usetrmnl/api-docs/blob/master/plugin-marketplace/plugin-screen-generation-flow.md This example demonstrates how to send a POST request to the plugin's markup URL using curl. It includes the necessary headers for authorization and content type, along with the user_uuid and metadata payload. ```bash curl -XPOST 'https://your-server.com/your-markup-url' \ -H 'Authorization: Bearer xxx' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'user_uuid=xx&trmnl=' ``` -------------------------------- ### BYOS API Endpoints (API) Source: https://context7.com/usetrmnl/api-docs/llms.txt Defines the core API endpoints that self-hosted BYOS servers must implement for device communication. Includes setup and display endpoints. ```bash # Setup endpoint - device provisioning curl "http://byos.local/api/setup" \ -H "ID: AA:BB:CC:DD:EE:FF" \ -H "Content-Type: application/json" # Display endpoint - fetch screen content curl "http://byos.local/api/display" \ -H "ID: AA:BB:CC:DD:EE:FF" \ -H "Content-Type: application/json" ``` -------------------------------- ### Generate Experimental 2-bit PNG Image using ImageMagick Source: https://github.com/usetrmnl/api-docs/blob/master/diy/imagemagick-guide.md Demonstrates the process for generating an experimental 2-bit PNG image compatible with TRMNL devices running FW 1.6.0+ with grayscale and fast refresh support. It involves creating a custom 4-color colormap and then converting an input JPEG image using this map with specific PNG format definitions. ```bash magick -size 4x1 xc:#000000 xc:#555555 xc:#aaaaaa xc:#ffffff +append -type Palette colormap-2bit.png magick input.jpeg -resize 800x480\! -dither FloydSteinberg -remap colormap-2bit.png -define png:bit-depth=2 -define png:color-type=0 output.png ``` -------------------------------- ### Retrieve Plugin Categories (API) Source: https://context7.com/usetrmnl/api-docs/llms.txt Fetches a list of valid plugin categories to enhance search visibility. This is a simple GET request to the categories endpoint. ```bash curl "https://trmnl.com/api/categories" ``` -------------------------------- ### Generate 1-bit PNG Image using ImageMagick Source: https://github.com/usetrmnl/api-docs/blob/master/diy/imagemagick-guide.md Provides ImageMagick commands to generate 1-bit PNG images for TRMNL devices. The first command performs a direct conversion, while the second applies dithering using the Floyd-Steinberg algorithm for better grayscale representation. The 'identify' command confirms the PNG format and bit depth. ```bash magick input.png -monochrome -colors 2 -depth 1 -strip png:output.png magick input.png -dither FloydSteinberg -remap pattern:gray50 -depth 1 -strip png:output.png magick identify output.png ``` -------------------------------- ### Valid Server Response with HTML Markup (JSON) Source: https://github.com/usetrmnl/api-docs/blob/master/plugin-marketplace/plugin-screen-generation-flow.md An example of a valid JSON response from the plugin server to TRMNL. This response includes HTML content for different screen layouts ('markup', 'markup_half_horizontal', 'markup_half_vertical', 'markup_quadrant') and a 'shared' field. ```json { "markup":"
Daily Scripture
Hello
World
", "markup_half_horizontal":"
Your content
", "markup_half_vertical":"
Your content
", "markup_quadrant":"
Your content
", "shared":"" } ``` -------------------------------- ### TRMNL API GET /api/display Endpoint Source: https://github.com/usetrmnl/api-docs/blob/master/private-api/introduction.md This snippet demonstrates how to make a GET request to the TRMNL API's /api/display endpoint to retrieve image URLs and other content information. It includes example request headers and response bodies, illustrating the data structure returned by the API. ```HTTP GET /api/display # request headers example { 'ID' => 'XX:XX:XX:XX', 'Access-Token' => '2r--SahjsAKCFksVcped2Q' } # response body example { "image_url"=>"https://trmnl.s3.us-east-2.amazonaws.com/path-to-img.bmp", "filename"=>"2025-05-10-plugin-T00:00:00", "update_firmware"=>false } ``` -------------------------------- ### Plugin Creation Source: https://github.com/usetrmnl/api-docs/blob/master/plugin-marketplace/plugin-creation.md This section details how to create a new plugin by providing specific information about the plugin's functionality, appearance, and integration endpoints. ```APIDOC ## POST /plugins/my/new ### Description Creates a new plugin by submitting detailed information about the plugin. ### Method POST ### Endpoint https://trmnl.com/plugins/my/new ### Parameters #### Request Body - **Name** (string) - Required - Branded title or brief tag describing the plugin's functionality. - **Description** (string) - Required - Additional text to help differentiate the plugin. - **Icon** (file) - Optional - PNG format preferred for the plugin icon. - **Installation URL** (string) - Required - Endpoint where TRMNL should trigger the installation flow. - **Installation Success Webhook URL** (string) - Required - URL to receive installation success events. - **Plugin Management URL** (string) - Required - URL for TRMNL users to manage their plugins. - **Plugin Markup URL** (string) - Required - Endpoint where TRMNL should ping for markup content. - **Uninstallation Webhook URL** (string) - Required - URL to receive uninstallation events. ### Request Example ```json { "Name": "Example Plugin", "Description": "A sample plugin for demonstration purposes.", "Icon": "path/to/icon.png", "Installation URL": "https://example.com/install", "Installation Success Webhook URL": "https://example.com/webhook/install/success", "Plugin Management URL": "https://example.com/manage", "Plugin Markup URL": "https://example.com/markup", "Uninstallation Webhook URL": "https://example.com/webhook/uninstall" } ``` ### Response #### Success Response (201 Created) - **plugin_id** (string) - The unique identifier for the newly created plugin. - **message** (string) - Confirmation message indicating successful plugin creation. #### Response Example ```json { "plugin_id": "plug_123abc456def", "message": "Plugin created successfully." } ``` ``` -------------------------------- ### Display BYOS API Endpoint (Bash) Source: https://github.com/usetrmnl/api-docs/blob/master/diy/byos.md Retrieves display information for a BYOS device. It uses the device's MAC address in the 'ID' header and expects JSON format. ```bash curl "http://byos.local/api/display" \ -H 'ID: ' \ -H 'Content-Type: application/json' ``` -------------------------------- ### Get Merge Variable Content Source: https://github.com/usetrmnl/api-docs/blob/master/private-plugins/webhooks.md Retrieve existing merge variables from a private plugin by sending a GET request to its Webhook URL. ```APIDOC ## GET /api/custom_plugins/{plugin_uuid} ### Description Fetch existing `merge_variables` from a private plugin. ### Method GET ### Endpoint `https://trmnl.com/api/custom_plugins/{plugin_uuid}` ### Parameters #### Path Parameters - **plugin_uuid** (string) - Required - The unique identifier for your private plugin instance. ### Response #### Success Response (200) - **merge_variables** (object) - An object containing the current merge variables. #### Response Example ```json { "merge_variables": { "text": "You can do it!", "author": "Rob Schneider" } } ``` ``` -------------------------------- ### List Recipes Source: https://github.com/usetrmnl/api-docs/blob/master/public-api/recipes-api.md Retrieves a list of community plugins with options for searching and sorting. This endpoint is currently in alpha and may be subject to change. ```APIDOC ## GET /recipes.json ### Description Retrieves a list of community plugins with options for searching and sorting. This endpoint is currently in alpha and may be subject to change. ### Method GET ### Endpoint /recipes.json ### Query Parameters All query parameters are optional. - **search** (string) - Optional - Name of the plugin (partial match OK) - **sort-by** (string) - Optional - Option by which to rank results. Valid options: oldest, newest, popularity, fork, install. - **user_id** (integer) - Optional - ID of the author, e.g. 51 - **per_page** (integer) - Optional - Results count (maximum 100, default 25) ### Request Example `https://trmnl.com/recipes.json?sort-by=install` ### Response #### Success Response (200) - **data** (array) - An array of plugin objects. - **id** (integer) - The unique identifier of the plugin. - **user_id** (integer) - The ID of the plugin's author. - **name** (string) - The name of the plugin. - **published_at** (string) - The date and time the plugin was published (ISO 8601 format). - **icon_url** (string) - URL to the plugin's icon. - **screenshot_url** (string) - URL to a screenshot of the plugin. - **author_bio** (string) - A brief biography of the author (can be null). - **custom_fields** (array) - An array of custom fields defined for the plugin. - **keyname** (string) - The internal key name for the custom field. - **field_type** (string) - The type of the custom field (e.g., 'string', 'integer', 'select'). - **name** (string) - The display name of the custom field. - **placeholder** (string) - Placeholder text for the input field. - **description** (string) - A description of the custom field. - **help_text** (string) - Additional help text for the user. - **required** (boolean) - Indicates if the field is required. - **options** (array) - List of options for select-type fields. - **default** (string) - The default value for the field. - **stats** (object) - Statistics related to the plugin. - **installs** (integer) - Number of times the plugin has been installed. - **forks** (integer) - Number of times the plugin has been forked. - **total** (integer) - The total number of plugins matching the query. - **from** (integer) - The starting index of the results for the current page. - **to** (integer) - The ending index of the results for the current page. - **per_page** (integer) - The number of results per page. - **current_page** (integer) - The current page number. - **prev_page_url** (string) - URL to the previous page of results (null if on the first page). - **next_page_url** (string) - URL to the next page of results (null if on the last page). #### Response Example ```json { "data": [{ "id": 49610, "user_id": 1158, "name": "Weather Chum", "published_at": "2025-05-14T05:32:00.000Z", "icon_url": "https://trmnl-public.s3.us-east-2.amazonaws.com/ajjlbek4cabcvhk3s1lxggn8cgon", "screenshot_url": "https://trmnl.s3.us-east-2.amazonaws.com/qv5d2r4hg4gxe0tnwhiatdfhuqzj?response-content-disposition=inline%3B%20filename%3D%22plugin-2025-04-30T19-47-15Z-21f687%22%3B%20filename%2A%3DUTF-8%27%27plugin-2025-04-30T19-47-15Z-21f687&response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA47CRUQUU4VKBBMOF%2F20251024%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20251024T210603Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=c5795146177d7f539b0743890018338b8a9d7188d685d1e54dde83d842eb404d", "author_bio": null, "custom_fields": [ { "keyname": "user_location", "field_type": "string", "name": "Weather Location", "placeholder": "New York, NY", "description": "Choose a location", "help_text": "Please be precise. Examples: \u003C/br\u003E Paris, France (City/country) \u003C/br\u003E 10101 (Pass US Zipcode, UK Postcode, Canada Postal code)\u003C/br\u003E 33.7501,84.3885 (Lat/long)\u003C/br\u003E", "required": true }, { "keyname": "metric", "name": "Temperature Metric", "description": "Celsius or Fahrenheit?", "field_type": "select", "options": [ "Fahrenheit", "Celsius" ], "default": "Fahrenheit" } ], "stats": { "installs": 1, "forks": 1230 } }], "total": 12, "from": 1, "to": 12, "per_page": 25, "current_page": 1, "prev_page_url": null, "next_page_url": "/recipes?page=2&search=weather&sort_by=popularity" } ``` ``` -------------------------------- ### Provision Discounted Devices (API) Source: https://context7.com/usetrmnl/api-docs/llms.txt Allows partners to provision discounted devices pre-loaded with custom plugins. Requires authentication headers and a POST request with specific JSON payload. ```bash # Request a discount coupon with pre-loaded plugin data curl "https://trmnl.com/api/partners" \ -H "Client-ID: your-partner-client-id" \ -H "Access-Token: your-partner-access-token" \ -H "Content-Type: application/json" \ -d '{ "partner": { "action": "provision_discount", "data": {"api_key": "customer-api-key", "user_id": "12345"}, "meta": {"expires_at": "2025-03-20"} } }' \ -X POST # Response {"status": 200, "data": {"code": "acme-123456789"}} ``` -------------------------------- ### Partners API - Device Provisioning Source: https://context7.com/usetrmnl/api-docs/llms.txt Partners can provision discounted devices pre-loaded with custom plugins for their customers. ```APIDOC ## POST /api/partners ### Description Partners can provision discounted devices pre-loaded with custom plugins for their customers. ### Method POST ### Endpoint /api/partners ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **partner** (object) - Required - Contains provisioning details. - **action** (string) - Required - The action to perform, e.g., "provision_discount". - **data** (object) - Required - Data specific to the action. - **api_key** (string) - Required - The customer's API key. - **user_id** (string) - Required - The customer's user ID. - **meta** (object) - Optional - Metadata for the provisioning request. - **expires_at** (string) - Optional - The expiration date for the provisioned item (YYYY-MM-DD). ### Request Example ```json { "partner": { "action": "provision_discount", "data": {"api_key": "customer-api-key", "user_id": "12345"}, "meta": {"expires_at": "2025-03-20"} } } ``` ### Response #### Success Response (200) - **data** (object) - Contains provisioning results. - **code** (string) - The generated discount or provision code. #### Response Example ```json {"status": 200, "data": {"code": "acme-123456789"}} ``` ``` -------------------------------- ### Log BYOS API Endpoint (Bash) Source: https://github.com/usetrmnl/api-docs/blob/master/diy/byos.md Fetches log data from a BYOS device. The request includes the device's MAC address via the 'ID' header and sets the Content-Type to application/json. ```bash curl "http://byos.local/api/log" \ -H 'ID: ' \ -H 'Content-Type: application/json' ``` -------------------------------- ### Display API Source: https://github.com/usetrmnl/api-docs/blob/master/diy/byos.md This endpoint retrieves display information for a BYOS device. It requires the device's MAC address in the 'ID' header. ```APIDOC ## GET /api/display ### Description Retrieves display information for a BYOS device. Requires the device's MAC address in the 'ID' header. ### Method GET ### Endpoint /api/display ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```bash curl "http://byos.local/api/display" \ -H 'ID: ' \ -H 'Content-Type: application/json' ``` ### Response #### Success Response (200) Details of the success response are not provided in the source text. #### Response Example None provided in the source text. ``` -------------------------------- ### Retrieve Merge Variable Content (cURL) Source: https://github.com/usetrmnl/api-docs/blob/master/private-plugins/webhooks.md Fetches existing merge variables from a TRMNL private plugin by sending a GET request to the specified webhook URL. ```cURL curl "https://trmnl.com/api/custom_plugins/asdfqwerty1234" ``` -------------------------------- ### Screen Templating with TRMNL Framework (HTML) Source: https://context7.com/usetrmnl/api-docs/llms.txt Demonstrates building e-ink friendly screens using TRMNL's CSS framework and Liquid templating. Includes linking to TRMNL's CSS and JS resources. ```html
{{ title }}
{{ quote }}
{{ author }}
Plugin Title Instance Title
``` -------------------------------- ### GET /api/display Source: https://github.com/usetrmnl/api-docs/blob/master/private-api/introduction.md Retrieves image and other content for your device to store or render. This endpoint can be used with a device's API key to request content without a TRMNL device or firmware. ```APIDOC ## GET /api/display ### Description Retrieves image and other content for your device to store or render. This endpoint can be used with a device's API key to request content without a TRMNL device or firmware. ### Method GET ### Endpoint /api/display ### Parameters #### Query Parameters - **ID** (string) - Required - The unique identifier of the device. - **Access-Token** (string) - Required - The API key for authentication. ### Request Example ``` GET /api/display Headers: ID: XX:XX:XX:XX Access-Token: 2r--SahjsAKCFksVcped2Q ``` ### Response #### Success Response (200) - **image_url** (string) - The URL of the image content. - **filename** (string) - The filename for the content. - **update_firmware** (boolean) - Indicates if firmware update is available. ``` -------------------------------- ### OAuth Token Exchange (API) Source: https://context7.com/usetrmnl/api-docs/llms.txt Exchanges an authorization code for an access token, used in the OAuth2 plugin installation flow for user authentication. Requires a POST request with grant type and credentials. ```bash # Exchange authorization code for access token curl "https://trmnl.com/oauth/token" \ -H "Content-Type: application/json" \ -d '{ "code": "authorization-code-from-installation", "client_id": "your-plugin-client-id", "client_secret": "your-plugin-secret", "grant_type": "authorization_code" }' \ -X POST # Response {"access_token": "user-specific-access-token"} ``` -------------------------------- ### Get Single Recipe JSON Response Source: https://github.com/usetrmnl/api-docs/blob/master/public-api/recipes-api.md This JSON object represents the successful response when retrieving a single recipe. It includes details about the recipe such as its ID, name, author information, custom fields, and statistics. The structure is designed for easy parsing and integration into applications. ```json { "data": { "id": 16382, "user_id": 934, "name": "Matrix", "published_at":"2025-02-10T11:33:00.000Z", "icon_url": "https://trmnl-public.s3.us-east-2.amazonaws.com/mtpxyr22spnwjheeh5kv1p7tpk6n", "screenshot_url": "https://trmnl.s3.us-east-2.amazonaws.com/jly9u094jtsc2bwmnhlnmwjnsokk?response-content-disposition=inline%3B%20filename%3D%22plugin-2025-04-10T12-47-23Z-776f51%22%3B%20filename%2A%3DUTF-8%27%27plugin-2025-04-10T12-47-23Z-776f51&response-content-type=image%2Fbmp&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA47CRUQUU4VKBBMOF%2F20251024%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20251024T210933Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=828e75fc333464c3ba13654c70434d307a8ca48053cd102f4a10a55e953c3ce2", "author_bio": { "keyname": "doesnt_matter", "name": "About This Plugin", "field_type": "author_bio", "description": "Matrix brings the iconic digital rain from the movies to your screen. By default, it displays the current date in the classic style, but you can also customize it to show any message you want.", "category": "calendar,life" }, "custom_fields": [ { "keyname": "doesnt_matter", "name": "About This Plugin", "field_type": "author_bio", "description": "Matrix brings the iconic digital rain from the movies to your screen. By default, it displays the current date in the classic style, but you can also customize it to show any message you want.", "category": "calendar,life" }, { "keyname": "message", "field_type": "string", "name": "Message", "default": "%date", "help_text": "%date to display current date" } ], "stats": { "installs": 25, "forks": 176 } } } ``` -------------------------------- ### Logs API Source: https://github.com/usetrmnl/api-docs/blob/master/diy/byos.md This endpoint retrieves logs for a BYOS device. It requires the device's MAC address in the 'ID' header. ```APIDOC ## GET /api/log ### Description Retrieves logs for a BYOS device. Requires the device's MAC address in the 'ID' header. ### Method GET ### Endpoint /api/log ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```bash curl "http://byos.local/api/log" \ -H 'ID: ' \ -H 'Content-Type: application/json' ``` ### Response #### Success Response (200) Details of the success response are not provided in the source text. #### Response Example None provided in the source text. ``` -------------------------------- ### Search Community Plugins - Recipes API (Bash) Source: https://context7.com/usetrmnl/api-docs/llms.txt Provides unauthenticated access to the public Recipes API for searching community-created plugins. Supports searching by keywords and sorting results by popularity. Also allows fetching specific recipes by their ID. ```bash # Search for weather plugins sorted by popularity curl "https://trmnl.com/recipes.json?search=weather&sort-by=popularity" # Get a specific recipe by ID curl "https://trmnl.com/recipes/16382.json" # Response for list endpoint { "data": [{ "id": 49610, "user_id": 1158, "name": "Weather Chum", "published_at": "2025-05-14T05:32:00.000Z", "icon_url": "https://trmnl-public.s3.us-east-2.amazonaws.com/icon.png", "screenshot_url": "https://trmnl.s3.us-east-2.amazonaws.com/screenshot.png", "custom_fields": [ { "keyname": "user_location", "field_type": "string", "name": "Weather Location", "placeholder": "New York, NY", "required": true } ], "stats": {"installs": 1, "forks": 1230} }], "total": 12, "per_page": 25, "current_page": 1, "next_page_url": "/recipes?page=2&search=weather&sort_by=popularity" } ``` -------------------------------- ### Handle Plugin Uninstallation Webhook (Bash) Source: https://github.com/usetrmnl/api-docs/blob/master/plugin-marketplace/plugin-uninstallation-flow.md This snippet demonstrates how to interpret the HTTP headers and JSON body of a plugin uninstallation webhook sent by TRMNL. It assumes a bash environment for receiving and parsing the request. ```bash HEADER_AUTH="Authorization: Bearer " HEADER_CONTENT_TYPE="Content-Type: application/json" # Example of receiving and parsing the webhook payload # In a real scenario, you would use a web framework to capture the POST request. # Assuming the payload is received and stored in a variable called webhook_payload # webhook_payload = '{"user_uuid": "uuid-of-the-user"}' # Extract user_uuid from the JSON payload USER_UUID=$(echo "$webhook_payload" | jq -r '.user_uuid') if [ -n "$USER_UUID" ]; then echo "Received uninstallation request for user: $USER_UUID" # Perform teardown operations here else echo "Failed to parse user_uuid from webhook payload." fi ``` -------------------------------- ### Generate BMP3 Image using ImageMagick Source: https://github.com/usetrmnl/api-docs/blob/master/diy/imagemagick-guide.md Converts an input PNG image to a TRMNL-compatible BMP3 format. It uses ImageMagick to apply monochrome conversion, reduce colors to 2, set bit depth to 1, and strip metadata before saving as BMP3. The 'identify' command verifies the output format. ```bash magick input.png -monochrome -colors 2 -depth 1 -strip bmp3:output.bmp magick identify output.bmp ```