Front

Base path: /api/v1/front. Current fronters (ordered members + active sessions), tier presence summaries, cursor-paginated history, and mutations (add/remove/reorder/clear, tier assign/remove). Read needs front: read. Write needs front: read_write.

Member media in JSON uses the same /api/v1/members/{id}/media?… URLs as Members when stored as MinIO refs; the same Bearer token works for those URLs.

Get current front

GET/api/v1/front

Response

200

memberIds: UUIDs in front order (same order as members)
members: full member objects for current fronters (see Members list shape)
activeSessions: open frontSessions rows (_id is session id, Unix ms timestamps)
primaryMemberId: primary fronter member id or null
primaryNote: note on the primary session when set
tieredPresence: co-front / co-conscious / custom tiers (slim rows; join to members by memberId)

JSON

{
  "memberIds": ["b1c2d3e4-f5a6-7890-abcd-ef1234567890"],
  "members": [
    {
      "_id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "userId": "…",
      "directoryId": "…",
      "name": "Alex",
      "displayName": "Alex R.",
      "pronouns": "they/them",
      "avatarUrl": "/api/v1/members/b1c2…/media?kind=avatar&v=0",
      "backgroundUrl": null,
      "aboutTags": [],
      "profileStyle": null,
      "archivedAt": null,
      "createdAt": 1714233600000,
      "updatedAt": 1714237200000
    }
  ],
  "activeSessions": [
    {
      "_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "userId": "…",
      "memberId": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "startedAt": 1714233600000,
      "note": "optional session note"
    }
  ],
  "primaryMemberId": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
  "primaryNote": "optional session note",
  "tieredPresence": [
    {
      "memberId": "c2d3e4f5-a6b7-8901-bcde-f12345678901",
      "tierKey": "coFront",
      "tierDisplayName": "Co-front",
      "note": null
    }
  ]
}

Examples

cURL

Shell

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

JavaScript (fetch)

JavaScript

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

Status codes

200: JSON object
401 / 403: auth / scope

List front history

GET/api/v1/front/history

Query parameters

Parameter	Type	Notes
`limit`	integer	Optional, 1–100, default 20
`startTime` / `endTime`	integer (Unix ms)	Optional; filter sessions overlapping the range
`cursorStartedAt` + `cursorId`	number + UUID	Optional pagination cursor (both required together); use nextCursor from the previous response

Response

200

Newest first. items[].durationMs is null for still-open sessions. count is the total number of history sessions matching the query (including startTime / endTime when set), not just the current page. nextCursor is null when there is no next page.

JSON

{
  "items": [
    {
      "session": {
        "_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "userId": "…",
        "memberId": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
        "startedAt": 1714233600000,
        "endedAt": 1714237200000
      },
      "member": {
        "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
        "name": "Alex",
        "displayName": "Alex R.",
        "archived": false,
        "avatarUrl": "/api/v1/members/b1c2…/media?kind=avatar&v=0"
      },
      "durationMs": 3600000
    }
  ],
  "count": 142,
  "nextCursor": { "startedAt": 1714230000000, "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }
}

Examples

cURL

Shell

curl -sS \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/front/history?limit=20"

JavaScript (fetch)

JavaScript

const url = new URL("https://api.floralitys.com/api/v1/front/history");
url.searchParams.set("limit", "20");
const res = await fetch(url.toString(), {
  headers: { Authorization: "Bearer YOUR_TOKEN" },
});
if (!res.ok) throw new Error(await res.text());
const { items, count, nextCursor } = await res.json();

Status codes

200: JSON object with items, count, and nextCursor
400: invalid query (e.g. only one of the cursor pair set)
401 / 403: auth / scope

Clear front

DELETE/api/v1/front

Ends all active sessions, clears front order and tier presence.

Response

204

Plain text

// 204 No Content: empty response body

Examples

Shell

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

Status codes

204: success, no body
401 / 403: auth / scope

Add member to front

POST/api/v1/front/members

Strict JSON: memberId (UUID, required), optional note, optional createdBy (member UUID). No-op with 204 if that member is already fronting.

Examples

Shell

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"memberId":"MEMBER_UUID"}' \
  "https://api.floralitys.com/api/v1/front/members"

Status codes

204: success
400: invalid body or business rule (see message)
401 / 403: auth / scope

Example error body:

JSON

{
  "code": "BAD_REQUEST",
  "message": "Reorder list must match the current set of fronting members exactly"
}

Remove member from front

DELETE/api/v1/front/members/{memberId}

Examples

Shell

curl -sS -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/front/members/MEMBER_UUID"

Status codes

204: success
400: not found / access denied (same error envelope)
401 / 403: auth / scope

Reorder fronters

PATCH/api/v1/front/order

Strict JSON: memberIds: array of member UUIDs, must match the current active front set exactly (same members, new order).

Examples

Shell

curl -sS -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"memberIds":["UUID_A","UUID_B"]}' \
  "https://api.floralitys.com/api/v1/front/order"

Status codes

204: success
400: invalid body or reorder rule violation
401 / 403: auth / scope

Assign tier presence

POST/api/v1/front/tier-presence

Strict JSON: memberId (UUID), tierKey (preset e.g. coFront / coConscious, or a custom tier id), optional note. Cannot assign a tier to the current primary fronter.

Examples

Shell

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"memberId":"MEMBER_UUID","tierKey":"coFront"}' \
  "https://api.floralitys.com/api/v1/front/tier-presence"

Status codes

204: success
400: validation / invalid tier / primary conflict
401 / 403: auth / scope

Remove tier presence

