Settings¶

The settings are the saved preferences of your AWTRIX - brightness, colors, clock and date formatting, transitions, volume, and the look of the built-in apps. There are 40 keys, all camelCase, all readable and writable through one endpoint.

Settings survive a reboot. Durations are integer milliseconds, colors are "#RRGGBB" on the way out and accept several forms on the way in, and a Content-Type sent on a write must be application/json. These hold across the whole API and are defined once under Conventions.

Reading the settings¶

curl http://<awtrix-ip>/api/v1/settings

{
  "autoBrightness": false,
  "brightness": 120,
  "autoTransition": true,
  "textColor": "#FFFFFF",
  "transitionEffect": "Rain",
  "transitionDurationMs": 1000,
  "appDurationMs": 7000,
  "timeMode": 1,
  "timeColor": null,
  "buzzerVolume": 80,
  "gamma": 1.9,
  "colorCorrection": null
}

(abbreviated - the real response carries all 40 keys)

Every value round-trips: what GET returns is exactly what PATCH accepts.

Updating settings¶

PATCH takes any subset of the keys. Omitted keys are left alone.

curl -X PATCH http://<awtrix-ip>/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"brightness": 200, "transitionEffect": "Fade", "timeSeparatorMode": "pulse"}'

The whole payload is validated first, before anything is written. If any single key is invalid the request is rejected with 422, nothing at all changes, and the response names the first offending field:

{ "error": { "code": "validationFailed", "message": "out of range", "field": "brightness" } }

A PATCH therefore applies completely or not at all - there is no partial write to clean up after a rejected request. Validation stops at that first failure, and it walks your payload's key order, not the order of the tables below: fix the reported field and re-send to discover the next one.

The tables below are the complete set of settings keys. Any other key fails validation with 422 and "message": "unknown field".

A successful PATCH responds 200 with all 40 settings, updated - use that response instead of a follow-up GET. Every change takes effect at once; no setting needs a reboot.

Resetting to defaults¶

curl -X POST http://<awtrix-ip>/api/v1/settings/reset

This erases the stored settings and reboots AWTRIX, which comes back up on the defaults listed in this page. Wi-Fi credentials, the panel wiring, the GPIO map and your scripts are not touched - that is POST /api/v1/device/factory-reset, documented in HTTP API v1.

Brightness¶

When autoBrightness is on, the measured light level sets the brightness and the brightness key is not consulted. The light level is measured and reported either way - see Brightness & sensors.

Panel¶

These four keys change how the matrix looks, not what the apps draw. They apply to everything on the panel at once - apps, icons, notifications, the moodlight and Art-Net frames alike - and they do not change the framebuffer GET /api/v1/display/screen returns.

colorTint is an RGB color, not a Kelvin value. Pass it the tint you want multiplied into every pixel (for example "#FFD6AA" to warm the panel), not 2700. null turns the tint off.

Panel size and wiring - panelWidth, panels, panelStart, panelWiring, panelSerpentine, mirror and rotate - are system configuration, not settings: see Panel and orientation.

Global text¶

scroll¶

Every field is concrete here - this is what a payload inherits when it leaves the matching key out.

PATCH merges field by field, so {"scroll":{"mode":"loop"}} changes the mode and keeps the configured speed. A bare string is shorthand for the mode: {"scroll":"loop"} means the same thing. An unknown field, an unknown value or a negative number is rejected with 422 validationFailed and the offending key in field, such as scroll.speed.

Changing a field here also moves apps that have already been pushed, unless their own payload set that field.

# Continuous marquee everywhere, a little slower than normal
curl -X PATCH http://<awtrix-ip>/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"scroll": {"mode": "loop", "speed": 80}}'

App rotation¶

Auto-rotation needs at least two apps in the list - with a single app there is nothing to rotate to and AWTRIX sits on it regardless of autoTransition.

transitionEffect values¶

A name string, not a number, and it is case-insensitive - "Ripple", "ripple" and "RIPPLE" all select the same transition. There are 22 of them; the names, and what each one looks like, are in Visual reference → Transitions. GET /api/v1/capabilities returns the same list at runtime.

Anything else is rejected with a message that begins must be one of: and then lists the valid names.

curl -X PATCH http://<awtrix-ip>/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"transitionEffect": "Ripple", "transitionDurationMs": 800}'

Which apps rotate¶

No setting decides that. The rotation is one list, set by PUT /api/v1/apps/order, and it treats the five built-ins (Time, Date, Temperature, Humidity, Battery) exactly like a pushed app or a script: name it in the order to keep it, omit it to switch it off. Until an order has ever been set, everything AWTRIX has rotates. See Pushed apps - Reordering, switching off and duplicating.

Humidity and Battery need the hardware: on a board with no humidity element or no battery pin, the app does not exist at all - it is absent from GET /api/v1/apps and cannot be ordered into the loop. See Power & battery.

The keys below shape those apps once they are on screen; they never add or remove one.

Clock app¶

timeMode styles¶

Only these seven exist; anything outside the range is rejected with 422 "out of range".

