### POST /oauth/token

Source: https://docs.trmnl.com/go/plugin-marketplace/plugin-installation-flow

Exchanges an authorization code for an access token to authenticate the plugin installation.

```APIDOC
## POST /oauth/token

### Description
Exchanges the authorization code received during the installation request for an access token required for subsequent API calls.

### Method
POST

### Endpoint
https://trmnl.com/oauth/token

### Parameters
#### Request Body
- **code** (string) - Required - The unique token received from the initial installation request.
- **client_id** (string) - Required - Your plugin's unique client identifier.
- **client_secret** (string) - Required - Your plugin's secret key.
- **grant_type** (string) - Required - Must be 'authorization_code'.

### Request Example
{
  "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 token used to authenticate API requests.

#### Response Example
{
  "access_token": "your-access-token-string"
}
```

--------------------------------

### Setup API

Source: https://docs.trmnl.com/go/diy/byos

This endpoint is used to set up a BYOS device. It requires the device's MAC address as an ID header.

```APIDOC
## POST /api/setup

### Description
This endpoint is used to set up a BYOS device. It requires the device's MAC address as an ID header.

### Method
POST

### Endpoint
https://byos.local/api/setup

### Parameters
#### Headers
- **ID** (string) - Required - The MAC address of the device.
- **Content-Type** (string) - Required - application/json

### Request Example
```shell
curl "https://byos.local/api/setup" \
    -H 'ID: <device_mac_address>' \
    -H 'Content-Type: application/json'
```

### Response
#### Success Response (200)
- **message** (string) - A success message indicating the setup was completed.

#### Response Example
```json
{
  "message": "Setup complete"
}
```
```

--------------------------------

### POST /installation_success_webhook_url

Source: https://docs.trmnl.com/go/plugin-marketplace/plugin-installation-flow

Endpoint to receive a notification from TRMNL once the user has successfully finished the plugin installation process.

```APIDOC
## POST /installation_success_webhook_url

### Description
TRMNL sends a POST request to this endpoint to notify your server that the plugin installation is complete, providing user details and the plugin setting ID.

### Method
POST

### Endpoint
[installation_success_webhook_url]

### Parameters
#### Request Body
- **user** (object) - Required - Contains user profile information including name, email, timezone, and plugin_setting_id.

### Request Example
{
  "user": {
    "name": "Ronak J",
    "email": "ronak@trmnl.com",
    "plugin_setting_id": 1234,
    "uuid": "674c9d99-cea1-4e52-9025-9efbe0e30901"
  }
}

### Response
#### Success Response (200)
- **status** (string) - Confirmation of receipt.
```

--------------------------------

### Setup Device API Endpoint

Source: https://docs.trmnl.com/go/diy/byos

Initializes the device connection. Requires the device's MAC address in the ID header to register the hardware with the local server.

```shell
curl "https://byos.local/api/setup" \
    -H 'ID: <device_mac_address>' \
    -H 'Content-Type: application/json'
```

--------------------------------

### Success Webhook Notification Body (JSON)

Source: https://docs.trmnl.com/go/plugin-marketplace/plugin-installation-flow

This JSON structure represents the data payload received by the `installation_success_webhook_url` when a user successfully installs a plugin. It includes user details such as name, email, locale, time zone, and a unique `plugin_setting_id` for referencing the installation.

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

--------------------------------

### Fetch Access Token using HTTParty (Ruby)

Source: https://docs.trmnl.com/go/plugin-marketplace/plugin-installation-flow

This snippet demonstrates how to request an access token from TRMNL using the provided client credentials and the installation token. It utilizes the HTTParty gem for making the POST request to the TRMNL OAuth token endpoint. The response contains the 'access_token' required for subsequent API interactions.

```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']
```

--------------------------------

### Manage Plugin Data via Webhooks

Source: https://docs.trmnl.com/go/private-plugins/webhooks

Examples of using cURL to interact with the TRMNL API. This includes setting new content, retrieving existing variables, and applying merge strategies.

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

