Florality

PATCH

/api/v1/appearance

appearance: read_write1,000 requests/minute/key · all plans

Active API keys: Free 1, Pro 5, Pro+ 5. The request rate is the same on every plan.

Custom fonts

PRO Custom fonts require Pro. A denied custom-font entitlement returns 403; other appearance settings are checked by their own rules.

Parameters

No path or query parameters.

Request body

application/json · required

Unknown properties are rejected.

Name	Type	Required	Description
`themeMode`	`string`	Optional	Theme Mode. Allowed values: "light", "dark", "system".
`darkVariant`	`string`	Optional	Dark Variant. Allowed values: "default", "storm", "night", "moon".
`colorScheme`	`string`	Optional	Color Scheme.
`colourScheme`	`string`	Optional	Colour Scheme.
`customColorSchemeId`	`string \| null`	Optional	Custom Color Scheme Id.
`fontFamily`	`string`	Optional	Font Family.
`customFontId`	`string \| null`	Optional	Custom Font Id.
`fontSize`	`string`	Optional	Font Size. Allowed values: "small", "medium", "large".
`fontScale`	`number`	Optional	Font Scale.
`fontSizePx`	`number`	Optional	Font Size Px.
`amoledBase`	`boolean`	Optional	Amoled Base.
`reduceMotion`	`boolean`	Optional	Reduce Motion.
`memberBannerGradientsEnabled`	`boolean`	Optional	Member Banner Gradients Enabled.
`memberListLayoutMode`	`string`	Optional	Member List Layout Mode. Allowed values: "list", "grid".

Response schema

200

Successful response.

Name	Type	Required	Description
`_id`	`string`	Required	Unique identifier.
`_creationTime`	`number`	Required	_creation Time.
`userId`	`string`	Required	Owning account identifier.
`themeMode`	`string`	Required	Theme Mode. Allowed values: "light", "dark", "system".
`darkVariant`	`string`	Optional	Dark Variant. Allowed values: "default", "storm", "night", "moon".
`colorScheme`	`string`	Optional	Color Scheme.
`colourScheme`	`string`	Optional	Colour Scheme.
`customColorSchemeId`	`string`	Optional	Custom Color Scheme Id.
`fontFamily`	`string`	Required	Font Family.
`customFontId`	`string`	Optional	Custom Font Id.
`fontSize`	`string`	Required	Font Size.
`fontScale`	`number`	Optional	Font Scale.
`fontSizePx`	`number`	Optional	Font Size Px.
`amoledBase`	`boolean`	Optional	Amoled Base. Allowed values: false, true.
`reduceMotion`	`boolean`	Optional	Reduce Motion. Allowed values: false, true.
`underlineLinks`	`boolean`	Optional	Underline Links. Allowed values: false, true.
`enhancedFocus`	`boolean`	Optional	Enhanced Focus. Allowed values: false, true.
`memberBannerGradientsEnabled`	`boolean`	Optional	Member Banner Gradients Enabled. Allowed values: false, true.
`memberListBannersEnabled`	`boolean`	Optional	Member List Banners Enabled. Full banner photos on members list cards. Independent of gradient strips. Allowed values: false, true.
`memberAnimatedGifsDisabled`	`boolean`	Optional	Member Animated Gifs Disabled. When true, member avatars and banners show the first frame of GIFs instead of animating. Allowed values: false, true.
`memberListLayoutMode`	`string`	Optional	Member List Layout Mode. Allowed values: "list", "grid".
`memberListGridActionStyle`	`string`	Optional	Member List Grid Action Style. Grid card front actions: `strip` (full-width bar) or `classic` (open-beta rounded buttons). Allowed values: "strip", "classic".
`memberListDisplayPreset`	`string`	Optional	Member List Display Preset. Saved settings preset; survives temporary list/grid toggles on the members page. Allowed values: "rows", "grid-photo", "grid-classic", "compact-rows", "panel-rows", "polaroid-grid".
`memberListRowPreset`	`string`	Optional	Member List Row Preset. Desktop list row style, independent of grid preset. Allowed values: "rows", "compact-rows", "panel-rows".
`memberListGridPreset`	`string`	Optional	Member List Grid Preset. Desktop grid style, independent of row preset. Allowed values: "grid-photo", "grid-classic", "polaroid-grid".
`memberListMobileLayoutStyle`	`string`	Optional	Member List Mobile Layout Style. Mobile members list: standard rows vs closed-beta classic cards. Allowed values: "classic", "standard".
`memberListMobileFrontButtonBehavior`	`string`	Optional	Member List Mobile Front Button Behavior. Mobile member list Front button: open action menu vs set as front on tap. Allowed values: "menu", "add-to-front", "set-as-front".
`memberListSortMode`	`string`	Optional	Member List Sort Mode. Members list sort mode. Omitted/`undefined` when never saved (clients may migrate localStorage → DB). Coalesced to `name_asc` on write/reset. Allowed values: "name_asc", "name_desc", "name_numeric_asc", "name_numeric_desc", "fronting_first", "fronting_first_name_desc", "fronting_first_name_numeric_asc", "directory_asc", "directory_desc", "fronting_first_directory_asc", "fronting_first_directory_desc".
`memberListSortNameField`	`string`	Optional	Member List Sort Name Field. Sort by display name vs member name. Omitted when never saved. Allowed values: "display", "alter".
`frontingMemberOpensProfile`	`boolean`	Optional	Fronting Member Opens Profile. Tap fronting member on dashboard → open member profile. Allowed values: false, true.
`hideFrontTypeLabels`	`boolean`	Optional	Hide Front Type Labels. Hide front type icons and labels on dashboard, friends, and profile surfaces. Allowed values: false, true.
`groupsDirectoryDragReorderEnabled`	`boolean`	Optional	Groups Directory Drag Reorder Enabled. Drag grip / long-press reorder on `/dashboard/groups` directory list. Allowed values: false, true.
`memberCustomFieldTagSuggestionsEnabled`	`boolean`	Optional	Member Custom Field Tag Suggestions Enabled. Suggest tags from same-label custom fields on other members while editing. Allowed values: false, true.
`membersListInfiniteScrollEnabled`	`boolean`	Optional	Members List Infinite Scroll Enabled. Scroll-to-load on `/dashboard/members` instead of prev/next page controls. Allowed values: false, true.
`membersListPaginationPosition`	`string`	Optional	Members List Pagination Position. Prev/next page controls above or below the members list when pagination is on. Allowed values: "top", "bottom".
`notesListInfiniteScrollEnabled`	`boolean`	Optional	Notes List Infinite Scroll Enabled. Allowed values: false, true.
`trashListInfiniteScrollEnabled`	`boolean`	Optional	Trash List Infinite Scroll Enabled. Allowed values: false, true.
`friendsListInfiniteScrollEnabled`	`boolean`	Optional	Friends List Infinite Scroll Enabled. Allowed values: false, true.
`archivedMembersListInfiniteScrollEnabled`	`boolean`	Optional	Archived Members List Infinite Scroll Enabled. Allowed values: false, true.
`notificationsListInfiniteScrollEnabled`	`boolean`	Optional	Notifications List Infinite Scroll Enabled. Allowed values: false, true.
`guestbookListInfiniteScrollEnabled`	`boolean`	Optional	Guestbook List Infinite Scroll Enabled. Allowed values: false, true.
`frontHistoryListInfiniteScrollEnabled`	`boolean`	Optional	Front History List Infinite Scroll Enabled. Allowed values: false, true.
`destructiveColor`	`null \| string`	Optional	Destructive Color. `#RRGGBB` override for `--destructive`; null = active colour scheme default.
`pdfExportAccentHex`	`null \| string`	Optional	Pdf Export Accent Hex.
`pdfExportLogoStorageId`	`null \| string`	Optional	Pdf Export Logo Storage Id.
`frontIndicatorBackgroundEnabled`	`boolean`	Optional	Front Indicator Background Enabled. Allowed values: false, true.
`frontIndicatorBackgroundStorageId`	`null \| string`	Optional	Front Indicator Background Storage Id.
`frontIndicatorBackgroundUrl`	`null \| string`	Optional	Front Indicator Background Url.
`updatedAt`	`number`	Required	Most recent update time.

Errors

400 · JSON error: Invalid JSON body.
401 · JSON error: Missing or invalid API key. Use Authorization: Bearer <token>.
403 · JSON error: Requires appearance: read_write; ownership or feature restrictions may also deny access.
404 · JSON error: Request failed (NOT_FOUND).
429 · JSON error: API rate limit exceeded (1000 requests per minute). Retry shortly.
500 · JSON error: Appearance update failed.

Request example

Set FLORALITY_KEY in your environment. These examples use demo identifiers.

Shell

curl --request PATCH 'https://floralitys.com/api/v1/appearance' \
  --header "Authorization: Bearer $FLORALITY_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "themeMode": "light"
}'