DELETE/api/v1/front/tier-presence/{memberId}

Examples

Shell

curl -sS -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/front/tier-presence/MEMBER_UUID"

Status codes

204: success
400: invalid id
401 / 403: auth / scope

Front

Member media in JSON uses the same /api/v1/members/{id}/media?… URLs as Members when stored as MinIO refs; the same Bearer token works for those URLs.

Get current front

GET/api/v1/front

Response

200

memberIds: UUIDs in front order (same order as members)
members: full member objects for current fronters (see Members list shape)
activeSessions: open frontSessions rows (_id is session id, Unix ms timestamps)
primaryMemberId: primary fronter member id or null
primaryNote: note on the primary session when set
tieredPresence: co-front / co-conscious / custom tiers (slim rows; join to members by memberId)

JSON

{
  "memberIds": ["b1c2d3e4-f5a6-7890-abcd-ef1234567890"],
  "members": [
    {
      "_id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "userId": "…",
      "directoryId": "…",
      "name": "Alex",
      "displayName": "Alex R.",
      "pronouns": "they/them",
      "avatarUrl": "/api/v1/members/b1c2…/media?kind=avatar&v=0",
      "backgroundUrl": null,
      "aboutTags": [],
      "profileStyle": null,
      "archivedAt": null,
      "createdAt": 1714233600000,
      "updatedAt": 1714237200000
    }
  ],
  "activeSessions": [
    {
      "_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "userId": "…",
      "memberId": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "startedAt": 1714233600000,
      "note": "optional session note"
    }
  ],
  "primaryMemberId": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
  "primaryNote": "optional session note",
  "tieredPresence": [
    {
      "memberId": "c2d3e4f5-a6b7-8901-bcde-f12345678901",
      "tierKey": "coFront",
      "tierDisplayName": "Co-front",
      "note": null
    }
  ]
}

Examples

cURL

Shell

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

JavaScript (fetch)

JavaScript

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

Status codes

200: JSON object
401 / 403: auth / scope

List front history

GET/api/v1/front/history

Query parameters

Parameter	Type	Notes
`limit`	integer	Optional, 1–100, default 20
`startTime` / `endTime`	integer (Unix ms)	Optional; filter sessions overlapping the range
`cursorStartedAt` + `cursorId`	number + UUID	Optional pagination cursor (both required together); use nextCursor from the previous response

Response

200

JSON

{
  "items": [
    {
      "session": {
        "_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "userId": "…",
        "memberId": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
        "startedAt": 1714233600000,
        "endedAt": 1714237200000
      },
      "member": {
        "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
        "name": "Alex",
        "displayName": "Alex R.",
        "archived": false,
        "avatarUrl": "/api/v1/members/b1c2…/media?kind=avatar&v=0"
      },
      "durationMs": 3600000
    }
  ],
  "count": 142,
  "nextCursor": { "startedAt": 1714230000000, "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }
}

Examples

cURL

Shell

curl -sS \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/front/history?limit=20"

JavaScript (fetch)

JavaScript

const url = new URL("https://api.floralitys.com/api/v1/front/history");
url.searchParams.set("limit", "20");
const res = await fetch(url.toString(), {
  headers: { Authorization: "Bearer YOUR_TOKEN" },
});
if (!res.ok) throw new Error(await res.text());
const { items, count, nextCursor } = await res.json();

Status codes

200: JSON object with items, count, and nextCursor
400: invalid query (e.g. only one of the cursor pair set)
401 / 403: auth / scope

Clear front

DELETE/api/v1/front

Ends all active sessions, clears front order and tier presence.

Response

204

Plain text

// 204 No Content: empty response body

Examples

Shell

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

Status codes

204: success, no body
401 / 403: auth / scope

Add member to front

POST/api/v1/front/members

Strict JSON: memberId (UUID, required), optional note, optional createdBy (member UUID). No-op with 204 if that member is already fronting.

Examples

Shell

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"memberId":"MEMBER_UUID"}' \
  "https://api.floralitys.com/api/v1/front/members"

Status codes

204: success
400: invalid body or business rule (see message)
401 / 403: auth / scope

Example error body:

JSON

{
  "code": "BAD_REQUEST",
  "message": "Reorder list must match the current set of fronting members exactly"
}

Remove member from front

DELETE/api/v1/front/members/{memberId}

Examples

Shell

curl -sS -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/front/members/MEMBER_UUID"

Status codes

204: success
400: not found / access denied (same error envelope)
401 / 403: auth / scope

Reorder fronters

PATCH/api/v1/front/order

Strict JSON: memberIds: array of member UUIDs, must match the current active front set exactly (same members, new order).

Examples

Shell

curl -sS -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"memberIds":["UUID_A","UUID_B"]}' \
  "https://api.floralitys.com/api/v1/front/order"

Status codes

204: success
400: invalid body or reorder rule violation
401 / 403: auth / scope

Assign tier presence

POST/api/v1/front/tier-presence

Strict JSON: memberId (UUID), tierKey (preset e.g. coFront / coConscious, or a custom tier id), optional note. Cannot assign a tier to the current primary fronter.

Examples

Shell

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"memberId":"MEMBER_UUID","tierKey":"coFront"}' \
  "https://api.floralitys.com/api/v1/front/tier-presence"

Status codes

204: success
400: validation / invalid tier / primary conflict
401 / 403: auth / scope

Remove tier presence

DELETE/api/v1/front/tier-presence/{memberId}

Examples

Shell

curl -sS -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/front/tier-presence/MEMBER_UUID"

Status codes

204: success
400: invalid id
401 / 403: auth / scope