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 and your scripts stay. To reset everything, use POST /api/v1/device/factory-reset – see HTTP API.

Brightness¶

Color¶

These four keys change how the whole display looks – apps, icons, notifications and the mood light 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.

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 and Status) 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.

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

Clock app¶

Clock faces¶

The clock is made for its 52×16 display. clockFace picks one of five faces:

timeShowSeconds shows seconds on the big face only; next to a sheet there is no room. timeShowAmPm and dateShowWeekday have no effect on the clock faces. The calendar colors paint every sheet. The big face shows the weekday in calendarHeaderColor and the date in dateColor, formatted with dateOrder, dateSeparator, dateYearMode and dateMonthNames. If the date is too wide, it drops the century first, then the year. Weekday and month names are always in capitals, whatever uppercase says.

When the clock appears, the sheet slides in showing yesterday and then falls off to show today. This also happens when the clock comes back after a notification, the mood light or a dark display, and at midnight. Switch off Calendar animation (calendarAnimation) and the sheet shows today right away.

Clock text¶

These keys format the time on the clock faces, where there is room.

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 date on the big clock face.

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 the time, 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"}}'

Sensor apps¶

useCelsius, temperatureColor, humidityColor and batteryColor are in the settings, but have no effect: the clock has no temperature, humidity or battery app.

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, POST /api/v1/audio/clip, the boot sound and the answer of Home Assistant Voice.

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.

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