Responses

Successful response.

JSON

{
  "_id": "11111111-1111-4111-8111-111111111111",
  "_creationTime": 1767225600000,
  "userId": "11111111-1111-4111-8111-111111111111",
  "themeMode": "light",
  "darkVariant": "default",
  "colorScheme": "#70846b",
  "colourScheme": "#70846b",
  "customColorSchemeId": "11111111-1111-4111-8111-111111111111",
  "fontFamily": "demo",
  "customFontId": "11111111-1111-4111-8111-111111111111",
  "fontSize": "demo",
  "fontScale": 0,
  "fontSizePx": 0,
  "amoledBase": false,
  "reduceMotion": false,
  "underlineLinks": false,
  "enhancedFocus": false,
  "memberBannerGradientsEnabled": true,
  "memberListBannersEnabled": true,
  "memberAnimatedGifsDisabled": false,
  "memberListLayoutMode": "list",
  "memberListGridActionStyle": "strip",
  "memberListDisplayPreset": "rows",
  "memberListRowPreset": "rows",
  "memberListGridPreset": "grid-photo",
  "memberListMobileLayoutStyle": "classic",
  "memberListMobileFrontButtonBehavior": "menu",
  "memberListSortMode": "name_asc",
  "memberListSortNameField": "display",
  "frontingMemberOpensProfile": false,
  "hideFrontTypeLabels": false,
  "groupsDirectoryDragReorderEnabled": true,
  "memberCustomFieldTagSuggestionsEnabled": true,
  "membersListInfiniteScrollEnabled": true,
  "membersListPaginationPosition": "top",
  "notesListInfiniteScrollEnabled": true,
  "trashListInfiniteScrollEnabled": true,
  "friendsListInfiniteScrollEnabled": true,
  "archivedMembersListInfiniteScrollEnabled": true,
  "notificationsListInfiniteScrollEnabled": true,
  "guestbookListInfiniteScrollEnabled": true,
  "frontHistoryListInfiniteScrollEnabled": true,
  "destructiveColor": null,
  "pdfExportAccentHex": null,
  "pdfExportLogoStorageId": null,
  "frontIndicatorBackgroundEnabled": true,
  "frontIndicatorBackgroundStorageId": null,
  "frontIndicatorBackgroundUrl": null,
  "updatedAt": 1767225600000
}

Example values are illustrative demo data.

Request body

application/json · required

Unknown properties are rejected.

Name	Type	Required	Description
`themeMode`	`string`	Optional	Theme Mode. Allowed values: "light", "dark", "system".
`darkVariant`	`string`	Optional	Dark Variant. Allowed values: "default", "storm", "night", "moon".
`colorScheme`	`string`	Optional	Color Scheme.
`colourScheme`	`string`	Optional	Colour Scheme.
`customColorSchemeId`	`string \| null`	Optional	Custom Color Scheme Id.
`fontFamily`	`string`	Optional	Font Family.
`customFontId`	`string \| null`	Optional	Custom Font Id.
`fontSize`	`string`	Optional	Font Size. Allowed values: "small", "medium", "large".
`fontScale`	`number`	Optional	Font Scale.
`fontSizePx`	`number`	Optional	Font Size Px.
`amoledBase`	`boolean`	Optional	Amoled Base.
`reduceMotion`	`boolean`	Optional	Reduce Motion.
`memberBannerGradientsEnabled`	`boolean`	Optional	Member Banner Gradients Enabled.
`memberListLayoutMode`	`string`	Optional	Member List Layout Mode. Allowed values: "list", "grid".

Response schema

200

Successful response.

