HTTP API¶

This page lists every HTTP route AWTRIX answers, with its fields, answers and errors.

The rules that apply to every route (camelCase keys, ...Ms durations, the color forms, the Content-Type header and the error body) are on Conventions and are not repeated here.

How to read a route entry¶

Each route below follows the same order:

1. one sentence on what it does,
2. Request: body, path or query values,
3. Response: what a successful call returns,
4. Errors: every status the route can answer besides success,
5. a curl example.

A wrong HTTP method answers 405 methodNotAllowed with the message allowed: <list>. The Errors table of each route names that list. Which check comes first, and the few paths that check their name before the method: Errors → Order of the checks.

Base URL¶

All routes live under http://<awtrix-ip>.

The web port is always 80.

AWTRIX also answers on its mDNS hostname (for example http://awtrix.local). See Find your clock.

Captive-portal redirect (setup mode only)¶

While AWTRIX is in setup mode, a GET or HEAD for a foreign or missing Host answers 302 with Location: http://<apIp>/. This sends captive-portal probes to the setup page. Writes to a foreign or missing host answer 403 forbidden. The hotspot's address, with its HTTP port when needed, is the accepted host. A foreign Origin or Sec-Fetch-Site: cross-site is refused. On the accepted host, GET probes outside /api/ whose paths contain no file extension are also redirected. In normal mode this setup policy does not apply.

Authentication¶

AWTRIX uses HTTP Basic authentication. It is off by default: every request is allowed until you set authEnabled to true in the system configuration. The username and password are authUser and authPass.

In the web UI this is under System › Web server. Type the new password twice: the page saves only when both entries match. The eye button next to a password field shows what you typed.

Once it is on, it applies:

• in every mode, including setup mode, so the setup page can be password protected,
• to everything AWTRIX serves: the API, the web UI at / and the static files.

A request without valid credentials gets:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="AWTRIX NG"
Content-Type: application/json

{"error":{"code":"unauthorized","message":"authentication required"}}

The WWW-Authenticate header makes a browser show its login prompt. The body is the normal JSON error body, never HTML.

For the uploads (/update, /api/v1/files, /api/v1/audio/mp3, /api/v1/restore) the credentials are checked before any file is stored. The answer, including a 401, arrives after the whole upload was sent. When a restore changes the username or password, the next request must use the restored credentials.

In setup mode AWTRIX permits only the setup page, device/setup status reads, Wi-Fi setup, reboot and backup restore. Logs, scripts, file routes, secrets export and firmware upload answer 403 forbidden. See the exact setup allow-list.

curl -u admin:secret http://<awtrix-ip>/api/v1/device

Requests from other web pages¶

A web page on another site, such as the AWTRIX Hub or your own dashboard, can read and control AWTRIX from your browser. Answers carry Access-Control-Allow-Origin: *, and a preflight OPTIONS request answers 204 with the allowed methods and headers and Access-Control-Allow-Private-Network: true.

Five requests read, replace or erase the passwords or the firmware. Only AWTRIX's own web UI and programs that are not browsers, such as curl or Home Assistant, can use them:

• GET /api/v1/system?secrets=1
• PUT /api/v1/system
• POST /api/v1/restore
• POST /update
• POST /api/v1/device/factory-reset

Their answers carry no Access-Control-Allow-Origin. When a page of another site sends one of them (its Origin header names another host, or Sec-Fetch-Site is neither same-origin nor none), AWTRIX answers 403 forbiddenOrigin and changes nothing:

{"error":{"code":"forbiddenOrigin","message":"only from this device's web page"}}

When the web login is on, it is checked first.

Content-Type¶

Send Content-Type: application/json with every JSON body. See Conventions. A PUT or PATCH with a different Content-Type answers 415 unsupportedMediaType. Script source uploads and the uploads listed above use their own formats.

An empty body or {} never clears anything. These three routes answer 422 validationFailed to it:

To remove an app, turn the mood light off or clear an indicator, use the DELETE route (or the empty-payload message over MQTT). For a pushed app that is DELETE /api/v1/apps/{name}. The pushed path itself answers 405 to anything but PUT. See Errors.

Method override¶

Some clients can only send GET and POST: for example the FRITZ!Box HTTP action and some home-automation gateways. For them, AWTRIX accepts this header on a POST:

X-HTTP-Method-Override: PATCH

A missing or empty header changes nothing.

An overridden PATCH or PUT needs Content-Type: application/json like a real one, or it answers 415.

Turn the display off from a client without PATCH:

curl -X POST http://<awtrix-ip>/api/v1/display \
  -H "X-HTTP-Method-Override: PATCH" \
  -H "Content-Type: application/json" \
  -d '{"power":false}'

The uploads /update, /api/v1/files, /api/v1/audio/mp3 and /api/v1/restore do not take the header. A valid override there answers 405 methodNotAllowed, a malformed one 400 invalidMethodOverride. So DELETE /api/v1/files?path=... needs a real DELETE.

Errors¶

Every failed request answers with the error body described in Conventions. All codes, statuses and messages are listed in Errors. Some availability and update errors differ by device.

Status mapping for command routes¶

Routes that change something answer when the change is done:

The one exception is PATCH /api/v1/settings: on success it returns all settings instead of {"ok":true}.

Device¶

GET /api/v1/device¶

Reads the device state and statistics.

Request: no body.

Response: 200 with these keys:

These keys appear only when the hardware is there:

Errors:

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

GET /api/v1/version¶

Reads the firmware version as JSON.

Request: no body.

Response: 200:

{"version":"1.0.12"}

Errors:

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

GET /version¶

Reads the firmware version as plain text, handy for shell scripts and health checks.

Request: no body.

Response: 200 text/plain. The body is only the version string, for example 1.0.12.

Errors: only GET is answered.

curl http://<awtrix-ip>/version

POST /api/v1/device/reboot¶

Restarts AWTRIX.

Request: no body.

Response: 200 {"ok":true}, sent before the restart. To know when AWTRIX is back, poll GET /version until it answers.

Errors:

This route also works in setup mode, like PUT /api/v1/system. The reboot applies the Wi-Fi credentials you wrote there. See Connect to Wi-Fi.

curl -X POST http://<awtrix-ip>/api/v1/device/reboot

POST /api/v1/device/factory-reset¶

Erases everything (settings, device configuration, all files and the Wi-Fi credentials) and restarts in setup mode.

Request: no body. This command exists over HTTP only, not over MQTT.

Response: 200 {"ok":true}, sent before the reset.

Errors:

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

Settings¶

GET /api/v1/settings¶

Reads all settings.

Request: no body.

Response: 200 with every setting of this device, always present. Choice fields come back as their name, colors as "#RRGGBB", and an unset nullable color as null. What each key means: Settings.

Errors:

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

PATCH /api/v1/settings¶

Changes one or more settings.

Request: any subset of the keys from Settings. All keys are checked first. If one is wrong, nothing is changed.

Response: 200 with all settings, as they are after the change: not {"ok":true}.

Errors:

An unknown key is rejected, not ignored: field: "<key>", message unknown field.

See Settings validation for the message returned for each kind of field.

Fields¶

Type, range, default and meaning of every key: Settings. Points that matter when you send them here:

• null on the five per-app *Color fields means use textColor. On colorCorrection and colorTint it means off. Both are the default.
• volume is the master volume, and radioVolume, appVolume and alertVolume are shares of it. 0 is silence. See Sound.
• transitionEffect accepts any upper/lower case: "slide", "Slide" and "SLIDE" are the same. The names are in GET /api/v1/capabilities. The other name fields (transitionDirection, timeSeparatorMode, dateOrder, dateSeparator, dateYearMode) accept any case too. Answers always use one fixed spelling. transitionDirection: "reverse" only reverses the direction of the animation. It never changes the app order.
• scroll sets how text moves on all apps: mode (static · wrap · loop · bounce), direction (left · right), entry (inline · offscreen), whenFits (static · scroll), speed in percent of 21 px/s, gap in pixels and holdMs in milliseconds. Only the fields you send change, so {"scroll":{"mode":"loop"}} keeps the speed. {"scroll":"loop"} is short for the same. A negative number, an unknown value or an unknown field is 422 validationFailed with field naming the key, for example scroll.speed. An app's own scroll overrides this field by field. See Payload → Scrolling.
• weekdayBar sets the weekday bar: show, startOnMonday, weekendDays (lowercase English day names, any subset, [] for no weekend) and four colors: activeColor / inactiveColor for a workday, weekendActiveColor / weekendInactiveColor for a weekend day: "active" is today, "inactive" the other days. The weekend colors start equal to the workday colors. Only the fields you send change, so {"weekdayBar":{"weekendDays":["friday","saturday"]}} leaves the other six alone. An unknown field, a wrong type or an unknown day name is 422 validationFailed with field naming the key, for example weekdayBar.weekendDays. startOnMonday only changes the display order. Which days are weekend days does not change. Do not confuse it with dateShowWeekday, which puts a weekday name in front of the date.

curl -X PATCH http://<awtrix-ip>/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"brightness":80,"autoBrightness":false,"timeColor":"#00FF00"}'

POST /api/v1/settings/reset¶

Resets all settings to their defaults and restarts. The system configuration, such as Wi-Fi and MQTT, stays as it is.

Request: no body.

Response: 200 {"ok":true}, sent before the reset.

Errors:

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

Display¶

GET /api/v1/display¶

Reads the display state: power, brightness, overlay and mood light.

Request: no body.

Response: 200:

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

PATCH /api/v1/display¶

Switches the display on or off and sets a weather overlay for all apps.

Request: all fields optional. If one field is wrong, nothing changes.

overlay accepts any upper/lower case. null or "" removes it. The names (also listed in GET /api/v1/capabilities) are drizzle, frost, rain, snow, storm, thunder.

Response: 200 {"ok":true}.

Errors:

The per-app overlay field of PUT /api/v1/apps/pushed/{name} accepts the same names.

curl -X PATCH http://<awtrix-ip>/api/v1/display \
  -H "Content-Type: application/json" \
  -d '{"power":true,"overlay":"snow"}'

PUT /api/v1/display/moodlight¶

Fills the whole display with one color.

Request: all fields optional, but the body must not be empty.

• If you send both kelvin and color, kelvin wins and color is ignored.
• Both values are kept. A field you leave out keeps its value: {"brightness":30} dims without changing the color, {"color":"#FF0000"} changes the color without changing the brightness.
• The first time, the mood light is white at brightness 120.

Response: 200 {"ok":true}.

Errors:

curl -X PUT http://<awtrix-ip>/api/v1/display/moodlight \
  -H "Content-Type: application/json" \
  -d '{"kelvin":2700,"brightness":90}'

DELETE /api/v1/display/moodlight¶

Turns the mood light off.

Request: no body.

Response: always 200 {"ok":true}.

Errors:

curl -X DELETE http://<awtrix-ip>/api/v1/display/moodlight

GET /api/v1/display/screen¶

Reads the picture currently on the display, pixel by pixel.

Request: no body.

Response: 200:

Each pixel is the color 0xRRGGBB written as a decimal number, not hex.

These are the colors the apps drew. Brightness and the display color settings (saturation, gamma, colorCorrection, colorTint) change what the LEDs show, not what this route returns.

Errors:

curl http://<awtrix-ip>/api/v1/display/screen

Apps¶

All apps are in one list. Each app has a name and an origin that says where it comes from:

Pushed apps and scripts are written through their own routes (/api/v1/apps/pushed/{name} and /api/v1/apps/script/{name}) because they carry different content. Listing, ordering and removing work the same for all apps.

Built-in apps are Time and Status. No setting switches them on or off.

Names¶

Every app name, pushed or script, must match [A-Za-z0-9_-]{1,32}: 1 to 32 letters, digits, _ or -. active, next, previous and order are taken by the routes of the same name and cannot be app names. A wrong name answers 400 invalidName (invalid name, field: "name") before the body is read, and nothing is stored.

The method is checked before the name: PATCH /api/v1/apps/pushed/bad.name answers 405. Only DELETE /api/v1/apps/{name} checks the name first. The paths without a name, /api/v1/apps/pushed/ and /api/v1/apps/script/, are 400 invalidName (not 405) with any method. A PUT to them with a Content-Type other than application/json answers 415 first, because without a name the path is no script upload. All checks in order: Errors → Order of the checks.

A script cannot use the name of a built-in app such as Time: that answers 422 validationFailed with the reason in message, and nothing is stored.

active, next, previous and order are reserved: DELETE /api/v1/apps/next is a 405, not the deletion of an app called next.

GET /api/v1/apps¶

Lists all apps: first the ones you arranged, in that order, then all others.

Request: no body.

Response: 200 with an array. Three keys describe the state of each app: enabled (it runs), inLoop (it is shown in the rotation) and present (it exists on AWTRIX right now). For most apps all three are the same. Two exceptions: a background script (@headless true) runs but is never shown, and a pushed app that was deleted keeps its place until the next push.

icon, import, skipped, config, error and meta are left out, not sent empty, where they do not apply. On a firmware without scripting, skipped, error and meta are never sent, and config only on built-in apps.

A module is listed because it shares the script routes, but it is not an app. Besides origin it has only name, import, error and meta: no enabled, inLoop or slot, because it is never shown. Read, write and delete it under /api/v1/apps/script/{name} like a script. An import name that cannot be used (or that another module or a built-in module already has) answers 422 validationFailed with the reason in message, and nothing is stored.

skipped is not the opposite of inLoop. inLoop: false means the app is not in the rotation at all. skipped: true means the app is in the rotation but declined its last turn. It can change that by itself at any moment.

[
  {"name":"Time","enabled":true,"inLoop":true,"slot":0,"present":true,"origin":"builtin","config":true},
  {"name":"weather","enabled":true,"inLoop":true,"slot":1,"present":true,"origin":"pushed","icon":"1"},
  {"name":"doorbell","enabled":true,"inLoop":false,"slot":2,"present":true,"origin":"script",
   "skipped":false,"headless":true,"config":false,"error":null,
   "meta":{"name":"Doorbell","desc":"","author":"me","version":"1.0","icons":[],"requires":[],
     "needs":[{"name":"audio.rtttl","missing":false}],"display":null}},
  {"name":"co2","enabled":true,"inLoop":false,"slot":3,"present":false,"origin":null},
  {"name":"clock","enabled":false,"inLoop":false,"slot":null,"present":true,"origin":"script",
   "skipped":false,"headless":false,"config":true,"error":null,
   "meta":{"name":"Wall Clock","desc":"","author":"me","version":"1.2","icons":["sun","moon"],
     "requires":[],"needs":[],"display":{"width":64,"height":32,"fits":false}}}
]

Here doorbell runs but is never shown, co2 keeps a place for an app that is not there, and clock is switched off.

The error object¶

This is how a script error looks: here and in the answer to PUT /api/v1/apps/script/{name}.

line and hook are left out when unknown, and often both are: "no draw() method" has neither. A syntax error usually has a line. An error with a hook usually has no line.

{"message":"syntax_error: unexpected token ')'","line":12}
{"message":"runtime_error: operand must be number","hook":"setup"}

Errors:

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

PUT /api/v1/apps/active¶

Shows a specific app now.

Request:

A body that does not start with { is read as the app name itself. A broken JSON body is also read as a name, so it answers 404 app not found, not 400.

The name of an @ondemand script starts it, as picking it in the device menu does. Showing any other app, next or previous ends it again.

Response: 200 {"ok":true}.

Errors:

curl -X PUT http://<awtrix-ip>/api/v1/apps/active \
  -H "Content-Type: application/json" \
  -d '{"name":"Time","fast":true}'

POST /api/v1/apps/next¶

Switches to the next app in the rotation.

Request: no body.

Response: always 200 {"ok":true}.

Errors:

curl -X POST http://<awtrix-ip>/api/v1/apps/next

POST /api/v1/apps/previous¶

Switches back to the previous app.

Request: no body.

Response: always 200 {"ok":true}.

Errors:

curl -X POST http://<awtrix-ip>/api/v1/apps/previous

PUT /api/v1/apps/order¶

Sets which apps are switched on, and the order in which they are shown.

Request: an object with two lists of app names:

disabled is always required. order is optional, but only together with disabled.

disabled is the complete list of switched-off apps. Every app it does not name is switched on, also one that was off before. To switch one app on or off and leave the others as they are, use PUT /api/v1/apps/{name}/enabled.

• Duplicates count in order: list an app twice and it is shown twice per round, each time with its own slot.
• A switched-off script does nothing at all: no loop(), no HTTP or MQTT callbacks. To keep a background script running, put it in order like any other app. The rotation skips it because it never draws.
• A name in order keeps its place even if the app does not exist yet. When the app appears, it takes that place. Any other new app is added after the ordered ones, switched on.
• A name in disabled stays switched off while the app is not there.
• Such names are listed in GET /api/v1/apps with present: false. Deleting a script is the exception: it removes the name from both lists.
• Both lists are kept after a restart.

Response: 200 {"ok":true}.

Errors:

Free storage and repeat the request before rebooting after a 507. AWTRIX also retries saving by itself.

curl -X PUT http://<awtrix-ip>/api/v1/apps/order \
  -H "Content-Type: application/json" \
  -d '{"order":["Time","weather","Time","Status"],"disabled":["doorbell"]}'

Keep the order, switch Status off and every other app on:

curl -X PUT http://<awtrix-ip>/api/v1/apps/order \
  -H "Content-Type: application/json" \
  -d '{"disabled":["Status"]}'

PUT /api/v1/apps/{name}/enabled¶

Switches one app on or off. Every other app stays as it is.

Request: {name} is the name of the app. The body is true to switch it on or false to switch it off.

• A switched-off app keeps its place in the order. Switched on again, it returns to that place.
• The name may belong to an app that is not there yet. When the app arrives, it is on or off as set.
• The switch is kept after a restart.

Response: 200 {"ok":true}, also when the app already was on or off.

Errors:

curl -X PUT http://<awtrix-ip>/api/v1/apps/Status/enabled \
  -H "Content-Type: application/json" -d 'false'

PUT /api/v1/apps/pushed/{name}¶

Creates a pushed app, or replaces the one with that name.

Request: {name} is everything after /api/v1/apps/pushed/. The body is an app payload: text, icon, color, draw, effect, charts and more: all fields are in App & notification payload.

The body is accepted whole or not at all. An unknown effect or overlay name (matched in any upper/lower case against GET /api/v1/capabilities) rejects the whole request, and for an array the whole batch.

A pushed app is kept in memory only. It stays until you replace or delete it, its lifetimeMs runs out, or AWTRIX restarts. For content that must come back after a restart, write a script.

Response: 200 {"ok":true}.

Errors:

A 415 or 422 never deletes or changes the existing app.

curl -X PUT http://<awtrix-ip>/api/v1/apps/pushed/weather \
  -H "Content-Type: application/json" \
  -d '{"text":"21.5C","icon":"2422","textColor":"#00AAFF"}'

DELETE /api/v1/apps/{name}¶

Removes an app of any kind.

Request: no body.

• Pushed app: removes that name and the numbered apps an array push to {name} created ({name}0, {name}1, …). An app you pushed to temp1 yourself is a separate app and stays. The name keeps its place in order or disabled, listed with present: false. The next push puts the app back there.
• Script: removes the source and its saved data (the only way to reset it). Its sounds stay. Delete them with DELETE /api/v1/apps/script/{name}/sounds. The name is removed from both lists. Installed again, the script joins at the end of the rotation, switched on, and uses the sounds that stayed.
• Built-in app: nothing happens. It stays in the rotation.

Response: always 200 {"ok":true} for a valid name: also when no such app exists. Deleting twice is safe.

Errors:

curl -X DELETE http://<awtrix-ip>/api/v1/apps/weather

Scripts¶

A script is a small program in the Berry language. An installed script becomes an app in the rotation, and its source is stored on AWTRIX, so it comes back after a restart. The language and worked examples are in the Scripting guide. This section lists the routes.

A script is addressed as /api/v1/apps/script/{name}. {name} is the app name and the file name under /SCRIPTS, and follows the name rule. To remove a script, use DELETE /api/v1/apps/{name}, the route that removes any app. The MP3s a script brings along are under /api/v1/apps/script/{name}/sounds.

/api/v1/apps/script/{name} answers other methods than GET and PUT with 405, allowed: GET, PUT.

GET /api/v1/apps/script/{name}¶

Downloads a script's source.

Request: no body.

Response: 200 text/plain: the source exactly as it was installed, so you can send it straight back with PUT.

Which scripts exist, whether they work, and the details from their @ headers are in GET /api/v1/apps (origin, error, meta), without the source.

This route also works while scriptingEnabled is off, so you can read and fix a script that made the device unreachable. See Scripts eat the memory.

Errors:

curl "http://<awtrix-ip>/api/v1/apps/script/clock" -o clock.ax

Script updates¶

PUT /api/v1/apps/script-update/{name} replaces a script only if its stored source is still exactly expected_source. Hub script updates use it. It is available when capabilities.scriptUpdates is true.

Request: a JSON body:

{"expected_source":"exact current source", "source":"replacement source"}

• expected_source: null creates the script only if no script of that name exists yet.
• {name} is 1–32 letters, digits, _ or -.
• An existing script keeps the settings that still fit.
• The whole request must fit the script size limit. See Limits.

Response: 200 {"ok":true}, the new source is installed. If the new script fails to compile or its setup() fails, the previous script is restored. Errors that happen later are reported in the script log.

Errors:

The request schema is in the OpenAPI description.

curl -X PUT "http://<awtrix-ip>/api/v1/apps/script-update/clock" \
  -H "Content-Type: application/json" \
  -d '{"expected_source":null,"source":"class Hello\n  def draw()\n    clear()\n    text(1, 6, \"hi\", 0x00FF00)\n  end\nend\nreturn Hello()"}'

PUT /api/v1/apps/script/{name}¶

Installs a script, or replaces the script with that name.

Request: the Berry source as it is: not JSON. Any Content-Type is accepted, or none.

Response:

• Replacing a script starts it fresh: its subscriptions, running requests and values in memory are dropped. Its saved data is kept, and it keeps its place in the rotation.
• While scriptingEnabled is off, the script is saved and the answer is {"ok":true,"name":"X","error":null}. It is not run or checked until scripting is on again after a restart. This is how the rescue works.

Errors:

A 507 can mean several different memory limits. See Script installation errors for the message, its meaning and the action to take.

curl -X PUT "http://<awtrix-ip>/api/v1/apps/script/clock" \
  -H "Content-Type: text/plain" --data-binary @clock.ax

GET /api/v1/apps/{name}/config¶

Reads the settings a script offers and their current values.

Request: no body.

Response: 200. A script without settings answers with an empty fields list, not 404. GET /api/v1/apps shows which scripts have settings, under config.

{
  "name": "Weather",
  "fields": [
    {"key": "lat", "type": "text", "label": "Latitude",
     "maxlen": 16, "default": "52.52", "value": "48.14"},
    {"key": "metric", "type": "bool", "label": "Celsius", "default": true, "value": true},
    {"key": "every", "type": "number", "label": "Refresh", "unit": "min",
     "min": 1, "max": 60, "default": 15, "value": 30},
    {"key": "mode", "type": "select", "label": "Show",
     "options": ["now", "today", "week"], "default": "now", "value": "today"},
    {"key": "tint", "type": "color", "label": "Color",
     "default": 16746496, "value": 65280}
  ],
  "warnings": []
}

A color is a number from 0 to 16777215. Every other type has the JSON type its name suggests.

Errors:

curl "http://<awtrix-ip>/api/v1/apps/Weather/config"

PATCH /api/v1/apps/{name}/config¶

Changes a script's settings.

Request: a JSON object with only the settings you want to change. Everything else keeps its value, including other data the script stored.

• A color accepts the number or "#RRGGBB".
• A number outside its min/max is set to the nearest limit, not refused.
• If one field is wrong, nothing is changed.

Response: saving restarts the script, like sending its source again: init() and setup() run again with the new values, values in memory and subscriptions are dropped, and the app keeps its place in the rotation.

Errors:

curl -X PATCH "http://<awtrix-ip>/api/v1/apps/Weather/config" \
  -H "Content-Type: application/json" -d '{"lat":"48.14","tint":"#00FF00"}'

GET /api/v1/apps/builtin/{name}/config¶

Reads the settings of a built-in app, for example Time, and their current values. The web UI shows them under Apps.

Request: no body.

Response: 200. GET /api/v1/apps shows which built-in apps have settings, under config. A built-in app without settings, for example Status, answers with an empty fields list.

{
  "name": "Time",
  "fields": [
    {"key": "time24h", "type": "bool", "group": "time", "path": ["time24h"],
     "default": true, "value": false},
    {"key": "timeColor", "type": "color", "group": "time", "path": ["timeColor"],
     "nullable": true, "default": null, "value": 16711680},
    {"key": "weekdayBar.weekendDays", "type": "days", "group": "weekday",
     "path": ["weekdayBar", "weekendDays"], "default": ["sunday", "saturday"],
     "value": ["saturday"]}
  ],
  "warnings": []
}

A color is a number from 0 to 16777215. 0 is black. Time offers clockFace and the date format. Its weekday bar is under weekdayBar.

Errors:

curl "http://<awtrix-ip>/api/v1/apps/builtin/Time/config"

PATCH /api/v1/apps/builtin/{name}/config¶

Changes the settings of a built-in app. The change shows at once and is saved like every other setting.

Request: a JSON object with only the settings you want to change, each at its path. Everything else keeps its value.

• A color accepts the number, "#RRGGBB" and the other color forms. null is allowed only where nullable is true.
• A days value is a list of lowercase English day names, for example ["saturday","sunday"].
• If one setting is wrong, nothing is changed.

Response: 200 {"ok":true,"name":"Time","error":null}.

Errors:

curl -X PATCH "http://<awtrix-ip>/api/v1/apps/builtin/Time/config" \
  -H "Content-Type: application/json" -d '{"time24h":false,"weekdayBar":{"show":false}}'

GET /api/v1/apps/{name}/data¶

Reads what a script saved with store.set(): high scores, save games, last known values.

Request: no body.

Response: 200 with one JSON object, key by key. A script that saved nothing answers {}.

{"unl": 7, "best": [12, 40, 9, 0]}

• The values of its settings are not in it. They are under /config.
• A key the script cleared with store.set(key, nil) is not in it.

Errors:

curl "http://<awtrix-ip>/api/v1/apps/lemmix/data"

PATCH /api/v1/apps/{name}/data¶

Changes what a script saved.

Request: a JSON object with only the keys you want to change.

• A value replaces the stored one, or adds the key.
• null removes the key.
• Every key you leave out keeps its value.
• A key that is one of the script's settings is refused. Change it with PATCH /config.

Response: saving restarts the script, like changing its settings: init() and setup() run again and read the new values.

Errors:

curl -X PATCH "http://<awtrix-ip>/api/v1/apps/lemmix/data" \
  -H "Content-Type: application/json" -d '{"unl":9,"best":null}'

Script sign-in¶

Some scripts sign in to a service with your account, see Signing in to services. These routes hold the client ID and client secret and run the sign-in. The web UI uses them in the app settings. They exist only while capabilities say "oauth": true, which needs scripting switched on.

Every change needs the header X-Awtrix-OAuth: 1 and an Origin header naming the device, as the device's own web UI sends them. This keeps other web pages from changing a sign-in. Answers are never cached.

GET /api/v1/oauth¶

Lists every script that signs in.

Response: 200:

{"redirectUri": "https://awtrix.de/oauth/callback",
 "apps": [{"name": "Spotify", "provider": "accounts.spotify.com", "scope": "user-read-currently-playing",
           "pkce": true, "clientId": "4f1c...", "clientSecretSet": true, "state": "signedIn"}]}

redirectUri is the address to enter in the developer app at the service.

GET /api/v1/oauth/{name}¶

One script's sign-in, as one entry of the list above.

404 notFound when the script does not sign in.

POST /api/v1/oauth/{name}¶

Saves client ID and client secret. Request: any of clientId, clientSecret, or "clearSecret": true. Fields you leave out keep their value. An empty clientSecret keeps the saved one. A new client ID ends the sign-in. Response: 200 {"ok":true}.

POST /api/v1/oauth/{name}/start¶

Starts a sign-in. Request: {}. Response: 200 {"url": "..."}, the service's sign-in page. Open it in the same browser. After you allow access, the service sends the browser back to the clock's web UI, which finishes the sign-in. A started sign-in expires after 10 minutes.

POST /api/v1/oauth/{name}/code¶

Finishes a sign-in with what the service sent back. Request: {"code": "...", "state": "..."}. Response: 202 {"ok":true}. A moment later state turns signedIn or error.

DELETE /api/v1/oauth/{name}¶

Signs out. Client ID and client secret stay. Response: 200 {"ok":true}.

Errors of these routes:

The 404 comes first: a script without an @oauth line answers it to every method, before 405 and 403.

curl -X POST http://<awtrix-ip>/api/v1/oauth/Spotify \
  -H "Content-Type: application/json" \
  -H "X-Awtrix-OAuth: 1" \
  -H "Origin: http://<awtrix-ip>" \
  -d '{"clientId":"4f1c...","clientSecret":"..."}'

Back up and restore scripts¶

Scripts can be read and written over the HTTP API, for example by a backup script:

# read one script back, verbatim
curl http://<awtrix-ip>/api/v1/apps/script/Weather

# install or replace (the body is Berry source, not JSON)
curl -X PUT http://<awtrix-ip>/api/v1/apps/script/Weather \
  -H 'Content-Type: text/plain' --data-binary @weather.ax

# every app on the device, with origin, compile state and metadata
curl http://<awtrix-ip>/api/v1/apps

# the settings a script offers, with their current values
curl http://<awtrix-ip>/api/v1/apps/Weather/config

# change one of them (the app restarts with the new value)
curl -X PATCH http://<awtrix-ip>/api/v1/apps/Weather/config \
  -H 'Content-Type: application/json' -d '{"lat":"48.14"}'

GET returns the source exactly as stored and PUT takes it exactly as sent, so backing up every script is a simple shell loop.

A script that fails to compile still installs. PUT answers 200, the app appears in the rotation, and the error field in the answer holds the error message and line. Check that field, or a typo looks like a working upload.

The source does not include the script's sounds. See Script sounds. Sign-ins are not part of the script and not part of a backup. After a restore, sign in again.

Removing a script¶

Use DELETE /api/v1/apps/{name}, the same route that removes a pushed app. It deletes the source, the saved data and the app in the rotation. The script's sounds stay. DELETE /api/v1/apps/script/{name}/sounds removes them. Deleting twice is safe: the second call also answers 200. See DELETE /api/v1/apps/{name}.

curl -X DELETE "http://<awtrix-ip>/api/v1/apps/clock"

Script sounds¶

A script can bring its own MP3s. They are stored in a folder named after the script, /SCRIPTS/<name>/<sound>.mp3. The script plays them by name: sound.play("boost") plays boost.mp3 from its own folder, or /MP3/boost.mp3 when its folder has none. See Sound and music.

• Replacing the script's source keeps its sounds, and so does removing the script. Sounds without a script stay listed, marked orphan, until they are deleted.
• A sound is named like a stored MP3: 1–32 characters of A-Za-z0-9_- plus .mp3. The folder holds MP3s only.
• A script's sound may have the name of a melody or of an MP3 in /MP3. The folder is its own set of names.

To hear one, send POST /api/v1/audio/play with {"file":"<name>/<sound>"}, or open GET /SCRIPTS/<name>/<sound>.mp3 in a browser.

GET /api/v1/apps/script/{name}/sounds¶

Lists a script's sounds with a SHA-256 checksum of each, so an installer can tell which ones it still has to upload.

Request: no body.

Response: 200:

{"files":[{"name":"boost.mp3","size":20411,
           "sha256":"df577af7d16e9636420caf755518243926865f63220570e4d9e0a33a6e605c09"}],
 "usedBytes":176128,"totalBytes":13107200}

Errors:

curl "http://<awtrix-ip>/api/v1/apps/script/Racer/sounds"

POST /api/v1/apps/script/{name}/sounds¶

Uploads one MP3 into a script's folder.

Request: a multipart/form-data upload of one file. The script must be installed first. The file name becomes the sound name: 1–32 characters of A-Za-z0-9_- plus .mp3. The content must be an MP3. A sound with the same name is replaced.

Response: 200 {"ok":true}.

Errors:

curl -X POST "http://<awtrix-ip>/api/v1/apps/script/Racer/sounds" -F "file=@boost.mp3"

DELETE /api/v1/apps/script/{name}/sounds/{sound}¶

Deletes one of a script's sounds, and stops it first if it is playing.

Request: no body. {sound} is the name without .mp3. The script does not have to be installed: sounds kept from a deleted script are deleted the same way.

Response: 200 {"ok":true}. The folder is removed with its last sound.

Errors:

curl -X DELETE "http://<awtrix-ip>/api/v1/apps/script/Racer/sounds/boost"

DELETE /api/v1/apps/script/{name}/sounds¶

Deletes all of a script's sounds and its folder, and stops any that is playing. Use it before or after DELETE /api/v1/apps/{name} to remove a script completely.

Request: no body.

Response: 200 {"ok":true}: also when there was nothing to delete.

Errors:

curl -X DELETE "http://<awtrix-ip>/api/v1/apps/script/Racer/sounds"

GET /api/v1/scripts/shared¶

Lists the values scripts share with each other through the shared module. See Talking to other apps.

Request: no body.

Response: 200 with an array, grouped by owner and sorted by key. [] when nothing is shared.

[{"owner":"weather","key":"temp","type":"real","value":21.5,"ageMs":3200},
 {"owner":"weather","key":"unit","type":"string","value":"C","ageMs":3200}]

This list is read-only. It is empty after a restart, and removing or re-saving a script removes everything it shared.

Errors:

curl "http://<awtrix-ip>/api/v1/scripts/shared"

Notifications¶

POST /api/v1/notifications¶

Shows a one-time message on top of the rotation.

Request: every app payload field (App & notification payload), plus these:

The payload is accepted whole or not at all. Validation errors answer 422 with the key in field, and nothing is shown. effect and overlay must be names from GET /api/v1/capabilities. All rules: Payload → Errors.

An array is accepted only with exactly one object in it, which becomes the notification. Unlike pushed apps, notifications are not split into several: more than one element answers 422.

sound is checked when the notification arrives, with the rules of audio playback. A notification with an invalid sound is refused whole. A name that is not stored, or a sound the clock cannot play, is not an error: the notification shows without sound.

Response: 200 {"ok":true}.

Errors:

curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d '{"text":"Doorbell","icon":"1234","textColor":"#FF0000","hold":true,"sound":{"rtttl":"d:d=4,o=5,b=120:c,e,g"}}'

DELETE /api/v1/notifications/active¶

Dismisses the notification shown.

Request: no body.

Response: always 200 {"ok":true}, also when no notification is shown.

Errors:

curl -X DELETE http://<awtrix-ip>/api/v1/notifications/active

DELETE /api/v1/notifications/{name}¶

Dismisses the notification with this name, wherever it is in the queue.

Request: no body. The notification does not have to be shown. Removing a waiting one does not affect the one shown.

active is reserved: /api/v1/notifications/active always means the notification that is shown, so a notification named active cannot be dismissed by name. Use a different name.

A name does not protect a notification: anyone who can reach the API can dismiss it. To limit who can use the API, turn on HTTP authentication.

Response: 200 {"ok":true}: a notification with that name was removed.

Errors:

# push one that you can dismiss later
curl -X POST http://<awtrix-ip>/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d '{"name":"backup-job","text":"Backup running","hold":true}'

# dismiss it, whatever else has arrived since
curl -X DELETE http://<awtrix-ip>/api/v1/notifications/backup-job

Indicators¶

The three indicators are small lights on the right edge of the display: id 1 at the top, id 2 in the middle, id 3 at the bottom. They can blink (blinkMs) or fade in and out (fadeMs). Their state is also shown in GET /api/v1/device and sent over MQTT and to Home Assistant.

PUT /api/v1/indicators/{id}¶

Switches an indicator on, changes its color, or sets it to blink or fade.

Request: {id} is 1, 2 or 3. The body must not be empty.

• Only color switches the indicator on or off. Without color, on/off and the color stay.
• color 0 or null switches it off and keeps the stored color, so Home Assistant can send it back unchanged.
• Any other color sets the color and switches it on.
• Each request sets blinking and fading anew. A request without blinkMs and fadeMs gives a steady light.
• A blinkMs or fadeMs outside 0–65535 is not refused. It is stored as 0.

Response: 200 {"ok":true}.

Errors:

curl -X PUT http://<awtrix-ip>/api/v1/indicators/1 \
  -H "Content-Type: application/json" \
  -d '{"color":"#FF0000","blinkMs":500}'

DELETE /api/v1/indicators/{id}¶

Switches an indicator off and resets it: color 0, blinkMs 0, fadeMs 0.

Request: no body.

Response: always 200 {"ok":true}.

Errors:

curl -X DELETE http://<awtrix-ip>/api/v1/indicators/1

Audio¶

Everything the speaker plays: stored MP3s, melodies, songs for the synthesizer, speech, recordings and internet radio.

What a device can play is in audio in GET /api/v1/capabilities. How loud each sound plays: Sound settings.

The sound object¶

POST /api/v1/audio/play, <P>/cmd/audio/play and a notification's sound all take the same value. It has three forms:

• A string is a stored name: "ding" is the same as {"file":"ding"}.
• An object has exactly one source key, plus options.
• A list holds 1 to 4 strings or objects. The clock plays the first entry it can play: it has the hardware for it, and for file the file is stored. station is not allowed in a list.

Source keys, exactly one per object:

Options:

How file finds a name:

• An address is downloaded and played. The answer comes at once. If the download fails, nothing plays and alert.error says why. A file can be up to 4 MB.
• "Script/name" is looked up in that script's folder only, /SCRIPTS/<Script>/<name>.mp3.
• A plain name is the MP3 /MP3/<name>.mp3, else the melody /MELODIES/<name>.txt. A script's own call looks in /SCRIPTS/<script>/<name>.mp3 first.

Names are 1 to 32 characters of A-Za-z0-9_-. An MP3 in /MP3 and a melody in /MELODIES never share a name, see nameTaken.

Who sends a sound decides its group, and so its volume: everything sent here is an alert, and station is the radio. What happens when sounds meet: What plays over what.

GET /api/v1/audio¶

Reads what each group plays, and the radio station list.

Request: no body.

Response: 200:

{
  "radio": {
    "playing": true,
    "station": "SWR3",
    "title": "Kraftwerk - Das Model",
    "error": "",
    "underruns": 0,
    "decodeUs": 4180,
    "starvedMs": 0,
    "bufferBytes": 12288
  },
  "app": {"playing": false, "name": "", "error": ""},
  "alert": {"playing": true, "name": "ding", "error": ""},
  "stations": [{"name": "SWR3", "url": "https://liveradio.swr.de/sw282p3/swr3/"}]
}

The four numbers from underruns to bufferBytes show playback health. underruns and starvedMs keep counting across stations, so compare two readings.

The same document is published, retained, on <P>/state/audio on every change of any group.

Errors:

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

POST /api/v1/audio/play¶

Plays a sound, or starts a radio station.

Request: a sound object: a string, an object or a list.

curl -X POST http://<awtrix-ip>/api/v1/audio/play \
  -H "Content-Type: application/json" \
  -d '{"rtttl":"beep:d=4,o=5,b=120:c,e,g"}'

The sound plays as an alert, at volume × alertVolume. station plays as the radio, at volume × radioVolume.

• A new alert replaces the alert that is playing.
• With "loop": true the alert repeats until POST /api/v1/audio/stop stops the alert group or everything, or until a new alert replaces it.
• While an alert plays, the radio pauses and comes back afterwards.
• A song plays once. With "loop": true it repeats.
• station takes a station name, its position in the list (counted from 0), or a stream address. A stream address pointing to an .m3u or .pls playlist plays its first entry.

Response: 200 {"ok":true}. The sound starts right after.

Errors:

Mistakes in the body are checked first. Then the stored files and the hardware are checked.

See Audio playback errors for the status, field and message of each failure.

Inside a list, field starts with the entry's position: [1].rtttl.

Play a script's own sound:

curl -X POST http://<awtrix-ip>/api/v1/audio/play \
  -H "Content-Type: application/json" \
  -d '{"file":"Racer/boost"}'

Speak once a voice is installed, play ding otherwise:

curl -X POST http://<awtrix-ip>/api/v1/audio/play \
  -H "Content-Type: application/json" \
  -d '[{"speech":"Good morning. It is 7:30."},"ding"]'

Start a station by its position in the list:

curl -X POST http://<awtrix-ip>/api/v1/audio/play \
  -H "Content-Type: application/json" \
  -d '{"station":0}'

POST /api/v1/audio/stop¶

Stops what is playing.

Request: no body or {} to stop everything, or {"group": ...} to stop one group:

Response: always 200 {"ok":true} for a valid body.

Errors:

curl -X POST http://<awtrix-ip>/api/v1/audio/stop \
  -H "Content-Type: application/json" \
  -d '{"group":"alert"}'

POST /api/v1/audio/clip¶

Plays a recording once, such as a voice message from a phone. The clip is not stored.

Request: the body is the audio file itself, with any Content-Type, up to 2 MiB:

• WAV: 16-bit PCM, mono or stereo, at 16000, 22050, 24000, 32000, 44100 or 48000 Hz
• MP3: MPEG-1, 2 or 2.5 layer III. An ID3 tag in front is fine

A clip is an alert, like a sound from POST /api/v1/audio/play. It plays at volume × alertVolume and replaces an alert that is playing. A radio station pauses and comes back afterwards. POST /api/v1/audio/stop stops it.

Response: 200 {"ok":true} once the clip starts.

Errors:

curl -X POST http://<awtrix-ip>/api/v1/audio/clip \
  -H "Content-Type: audio/wav" \
  --data-binary @message.wav

GET /api/v1/audio/melodies¶

Lists all stored melodies with their content.

Request: no body.

Response: 200:

{"melodies":[{"name":"doorbell","rtttl":"doorbell:d=4,o=5,b=100:e,c",
              "bytes":26,"notes":2,"durationMs":2400,"valid":true}],
 "usedBytes":41216,"totalBytes":1048576}

A melody with an error is listed, not hidden, with valid: false and the reason in error, so you can open and fix it.

Errors:

curl http://<awtrix-ip>/api/v1/audio/melodies

PUT /api/v1/audio/melodies/{name}¶

Saves a melody.

Request: {name} is 1–24 characters of A-Z, a-z, 0-9, _ and -. The body is {"rtttl": "d=4,o=5,b=100:e,c"}.

The melody title is always set to {name}: a two-part defaults:notes text gets the name added in front, and a three-part text has its title replaced.

Response: 201 when the melody is new, 200 when it replaced an existing one.

Errors:

To rename a melody, save it under the new name, then delete the old one.

curl -X PUT http://<awtrix-ip>/api/v1/audio/melodies/doorbell \
  -H "Content-Type: application/json" \
  -d '{"rtttl":"d=4,o=5,b=100:e,c"}'

DELETE /api/v1/audio/melodies/{name}¶

Deletes a melody.

Request: no body.

Response: 200 {"ok":true}.

Errors:

curl -X DELETE http://<awtrix-ip>/api/v1/audio/melodies/doorbell

GET /api/v1/audio/mp3¶

Lists the stored MP3s: your own under files, and the sounds of each installed script under scripts.

Request: no body.

Response: 200:

{"files":[{"name":"ding.mp3","size":40118}],
 "scripts":[{"name":"awtrix-gp","title":"AWTRIX GP","orphan":false,
             "files":[{"name":"boost.mp3","size":20411}]}],
 "usedBytes":176128,"totalBytes":13107200}

curl http://<awtrix-ip>/api/v1/audio/mp3

POST /api/v1/audio/mp3¶

Uploads one MP3 into /MP3.

Request: a multipart/form-data upload of one file. There is no ?dir=. The file name is the name you play it by, so it must be 1–32 characters of A-Za-z0-9_- plus .mp3. The content must be an MP3.

Response: 200 {"ok":true}.

Errors:

curl -X POST http://<awtrix-ip>/api/v1/audio/mp3 -F "file=@ding.mp3"

DELETE /api/v1/audio/mp3/{name}¶

Deletes one MP3.

Request: no body. {name} is the name without .mp3.

Response: 200 {"ok":true}.

Errors:

curl -X DELETE http://<awtrix-ip>/api/v1/audio/mp3/ding

POST /api/v1/audio/mp3/rename¶

Renames one MP3 in /MP3. Sounds in a script's own folder cannot be renamed.

Request: a JSON body:

Alarms, notifications and scripts that play the old name stay silent until you change them.

Response: 200 {"ok":true}, also when from and to are the same.

Errors:

curl -X POST http://<awtrix-ip>/api/v1/audio/mp3/rename -H "Content-Type: application/json" -d '{"from":"ding","to":"bell"}'

Radio¶

Internet radio plays on the speaker.

To start a station, use POST /api/v1/audio/play with station: a name, a position in the list, or a stream address. To stop it, use POST /api/v1/audio/stop with {"group":"radio"}. Wiring, limits and troubleshooting: Internet radio.

GET /api/v1/audio/stations¶

Reads the stored station list.

Request: no body.

Response: 200 {"stations":[{"name":"Example","url":"https://example.com/radio.mp3"}]}.

curl http://<awtrix-ip>/api/v1/audio/stations

PUT /api/v1/audio/stations¶

Replaces the whole station list. There is no route for a single station.

Request:

{"stations": [{"name": "SWR3", "url": "https://liveradio.swr.de/sw282p3/swr3/"}]}

A plain array is also accepted. Limits: at most 32 stations, name 1–24 characters, URL at most 255 characters starting with http or https, every name only once.

Response: 200 {"ok":true}. The list is saved.

Errors: the list is saved whole or not at all. The error names the wrong entry:

{"error":{"code":"validationFailed","message":"must not be empty","field":"stations[1].name"}}

Free storage and repeat the request before rebooting after a 507. AWTRIX also retries saving by itself.

curl -X PUT http://<awtrix-ip>/api/v1/audio/stations \
  -H "Content-Type: application/json" \
  -d '{"stations":[{"name":"SWR3","url":"https://liveradio.swr.de/sw282p3/swr3/"}]}'

Capabilities¶

GET /api/v1/capabilities¶

Lists what this device supports: effect, transition, overlay and palette names, sound outputs and sensors. Read the names here instead of writing them into your code.

Request: no body.

Response: 200:

{"effects":[...],"transitions":[...],"overlays":[...],"palettes":[...],"audio":{...},"gpio":null,"sensors":{...}}

effects and overlays are sorted alphabetically. transitions has its own fixed order. All effect, overlay, palette and transition names accept any upper/lower case: "matrix", "Matrix" and "MATRIX" are the same effect. This list shows the spelling AWTRIX uses in its answers.

These keys appear only while the feature is available:

gamepad, gamepadRemote, oauth, crypto, layout and tcp need scripting switched on. The layouts object holds the limits of prepared layouts. Further keys describe the display size and fonts. They are listed in the OpenAPI description.

audio: what the device can play¶

One flag for each kind of sound. Every flag is always present:

"audio":{"mp3":true,"rtttl":true,"song":true,"speech":true,"track":false,"radio":true,"url":true,"effect":true,"clip":true}

track is always false on this clock.

The web UI shows each Audio section only when its flag is true.

sensors¶

"sensors":{"light":false}

Errors:

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

System¶

Device configuration: Wi-Fi, MQTT, time server, login and hardware. Each field explained: System configuration.

GET /api/v1/system¶

Reads the device configuration.

Request: no body. Add ?secrets=1 to include wifiPass, mqttPass and authPass, for example for a backup. Without it, they are left out. In setup mode any secrets query parameter makes the request fail with 403 forbidden, because that access point is open. A request for secrets from another website answers 403 forbiddenOrigin (details). When authentication is on, this request needs it like any other.

Response: 200 with every readable field from the field table below, under its own name.

curl http://<awtrix-ip>/api/v1/system
curl "http://<awtrix-ip>/api/v1/system?secrets=1"

PUT /api/v1/system¶

In setup mode only wifiSsid, wifiPass and hostname may be written, as strings. Other fields, duplicate keys and malformed setup bodies answer 403 forbidden.

Changes one or more configuration fields.

Request: any subset of the fields below. All values are checked before anything is saved.

• Numbers are range-checked. A value outside its range answers 422 validationFailed with the key in field, and nothing is saved. The ranges are in the table below and in Errors → PUT /api/v1/system.
• Unknown keys are ignored. Text fields (tz, hostname, buttonCallback, …) are not checked either. This clock has no wiring, orientation or pin… fields. They are ignored like unknown keys, whatever their value.
• An empty secret is ignored: "authPass": "" keeps the stored password. Most other text fields can be cleared with "": ntpServer, ip, mqttUser and so on.

• MQTT and login have an on/off switch. mqttEnabled runs the MQTT client, authEnabled requires HTTP login. Switching one off keeps the stored host, username and password, and you can clear mqttHost and authUser freely. A switch can only be turned on when its values are set. Otherwise it answers 422 validationFailed with the key in field:

  Set	Requires	field on 422
  mqttEnabled: true	a non-empty mqttHost	mqttHost
  authEnabled: true	a non-empty authUser and authPass	authUser

• wifiSsid cannot be cleared. "" answers 422 validationFailed (field: wifiSsid) and points to POST /api/v1/device/factory-reset. A PUT never clears a secret. A factory reset does.

• Most changes need a restart. The web UI then shows a "reboot required" banner.

Response: 200 with the whole configuration after the change (secrets left out). It is saved.

Errors:

curl -X PUT http://<awtrix-ip>/api/v1/system \
  -H "Content-Type: application/json" \
  -d '{"ntpServer":"192.168.1.1","statsInterval":30000}'

Fields¶

The answer also holds a few fields that have no effect on this clock, such as webPort and artnet. Leave them as they are.

GET /api/v1/system/wifi-scan¶

Scans for Wi-Fi networks. The scan takes a moment, so ask again until results arrive.

Request: no body.

Response:

Results are delivered once: the next request starts a new scan and answers 202 again.

Errors:

curl http://<awtrix-ip>/api/v1/system/wifi-scan   # 202, then ask again

GET /api/v1/logs¶

Reads the device log shown in the web UI console, a few lines at a time.

Request:

Response: 200:

To follow the log, pass the last next as after in the next request. AWTRIX keeps the last 34 lines, each up to 120 characters. Older lines are dropped. Each line starts with the time HH:MM:SS once the clock has the time from the internet, before that with the seconds since start, [ 123s].

The log also shows messages from the clock's system about Wi-Fi, the network address, the time server, updates, the speaker and restarts of AWTRIX, such as wifi: association rejected: wrong key. Messages from while AWTRIX was not running (during the start, or why it stopped) appear once it runs again, up to the last 16 lines.

Errors:

curl "http://<awtrix-ip>/api/v1/logs?after=0"

GET /api/v1/gamepad¶

Reads the two gamepad slots and the phones that play.

This route exists only while capabilities say "gamepad": true. Otherwise it answers 404.

Request: no body.

Response: 200:

A single ready gamepad is player 1. With two, the one whose first input arrived first is player 1. The slot number is not the player number: slot 2 can be player 1. Without Bluetooth both slots are unpaired.

curl http://<awtrix-ip>/api/v1/gamepad
# {"devices":[{"id":1,"state":"ready","name":"8BitDo Ultimate","address":"E4:17:D8:BC:EC:1D","player":1},
#  {"id":2,"state":"unpaired","name":"","address":"","player":null}],
#  "remotes":[{"session":7,"name":"Pixel 8","player":2}]}

POST /api/v1/gamepad/pair¶

Looks for a new gamepad for one minute and pairs the first one it finds into a free slot. Exists only while capabilities say "ble": true as well.

Request: no body. Put the gamepad into pairing mode first. A gamepad that is paired already is not taken again.

Response:

Calling it again during the search answers the same slot and does not start the minute over. The other gamepad stays connected.

curl -X POST http://<awtrix-ip>/api/v1/gamepad/pair

DELETE /api/v1/gamepad/{id}¶

Forgets the gamepad in slot 1 or 2, with its pairing. The other gamepad stays connected. Exists only while capabilities say "ble": true as well.

Request: no body.

Response: 200 {"ok":true} at once, also for an empty slot. Any other {id} answers 404 notFound with the message no such gamepad.

curl -X DELETE http://<awtrix-ip>/api/v1/gamepad/2

POST /api/v1/gamepad/remote¶

Makes a phone the gamepad of one player. While it plays, gamepad.state(player) is ready and gamepad.name(player) is the phone's name. The other player keeps their own gamepad or phone. When the phone stops, that player's Bluetooth gamepad counts again. Bluetooth is not needed.

This route exists only while capabilities say "gamepadRemote": true.

Request: an optional JSON body:

Without player the clock picks a player that no phone and no Bluetooth gamepad plays, else one that no phone plays, else player 1. A phone that asks for a player another phone plays takes it over. The token of the other phone then stops working.

Response:

Sending the controls: UDP datagrams of exactly 32 bytes to the port, numbers little-endian. Send one on every change and at least every 100 ms. After one second without a valid datagram the controls are released and the session ends. Send a new POST for a new token.

Datagrams of another size, version or token are ignored.

curl -X POST http://<awtrix-ip>/api/v1/gamepad/remote \
  -H "Content-Type: application/json" \
  -d '{"name":"Pixel 8","player":2}'
# {"port":4214,"token":"3f9c0e5a7b21d4c68e0f1a2b3c4d5e6f","player":2,"session":7}

DELETE /api/v1/gamepad/remote/{session}¶

Ends the session of one phone. Its player's Bluetooth gamepad counts again.

Request: no body. {session} is the number from POST /api/v1/gamepad/remote.

Response: 200 {"ok":true}.

Errors:

curl -X DELETE http://<awtrix-ip>/api/v1/gamepad/remote/7

GET /api/v1/mqtt/tls¶

Reads how AWTRIX trusts the MQTT broker when it connects over TLS. See MQTT → Connect over TLS.

This route and the two below exist only while capabilities say "mqttTls": true. Otherwise they answer 404.

Request: no body.

Response: 200:

curl http://<awtrix-ip>/api/v1/mqtt/tls
# {"ca":"public","pending":"ce781fea…c798"}

PUT /api/v1/mqtt/tls/ca¶

Uploads the certificate of your own certificate authority for the MQTT broker. From the next connection attempt on, AWTRIX accepts only a broker with a certificate from this authority that names mqttHost.

Request:

Response: 200 with the same body as GET /api/v1/mqtt/tls.

Errors:

jq -n --rawfile certificate ca.crt '{$certificate}' |
  curl -X PUT http://<awtrix-ip>/api/v1/mqtt/tls/ca -H "Content-Type: application/json" -d @-

DELETE /api/v1/mqtt/tls/ca¶

Deletes the uploaded broker CA, also an unusable one. Public certificate authorities and the trusted fingerprint count again.

Request: no body.

Response: 200 with the same body as GET /api/v1/mqtt/tls.

curl -X DELETE http://<awtrix-ip>/api/v1/mqtt/tls/ca

GET /api/v1/voice¶

Reads the Home Assistant Voice settings and connection state.

This route and POST below exist only while capabilities say "voice": true. Otherwise they answer 404.

Request: no body.

Response: 200:

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

POST /api/v1/voice¶

Changes the Home Assistant Voice settings.

Request: any of enabled, url, pipeline, device, token, or "clearToken": true to delete the token. Fields you leave out keep their value.

• device is a Home Assistant device ID (letters and digits, up to 64), "" for none.

• enabled: true needs an address and a token.

• After you change the address, send the token again.
• With "enabled": false the clock closes its connection to Home Assistant, and a long press on the knob does nothing.

This route accepts requests only from the device's own web UI: it needs the header X-Awtrix-Voice: 1 and an Origin header naming the device, as a browser sends it. This keeps other web pages and scripts from sending your voice to another server.

Response: 200 {"ok":true}.

Errors:

curl -X POST http://<awtrix-ip>/api/v1/voice \
  -H "Content-Type: application/json" \
  -H "X-Awtrix-Voice: 1" \
  -H "Origin: http://<awtrix-ip>" \
  -d '{"enabled":false}'

Files¶

The storage holds your icons, melodies, palettes and MP3s. See Limits. GET /api/v1/files reports the real values as usedBytes and totalBytes.

GET /api/v1/files¶

Lists the files in a folder. File and script-group ordering is unspecified. Clients that need a particular order should sort the returned names. This also applies to melody, MP3 and script-sound listings.

Request:

Response: 200:

A dir that does not exist, or is not a folder, answers 200 with an empty files list, not 404.

Errors:

curl "http://<awtrix-ip>/api/v1/files?dir=/MELODIES"

POST /api/v1/files¶

Uploads files into one of the asset folders.

Request: a multipart/form-data upload. The name of the form field does not matter. Every file in it is taken.

Where the file goes:

• a file name that starts with / is the full path. ?dir= is ignored,
• otherwise the path is <dir>/<filename> (a missing / in front of dir is added),
• the path must be inside /ICONS, /MELODIES, /PALETTES or /MP3 and must not contain ..,
• a file for /MP3 must be named the way you play it: 1–32 characters of A-Za-z0-9_- plus .mp3,
• an MP3 in /MP3 and a melody in /MELODIES never share a name,
• a missing folder is created.

The content must fit the folder: /ICONS takes GIF or JPEG (not PNG), /MELODIES RTTTL text, /PALETTES one RRGGBB color per line, /MP3 MP3 files. Empty files are refused.

A refused file never replaces the file that was there. When one request carries several files, files saved before a failing one stay saved, and the request reports the failure.

Response: 200 {"ok":true}. Check the result with GET /api/v1/files.

Errors:

curl -X POST "http://<awtrix-ip>/api/v1/files?dir=/ICONS" \
  -F "file=@1234.jpg"

DELETE /api/v1/files¶

Deletes one file from the asset folders.

Request:

Deleting an icon also removes its Hub link.

Response: 200 {"ok":true}.

Errors: