Systems

Side systems and sub systems partition members, groups, notes, front state, and related data. The dashboard system switcher selects which bucket is active; optional unified view merges reads across the account while writes still target the persisted active side/sub pair.

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

Listing members and groups without query parameters uses the account's effective . Pass explicit sideSystemId and optional subSystemId to read another bucket (those endpoints use the members / groups scopes, not systems).

Concepts

• Side system: top-level partition (every account has at least one; a default is created automatically).
• Sub system: nested partition under a side system, always linked to one member in that side system.
• Active scope: which side (and optional sub) the UI treats as selected; returned in active on list.
• Unified view: when isUnifiedView is true, many reads ignore scope filters; setting active scope clears unified view.

Side system object

Sub system object

List systems

GET/api/v1/systems

Returns the active context plus all non-deleted side systems and sub systems for the account.

Response

200: object with active, sideSystems, and subSystems.

{
  "active": {
    "sideSystemId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "subSystemId": null,
    "isUnifiedView": false,
    "updatedAt": 1714237200000
  },
  "sideSystems": [
    {
      "_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "userId": "a0a0a0a0-a0a0-a0a0-a0a0-a0a0a0a0a0a0",
      "name": "Default",
      "description": null,
      "icon": null,
      "tagCode": null,
      "tagColor": null,
      "createdAt": 1714233600000,
      "updatedAt": 1714237200000
    }
  ],
  "subSystems": [
    {
      "_id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "userId": "a0a0a0a0-a0a0-a0a0-a0a0-a0a0a0a0a0a0",
      "sideSystemId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "parentSubSystemId": null,
      "linkedMemberId": "c2d3e4f5-a6b7-8901-cdef-123456789abc",
      "name": "River",
      "createdAt": 1714233600000,
      "updatedAt": 1714237200000
    }
  ]
}

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

const res = await fetch("https://api.floralitys.com/api/v1/systems", {
  headers: { Authorization: "Bearer YOUR_TOKEN" },
});
if (!res.ok) throw new Error(await res.text());
const systems = await res.json();

Set active scope

PATCH/api/v1/systems/active

Selects the side system (and optional sub system) for the dashboard switcher. Turns off unified view.

Request body

sideSystemId (required UUID), subSystemId (optional UUID or null for side-only scope).

Response

200: updated ActiveSystemContext. 404 if side/sub not found or sub not in side.

{
  "sideSystemId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "subSystemId": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
  "isUnifiedView": false,
  "updatedAt": 1714237200000
}

curl -sS -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sideSystemId":"SIDE_SYSTEM_UUID","subSystemId":null}' \
  "https://api.floralitys.com/api/v1/systems/active"

Toggle unified view

PATCH/api/v1/systems/unified-view

Request body

{ "enabled": true }

When enabled, reads that respect scope may aggregate across systems; the active side/sub ids are still stored for writes.

Response

200: updated active context (includes isUnifiedView).

Create side system

POST/api/v1/systems/side-systems

Request body

name (required, 1–80 characters). Optional: description, icon, tagCode, tagColor.

Response

201: created side system object.

{
  "_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "userId": "a0a0a0a0-a0a0-a0a0-a0a0-a0a0a0a0a0a0",
  "name": "Work",
  "description": "Office system",
  "icon": "briefcase",
  "tagCode": "WRK",
  "tagColor": "#3B82F6",
  "createdAt": 1714233600000,
  "updatedAt": 1714233600000
}

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Work","tagCode":"WRK","tagColor":"#3B82F6"}' \
  "https://api.floralitys.com/api/v1/systems/side-systems"

Create sub system

POST/api/v1/systems/sub-systems

Request body

sideSystemId and linkedMemberId (required). name (required). Optional: parentSubSystemId, description, icon, tagCode, tagColor.

Response

201: created sub system object.

Update side system

PATCH/api/v1/systems/side-systems/{sideSystemId}

Partial update of name, description, icon, tagCode, or tagColor.

Response

200: updated side system. 404 if not found.

Delete side system

DELETE/api/v1/systems/side-systems/{sideSystemId}

Soft-deletes the side system. Fails if it is the last side system, still has sub systems, or still has members/groups/notes/front data in that bucket. Active scope moves to another side system when the deleted one was selected.

Response

200: { success: true }. 400 when deletion is blocked.

{
  "success": true
}

{
  "code": "BAD_REQUEST",
  "message": "Side system has data. Move members, groups, notes, or folders out before deleting."
}

Update sub system

PATCH/api/v1/systems/sub-systems/{subSystemId}

Partial update. May change parentSubSystemId or linkedMemberId (new member must live in the same side system).

Response

200: updated sub system.

Delete sub system

DELETE/api/v1/systems/sub-systems/{subSystemId}

Soft-deletes the sub system. Fails if any data still references that sub system id. Clears active sub selection when this sub was active.

Response

200: { success: true }.

Assignable members

GET/api/v1/systems/side-systems/{sideSystemId}/assignable-members

Active, non-archived members in the given side system: used when creating a sub system and linking it to a member.

Response

200: array of { _id, name } options (name prefers display name).

[
  {
    "_id": "c2d3e4f5-a6b7-8901-cdef-123456789abc",
    "name": "River"
  }
]

Scoped members and groups

These endpoints are documented on their own pages but are the main way automation reads data inside a system bucket:

Omit query params to list using the account's effective active scope (respects unified view the same way as the dashboard).

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

Errors

Failures return { code, message }. Common codes: UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), BAD_REQUEST (400). See Errors.

{
  "code": "NOT_FOUND",
  "message": "Side system not found."
}