Name	Type	Required	Description
`_id`	`string`	Required	Unique identifier.
`_creationTime`	`number`	Required	_creation Time.
`userId`	`string`	Required	Owning account identifier.
`themeMode`	`string`	Required	Theme Mode. Allowed values: "light", "dark", "system".
`darkVariant`	`string`	Optional	Dark Variant. Allowed values: "default", "storm", "night", "moon".
`colorScheme`	`string`	Optional	Color Scheme.
`colourScheme`	`string`	Optional	Colour Scheme.
`customColorSchemeId`	`string`	Optional	Custom Color Scheme Id.
`fontFamily`	`string`	Required	Font Family.
`customFontId`	`string`	Optional	Custom Font Id.
`fontSize`	`string`	Required	Font Size.
`fontScale`	`number`	Optional	Font Scale.
`fontSizePx`	`number`	Optional	Font Size Px.
`amoledBase`	`boolean`	Optional	Amoled Base. Allowed values: false, true.
`reduceMotion`	`boolean`	Optional	Reduce Motion. Allowed values: false, true.
`underlineLinks`	`boolean`	Optional	Underline Links. Allowed values: false, true.
`enhancedFocus`	`boolean`	Optional	Enhanced Focus. Allowed values: false, true.
`memberBannerGradientsEnabled`	`boolean`	Optional	Member Banner Gradients Enabled. Allowed values: false, true.
`memberListBannersEnabled`	`boolean`	Optional	Member List Banners Enabled. Full banner photos on members list cards. Independent of gradient strips. Allowed values: false, true.
`memberAnimatedGifsDisabled`	`boolean`	Optional	Member Animated Gifs Disabled. When true, member avatars and banners show the first frame of GIFs instead of animating. Allowed values: false, true.
`memberListLayoutMode`	`string`	Optional	Member List Layout Mode. Allowed values: "list", "grid".
`memberListGridActionStyle`	`string`	Optional	Member List Grid Action Style. Grid card front actions: `strip` (full-width bar) or `classic` (open-beta rounded buttons). Allowed values: "strip", "classic".
`memberListDisplayPreset`	`string`	Optional	Member List Display Preset. Saved settings preset; survives temporary list/grid toggles on the members page. Allowed values: "rows", "grid-photo", "grid-classic", "compact-rows", "panel-rows", "polaroid-grid".
`memberListRowPreset`	`string`	Optional	Member List Row Preset. Desktop list row style, independent of grid preset. Allowed values: "rows", "compact-rows", "panel-rows".
`memberListGridPreset`	`string`	Optional	Member List Grid Preset. Desktop grid style, independent of row preset. Allowed values: "grid-photo", "grid-classic", "polaroid-grid".
`memberListMobileLayoutStyle`	`string`	Optional	Member List Mobile Layout Style. Mobile members list: standard rows vs closed-beta classic cards. Allowed values: "classic", "standard".
`memberListMobileFrontButtonBehavior`	`string`	Optional	Member List Mobile Front Button Behavior. Mobile member list Front button: open action menu vs set as front on tap. Allowed values: "menu", "add-to-front", "set-as-front".
`memberListSortMode`	`string`	Optional	Member List Sort Mode. Members list sort mode. Omitted/`undefined` when never saved (clients may migrate localStorage → DB). Coalesced to `name_asc` on write/reset. Allowed values: "name_asc", "name_desc", "name_numeric_asc", "name_numeric_desc", "fronting_first", "fronting_first_name_desc", "fronting_first_name_numeric_asc", "directory_asc", "directory_desc", "fronting_first_directory_asc", "fronting_first_directory_desc".
`memberListSortNameField`	`string`	Optional	Member List Sort Name Field. Sort by display name vs member name. Omitted when never saved. Allowed values: "display", "alter".
`frontingMemberOpensProfile`	`boolean`	Optional	Fronting Member Opens Profile. Tap fronting member on dashboard → open member profile. Allowed values: false, true.
`hideFrontTypeLabels`	`boolean`	Optional	Hide Front Type Labels. Hide front type icons and labels on dashboard, friends, and profile surfaces. Allowed values: false, true.
`groupsDirectoryDragReorderEnabled`	`boolean`	Optional	Groups Directory Drag Reorder Enabled. Drag grip / long-press reorder on `/dashboard/groups` directory list. Allowed values: false, true.
`memberCustomFieldTagSuggestionsEnabled`	`boolean`	Optional	Member Custom Field Tag Suggestions Enabled. Suggest tags from same-label custom fields on other members while editing. Allowed values: false, true.
`membersListInfiniteScrollEnabled`	`boolean`	Optional	Members List Infinite Scroll Enabled. Scroll-to-load on `/dashboard/members` instead of prev/next page controls. Allowed values: false, true.
`membersListPaginationPosition`	`string`	Optional	Members List Pagination Position. Prev/next page controls above or below the members list when pagination is on. Allowed values: "top", "bottom".
`notesListInfiniteScrollEnabled`	`boolean`	Optional	Notes List Infinite Scroll Enabled. Allowed values: false, true.
`trashListInfiniteScrollEnabled`	`boolean`	Optional	Trash List Infinite Scroll Enabled. Allowed values: false, true.
`friendsListInfiniteScrollEnabled`	`boolean`	Optional	Friends List Infinite Scroll Enabled. Allowed values: false, true.
`archivedMembersListInfiniteScrollEnabled`	`boolean`	Optional	Archived Members List Infinite Scroll Enabled. Allowed values: false, true.
`notificationsListInfiniteScrollEnabled`	`boolean`	Optional	Notifications List Infinite Scroll Enabled. Allowed values: false, true.
`guestbookListInfiniteScrollEnabled`	`boolean`	Optional	Guestbook List Infinite Scroll Enabled. Allowed values: false, true.
`frontHistoryListInfiniteScrollEnabled`	`boolean`	Optional	Front History List Infinite Scroll Enabled. Allowed values: false, true.
`destructiveColor`	`null \| string`	Optional	Destructive Color. `#RRGGBB` override for `--destructive`; null = active colour scheme default.
`pdfExportAccentHex`	`null \| string`	Optional	Pdf Export Accent Hex.
`pdfExportLogoStorageId`	`null \| string`	Optional	Pdf Export Logo Storage Id.
`frontIndicatorBackgroundEnabled`	`boolean`	Optional	Front Indicator Background Enabled. Allowed values: false, true.
`frontIndicatorBackgroundStorageId`	`null \| string`	Optional	Front Indicator Background Storage Id.
`frontIndicatorBackgroundUrl`	`null \| string`	Optional	Front Indicator Background Url.
`updatedAt`	`number`	Required	Most recent update time.