The narrow layouts cannot fit everything: timeMode 1–4 reserve the left nine columns for the calendar box and force timeShowSeconds and timeShowAmPm off, and modes 5 and 6 ignore both entirely. Those keys keep their stored values and read back unchanged - they simply have no effect in those modes.

Clock text¶

These shape the time string in timeMode 0–4, and - where they fit - the big clock.

A dropped timeShowAmPm is not an error: the key keeps its stored value and is simply not rendered.

timeSeparatorMode values¶

Case-insensitive, exactly one of:

The colon keeps its width even while invisible, so the digits never shift as it blinks.

Date text¶

These shape the built-in Date app.

All three enum values are case-insensitive. Day and month numbers are always two digits.

With dateOrder: "dayMonthYear", dateSeparator: "dot" and dateYearMode: "none", the date renders with a trailing dot - 31.12. - which is the correct German short form. No other combination adds one.

# Sat 31/12/2026
curl -X PATCH http://<awtrix-ip>/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"dateShowWeekday": true, "dateSeparator": "slash",
       "dateYearMode": "fourDigit"}'

Weekday bar¶

The seven-segment bar drawn under (or over) the clock and the date.

weekdayBar¶

Every field is concrete here. A segment is colored on two independent axes - weekend or workday, today or not - which is what the four colors cover.

PATCH merges field by field, so {"weekdayBar":{"weekendDays":["friday","saturday"]}} moves the weekend and leaves the other six fields alone. An unknown field, a wrong type or a weekday name that is not one of the seven is rejected with 422 validationFailed and the offending key in field, such as weekdayBar.weekendDays or weekdayBar.startOnMonday - the whole request is refused and nothing is applied.

Weekend membership is decided on the calendar day, not on the column number, so startOnMonday never changes which days are weekend. weekendDays is read back in calendar order, Sunday first.

The two weekend colors start out identical to the two workday colors, so the bar looks uniform until you set them yourself.

# A Friday/Saturday weekend, picked out in amber
curl -X PATCH http://<awtrix-ip>/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"weekdayBar": {"weekendDays": ["friday", "saturday"],
                      "weekendActiveColor": "#FFAA00",
                      "weekendInactiveColor": "#664400"}}'

weekdayBar.show is not the same setting as dateShowWeekday: the first draws the seven-segment bar, the second prefixes a three-letter weekday name to the date text.

Sensor apps¶

Sound¶

mp3Volume and radioVolume drive the same amplifier but are applied per source, so a station turned down to sit in the background does not also turn down the doorbell.

With soundEnabled: false, sound and melody commands are still accepted and answered with a success response - they simply produce no sound. A mute is not an error. The switch covers one-shot sounds only: a stream is something you asked for out loud, a notification arrives uninvited. See Sound.

Buttons¶

Value types¶

Colors¶

Colors come back as uppercase "#RRGGBB". On input, every color key accepts any of the forms listed under Conventions → Colors - "RRGGBB", "#RGB" shorthand, [r, g, b], ["HSV", h, s, v], or a packed integer.

Two kinds of color key exist:

• Required colors - textColor, calendarHeaderColor, calendarTextColor, calendarBodyColor and all four colors inside weekdayBar. A null is rejected with 422.
• Nullable colors - timeColor, dateColor, temperatureColor, humidityColor, batteryColor (where null means inherit textColor) and colorCorrection, colorTint (where null means off). All seven default to null.

Both extremes round-trip. "#000000" on a nullable text color is stored as black and reads back as "#000000", not null; "#FFFFFF" on colorCorrection or colorTint is stored as white and reads back as "#FFFFFF", which looks the same as off because white multiplies every channel by 1. Only an explicit JSON null means inherit textColor or correction off.

# Give the clock its own color, and let the date fall back to textColor again
curl -X PATCH http://<awtrix-ip>/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"timeColor": "#00AAFF", "dateColor": null}'

Name strings¶

transitionEffect, timeSeparatorMode, dateOrder, dateSeparator and dateYearMode are name strings, never numbers, and all of them resolve case-insensitively - "pulse", "Pulse" and "PULSE" are the same value. GET /api/v1/capabilities lists the spelling of transitionEffect; the other four are spelled out in the tables on this page. In every case it is the spelling GET /api/v1/settings returns. Passing a number gives you the same error as passing a wrong name:

curl -X PATCH http://<awtrix-ip>/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"timeSeparatorMode": 1}'

{ "error": { "code": "validationFailed",
             "message": "must be one of: steady blink pulse",
             "field": "timeSeparatorMode" } }

The weekday names in weekdayBar.weekendDays are the exception: they are matched exactly, in lowercase.

Numbers¶

Integer keys reject JSON floats and booleans - {"brightness": 120.5} and {"brightness": true} both fail with "must be an integer". gamma is the one key that takes a fractional number; it accepts a plain integer too, so 2 is a valid gamma.

An upper bound of 2147483647 is the platform integer maximum rather than a meaningful ceiling.

Validation errors¶

Every failure is a 422 with the standard error body and the offending key in field. Unknown keys are rejected too, so a typo fails loudly rather than being ignored - and nothing in the body is applied. A body that is not valid JSON fails earlier, with 400 invalidJson.

Every message this route produces: Errors - PATCH /api/v1/settings.