Settings¶

Settings are your saved preferences: brightness, colors, clock and date format, transitions, volume, and the look of the built-in apps. This page lists every settings key.

Settings survive a restart. Durations are whole milliseconds. Colors come back as "#RRGGBB" and can be sent in several forms. If you send a Content-Type, it must be application/json. These rules apply to the whole API and are described once under Conventions.

Restoring a backup skips settings that this clock does not have.

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,
  "volume": 60,
  "gamma": 1.9,
  "colorCorrection": null
}

(shortened – the real response contains all settings keys)

You can send back exactly what GET returns: every value GET returns is accepted by PATCH.

Updating settings¶

Send any subset of the keys with PATCH. Keys you leave out stay as they are.

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

AWTRIX checks the whole request before it changes anything. If one key is not valid, it answers 422, nothing changes, and the answer names the first wrong key:

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

So a PATCH is applied completely or not at all. AWTRIX reports only the first problem, in the order of the keys in your request. Fix it and send again to find the next one.

The tables below list every settings key. Any other key is rejected with 422 and "message": "unknown field".

A successful PATCH answers 200 with all settings, already updated – you do not need a second GET. Every change takes effect at once; no setting needs a restart.

Resetting to defaults¶

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

This deletes the stored settings and restarts AWTRIX with the defaults listed on this page. Wi-Fi, display wiring, pin map and your scripts stay. To reset everything, use POST /api/v1/device/factory-reset – see HTTP API.

Brightness¶

With autoBrightness on, the measured light sets the brightness and brightness is ignored. The light level is measured and reported in both cases – see Brightness & sensors. On a device without a light sensor (sensors.light is false in GET /api/v1/capabilities) you can still set and read autoBrightness, but the display always uses brightness.

Color¶

These four keys change how the whole display looks – apps, icons, notifications, the mood light and Art-Net alike. They do not change the picture that GET /api/v1/display/screen returns.

colorTint is an RGB color, not a Kelvin value. To make the display warmer, send for example "#FFD6AA", not 2700. null switches the tint off.

What each of these looks like on the display is described under Display colors.

Panel size and wiring – panelWidth, panels, panelStart, panelWiring, panelColorOrder, panelSerpentine, mirror and rotate – are part of the system configuration, not settings. See Panel and orientation.

Global text¶

scroll¶

These are the values a payload uses when it leaves out the matching field.

PATCH changes only the fields you send: {"scroll":{"mode":"loop"}} changes the mode and keeps the speed. A plain string sets only the mode: {"scroll":"loop"} means the same. An unknown field, an unknown value or a negative number is rejected with 422 validationFailed, and field names the key, for example scroll.speed.

A change here also affects apps you have already pushed, unless their payload set that field.

# Continuous scrolling 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¶

The apps rotate only when there are at least two in the list. With one app, AWTRIX stays on it whatever autoTransition says.

transitionEffect values¶

A name, not a number. Upper and lower case do not matter – "Ripple", "ripple" and "RIPPLE" are the same. There are 22 transitions; their names and what they look like are in Visual reference → Transitions. GET /api/v1/capabilities returns the same list.

Any other value is rejected with a message that starts with 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", "transitionDirection": "reverse", "transitionDurationMs": 800}'

With normal, automatic and Next transitions move in their usual direction. reverse flips that movement; Previous always moves the other way. Transitions without a direction, such as Fade, look the same either way.

Which apps rotate¶

No setting decides that. The rotation is one list, set with PUT /api/v1/apps/order. Built-in apps (Time, Date, Temperature, Humidity, Battery) are treated exactly like pushed apps and scripts: order sets the order, and disabled switches an app off. Enabled apps missing from order are added at the end. Until you change it, all available apps rotate. See Pushed apps – Reordering, switching off and duplicating.

Humidity and Battery need the hardware. On a board without a humidity sensor or without a battery pin, the app does not exist: it is missing from GET /api/v1/apps and cannot be added to the rotation. See Power & battery.

The keys below change how these apps look. They never add or remove an app.

Clock app¶

timeMode styles¶

Only these seven exist. Any other number is rejected with 422 "out of range".

Not everything fits in every style. timeMode 1–4 use the left nine columns for the calendar box, so seconds and AM/PM are not shown there. Modes 5 and 6 also ignore timeShowSeconds and timeShowAmPm. The keys keep their stored values; they simply have no effect in these modes.

Clock text¶

