Homarr
Manage users and preferences

Get user preferences

GET/api/users/preferences

Read every preference as structured JSON. Omit userId for the current user; reading another user requires admin permission.

Authorization

apikey
ApiKey<token>

API key which can be obtained in the Homarr administration dashboard

In: header

Query Parameters

userId?string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/users/preferences"
{  "colorScheme": "auto",  "byteUnitSystem": "binary",  "firstDayOfWeek": 0,  "pingIconsEnabled": true,  "enableRightClickOnWidgets": true,  "homeBoardId": "string",  "mobileHomeBoardId": "string",  "defaultSearchEngineId": "string",  "openSearchInNewTab": true,  "ddgBangs": true,  "headerPreferences": {    "version": 3,    "visible": true,    "searchDisplay": "input",    "logoDisplay": "logo",    "zones": {      "left": [        {          "type": "builtin",          "id": "logo"        }      ],      "center": [        {          "type": "builtin",          "id": "logo"        }      ],      "right": [        {          "type": "builtin",          "id": "logo"        }      ]    }  },  "userId": "string"}

Search users

Find users whose names contain the query. Returns IDs, names, profile images, and email addresses, with up to 100 results. Requires admin permission.

Update user preferences

Update only supplied preferences and return the result. Omitted fields remain unchanged; null clears nullable references. Header fields and zones merge, while each supplied zone array replaces that zone. The complete merged header must retain unique items and account access. New board shortcuts must be accessible to the target user. Omit userId for yourself; another user requires admin permission. All validation completes before one write.