```bash
curl "https://trmnl.com/api/custom_plugins/asdfqwerty1234"
```

```bash
curl "https://trmnl.com/api/custom_plugins/asdfqwerty1234" \
  -H "Content-Type: application/json" \
  -d '{"merge_variables": {"sensor": {"temperature": 42}}, "merge_strategy": "deep_merge"}' \
  -X POST
```

```bash
curl "https://trmnl.com/api/custom_plugins/asdfqwerty1234" \
  -H "Content-Type: application/json" \
  -d '{"merge_variables": {"temperatures": [40, 42]}, "merge_strategy": "stream", "stream_limit": 10}' \
  -X POST
```

--------------------------------

### Retrieve Recipe Details via JSON API

Source: https://docs.trmnl.com/go/public-api/recipes-api

Fetches a single recipe record by its ID. The response includes the recipe name, icon, screenshot URL, author bio, custom configuration fields, and installation statistics.

```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",
    "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.",
      "category": "calendar,life"
    },
    "custom_fields": [
      {
        "keyname": "message",
        "field_type": "string",
        "name": "Message",
        "default": "%date",
        "help_text": "%date to display current date"
      }
    ],
    "stats": {
      "installs": 25,
      "forks": 176
    }
  }
}
```

--------------------------------

### Receive TRMNL Screen Generation Request

Source: https://docs.trmnl.com/go/plugin-marketplace/plugin-screen-generation-flow

Example of the POST request sent by the TRMNL server to your plugin's markup URL. It includes an authorization header and a body containing the user UUID and metadata.

```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=<metadata-object>'
```

--------------------------------

### GET /recipes/{id}.json

Source: https://docs.trmnl.com/go/public-api/recipes-api

Retrieves the details of a specific recipe by its unique identifier.

```APIDOC
## GET /recipes/{id}.json

### Description
Retrieves detailed information about a specific recipe, including metadata, author bio, custom fields, and installation statistics.

### Method
GET

### Endpoint
/recipes/{id}.json

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the recipe.

### Request Example
https://trmnl.com/recipes/16382.json

### Response
#### Success Response (200)
- **data** (object) - The recipe details object.

#### Response Example
{
  "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",
    "stats": {
      "installs": 25,
      "forks": 176
    }
  }
}
```

--------------------------------

### Generate 2-bit Grayscale PNG Image

Source: https://docs.trmnl.com/go/diy/imagemagick-guide

Creates an experimental 2-bit grayscale image for TRMNL devices with fast refresh support. Requires generating a custom color palette map before converting the source image.

```bash
magick -size 4x1 xc:#000000 xc:#555555 xc:#aaaaaa xc:#ffffff +append -type Palette colormap-2bit.png
```

```bash
magick input.jpeg -resize 800x480! -dither FloydSteinberg -remap colormap-2bit.png -define png:bit-depth=2 -define png:color-type=0 output.png
```

--------------------------------

### GET /api/display

Source: https://docs.trmnl.com/go/private-api/introduction

This endpoint retrieves image and other content for your device to store or render. It can be accessed with or without a TRMNL device using an API key.

```APIDOC
## GET /api/display

### Description
Retrieves image and other content for your device to store or render. This endpoint can be accessed with or without a TRMNL device using an API key.

### Method
GET

### Endpoint
/api/display

### Parameters
#### Request Headers
- **ID** (string) - Required - The device ID.
- **Access-Token** (string) - Required - The API access token.

### Request Example
```json
{
  "ID": "XX:XX:XX:XX",
  "Access-Token": "2r--SahjsAKCFksVcped2Q"
}
```

### Response
#### Success Response (200)
- **image_url** (string) - The URL of the image.
- **filename** (string) - The filename for the content.
- **update_firmware** (boolean) - Indicates if firmware update is required.

#### Response Example
```json
{
  "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
}
```
```

--------------------------------

### Generate 1-bit PNG Image with ImageMagick

Source: https://docs.trmnl.com/go/diy/imagemagick-guide