These keys format the time in timeMode 0–4 and, where there is room, on the big clock.

If AM/PM is not shown for one of these reasons, that is not an error: the key keeps its value.

timeSeparatorMode values¶

Upper and lower case do not matter. One of:

The colon keeps its space while it is dark, so the digits do not move.

Date text¶

These keys format the built-in Date app.

Upper and lower case do not matter for the three name values. Day and month always have two digits.

With dateOrder: "dayMonthYear", dateSeparator: "dot" and dateYearMode: "none", the date ends with a dot – 31.12. – the usual 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 row of seven small segments below (or above) the clock and the date, one per weekday.

weekdayBar and dateWeekdayBar¶

Each segment is either a workday or a weekend day, and either today or not. The four colors cover these four cases.

PATCH changes only the fields you send: {"weekdayBar":{"weekendDays":["friday","saturday"]}} moves the weekend and keeps the other six fields. An unknown field, a wrong type or a day name that is not one of the seven is rejected with 422 validationFailed, and field names the key, for example weekdayBar.weekendDays or weekdayBar.startOnMonday. Nothing in the request is applied.

startOnMonday never changes which days are weekend. weekendDays is always returned in calendar order, Sunday first.

The weekend colors start with the same values as the workday colors, so the bar looks the same for all days until you change them.

# A Friday/Saturday weekend, shown 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"}}'

dateWeekdayBar.show is not the same as dateShowWeekday: the first shows the segment bar in Date, the second puts a weekday name in front of the date text.

Sensor apps¶

Sound¶

The clock has one master volume and three groups. Who plays a sound decides its group:

• radio: every internet radio station.
• app: everything a script plays.
• alert: notification sounds, POST /api/v1/audio/play and cmd/audio/play.

What you hear is volume × group volume / 100. With volume at 50 and alertVolume at 60, an alert plays at 30. A change applies at once, also to sounds that are playing. 0 is silence, and volume: 0 silences every sound.

The web UI shows the four volumes as the Mixer on the Audio tab. The Radio slider shows only when the clock can play radio: the I2S pins are set and the board has PSRAM.

curl -X PATCH http://<awtrix-ip>/api/v1/settings \
  -H 'Content-Type: application/json' \
  -d '{"volume":50,"alertVolume":40}'

See Sound.

Buttons¶

Value types¶

Colors¶

Colors come back as uppercase "#RRGGBB". When you send a color, you can use any form listed under Conventions → Colors: "RRGGBB", "#RGB", [r, g, b], ["HSV", h, s, v], or a number.

There are two kinds of color keys:

• Required colors – textColor, calendarHeaderColor, calendarTextColor, calendarBodyColor and the four colors in weekdayBar. null is rejected with 422.
• Optional colors – timeColor, dateColor, temperatureColor, humidityColor, batteryColor (null means use textColor) and colorCorrection, colorTint (null means off). All seven default to null.

Black and white are real colors, not "unset". "#000000" on an optional text color is stored as black and read back as "#000000", not null. "#FFFFFF" on colorCorrection or colorTint is stored as white and looks the same as off, because white changes nothing. Only JSON null means use textColor or off.

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

Name strings¶

transitionEffect, transitionDirection, timeSeparatorMode, dateOrder, dateSeparator and dateYearMode take names, never numbers. Upper and lower case do not matter – "pulse", "Pulse" and "PULSE" are the same. GET /api/v1/capabilities lists the names for transitionEffect; the others are in the tables on this page. GET /api/v1/settings always returns that spelling. A number gets the same error as 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 day names in weekdayBar.weekendDays are different: they must be lowercase, exactly as listed.

Numbers¶

Integer keys reject decimals and booleans – {"brightness": 120.5} and {"brightness": true} both fail with "must be an integer". gamma is the only key that takes a decimal number. It also accepts a whole number, so 2 is a valid gamma.

An upper limit of 2147483647 just means "no real limit".

Validation errors¶

Every problem is answered with 422, the standard error body and the wrong key in field. Unknown keys are rejected too, so a typo fails instead of being silently ignored – and nothing in the request is applied. A request that is not valid JSON gets 400 invalidJson.

All messages this route can return: Errors – PATCH /api/v1/settings.

Related¶

• Conventions – color formats and rules for the whole API
• Visual reference – transitions, effects and how the display colors look
• System configuration – Wi-Fi, MQTT, time zone, display wiring and other device keys
• Brightness & sensors
• Sound