### Setup API Response

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

This is an example JSON response from the setup API endpoint, containing an API key, friendly ID, image URL, and a welcome message.

```json
{
  "api_key": "<redacted>",
  "friendly_id": "ABC123",
  "image_url": "https://localhost:2443/assets/setup.bmp",
  "message": "Welcome to TRMNL BYOS"
}
```

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

### Setup Terminus for Local Development

Source: https://github.com/usetrmnl/terminus/blob/main/README.adoc

Clone the Terminus repository and run the setup script to prepare for local development. The setup script is idempotent.

```bash
git clone https://github.com/usetrmnl/terminus
cd terminus
bin/setup
```

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

### Setup Terminus with Docker

Source: https://github.com/usetrmnl/terminus/blob/main/doc/docker.adoc

Clone the Terminus repository and run the Docker setup script. Ensure you have Docker and Docker Compose installed.

```bash
git clone https://github.com/usetrmnl/terminus
cd terminus
bin/setup docker
```

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

### Firmware POST Response Example

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Example JSON response after successfully creating firmware.

```json
{
  "data": {
    "id": 10,
    "version": "2.0.0",
    "kind": "terminus",
    "file_name": "2.0.0.bin",
    "mime_type": "application/octet-stream",
    "size": 1225536,
    "uri": "/uploads/0c2f5a1acb23d20e9f72828254c4f258.bin",
    "created_at": "2026-01-12T22:32:08+00:00",
    "updated_at": "2026-01-12T22:32:09+00:00"
  }
}
```

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

### Models GET Response Example

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Example JSON response for retrieving all models.

```json
# All models.
{
  "data": [
    {
      "default_palette_id": 1,
      "id": 1,
      "name": "v2",
      "label": "TRMNL X",
      "description": "TRMNL X",
      "kind": "trmnl",
      "mime_type": "image/png",
      "colors": 16,
      "bit_depth": 4,
      "rotation": 0,
      "offset_x": 0,
      "offset_y": 0,
      "scale_factor": 1.8,
      "css": {
        "classes": {
          "size": "screen--lg",
          "device": "screen--v2",
          "density": "screen--density-2x"
        },
        "variables": [
          [
            "--screen-w",
            "1040px"
          ],
          [
            "--screen-h",
            "780px"
          ],
          [
            "--pixel-ratio",
            "1.8"
          ],
          [
            "--dither-pixel-ratio",
            "2.0"
          ],
          [
            "--ui-scale",
            "1.0"
          ],
          [
            "--gap-scale",
            "1.0"
          ]
        ]
      },
      "width": 1872,
      "height": 1404,
      "created_at": "2026-02-12T15:57:28+00:00",
      "updated_at": "2026-04-01T20:09:35+00:00"
    }
  ]
}
```

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

### Start Development Server

Source: https://github.com/usetrmnl/terminus/blob/main/README.adoc

Starts the development server with a specific port step and procfile. The 'assets' and 'migrate' processes are allowed to die.

```bash
overmind start --port-step 10 --procfile Procfile.dev --can-die assets,migrate
```

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

### Start Production Server

Source: https://github.com/usetrmnl/terminus/blob/main/README.adoc

Starts the production server with a specific port step. The 'assets' and 'migrate' processes are allowed to die.

```bash
overmind start --port-step 10 --can-die assets,migrate
```

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

### Setup Endpoint

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Used for new device setup (auto-provisioning) only. The device still hits this endpoint but, once auto-provisioned, is ignored by the server.

```APIDOC
## POST /api/setup

### Description
Used for new device setup (auto-provisioning) only. The device still hits this endpoint but, once auto-provisioned, is ignored by the server.

### Method
POST

### Endpoint
/api/setup
```

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

### Setup API

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Initiates the setup process for the TRMNL BYOS service. Requires an 'ID' header and returns API key, friendly ID, and image URL.

```APIDOC
## GET /api/setup/

### Description
Initiates the setup process for the TRMNL BYOS service. Requires an 'ID' header and returns API key, friendly ID, and image URL.

### Method
GET

### Endpoint
/api/setup/

### Request Example
```bash
curl "https://localhost:2443/api/setup/" \
     -H 'ID: <redacted>' \
     -H 'Content-Type: application/json'