Converts an input image to a 1-bit PNG format, supporting both standard monochrome and Floyd-Steinberg dithering. Use this for standard black and white display requirements.

```bash
magick input.png -monochrome -colors 2 -depth 1 -strip png:output.png
```

```bash
magick input.png -dither FloydSteinberg -remap pattern:gray50 -depth 1 -strip png:output.png
```

```bash
magick identify output.png
```

--------------------------------

### Recipes API JSON Response Structure

Source: https://docs.trmnl.com/go/public-api/recipes-api

An example of the JSON response returned by the /recipes.json endpoint. It includes metadata about the result set and a list of recipe objects containing details like ID, name, and custom configuration fields.

```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",
      "author_bio": null,
      "custom_fields": [
        {
          "keyname": "user_location",
          "field_type": "string",
          "name": "Weather Location",
          "placeholder": "New York, NY",
          "description": "Choose a location",
          "required": true
        }
      ],
      "stats": {
        "installs": 1,
        "forks": 1230
      }
  }],
  "total": 12,
  "per_page": 25,
  "current_page": 1
}
```

--------------------------------

### Fetch Display Content via GET /api/display

Source: https://docs.trmnl.com/go/private-api/introduction

This snippet demonstrates the request structure for the TRMNL display API. It requires an ID and Access-Token in the headers and returns a JSON object containing the image URL, filename, and firmware update status.

```http
GET /api/display

# request headers
ID: XX:XX:XX:XX
Access-Token: 2r--SahjsAKCFksVcped2Q

# response body
{
  "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
}
```

--------------------------------

### GET /api/custom_plugins/{uuid}

Source: https://docs.trmnl.com/go/private-plugins/webhooks

Retrieves the current merge variables stored for a specific private plugin instance.

```APIDOC
## GET /api/custom_plugins/{uuid}

### Description
Fetches the existing merge variables currently associated with the specified private plugin instance.

### Method
GET

### Endpoint
https://trmnl.com/api/custom_plugins/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The unique identifier for your plugin instance.

### Request Example
curl "https://trmnl.com/api/custom_plugins/asdfqwerty1234"

### Response
#### Success Response (200)
- **merge_variables** (object) - The current variables stored for the plugin.

#### Response Example
{
  "merge_variables": {
    "text": "Hello World"
  }
}
```

--------------------------------

### Authenticate and Fetch Devices via TRMNL API

Source: https://docs.trmnl.com/go/private-api/account

Demonstrates the structure of a GET request to the devices endpoint and the expected JSON response. Authentication requires a bearer token provided in the Authorization header.

```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
    }
  ]
}
```

--------------------------------

### Generate BMP3 Image with ImageMagick

Source: https://docs.trmnl.com/go/diy/imagemagick-guide

Converts an input image to a 1-bit monochrome BMP3 format suitable for TRMNL devices. Includes the identify command to verify the output file properties.

```bash
magick input.png -monochrome -colors 2 -depth 1 -strip bmp3:output.bmp
```

```bash
magick identify output.bmp
```

--------------------------------

### TRMNL Display API JSON Response

Source: https://docs.trmnl.com/go/diy/byod-s

The TRMNL web server generates PNG images and responds to device pings with a JSON object containing the absolute URL of the next image in the queue. This is a key part of the server quickstart for BYOD/S configurations.

```json
{
  "image_url":"https://trmnl.s3.us-east-2.amazonaws.com/path-to-img.png"
}
```

--------------------------------

### Search and List Recipes via HTTP

Source: https://docs.trmnl.com/go/public-api/recipes-api

Demonstrates how to construct a URL to search for recipes and retrieve the results in JSON format. The API supports optional query parameters for filtering and sorting.

```HTTP
# search for "weather"
https://trmnl.com/recipes?search=weather&sort-by=newest

# in JSON format
https://trmnl.com/recipes.json?search=weather&sort-by=newest
```

--------------------------------

### Display API

Source: https://docs.trmnl.com/go/diy/byos

