Documentation

API reference and setup guide

API Endpoints
TRMNL BYOS implements the standard BYOS API specification

Setup Endpoint

Register or update a device. Called when device first connects or firmware updates.

# Request
curl -X POST "http://localhost:3000/api/setup" \
-H "ID: YOUR_DEVICE_ID" \
-H "Content-Type: application/json" \
-d 'firmware_version": "1.0.0'

Display Endpoint

Get the current screen to display. Returns image URL and refresh rate.

# Request
curl -X GET "http://localhost:3000/api/display" \
-H "ID: YOUR_DEVICE_ID"
# Response
{
"image_url": "http://localhost:3000/api/render?device_id=...",
"refresh_rate": 300
}

Log Endpoint

Send device logs to the server for monitoring and debugging.

# Request
curl -X POST "http://localhost:3000/api/log" \
-H "ID: YOUR_DEVICE_ID" \
-H "Content-Type: application/json" \
-d 'message": "Screen updated'
Device Configuration
How to configure your TRMNL device

1. Set API Endpoint

Configure your TRMNL device to use this server:

http://localhost:3000

2. Device ID

Your device will automatically register with its unique ID when it first connects. You can then manage it from the dashboard.

3. Create Screens

Once your device is registered, create screens in the dashboard to display content. Screens can be clock, weather, quotes, or custom content.

Screen Types
Available screen templates

Clock

Display current time and date in a clean, readable format

Weather

Show temperature, conditions, and location

Quote

Display inspirational quotes with attribution

Custom

Create your own custom content with configurable styling