```

### Response
#### Success Response (200)
- **api_key** (string) - The generated API key.
- **friendly_id** (string) - A user-friendly identifier.
- **image_url** (string) - URL to an image related to the setup.
- **message** (string) - A welcome message.

#### Response Example
```json
{
  "api_key": "<redacted>",
  "friendly_id": "ABC123",
  "image_url": "https://localhost:2443/assets/setup.bmp",
  "message": "Welcome to TRMNL BYOS"
}
```
```

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

### Firmware PATCH Response Example

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Example JSON response after successfully updating firmware.

```json
{
  "data": {
    "id": 10,
    "version": "2.0.0",
    "kind": "terminus",
    "file_name": "2.0.0.bin",
    "mime_type": "application/octet-stream",
    "size": 1225536,
    "uri": "/uploads/31c6151dfa9362053022a9bfcab5b2b5.bin",
    "created_at": "2026-01-12T22:32:08+00:00",
    "updated_at": "2026-01-12T22:32:42+00:00"
  }
}
```

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

### Setup API Endpoint

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

This snippet shows how to make a curl request to the setup API endpoint. It includes necessary headers for authentication and content type.

```bash
curl "https://localhost:2443/api/setup/" \
     -H 'ID: <redacted>' \
     -H 'Content-Type: application/json'
```

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

### Get Screens GET Response

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

This is an example response for retrieving screens. It returns an array of screen objects, each with its ID, model ID, label, name, and creation timestamp.

```json
{
  "data": [
    {
      "id": 3,
      "model_id": 1,
      "label": "Moon",
      "name": "plugin-6e6740",
      "created_at": "2025-07-29T16:29:02+00:00"
    }
  ]
}
```

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

### Get All Models

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Retrieves a list of all available device models.

```bash
# All models.
curl "https://localhost:2443/api/models" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json'
```

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

### Interact with Repositories

Source: https://github.com/usetrmnl/terminus/blob/main/doc/development.adoc

Example of using the Hanami repository to fetch and view device data within the console.

```ruby
# Use a repository.
repository = Hanami.app["repositories.device"]

repository.all              # View all devices.
device = repository.find 1  # Find by Device ID.
```

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

### Get Screens GET Request

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Use this endpoint to retrieve a list of all screens. This request does not require a body.

```bash
curl "https://localhost:2443/api/screens" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json'
```

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

### Get All Firmware

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Retrieves a list of all firmware records. Returns an empty array if no firmware exists.

```bash
curl "https://localhost:2443/api/firmware" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json'
```

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

### Configure Terminus as a service

Source: https://github.com/usetrmnl/terminus/blob/main/doc/raspberry_pi.adoc

Use this script to clone the Terminus repository and run the setup process within a service configuration.

```bash
#! /usr/bin/env bash

set -o errexit
set -o nounset
set -o pipefail
IFS=$'\n\t'

git clone https://github.com/usetrmnl/terminus
cd terminus
bin/setup docker
```

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

### Get Firmware Records (GET Request)

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Use this endpoint to retrieve firmware records. You can fetch all records or a single record by its ID.

```bash
# All records.
curl "https://localhost:2443/api/firmware" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json'

# Single record.
curl "https://localhost:2443/api/firmware/1" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json'
```

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

### Configure sensor support as a service

Source: https://github.com/usetrmnl/terminus/blob/main/doc/raspberry_pi.adoc

This script installs necessary I2C dependencies, compiles the SCD41 driver, and initializes the sensor scanner.

```bash
#! /usr/bin/env bash

set -o errexit
set -o nounset
set -o pipefail
IFS=$'\n\t'

cd "$HOME"

sudo apt-get install libi2c-dev
sudo raspi-config nonint do_i2c 0

git clone https://github.com/bitbank2/bb_scd41 scd41

(
  cd scd41/Linux
  make
)

git clone https://github.com/usetrmnl/sensor_scanner

(
  cd sensor_scanner
  make
  sensor2json "$HOME/terminus/public/sensors.json" &
)
```

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

### Quick Start Terminus with Docker

Source: https://github.com/usetrmnl/terminus/blob/main/README.adoc

Use this script to quickly spin up Terminus on your local machine using Docker. Note that this script is not idempotent and is intended for exploration only.

```bash
curl https://raw.githubusercontent.com/usetrmnl/terminus/refs/heads/main/scripts/docker/quick.sh | bash
```

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

### Launch Terminus via SSH

Source: https://github.com/usetrmnl/terminus/blob/main/doc/raspberry_pi.adoc

