Privacy buckets

Privacy buckets label who can see what. You assign buckets to friends (which trust levels they have) and buckets to content (members, groups, notes fields, profile sections, systems). A friend only sees content when one of their buckets overlaps a content bucket's assignment.

Base path: /api/v1/privacy-buckets. Read (GET) needs privacyBuckets: read. Write (POST, PATCH, PUT, DELETE) needs privacyBuckets: read_write. See Authentication and Scopes.

New accounts get seeded presets (e.g. Regular friends, Trusted friend, Partner, Complete privacy). Built-in buckets use fixed slug values and cannot be deleted.

Concepts

• Bucket: named label with optional icon and a friend permission matrix (what friends in this bucket may access).
• Friend assignment: which buckets a friend belongs to.
• Content assignment: which buckets gate a member, group, directory (folder), custom field definition, profile section, side system, or sub system.
• Defaults: buckets auto-applied when you create new members, groups, etc.
• Bulk adjust: add or remove one bucket from many friends/members/groups at once.

Friend permission groups

On create/patch, optional friendPermissions maps each group to none, read, or read_write:

Overlapping buckets merge with the maximum access level per group.

Endpoint index

All paths are prefixed with /api/v1.

List buckets

GET/api/v1/privacy-buckets

Returns all buckets for the account (ensures default presets exist). Ordered by creation time.

{
  "_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Regular friends",
  "description": "Default visibility for day-to-day friends",
  "icon": "users",
  "iconColorPreset": "blue",
  "slug": "public_friends",
  "friendPermissions": {
    "members_view": "read",
    "member_profile": "read",
    "member_avatar": "read",
    "member_notes": "read",
    "member_custom_fields": "read",
    "member_statuses": "read",
    "groups": "read",
    "front": "read",
    "friend_data": "read"
  },
  "createdAt": 1714233600000,
  "updatedAt": 1714237200000
}

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

Create bucket

POST/api/v1/privacy-buckets

Request body

Response

201: 201: created bucket (custom slug like u_…).

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Close friends",
    "description": "Inner circle",
    "friendPermissions": {
      "members_view": "read",
      "member_profile": "read",
      "front": "read_write"
    }
  }' \
  "https://api.floralitys.com/api/v1/privacy-buckets"

Get, update, delete bucket

GET /api/v1/privacy-buckets/{bucketId}: single bucket. PATCH same path: partial update of name, description, icon, colour, friendPermissions. DELETE same path: deletes custom buckets only. Built-in slugs (public_friends, trusted_friend, etc.) return 400. 204 on success.

{
  "code": "BAD_REQUEST",
  "message": "Cannot delete built-in privacy bucket."
}

Default buckets for new content

GET /api/v1/privacy-buckets/defaults/{kind}. PUT same path: body { bucketIds: [uuid, …] } (at least one id). 204. Applied when matching content is created without explicit bucket picks.

Valid kinds

• new_member
• new_group
• new_directory
• new_custom_field
• new_profile_section
• new_friend

Resource → bucket assignments

For each resource type, GET returns which buckets apply; PUT replaces the full set. Body: { bucketIds: [uuid, …] }: at least one bucket for most types (friends included).

Profile section keys

sectionKey is one of: avatar, displayName, pronouns, about, profileStyle.

{
  "memberId": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
  "bucketIds": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]
}

curl -sS -X PUT \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bucketIds":["BUCKET_UUID_1","BUCKET_UUID_2"]}' \
  "https://api.floralitys.com/api/v1/privacy-buckets/assignments/members/MEMBER_UUID"

Bucket → resource lists

Read which entities are tagged with a given bucket:

• GET/api/v1/privacy-buckets/{bucketId}/members → { bucketId, memberIds }
• GET/api/v1/privacy-buckets/{bucketId}/groups → { bucketId, groupIds }
• GET/api/v1/privacy-buckets/{bucketId}/directories → { bucketId, directoryIds }

Bulk add or remove

Add or remove one bucket from many resources in one call. Each endpoint requires the matching id array.

Shared body

{
  "bucketId": "BUCKET_UUID",
  "mode": "add",
  "memberIds": ["…"]
}

mode is add or remove. Returns 204.

Member status privacy

Status definitions can also be linked to buckets via PUT /api/v1/member-statuses/{definitionId}/privacy-buckets (memberStatuses scope). That controls which friends see each status tag.

Errors

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

// 204 No Content: empty response body