This endpoint retrieves display information for a BYOS device. It requires the device's MAC address as an ID header.

```APIDOC
## GET /api/display

### Description
This endpoint retrieves display information for a BYOS device. It requires the device's MAC address as an ID header.

### Method
GET

### Endpoint
http://byos.local/api/display

### Parameters
#### Headers
- **ID** (string) - Required - The MAC address of the device.
- **Content-Type** (string) - Required - application/json

### Request Example
```bash
curl "http://byos.local/api/display" \
     -H 'ID: <device_mac_address>' \
     -H 'Content-Type: application/json'
```

### Response
#### Success Response (200)
- **display_info** (object) - An object containing display-related information.
  - **resolution** (string) - The display resolution (e.g., "1920x1080").
  - **brightness** (integer) - The current brightness level (0-100).

#### Response Example
```json
{
  "display_info": {
    "resolution": "1920x1080",
    "brightness": 80
  }
}
```
```

--------------------------------

### POST /api/partners

Source: https://docs.trmnl.com/go/partners-api/provisioning-devices

Generates a unique coupon code for a customer and associates custom plugin data for device provisioning.

```APIDOC
## POST /api/partners

### Description
Generates a coupon code for a customer and saves plugin configuration data to be pre-loaded onto a device upon activation.

### Method
POST

### Endpoint
/api/partners

### Parameters
#### Request Body
- **partner.action** (string) - Required - Must be "provision_discount"
- **partner.data** (object) - Required - Key/value pairs containing plugin credentials or configuration variables
- **partner.meta.expires_at** (string) - Optional - Expiration date in YYYY-MM-DD format

### Request Example
{
  "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) - HTTP status code
- **data.code** (string) - The generated coupon code or null if quota is reached

#### Response Example
{
  "status": 200,
  "data": { "code": "acme-123456789" }
}
```

--------------------------------

### Requesting a Provision Discount Coupon (API)

Source: https://docs.trmnl.com/go/partners-api/provisioning-devices

This API request is used by partners to initiate the provisioning of a custom plugin on a customer's device. It requires specific headers and a JSON body containing action, data, and meta information. The response includes a generated coupon code.

```JSON
POST /api/partners

Headers: 
Client-ID, Access-Token # provided by TRMNL team

Body:
{
  partner: {
    action: "provision_discount",
    data: { "user-data": "goes here", "more-data": "also ok" },
    meta: { "expires_at": "2025-03-20" } # will expire at 23:59 EST on this date
  }
}
```

```JSON
# response example
{
  status: 200,
  data: {
    code: "acme-123456789"
  }
}
```

--------------------------------

### Retrieve Logs API Endpoint

Source: https://docs.trmnl.com/go/diy/byos

Fetches diagnostic logs from the device. Requires the device MAC address header for authentication and identification.

```bash
curl "http://byos.local/api/log" \
     -H 'ID: <device_mac_address>' \
     -H 'Content-Type: application/json'
```

--------------------------------

### Logs API

Source: https://docs.trmnl.com/go/diy/byos

This endpoint retrieves logs for a BYOS device. It requires the device's MAC address as an ID header.

```APIDOC
## GET /api/log

### Description
This endpoint retrieves logs for a BYOS device. It requires the device's MAC address as an ID header.

### Method
GET

### Endpoint
http://byos.local/api/log

### Parameters
#### Headers
- **ID** (string) - Required - The MAC address of the device.
- **Content-Type** (string) - Required - application/json

### Request Example
```bash
curl "http://byos.local/api/log" \
     -H 'ID: <device_mac_address>' \
     -H 'Content-Type: application/json'
```

### Response
#### Success Response (200)
- **logs** (array) - An array of log entries.
  - **timestamp** (string) - The timestamp of the log entry.
  - **level** (string) - The log level (e.g., "INFO", "ERROR").
  - **message** (string) - The log message.

#### Response Example
```json
{
  "logs": [
    {
      "timestamp": "2023-10-27T10:00:00Z",
      "level": "INFO",
      "message": "Device started successfully."
    },
    {
      "timestamp": "2023-10-27T10:05:00Z",
      "level": "WARN",
      "message": "Low battery detected."
    }
  ]
}
```
```