Commands to connect to the Raspberry Pi and start the Terminus Docker container.

```bash
ssh admin@demo.local
cd terminus
docker compose up
```

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

### Create Playlist POST Response

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

This is an example of a successful response after creating a playlist. It includes the playlist's ID, name, label, current item, mode, timestamps, and the list of items with their details.

```json
{
  "data": {
    "id": 1,
    "name": "demo",
    "label": "Demo",
    "current_item_id": 39,
    "mode": "automatic",
    "created_at": "2026-03-05T00:14:56+00:00",
    "updated_at": "2026-03-05T00:14:56+00:00",
    "items": [
      {
        "id": 39,
        "screen_id": 15,
        "position": 1,
        "created_at": "2026-03-05T00:14:56+00:00",
        "updated_at": "2026-03-05T00:14:56+00:00"
      },
      {
        "id": 40,
        "screen_id": 16,
        "position": 2,
        "created_at": "2026-03-05T00:14:56+00:00",
        "updated_at": "2026-03-05T00:14:56+00:00"
      }
    ]
  }
}
```

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

### Launch Development Docker Compose Stack

Source: https://github.com/usetrmnl/terminus/blob/main/doc/docker.adoc

Starts the Terminus development environment using Docker Compose and the 'compose.dev.yml' file.

```bash
docker-compose --file compose.dev.yml up
```

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

### POST /api/models

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Creates a new model with the provided details. All attributes shown in the example are supported for creation.

```APIDOC
## POST /api/models

### Description
Creates a new model with the provided details. All attributes shown in the example are supported for creation. The `default_palette_id` key is optional.

### Method
POST

### Endpoint
/api/models

### Parameters
#### Request Body
- **model** (object) - Required - The model object containing attributes to create.
  - **default_palette_id** (integer) - Optional - The ID of the default palette.
  - **name** (string) - Required - The name of the model.
  - **label** (string) - Required - The label of the model.
  - **description** (string) - Optional - A description of the model.
  - **mime_type** (string) - Required - The MIME type of the model.
  - **bit_depth** (integer) - Required - The bit depth of the model.
  - **colors** (integer) - Required - The number of colors in the model.
  - **css** (object) - Optional - CSS configurations for the model.
    - **classes** (object) - Optional - CSS classes.
  - **scale_factor** (number) - Optional - The scale factor of the model.
  - **rotation** (integer) - Optional - The rotation of the model in degrees.
  - **offset_x** (integer) - Optional - The X offset of the model.
  - **offset_y** (integer) - Optional - The Y offset of the model.
  - **width** (integer) - Optional - The width of the model.
  - **height** (integer) - Optional - The height of the model.

### Request Example
```bash
curl -X "POST" "https://localhost:2443/api/models" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json' \
     -d $'{ 
  "model": { 
    "default_palette_id": 1, 
    "name": "demo", 
    "label": "Demo", 
    "description": "A demonstration.", 
    "mime_type": "image/png", 
    "bit_depth": 2, 
    "colors": 4, 
    "css": {"classes" => {"size" => "screen--md"}}, 
    "scale_factor": 1.5, 
    "rotation": 90, 
    "offset_x": 10, 
    "offset_y": 15, 
    "width": 800, 
    "height": 480 
  } 
}'
```

### Response
#### Success Response (200)
- **data** (object) - The created model object.
  - **default_palette_id** (integer) - The ID of the default palette.
  - **id** (integer) - The unique identifier of the model.
  - **name** (string) - The name of the model.
  - **label** (string) - The label of the model.
  - **description** (string) - A description of the model.
  - **kind** (string) - The kind of model.
  - **mime_type** (string) - The MIME type of the model.
  - **colors** (integer) - The number of colors in the model.
  - **bit_depth** (integer) - The bit depth of the model.
  - **rotation** (integer) - The rotation of the model in degrees.
  - **offset_x** (integer) - The X offset of the model.
  - **offset_y** (integer) - The Y offset of the model.
  - **scale_factor** (number) - The scale factor of the model.
  - **css** (object) - CSS configurations for the model.
    - **classes** (object) - CSS classes.
  - **width** (integer) - The width of the model.
  - **height** (integer) - The height of the model.
  - **created_at** (string) - The timestamp when the model was created.
  - **updated_at** (string) - The timestamp when the model was last updated.

#### Response Example
```json
{
  "data": {
    "default_palette_id": 1,
    "id": 1,
    "name": "demo",
    "label": "Demo",
    "description": "A demonstration.",
    "kind": "terminus",
    "mime_type": "image/png",
    "colors": 4,
    "bit_depth": 2,
    "rotation": 25,
    "offset_x": 10,
    "offset_y": 15,
    "scale_factor": 1.5,
    "css": {
      "classes": {
        "size": "screen-md"
      }
    },
    "width": 800,
    "height": 480,
    "created_at": "2026-04-01T23:55:12+00:00",
    "updated_at": "2026-04-01T23:55:12+00:00"
  }
}
```
```

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

