UI Variables
The UI customization surface: a set of typed variables (logos, colors, copy strings, feature toggles) grouped into categories, plus a couple of top-level endpoints for the bundled "style" and "menu" config that drives the UI shell. Where Themes capture branding as a whole package, UI Variables let you tweak individual values without swapping themes.
Scopes
| Scope | Reach |
|---|---|
ui:read | Reading style config, menu config, variables, categories, filters. |
ui:write | Creating/updating/deleting variables and categories. |
Top-level Endpoints
Get Style Config
GET /api/ui/
Returns the combined style configuration the UI shell uses on boot. This is essentially "active theme + active UI variables" composed into a single payload.
Required scope: ui:read
Response 200 — ThemeRead
Get Menu Config
GET /api/ui/menu
Returns the navigation menu configuration the UI shell uses to render its main menus.
Required scope: ui:read
Response 200 — menu configuration payload.
UI Categories
Categories group related UI variables (e.g., "Login screen", "Email footer", "Brand colors") for display in the admin UI.
List UI Categories
GET /api/ui/categories/
Returns a page of UI categories.
Required scope: ui:read · also accepts API key
Query parameters — standard pagination set; see Conventions › Pagination. Defaults: sort_by=created, sort_order=desc, hydrate=true.
Response 200 — UiCategoryInDbCursorPage
Get UI Category Filter Metadata
GET /api/ui/categories/filters
Returns filter/operator/sort options for List UI Categories.
Required scope: ui:read
Response 200 — open metadata object.
Get UI Category by ID
GET /api/ui/categories/{id}
Returns a single UI category record.
Required scope: ui:read · also accepts API key
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Category ID. |
Response 200 — UiCategoryRead
Create UI Category
POST /api/ui/categories/
Creates a new UI category.
Required scope: ui:write
Request body — UiCategoryWriteCreate
Response 201 — UiCategoryRead
Update UI Category by ID
PUT /api/ui/categories/categories/{id}
Replaces the UI category.
WARNING
The path segment /categories/categories/ is doubled — this is intentional in the current API and should be sent verbatim. The same applies to UI Variables (see below).
Required scope: ui:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Category ID. |
Request body — UiCategoryWriteReplace
Response 200 — UiCategoryRead
Patch UI Category
PATCH /api/ui/categories/categories/{id}
Partial UI category update. Path segment is doubled — see the warning under Update UI Category by ID.
Required scope: ui:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Category ID. |
Request body — UiCategoryWriteUpdate
Response 200 — UiCategoryRead
Delete UI Category by ID
DELETE /api/ui/categories/categories/{id}
Removes the UI category. Path segment is doubled — see the warning under Update UI Category by ID.
Required scope: ui:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Category ID. |
Response 204 — empty.
UI Variables
Individual configurable values that the UI shell consumes.
List UI Variables
GET /api/ui/variables/
Returns a page of UI variables.
Required scope: ui:read · also accepts API key
Query parameters — standard pagination set; see Conventions › Pagination. Defaults: sort_by=created, sort_order=desc, hydrate=true.
Response 200 — UiVariableInDbCursorPage
Get UI Variable Filter Metadata
GET /api/ui/variables/filters
Returns filter/operator/sort options for List UI Variables.
Required scope: ui:read
Response 200 — open metadata object.
Get UI Variable by ID
GET /api/ui/variables/{id}
Returns a single UI variable.
Required scope: ui:read · also accepts API key
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Variable ID. |
Response 200 — UiVariableRead
Create UI Variable
POST /api/ui/variables/
Creates a new UI variable.
Required scope: ui:write
Request body — UiVariableWriteCreate
Response 201 — UiVariableRead
Update UI Variable by ID
PUT /api/ui/variables/variables/{id}
Replaces a UI variable. Path segment is doubled — /variables/variables/{id} is the literal path.
Required scope: ui:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Variable ID. |
Request body — UiVariableWriteReplace
Response 200 — UiVariableRead
Patch UI Variable
PATCH /api/ui/variables/variables/{id}
Partial UI variable update. Path segment is doubled.
Required scope: ui:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Variable ID. |
Request body — UiVariableWriteUpdate
Response 200 — UiVariableRead
Delete UI Variable by ID
DELETE /api/ui/variables/variables/{id}
Deletes a UI variable. Path segment is doubled.
Required scope: ui:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Variable ID. |
Response 204 — empty.
See also
- Themes — whole-package branding (selected via
POST /api/themes/{id_or_name}/activate). - Mail Templates — branded transactional emails.