--------------------------------

### Create a Full-Layout TRMNL Plugin Template

Source: https://docs.trmnl.com/go/private-plugins/templates

A foundational HTML structure for a full-screen TRMNL plugin. It includes the necessary CSS and JavaScript dependencies and demonstrates the required class-based layout structure.

```html
<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="https://trmnl.com/css/latest/plugins.css">
    <script src="https://trmnl.com/js/latest/plugins.js"></script>
  </head>
  <body class="environment trmnl">
    <div class="screen">
      <div class="view view--full">
        <div class="layout">
          <div class="columns">
            <div class="column">
              <div class="markdown">
                <span class="title">Motivational Quote</span>
                <div class="content content--center">“I love inside jokes. I hope to be a part of one someday.”</div>
                <span class="label label--underline">Michael Scott</span>
              </div>
            </div>
          </div>
        </div>
        
        <div class="title_bar">
          <img class="image" src="https://trmnl.com/images/plugins/trmnl--render.svg" />
          <span class="title">Plugin Title</span>
          <span class="instance">Instance Title</span>
        </div>
      </div>
    </div>
  </body>
</html>
```

--------------------------------

### List Devices

Source: https://docs.trmnl.com/go/private-api/account

Retrieves a list of all devices associated with your account. This endpoint requires authentication.

```APIDOC
## GET /api/devices

### Description
Retrieves a list of all devices associated with your account.

### Method
GET

### Endpoint
/api/devices

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **data** (array) - A list of device objects.
  - **id** (integer) - The unique identifier for the device.
  - **name** (string) - The name of the device.
  - **friendly_id** (string) - A user-friendly identifier for the device.
  - **mac_address** (string) - The MAC address of the device.
  - **battery_voltage** (float) - The current battery voltage of the device.
  - **rssi** (integer) - The Received Signal Strength Indicator (RSSI) of the device's connection.

#### Response Example
```json
{
  "data": [
    {
      "id": 123456,
      "name": "My TRMNL",
      "friendly_id": "A1B2C3",
      "mac_address": "AB:CD:EF:12:34:56",
      "battery_voltage": 3.9,
      "rssi": -41
    }
  ]
}
```
```

--------------------------------

### List Recipes

Source: https://docs.trmnl.com/go/public-api/recipes-api

Retrieves a list of recipes based on specified query parameters. This endpoint is currently in alpha and may be subject to change.

```APIDOC
## GET /recipes.json

### Description
Retrieves a list of recipes with options to filter and sort the results. This endpoint is in alpha testing and may be moved or changed before the end of 2025.

### Method
GET

### Endpoint
/recipes.json

### Parameters
#### Query Parameters
- **search** (string) - Optional - Name of the recipe (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 recipe objects.
  - **id** (integer) - The unique identifier for the recipe.
  - **user_id** (integer) - The ID of the recipe author.
  - **name** (string) - The name of the recipe.
  - **published_at** (string) - The publication date and time of the recipe in ISO 8601 format.
  - **icon_url** (string) - URL to the recipe's icon.
  - **screenshot_url** (string) - URL to a screenshot of the recipe.
  - **author_bio** (string) - The author's biography (can be null).
  - **custom_fields** (array) - An array of custom fields associated with the recipe.
    - **keyname** (string) - The internal key name for the custom field.
    - **field_type** (string) - The type of the custom field (e.g., 'string', 'select').
    - **name** (string) - The display name of the custom field.
    - **placeholder** (string) - Placeholder text for input fields.
    - **description** (string) - Description of the custom field.
    - **help_text** (string) - Additional help text for the custom field.
    - **required** (boolean) - Indicates if the field is required.
    - **options** (array) - List of options for select field types.
    - **default** (string) - Default value for the field.
  - **stats** (object) - Statistics related to the recipe.
    - **installs** (integer) - Number of times the recipe has been installed.
    - **forks** (integer) - Number of times the recipe has been forked.
- **total** (integer) - The total number of recipes available.
- **from** (integer) - The starting index of the current page of results.
- **to** (integer) - The ending index of the current page of results.
- **per_page** (integer) - The number of recipes per page.
- **current_page** (integer) - The current page number.
- **prev_page_url** (string) - URL to the previous page of results (null if none).
- **next_page_url** (string) - URL to the next page of results (null if none).

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

--------------------------------

### Define and Render Reusable Liquid Templates

Source: https://docs.trmnl.com/go/reusing-markup

Custom Liquid templates (partials/components) can be defined and reused within the same context using the `{% template %}` and `{% render %}` tags. This enables modularity and avoids repeating markup chunks.

```liquid
<!-- shared markup -->
{% template say_hello %}
Hello there, {{ name }}.
{% endtemplate %}