### Launch Production Docker Compose Stack

Source: https://github.com/usetrmnl/terminus/blob/main/doc/docker.adoc

Starts the Terminus production environment using Docker Compose and the 'compose.yml' file.

```bash
docker-compose up
```

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

### Display API Response

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Example response sent back to the device, which also allows changing device behavior.

```json
{
  "filename": "demo.bmp",
  "firmware_url": "http://localhost:2443/assets/firmware/1.4.8.bin",
  "firmware_version": "1.4.8",
  "image_url": "https://localhost:2443/assets/screens/A1B2C3D4E5F6/demo.bmp",
  "image_url_timeout": 0,
  "refresh_rate": 130,
  "reset_firmware": false,
  "special_function": "sleep",
  "update_firmware": false
}
```

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

### Get Single Model

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Retrieves a specific device model by its ID.

```bash
# Single model.
curl "https://localhost:2443/api/models/1" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json'
```

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

### GET /api/firmware

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Retrieves a list of all available firmware records. This endpoint is useful for checking available firmware versions and their details.

```APIDOC
## GET /api/firmware

### Description
Retrieves a list of all available firmware records. This endpoint is useful for checking available firmware versions and their details.

### Method
GET

### Endpoint
/api/firmware

### Response
#### Success Response (200)
- **data** (array) - An array of firmware objects.
  - **id** (integer) - The unique identifier for the firmware record.
  - **version** (string) - The firmware version string.
  - **kind** (string) - The type or source of the firmware (e.g., 'trmnl').
  - **file_name** (string) - The name of the firmware file.
  - **mime_type** (string) - The MIME type of the firmware file.
  - **size** (integer) - The size of the firmware file in bytes.
  - **uri** (string) - The URI or path to the firmware file.
  - **created_at** (string) - The timestamp when the firmware record was created.
  - **updated_at** (string) - The timestamp when the firmware record was last updated.

#### Response Example
```json
{
  "data": [
    {
      "id": 1,
      "version": "1.7.2",
      "kind": "trmnl",
      "file_name": "1.7.2.bin",
      "mime_type": "application/octet-stream",
      "size": 1306608,
      "uri": "/uploads/60a5253edd0ab53cc31619a836c6cdb8.bin",
      "created_at": "2026-01-08T21:26:34+00:00",
      "updated_at": "2026-01-08T21:26:34+00:00"
    }
  ]
}
```
```

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

### Get Playlists GET Request

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Retrieve all playlists or a single playlist by its ID.

```bash
# All playlists
curl "https://localhost:2443/api/playlists" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json'

# Single playlist.
curl "https://localhost:2443/api/playlists/1" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json'
```

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

### GET /api/firmware/{id}

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Retrieves a specific firmware record by its ID. This allows you to get detailed information about a particular firmware version.

```APIDOC
## GET /api/firmware/{id}

### Description
Retrieves a specific firmware record by its ID. This allows you to get detailed information about a particular firmware version.

### Method
GET

### Endpoint
/api/firmware/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the firmware record to retrieve.

### Response
#### Success Response (200)
- **data** (object) - The firmware object.
  - **id** (integer) - The unique identifier for the firmware record.
  - **version** (string) - The firmware version string.
  - **kind** (string) - The type or source of the firmware (e.g., 'trmnl').
  - **file_name** (string) - The name of the firmware file.
  - **mime_type** (string) - The MIME type of the firmware file.
  - **size** (integer) - The size of the firmware file in bytes.
  - **uri** (string) - The URI or path to the firmware file.
  - **created_at** (string) - The timestamp when the firmware record was created.
  - **updated_at** (string) - The timestamp when the firmware record was last updated.

#### Response Example
```json
{
  "data": {
    "id": 1,
    "version": "1.7.2",
    "kind": "trmnl",
    "file_name": "1.7.2.bin",
    "mime_type": "application/octet-stream",
    "size": 1306608,
    "uri": "/uploads/60a5253edd0ab53cc31619a836c6cdb8.bin",
    "created_at": "2026-01-08T21:26:34+00:00",
    "updated_at": "2026-01-08T21:26:34+00:00"
  }
}
```
```

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