Errors

400 · JSON error

Invalid JSON body.

401 · JSON error

Missing or invalid API key. Use Authorization: Bearer <token>.

403 · JSON error

Requires appearance: read_write; ownership or feature restrictions may also deny access.

404 · JSON error

Request failed (NOT_FOUND).

429 · JSON error

API rate limit exceeded (1000 requests per minute). Retry shortly.

500 · JSON error

Appearance update failed.

Request example

Set FLORALITY_KEY in your environment. These examples use demo identifiers.

Shell

curl --request PATCH 'https://floralitys.com/api/v1/appearance' \
  --header "Authorization: Bearer $FLORALITY_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "themeMode": "light"
}'

Responses

Successful response.

JSON

{
  "_id": "11111111-1111-4111-8111-111111111111",
  "_creationTime": 1767225600000,
  "userId": "11111111-1111-4111-8111-111111111111",
  "themeMode": "light",
  "darkVariant": "default",
  "colorScheme": "#70846b",
  "colourScheme": "#70846b",
  "customColorSchemeId": "11111111-1111-4111-8111-111111111111",
  "fontFamily": "demo",
  "customFontId": "11111111-1111-4111-8111-111111111111",
  "fontSize": "demo",
  "fontScale": 0,
  "fontSizePx": 0,
  "amoledBase": false,
  "reduceMotion": false,
  "underlineLinks": false,
  "enhancedFocus": false,
  "memberBannerGradientsEnabled": true,
  "memberListBannersEnabled": true,
  "memberAnimatedGifsDisabled": false,
  "memberListLayoutMode": "list",
  "memberListGridActionStyle": "strip",
  "memberListDisplayPreset": "rows",
  "memberListRowPreset": "rows",
  "memberListGridPreset": "grid-photo",
  "memberListMobileLayoutStyle": "classic",
  "memberListMobileFrontButtonBehavior": "menu",
  "memberListSortMode": "name_asc",
  "memberListSortNameField": "display",
  "frontingMemberOpensProfile": false,
  "hideFrontTypeLabels": false,
  "groupsDirectoryDragReorderEnabled": true,
  "memberCustomFieldTagSuggestionsEnabled": true,
  "membersListInfiniteScrollEnabled": true,
  "membersListPaginationPosition": "top",
  "notesListInfiniteScrollEnabled": true,
  "trashListInfiniteScrollEnabled": true,
  "friendsListInfiniteScrollEnabled": true,
  "archivedMembersListInfiniteScrollEnabled": true,
  "notificationsListInfiniteScrollEnabled": true,
  "guestbookListInfiniteScrollEnabled": true,
  "frontHistoryListInfiniteScrollEnabled": true,
  "destructiveColor": null,
  "pdfExportAccentHex": null,
  "pdfExportLogoStorageId": null,
  "frontIndicatorBackgroundEnabled": true,
  "frontIndicatorBackgroundStorageId": null,
  "frontIndicatorBackgroundUrl": null,
  "updatedAt": 1767225600000
}

Example values are illustrative demo data.

Update appearance

Parameters

Request body

Response schema

200

Errors

Request example

Responses

Update appearance

Parameters

Request body

Response schema

200

Errors

Request example

Responses