<!-- view markup -->
{% render "say_hello", name: "General Kenobi" %}
```

--------------------------------

### Fetch and Advance Display Content

Source: https://docs.trmnl.com/go/private-api/screens

Retrieves the next item in the device playlist and advances the queue. Requires an access token in the header; the response includes an image URL and device configuration settings.

```bash
curl https://trmnl.com/api/display --header "access-token:xxxxxx"
```

--------------------------------

### Render Highcharts Line Chart in TRMNL Markup

Source: https://docs.trmnl.com/go/private-plugins/templates-advanced

This snippet demonstrates how to include Highcharts and Chartkick via CDN and initialize a logarithmic line chart within a TRMNL screen layout. It requires the script tags to be included in the plugin markup field to render the visualization.

```html
<script src="https://code.highcharts.com/highcharts.js"></script>
<script src="https://cdn.jsdelivr.net/npm/chartkick@5.0.1/dist/chartkick.min.js"></script>
<div class="screen">
  <div class="layout">
    <div id="container"></div>
  </div>
</div>
<script>
Highcharts.chart("container", {
    title: {
        text: "Chart demo"
    },
    credits: { enabled: false },
    xAxis: {
        tickInterval: 1,
        type: "logarithmic"
    },
    yAxis: {
        type: "logarithmic",
        minorTickInterval: 0.1,
    },
    tooltip: {
        headerFormat: "<b>{series.name}</b><br />",
        pointFormat: "x = {point.x}, y = {point.y}"
    },
    series: [{
        data: [1, 2, 4, 8, 16, 32, 64, 128, 256, 512],
        pointStart: 1
    }]
});
</script>
```

--------------------------------

### Update Display API Endpoint

Source: https://docs.trmnl.com/go/diy/byos

Triggers a display update on the TRMNL device. The request must include the device MAC address to target the correct hardware.

```bash
curl "http://byos.local/api/display" \
     -H 'ID: <device_mac_address>' \
     -H 'Content-Type: application/json'
```

--------------------------------

### Handle Plugin Uninstallation Webhook

Source: https://docs.trmnl.com/go/plugin-marketplace/plugin-uninstallation-flow

This snippet demonstrates how to parse the JSON payload from the TRMNL uninstallation webhook. It expects a POST request with specific headers and a JSON body containing the user's UUID. This is crucial for implementing server-side teardown logic.

```bash
POST /your-webhook-endpoint HTTP/1.1
Host: your-server.com
Authorization: Bearer <access_token>
Content-Type: application/json

{"user_uuid": "uuid-of-the-user"}
```

```json
{
  "user_uuid": "uuid-of-the-user"
}
```

--------------------------------

### Current screen

Source: https://docs.trmnl.com/go/private-api/screens

This endpoint mirrors the content currently showing on an official TRMNL or BYOD device. It is primarily intended for consumption by the TRMNL Chrome extension.

```APIDOC
## GET /api/current_screen

### Description
Retrieves the currently displayed content on a TRMNL device.

### Method
GET

### Endpoint
https://trmnl.com/api/current_screen

### Parameters
#### Headers
- **access-token** (string) - Required - Your API Key obtained from Devices > Edit.

### Request Example
```bash
curl https://trmnl.com/api/current_screen --header "access-token:xxxxxx"
```

### Response
#### Success Response (200)
- **status** (integer) - Status code, typically 200.
- **refresh_rate** (integer) - The refresh rate for content updates in seconds.
- **image_url** (string) - URL of the currently displayed image content.
- **filename** (string) - The filename of the currently displayed image.
- **rendered_at** (string or null) - Timestamp indicating when the content was rendered, if available.

#### Response Example
```json
{
 "status": 200,
 "refresh_rate": 1800,
 "image_url": "https://trmnl.com/rails/active_storage/blobs/redirect/hash-here/plugin-YYYY-MM-DD-TXX-XX-XXZ-hash",
 "filename": "plugin-YYYY-MM-DD-TXX-XX-XXZ-hash",
 "rendered_at": null
}
```
```

--------------------------------

### Server Response Markup Structure

Source: https://docs.trmnl.com/go/plugin-marketplace/plugin-screen-generation-flow

The required JSON response format for the plugin server, containing HTML markup for different screen layouts such as full screen, half-horizontal, half-vertical, and quadrant.

```json
{
   "markup":"<div class=\"view view--full\"><div class=\"layout\"><div class=\"columns\"><div class=\"column\"><div class=\"markdown gap--large\"><span class=\"title\">Daily Scripture</span><div class=\"content-element content content--center\">Hello</div><span class=\"label label--underline mt-4\">World</span></div></div></div></div><div>",
   "markup_half_horizontal":"<div class=\"view view--half_horizontal\">Your content</div>",
   "markup_half_vertical":"<div class=\"view view--half_vertical\">Your content</div>",
   "markup_quadrant":"<div class=\"view view--quadrant\">Your content</div>",
   "shared":""
}
```

--------------------------------

### Prepend Shared Markup for CSS/JS

Source: https://docs.trmnl.com/go/reusing-markup

Shared markup is prepended to every view layout before rendering, allowing common JS and CSS resources to be defined in one place. This avoids copy-pasting resources across multiple layouts.

```liquid
<!-- shared markup -->
<style>
.shout { text-transform: uppercase; }
</style>

<!-- view markup -->
<span class="shout">Brawndo! It's got what plants crave!</span>
```

--------------------------------

### POST /plugin_markup_url

Source: https://docs.trmnl.com/go/plugin-marketplace/plugin-screen-generation-flow

TRMNL sends a POST request to your configured endpoint to fetch the HTML markup required to render the plugin screen.

```APIDOC
## POST /plugin_markup_url

### Description
TRMNL triggers this request at the user-defined refresh frequency. Your server must return the appropriate HTML markup for the requested layout.

### Method
POST

### Endpoint
[Your configured plugin_markup_url]

### Parameters
#### Request Body (x-www-form-urlencoded)
- **user_uuid** (string) - Required - The unique identifier for the user's plugin connection.
- **trmnl** (string) - Required - A JSON-encoded string containing user, device, and system metadata.

### Request Example
```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={"user":{...},"device":{...}}'
```

### Response
#### Success Response (200)
- **markup** (string) - HTML for full screen layout.
- **markup_half_horizontal** (string) - HTML for half horizontal layout.
- **markup_half_vertical** (string) - HTML for half vertical layout.
- **markup_quadrant** (string) - HTML for quadrant layout.
- **shared** (string) - Optional shared content.

#### Response Example
{
  "markup": "<div class=\"view view--full\">...</div>",
  "markup_half_horizontal": "<div class=\"view view--half_horizontal\">...</div>",
  "markup_half_vertical": "<div class=\"view view--half_vertical\">...</div>",
  "markup_quadrant": "<div class=\"view view--quadrant\">...</div>",
  "shared": ""
}
```

--------------------------------

### POST /api/custom_plugins/{uuid}

Source: https://docs.trmnl.com/go/private-plugins/webhooks

Updates the merge variables for a specific private plugin instance.

```APIDOC
## POST /api/custom_plugins/{uuid}