### Create Firmware

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Creates a new firmware record. Requires version, kind, and URI. The response includes the created firmware details.

```bash
curl -X "POST" "https://localhost:2443/api/firmware" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json' \
     -d $'{ 
  "firmware": { 
    "version": "2.0.0", 
    "kind": "terminus", 
    "uri": "https://demo.terminus.io/2.0.0.bin" 
  } 
}'
```

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

### GET /api/playlists

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Retrieves a list of all playlists.

```APIDOC
## GET /api/playlists

### Description
Retrieves a list of all playlists.

### Method
GET

### Endpoint
/api/playlists

### Request Example
```bash
curl "https://localhost:2443/api/playlists" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json'
```

### Response
#### Success Response (200)
- **data** (array) - A list of playlist objects.
  - Each playlist object contains details such as id, name, description, etc. (Specific fields not detailed in source)

#### Response Example
```json
{
  "data": [
    {
      "id": 1,
      "name": "Playlist 1",
      "description": "First playlist"
    },
    {
      "id": 2,
      "name": "Playlist 2",
      "description": "Second playlist"
    }
  ]
}
```
```

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

### List All Devices

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Use this endpoint to retrieve a list of all registered devices. Ensure your Authorization header is correctly set.

```bash
curl "https://localhost:2443/api/devices" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json'
```

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

### GET /api/models

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Retrieves a list of all available models.

```APIDOC
## GET /api/models

### Description
Retrieves a list of all available models.

### Method
GET

### Endpoint
/api/models

### Response
#### Success Response (200)
- **data** (array) - An array of model objects.
  - **default_palette_id** (integer) - The ID of the default color palette for the model.
  - **id** (integer) - The unique identifier for the model.
  - **name** (string) - The name of the model.
  - **label** (string) - A user-friendly label for the model.
  - **description** (string) - A description of the model.
  - **kind** (string) - The kind of the model (e.g., trmnl, terminus).
  - **mime_type** (string) - The MIME type of the model's associated assets.
  - **colors** (integer) - The number of colors supported by the model.
  - **bit_depth** (integer) - The bit depth of the model's display.
  - **rotation** (integer) - The rotation angle of the model's display.
  - **offset_x** (integer) - The X offset for the model's display.
  - **offset_y** (integer) - The Y offset for the model's display.
  - **scale_factor** (number) - The scale factor for the model's display.
  - **css** (object) - CSS information for styling.
    - **classes** (object) - CSS classes for different screen properties.
      - **size** (string) - CSS class for screen size.
      - **device** (string) - CSS class for device type.
      - **density** (string) - CSS class for screen density.
    - **variables** (array) - Array of CSS variables and their values.
  - **width** (integer) - The width of the model's display in pixels.
  - **height** (integer) - The height of the model's display in pixels.
  - **created_at** (string) - The timestamp when the model was created.
  - **updated_at** (string) - The timestamp when the model was last updated.

#### Response Example
```json
{
  "data": [
    {
      "default_palette_id": 1,
      "id": 1,
      "name": "v2",
      "label": "TRMNL X",
      "description": "TRMNL X",
      "kind": "trmnl",
      "mime_type": "image/png",
      "colors": 16,
      "bit_depth": 4,
      "rotation": 0,
      "offset_x": 0,
      "offset_y": 0,
      "scale_factor": 1.8,
      "css": {
        "classes": {
          "size": "screen--lg",
          "device": "screen--v2",
          "density": "screen--density-2x"
        },
        "variables": [
          [
            "--screen-w",
            "1040px"
          ],
          [
            "--screen-h",
            "780px"
          ],
          [
            "--pixel-ratio",
            "1.8"
          ],
          [
            "--dither-pixel-ratio",
            "2.0"
          ],
          [
            "--ui-scale",
            "1.0"
          ],
          [
            "--gap-scale",
            "1.0"
          ]
        ]
      },
      "width": 1872,
      "height": 1404,
      "created_at": "2026-02-12T15:57:28+00:00",
      "updated_at": "2026-04-01T20:09:35+00:00"
    }
  ]
}
```
```

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

