Terminology

Customize display labels in the Florality UI: nouns like "member" and "system", workflow strings like trash/archive actions, and the trash icon preset. API paths, database tables, and scope names do not change; only user-facing copy does.

Base path: /api/v1/terminology. Read (GET) needs terminology: read. Write (PATCH, POST) needs terminology: read_write. See Authentication and Scopes.

Labels are scoped in layers: global (account-wide) → side system → sub system. Unified account view uses global labels only. Side/sub overrides apply when that system is active.

Concepts

• Global settings: stored per account; returned by GET /terminology when configured.
• Resolved labels: effective dictionary after merging global + optional side/sub overrides; always includes defaults for missing keys.
• Scoped overrides: partial patches stored per side or sub system; only fields that differ from the inherited layer are persisted.

Each noun key accepts singular and plural strings (max 40 characters, trimmed and title-cased). Empty strings fall back to product defaults.

Customizable keys

Nouns (terms)

Actions (actions)

archiveMember, archivedMembers, trash, deleteMember, permanentlyDeleteMember, unarchiveMember, restoreFromTrash, mostFronted.

Icons (icons)

trash: preset keys fa-tombstone-blank (default) or fa-trash, or another catalog icon id.

Endpoint index

Get global settings

GET/api/v1/terminology

Returns the stored global document, or null if the account has never saved terminology (clients should use /resolved for effective labels with defaults).

{
  "_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "_creationTime": 1714237200000,
  "userId": "a0a0a0a0-a0a0-a0a0-a0a0-a0a0a0a0a0a0",
  "terms": {
    "member": { "singular": "Alter", "plural": "Alters" },
    "group": { "singular": "Group", "plural": "Groups" },
    "folder": { "singular": "Group", "plural": "Groups" },
    "system": { "singular": "System", "plural": "Systems" },
    "front": { "singular": "Front", "plural": "Fronts" },
    "friend": { "singular": "Friend", "plural": "Friends" },
    "note": { "singular": "Note", "plural": "Notes" },
    "privacyBucket": { "singular": "Privacy bucket", "plural": "Privacy buckets" },
    "customField": { "singular": "Custom field", "plural": "Custom fields" },
    "sideSystem": { "singular": "Side system", "plural": "Side systems" },
    "subSystem": { "singular": "Sub system", "plural": "Sub systems" }
  },
  "actions": {
    "archiveMember": "Move out",
    "archivedMembers": "Moved out",
    "trash": "The graveyard",
    "deleteMember": "Take them out back",
    "permanentlyDeleteMember": "Banish them to the shadow realm",
    "unarchiveMember": "Move in",
    "restoreFromTrash": "Quick Revive",
    "mostFronted": "Most fronted"
  },
  "icons": {
    "trash": "fa-tombstone-blank"
  },
  "updatedAt": 1714237200000
}

null

curl -sS \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/terminology"

Update global settings

PATCH/api/v1/terminology

Partial update. Top-level noun keys plus optional nested actions and icons. Omitted keys are unchanged. Merges with existing values, then returns the full settings document (200).

Example body fields:

{
  "member": { "singular": "alter", "plural": "alters" },
  "actions": { "trash": "The void" },
  "icons": { "trash": "fa-trash" }
}

curl -sS -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "member": { "singular": "alter", "plural": "alters" },
    "actions": { "trash": "The void" }
  }' \
  "https://api.floralitys.com/api/v1/terminology"

Reset global settings

POST/api/v1/terminology/reset

Restores all global nouns, actions, and icons to product defaults. Creates a row if none exists. Returns the settings document (200).

Get resolved labels

GET/api/v1/terminology/resolved

Effective labels for a scope, with defaults filled in. Response matches TerminologySettingsDoc plus metadata:

• scope: { "kind": "global" }, { "kind": "side", "sideSystemId": "…" }, or { "kind": "sub", "sideSystemId": "…", "subSystemId": "…" }
• hasSideOverride, hasSubOverride: whether stored overrides exist at that layer

Query parameters

{
  "_id": "resolved",
  "_creationTime": 1714237200000,
  "userId": "a0a0a0a0-a0a0-a0a0-a0a0-a0a0a0a0a0a0",
  "terms": { "...": "merged labels for the requested scope" },
  "actions": { "...": "merged action labels" },
  "icons": { "trash": "fa-tombstone-blank" },
  "updatedAt": 1714237200000,
  "scope": {
    "kind": "sub",
    "sideSystemId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "subSystemId": "b1c2d3e4-f5a6-7890-abcd-ef1234567890"
  },
  "hasSideOverride": true,
  "hasSubOverride": false
}

curl -sS \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/terminology/resolved?sideSystemId=SIDE_SYSTEM_UUID&subSystemId=SUB_SYSTEM_UUID"

Set scoped overrides

PATCH/api/v1/terminology/scoped

Upsert side- or sub-system terminology overrides. Body (strict):

{
  "sideSystemId": "SIDE_SYSTEM_UUID",
  "subSystemId": null,
  "terms": {
    "system": { "singular": "headspace", "plural": "headspaces" }
  }
}

• Omit subSystemId or set null to edit the side layer.
• Set subSystemId to a UUID to edit the sub layer (inherits global + side, then applies sub patch).
• terms uses the same shape as global PATCH (nouns, actions, icons).
• If the patch matches inherited labels, the override row is removed.

Returns resolved document for that scope (200).

curl -sS -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sideSystemId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "subSystemId": null,
    "terms": {
      "system": { "singular": "headspace", "plural": "headspaces" }
    }
  }' \
  "https://api.floralitys.com/api/v1/terminology/scoped"

Reset scoped overrides

POST/api/v1/terminology/scoped

Deletes overrides for the given scope. Body:

{
  "sideSystemId": "SIDE_SYSTEM_UUID",
  "subSystemId": "SUB_SYSTEM_UUID"
}

Omit or null subSystemId to clear side-level overrides only. Returns resolved labels after reset (200).

Errors

JSON errors: { code, message }. Common codes: UNAUTHORIZED (401), FORBIDDEN (403), BAD_REQUEST (400): invalid UUID, unknown system, invalid body. PRECONDITION_FAILED (503) when the terminology tables are missing (migrations not applied).

{
  "code": "PRECONDITION_FAILED",
  "message": "Terminology storage is temporarily unavailable. Run latest migrations and retry."
}

See Errors.