### Description
Updates the content of a private plugin by sending a payload to the webhook URL. Supports standard updates, deep_merge, and stream strategies.

### Method
POST

### Endpoint
https://trmnl.com/api/custom_plugins/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The unique identifier for your plugin instance.

#### Request Body
- **merge_variables** (object) - Required - The key/value pairs to be stored.
- **merge_strategy** (string) - Optional - Strategy for merging data: 'deep_merge' or 'stream'.
- **stream_limit** (integer) - Optional - Maximum number of items to keep in arrays when using the 'stream' strategy.

### Request Example
{
  "merge_variables": {"text": "Hello World"},
  "merge_strategy": "deep_merge"
}

### Response
#### Success Response (200)
- **status** (string) - Confirmation of the update.

#### Response Example
{
  "status": "success"
}
```

--------------------------------

### Retrieve Current Screen Content

Source: https://docs.trmnl.com/go/private-api/screens

Fetches the currently displayed content without advancing the playlist. Primarily intended for mirroring content on secondary devices like tablets or Raspberry Pi units.

```bash
curl https://trmnl.com/api/current_screen --header "access-token:xxxxxx"
```

--------------------------------

### POST /uninstallation_webhook_url

Source: https://docs.trmnl.com/go/plugin-marketplace/plugin-uninstallation-flow

TRMNL sends a POST request to your specified uninstallation webhook URL when a user uninstalls your plugin. This notification is in JSON format and contains the user's UUID.

```APIDOC
## POST /uninstallation_webhook_url

### Description
TRMNL sends a POST request to your specified `uninstallation_webhook_url` when a user uninstalls your plugin. This webhook allows you to perform necessary cleanup or teardown operations on your server.

### Method
POST

### Endpoint
`uninstallation_webhook_url` (provided by your plugin configuration)

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - `application/json`

#### Request Body
- **user_uuid** (string) - Required - The unique identifier of the user who uninstalled the plugin.

### Request Example
```json
{
  "user_uuid": "uuid-of-the-user"
}
```

### Response
#### Success Response (200)
This endpoint typically does not require a specific response body, but a 200 OK status code indicates successful receipt of the webhook.

#### Response Example
(No specific response body required, but a 200 OK status is expected)
```

--------------------------------

### Auto advance content

Source: https://docs.trmnl.com/go/private-api/screens

This endpoint is used by TRMNL firmware to fetch new screen content. Making a request to this endpoint automatically advances the Playlist to the next item in the queue.

```APIDOC
## GET /api/display

### Description
Fetches the next content item in the playlist and advances the device's queue.

### Method
GET

### Endpoint
https://trmnl.com/api/display

### Parameters
#### Headers
- **access-token** (string) - Required - Your API Key obtained from Devices > Edit.

### Request Example
```bash
curl https://trmnl.com/api/display --header "access-token:xxxxxx"
```

### Response
#### Success Response (200)
- **status** (integer) - Status code. 202 if no user_id is attached to the device.
- **image_url** (string) - URL of the image content to display.
- **image_name** (string) - Name of the image file.
- **update_firmware** (boolean) - Indicates if firmware update is available.
- **firmware_url** (string or null) - URL for firmware update, if applicable.
- **refresh_rate** (string) - The refresh rate for content updates in seconds.
- **reset_firmware** (boolean) - Indicates if a firmware reset is required.

#### Response Example
```json
{
  "status": 0,
  "image_url": "https://trmnl.s3.us-east-2.amazonaws.com/path-to-img.png",
  "image_name": "plugin-YYYY-MM-DD-TXX-XX-XXZ-hash",
  "update_firmware": false,
  "firmware_url": null,
  "refresh_rate": "1800",
  "reset_firmware": false
}
```
```