### GET /api/models/{id}

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Retrieves a single model by its ID.

```APIDOC
## GET /api/models/{id}

### Description
Retrieves a single model by its ID.

### Method
GET

### Endpoint
/api/models/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the model to retrieve.

### Response
#### Success Response (200)
- **data** (object) - Contains the details of the requested model.
  - **default_palette_id** (integer) - The ID of the default color palette for the model.
  - **id** (integer) - The unique identifier for the model.
  - **name** (string) - The name of the model.
  - **label** (string) - A user-friendly label for the model.
  - **description** (string) - A description of the model.
  - **kind** (string) - The kind of the model (e.g., trmnl, terminus).
  - **mime_type** (string) - The MIME type of the model's associated assets.
  - **colors** (integer) - The number of colors supported by the model.
  - **bit_depth** (integer) - The bit depth of the model's display.
  - **rotation** (integer) - The rotation angle of the model's display.
  - **offset_x** (integer) - The X offset for the model's display.
  - **offset_y** (integer) - The Y offset for the model's display.
  - **scale_factor** (number) - The scale factor for the model's display.
  - **css** (object) - CSS information for styling.
    - **classes** (object) - CSS classes for different screen properties.
      - **size** (string) - CSS class for screen size.
      - **device** (string) - CSS class for device type.
      - **density** (string) - CSS class for screen density.
    - **variables** (array) - Array of CSS variables and their values.
  - **width** (integer) - The width of the model's display in pixels.
  - **height** (integer) - The height of the model's display in pixels.
  - **created_at** (string) - The timestamp when the model was created.
  - **updated_at** (string) - The timestamp when the model was last updated.

#### Response Example
```json
{
  "data": {
    "default_palette_id": 1,
    "id": 1,
    "name": "v2",
    "label": "TRMNL X",
    "description": "TRMNL X",
    "kind": "trmnl",
    "mime_type": "image/png",
    "colors": 16,
    "bit_depth": 4,
    "rotation": 0,
    "offset_x": 0,
    "offset_y": 0,
    "scale_factor": 1.8,
    "css": {
      "classes": {
        "size": "screen--lg",
        "device": "screen--v2",
        "density": "screen--density-2x"
      },
      "variables": [
        [
          "--screen-w",
          "1040px"
        ],
        [
          "--screen-h",
          "780px"
        ],
        [
          "--pixel-ratio",
          "1.8"
        ],
        [
          "--dither-pixel-ratio",
          "2.0"
        ],
        [
          "--ui-scale",
          "1.0"
        ],
        [
          "--gap-scale",
          "1.0"
        ]
      ]
    },
    "width": 1872,
    "height": 1404,
    "created_at": "2026-02-12T15:57:28+00:00",
    "updated_at": "2026-04-01T20:09:35+00:00"
  }
}
```
```

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

### Create Playlist POST Request

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Use this endpoint to create a new playlist. You can specify the name, label, and the screens to include. The response will contain the newly created playlist details.

```bash
curl -X "POST" "https://localhost:2443/api/playlists" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json' \
     -d $'{ \
  "playlist": { \
    "name": "demo", \
    "label": "Demo", \
    "items": [ \
      { \
        "screen_id": "15" \
      }, \
      { \
        "screen_id": "16" \
      } \
    ] \
  } \
}'
```

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

### GET /api/playlists/{id}

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Retrieves details for a single playlist by its ID.

```APIDOC
## GET /api/playlists/{id}

### Description
Retrieves details for a single playlist by its ID.

### Method
GET

### Endpoint
/api/playlists/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the playlist to retrieve.

### Request Example
```bash
curl "https://localhost:2443/api/playlists/1" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json'
```

### Response
#### Success Response (200)
- **data** (object) - The playlist object.
  - **id** (integer) - The unique identifier of the playlist.
  - **name** (string) - The name of the playlist.
  - **description** (string) - A description of the playlist.
  - (Other fields may be present but are not detailed in the source)

#### Response Example
```json
{
  "data": {
    "id": 1,
    "name": "My Awesome Playlist",
    "description": "A collection of great tracks."
  }
}
```
```

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

### POST Response for Screen Creation

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

This is a sample JSON response after successfully creating a screen. It includes details of the created screen, such as its ID, URI, and dimensions.

```json
{
  "data": {
    "id": 13,
    "model_id": 1,
    "label": "Demo",
    "name": "demo",
    "created_at": "2025-07-29T19:06:04+00:00",
    "updated_at": "2025-07-29T19:06:04+00:00",
    "filename": "demo.png",
    "mime_type": "image/png",
    "bit_depth": 1,
    "width": 800,
    "height": 480,
    "size": 415,
    "uri": "/uploads/619415a00830fa630649706977e95302.png"
  }
}
```

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

### POST Request to Create Screen with Unprocessed URI

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Create a new screen using an unprocessed image URI. The system will handle any necessary preprocessing.

```bash
curl -X "POST" "https://localhost:2443/api/screens" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json' \
     -d $'{ 
  "screen": { 
    "model_id": "1", 
    "label": "Demo", 
    "name": "demo", 
    "uri": "https://leonardo.ai/wp-content/uploads/2023/07/image-131.jpeg", 
    "file_name": "demo.png" 
  } 
}'
```

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

### Get Single Device

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Retrieve details for a specific device by its ID. The ID is appended to the /api/devices path.

```bash
curl "https://localhost:2443/api/devices/1" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json'
```

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

### POST Request to Create Screen with HTML Content

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Use this endpoint to create a new screen by providing custom HTML content. This allows for dynamic rendering of HTML, CSS, and JavaScript. Ensure proper styling to avoid unwanted borders.

```bash
curl -X "POST" "https://localhost:2443/api/screens" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json' \
     -d $'{ 
  "screen": { 
    "model_id": "1", 
    "label": "Demo", 
    "name": "demo", 
    "content": "<h1>Demo</h1>", 
    "file_name": "demo.png" 
  } 
}'
```

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

### Create Device (Maximum Fields)

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Use this endpoint to create a new device with all possible fields specified. Ensure all required fields are present in the request body.

```bash
curl -X "POST" "https://localhost:2443/api/devices" \
     -H 'Authorization: <redacted>' \
     -H 'Content-Type: application/json' \
     -d $\'{
  "device": {
    "model_id": 1,
    "playlist_id": 1,
    "label": "Demo",
    "friendly_id": "DEMO11",
    "mac_address": "02:A1:B2:C3:D4:E5",
    "api_key": "OScdcN0kFbKjFcid9Kz6Cx",
    "refresh_rate": 500,
    "image_timeout": 0,
    "firmware_update": true,
    "firmware_version": "1.2.3",
    "battery_charge": 85.0,
    "battery_voltage": -70,
    "wifi": -70,
    "width": 800,
    "height": 480,
    "wake_reason": "Awoken from API.",
    "sleep_start_at": "18:00:00",
    "sleep_stop_at": "06:00:00"
  }
}\'
```

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

### Launch Terminus Server

Source: https://github.com/usetrmnl/terminus/blob/main/README.adoc

Command to launch the Terminus server for local development.

```bash
bin/server
```

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

### Delete Playlist DELETE Response

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

This is an example of a successful response after deleting a playlist. It returns the details of the deleted playlist.

```json
{
  "data": {
    "id": 11,
    "name": "update",
    "label": "Update",
    "current_item_id": null,
    "mode": "manual",
    "created_at": "2026-03-05T00:14:56+00:00",
    "updated_at": "2026-03-05T00:26:44+00:00",
    "items": [
      {
        "id": 51,
        "screen_id": 16,
        "position": 1,
        "created_at": "2026-03-05T00:26:44+00:00",
        "updated_at": "2026-03-05T00:26:44+00:00"
      },
      {
        "id": 52,
        "screen_id": 15,
        "position": 2,
        "created_at": "2026-03-05T00:26:44+00:00",
        "updated_at": "2026-03-05T00:26:44+00:00"
      }
    ]
  }
}
```

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

### Create Device

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Creates a new device with the specified model and playlist IDs.

```APIDOC
## POST /api/devices

### Description
Creates a new device with the specified model and playlist IDs.

### Method
POST

### Endpoint
/api/devices

### Parameters
#### Request Body
- **device** (object) - Required - The device object containing configuration details.
  - **model_id** (integer) - Required - The ID of the device model.
  - **playlist_id** (integer) - Required - The ID of the playlist to associate with the device.

### Request Example
```json
{
  "device": {
    "model_id": 1,
    "playlist_id": 1
  }
}
```
```

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

### Login API Response

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

This is an example JSON response after a successful login, providing an access token and a refresh token.

```json
{
  "access_token": "<redacted>",
  "refresh_token": "1_3_jm6ajAaXyUoaL6cdehXLPKRxvj9RJMmJecA_3p7lmj8",
  "success": "You have been logged in."
}
```

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

### Run Tests

Source: https://github.com/usetrmnl/terminus/blob/main/README.adoc

Executes the test suite for the application.

```bash
bin/rake
```

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

### Deploy Valkey Instance

Source: https://github.com/usetrmnl/terminus/blob/main/doc/kubernetes.adoc

Deploys a Valkey instance as a Deployment and Service for Sidekiq job queue storage.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: terminus-valkey
spec:
  replicas: 1
  selector:
    matchLabels:
      app: terminus-valkey
  template:
    metadata:
      labels:
        app: terminus-valkey
    spec:
      containers:
      - name: valkey
        image: valkey/valkey:8-alpine
        ports:
        - containerPort: 6379
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 512Mi
---
apiVersion: v1
kind: Service
metadata:
  name: terminus-valkey
spec:
  selector:
    app: terminus-valkey
  ports:
  - port: 6379
    targetPort: 6379
```

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

### GET Firmware Response

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

The response to a firmware retrieval request, containing a list of firmware records or a single record's details.

```json
# All records.
{
  "data": [
    {
      "id": 1,
      "version": "1.7.2",
      "kind": "trmnl",
      "file_name": "1.7.2.bin",
      "mime_type": "application/octet-stream",
      "size": 1306608,
      "uri": "/uploads/60a5253edd0ab53cc31619a836c6cdb8.bin",
      "created_at": "2026-01-08T21:26:34+00:00",
      "updated_at": "2026-01-08T21:26:34+00:00"
    }
  ]
}
```

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

### GET /api/screens

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

Retrieves a list of all screens. This endpoint can be used to manage device screens by supplying content for rendering, screenshotting, and grey scaling.

```APIDOC
## GET /api/screens

### Description
Retrieves a list of all screens. This endpoint can be used to manage device screens by supplying content for rendering, screenshotting, and grey scaling.

### Method
GET

### Endpoint
https://localhost:2443/api/screens

### Parameters
#### Query Parameters
- **playlist_id** (integer) - Optional - Ensures your screen is added to an existing playlist.
- **mode** (string) - Optional - Determines the mode in which the screen will be processed. Supported values: 'dither'.
- **file_name** (string) - Optional - Ensures your desired file name is used. If not supplied, the server will generate a UUID for the file name.

### Response
#### Success Response (200)
- **data** (array) - An array of screen objects.
  - **id** (integer) - The unique identifier for the screen.
  - **model_id** (integer) - The ID of the model associated with the screen.
  - **label** (string) - The label of the screen.
  - **name** (string) - The name of the screen.
  - **created_at** (string) - The timestamp when the screen was created.

#### Response Example
{
  "data": [
    {
      "id": 3,
      "model_id": 1,
      "label": "Moon",
      "name": "plugin-6e6740",
      "created_at": "2025-07-29T16:29:02+00:00"
    }
  ]
}
```

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

### Troubleshooting Image Generation Issues

Source: https://github.com/usetrmnl/terminus/blob/main/doc/kubernetes.adoc

Check the logs for the 'sidekiq' container to diagnose image generation failures. Ensure the shared volume is mounted correctly and both containers have write access to the upload directory.

```bash
kubectl logs deployment/terminus --container sidekiq
```

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

### Update Playlist PATCH Response

Source: https://github.com/usetrmnl/terminus/blob/main/doc/api.adoc

This is an example of a successful response after updating a playlist. It reflects the changes made to the playlist's attributes and its items.

```json
{
  "data": {
    "id": 1,
    "name": "update",
    "label": "Update",
    "current_item_id": null,
    "mode": "manual",
    "created_at": "2026-03-05T00:14:56+00:00",
    "updated_at": "2026-03-05T00:26:44+00:00",
    "items": [
      {
        "id": 51,
        "screen_id": 16,
        "position": 1,
        "created_at": "2026-03-05T00:26:44+00:00",
        "updated_at": "2026-03-05T00:26:44+00:00"
      },
      {
        "id": 52,
        "screen_id": 15,
        "position": 2,
        "created_at": "2026-03-05T00:26:44+00:00",
        "updated_at": "2026-03-05T00:26:44+00:00"
      }
    ]
  }
}
```