Florality

GET

/api/v1/friends/{friendUserId}/groups/folder/page

friends: read1,000 requests/minute/key · all plans

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

Parameters

Path parameters

Name	Type	Required	Description
`friendUserId`	`string (uuid)`	Required	Identifier of the friend user.

Query parameters

Name	Type	Required	Description
`limit`	`integer`	Required	Filter or option: limit. Minimum: 1. Maximum: 100.
`cursor`	`integer`	Optional	Filter or option: cursor. Minimum: 0.
`folderId`	`string \| null`	Required	Filter or option: folder id.
`search`	`string`	Optional	Filter or option: search. Maximum length: 200.
`sideSystemId`	`string (uuid)`	Optional	Filter or option: side system id.
`subSystemId`	`string (uuid)`	Optional	Filter or option: sub system id.

Behaviour and pagination

Omit cursor for the first page. Pass the nextCursor value from the response into the next request; if nextCursor is an object, use its index property. A null nextCursor indicates the end.

Response schema

200

Successful response.

Name	Type	Required	Description
`canonicalRootId`	`string`	Required	Canonical Root Id.
`layoutDirectoryId`	`string`	Required	Layout Directory Id.
`atSystemRoot`	`boolean`	Required	At System Root.
`subtreeMemberCountByFolderId`	`object`	Required	Subtree Member Count By Folder Id.
`folderDateModifiedById`	`object`	Required	Folder Date Modified By Id. yyyy-mm-dd style display strings aligned with `/dashboard/groups` name column secondary info
`pathSegments`	`array<object>`	Required	Path Segments.
`pathSegments[].id`	`string`	Required	Unique identifier.
`pathSegments[].name`	`string`	Required	Name of the resource.
`currentFrontMemberIds`	`array<string>`	Required	Current Front Member Ids.
`customIcons`	`array<object>`	Required	Custom Icons.
`customIcons[]._id`	`string`	Required	Unique identifier.
`customIcons[].userId`	`string`	Required	Owning account identifier.
`customIcons[].storageId`	`string`	Required	Storage Id.
`customIcons[].name`	`null \| string`	Required	Name of the resource.
`customIcons[].mimeType`	`string`	Required	Mime Type.
`customIcons[].isAnimated`	`boolean`	Required	Is Animated.
`customIcons[].displayTintHex`	`null \| string`	Required	Display Tint Hex.
`customIcons[].createdAt`	`number`	Required	Creation time.
`customIcons[].updatedAt`	`number`	Required	Most recent update time.
`customIcons[].url`	`null \| string`	Required	Url.
`customIcons[].iconRef`	`string`	Required	Icon Ref.
`membersById`	`object`	Required	Members By Id.
`memberProfileReadByMemberId`	`object`	Required	Member Profile Read By Member Id. Whether the viewer may open `/dashboard/friends/{owner}/members/{id}` for this member (`members.profile.read` + privacy buckets).
`stats`	`object`	Required	Stats.
`stats.childFolderCount`	`number`	Required	Child Folder Count.
`stats.headerMemberCount`	`number`	Required	Header Member Count.
`layoutScopeTags`	`object`	Required	Layout Scope Tags. Side / sub-system tags for the directory row whose layout is shown (owner scope).
`layoutScopeTags.side`	`null \| object`	Required	Side.
`layoutScopeTags.side.name`	`string`	Required	Name of the resource.
`layoutScopeTags.side.code`	`string`	Required	Code.
`layoutScopeTags.side.color`	`string`	Required	Color.
`layoutScopeTags.side.icon`	`string`	Optional	Icon.
`layoutScopeTags.sub`	`null \| object`	Required	Sub.
`layoutScopeTags.sub.name`	`string`	Required	Name of the resource.
`layoutScopeTags.sub.code`	`string`	Required	Code.
`layoutScopeTags.sub.color`	`string`	Required	Color.
`layoutScopeTags.sub.icon`	`string`	Optional	Icon.
`showFolderMemberSideTags`	`boolean`	Required	Show Folder Member Side Tags. Same rule as the owner dashboard groups table (`DirectoryListView`): when the owner has unified multi-side view, show per-folder / per-member side-system badges in the table.
`sideSystemTagBySideSystemId`	`object`	Required	Side System Tag By Side System Id.
`subSystemTagBySubSystemId`	`object`	Required	Sub System Tag By Sub System Id.
`subSystemSideSystemIdBySubSystemId`	`object`	Required	Sub System Side System Id By Sub System Id.
`folderSideSystemIdByFolderId`	`object`	Required	Folder Side System Id By Folder Id.
`folderSubSystemIdByFolderId`	`object`	Required	Folder Sub System Id By Folder Id.
`memberSideSystemIdByMemberId`	`object`	Required	Member Side System Id By Member Id.
`memberSubSystemIdByMemberId`	`object`	Required	Member Sub System Id By Member Id.
`directoryScopeSideSystems`	`array<object>`	Required	Directory Scope Side Systems. Ordered like the owner system switcher; used for friend directory scope UI only.
`directoryScopeSideSystems[]._id`	`string`	Required	Unique identifier.
`directoryScopeSideSystems[].name`	`string`	Required	Name of the resource.
`directoryScopeSideSystems[].icon`	`string`	Optional	Icon.
`directoryScopeSubSystems`	`array<object>`	Required	Directory Scope Sub Systems.
`directoryScopeSubSystems[]._id`	`string`	Required	Unique identifier.
`directoryScopeSubSystems[].sideSystemId`	`string`	Required	Side System Id.
`directoryScopeSubSystems[].parentSubSystemId`	`null \| string`	Required	Parent Sub System Id.
`directoryScopeSubSystems[].name`	`string`	Required	Name of the resource.
`directoryScopeSubSystems[].icon`	`string`	Optional	Icon.
`rows`	`array<object>`	Required	Rows.
`rows[].type`	`string`	Required	Type.
`rows[].id`	`string`	Optional	Unique identifier.
`rows[].name`	`string`	Optional	Name of the resource.
`rows[].description`	`null \| string`	Optional	Description of the resource. Optional folder / group blurb (`directories.description`); highlights via `[text]()`.
`rows[].icon`	`string`	Optional	Icon.
`rows[].iconColorPreset`	`string`	Optional	Icon Color Preset. Folder glyph colour preset; undefined = default (theme).
`rows[].displayName`	`string`	Optional	Display name. Display name (shown instead of name if set)
`rows[].isFronting`	`boolean`	Optional	Is Fronting.
`rows[].avatarUrl`	`null \| string`	Optional	Resolved avatar URL, or null when unavailable. Resolved avatar URL; undefined if none.
`rows[].backgroundUrl`	`null \| string`	Optional	Resolved background URL, or null when unavailable. Resolved profile background URL; undefined if none.
`rows[].isLinked`	`boolean`	Optional	Is Linked. True if the member's home folder is not the current directory Allowed values: false, true.
`rows[].layoutEntryId`	`string`	Optional	Layout Entry Id.
`rows[].label`	`string`	Optional	Label.
`rows[].colorPreset`	`string`	Optional	Color Preset. Tailwind color preset key (e.g. "slate", "zinc"). Omit = default.
`nextCursor`	`null \| object`	Required	Cursor for the next page; null when there are no further results.
`nextCursor.index`	`number`	Required	Index.
`totalRowCount`	`number`	Required	Total Row Count.

Errors

400 · JSON error: Missing friend user id.
401 · JSON error: Missing or invalid API key. Use Authorization: Bearer <token>.
403 · JSON error: Requires friends: read; ownership or feature restrictions may also deny access.
404 · JSON error: Request failed (NOT_FOUND).
409 · JSON error: Request failed (CONFLICT).
429 · JSON error: API rate limit exceeded (1000 requests per minute). Retry shortly.

Request example

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

Shell

curl --request GET 'https://floralitys.com/api/v1/friends/11111111-1111-4111-8111-111111111111/groups/folder/page?limit=20&folderId=null' \
  --header "Authorization: Bearer $FLORALITY_KEY"

Responses

Successful response.

JSON

{
  "canonicalRootId": "11111111-1111-4111-8111-111111111111",
  "layoutDirectoryId": "11111111-1111-4111-8111-111111111111",
  "atSystemRoot": false,
  "subtreeMemberCountByFolderId": {},
  "folderDateModifiedById": {},
  "pathSegments": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "River"
    }
  ],
  "currentFrontMemberIds": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "customIcons": [
    {
      "_id": "11111111-1111-4111-8111-111111111111",
      "userId": "11111111-1111-4111-8111-111111111111",
      "storageId": "11111111-1111-4111-8111-111111111111",
      "name": null,
      "mimeType": "image/png",
      "isAnimated": false,
      "displayTintHex": null,
      "createdAt": 1767225600000,
      "updatedAt": 1767225600000,
      "url": null,
      "iconRef": "demo"
    }
  ],
  "membersById": {},
  "memberProfileReadByMemberId": {},
  "stats": {
    "childFolderCount": 0,
    "headerMemberCount": 0
  },
  "layoutScopeTags": {
    "side": null,
    "sub": null
  },
  "showFolderMemberSideTags": false,
  "sideSystemTagBySideSystemId": {},
  "subSystemTagBySubSystemId": {},
  "subSystemSideSystemIdBySubSystemId": {},
  "folderSideSystemIdByFolderId": {},
  "folderSubSystemIdByFolderId": {},
  "memberSideSystemIdByMemberId": {},
  "memberSubSystemIdByMemberId": {},
  "directoryScopeSideSystems": [
    {
      "_id": "11111111-1111-4111-8111-111111111111",
      "name": "River",
      "icon": "demo"
    }
  ],
  "directoryScopeSubSystems": [
    {
      "_id": "11111111-1111-4111-8111-111111111111",
      "sideSystemId": "11111111-1111-4111-8111-111111111111",
      "parentSubSystemId": null,
      "name": "River",
      "icon": "demo"
    }
  ],
  "rows": [
    {
      "type": "member",
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "River",
      "displayName": "River",
      "isFronting": false,
      "avatarUrl": null,
      "backgroundUrl": null,
      "isLinked": false,
      "layoutEntryId": "11111111-1111-4111-8111-111111111111"
    }
  ],
  "nextCursor": null,
  "totalRowCount": 0
}

Example values are illustrative demo data.

Parameters

Path parameters

Name	Type	Required	Description
`friendUserId`	`string (uuid)`	Required	Identifier of the friend user.

Query parameters

Name	Type	Required	Description
`limit`	`integer`	Required	Filter or option: limit. Minimum: 1. Maximum: 100.
`cursor`	`integer`	Optional	Filter or option: cursor. Minimum: 0.
`folderId`	`string \| null`	Required	Filter or option: folder id.
`search`	`string`	Optional	Filter or option: search. Maximum length: 200.
`sideSystemId`	`string (uuid)`	Optional	Filter or option: side system id.
`subSystemId`	`string (uuid)`	Optional	Filter or option: sub system id.

Response schema

200

Successful response.

Name	Type	Required	Description
`canonicalRootId`	`string`	Required	Canonical Root Id.
`layoutDirectoryId`	`string`	Required	Layout Directory Id.
`atSystemRoot`	`boolean`	Required	At System Root.
`subtreeMemberCountByFolderId`	`object`	Required	Subtree Member Count By Folder Id.
`folderDateModifiedById`	`object`	Required	Folder Date Modified By Id. yyyy-mm-dd style display strings aligned with `/dashboard/groups` name column secondary info
`pathSegments`	`array<object>`	Required	Path Segments.
`pathSegments[].id`	`string`	Required	Unique identifier.
`pathSegments[].name`	`string`	Required	Name of the resource.
`currentFrontMemberIds`	`array<string>`	Required	Current Front Member Ids.
`customIcons`	`array<object>`	Required	Custom Icons.
`customIcons[]._id`	`string`	Required	Unique identifier.
`customIcons[].userId`	`string`	Required	Owning account identifier.
`customIcons[].storageId`	`string`	Required	Storage Id.
`customIcons[].name`	`null \| string`	Required	Name of the resource.
`customIcons[].mimeType`	`string`	Required	Mime Type.
`customIcons[].isAnimated`	`boolean`	Required	Is Animated.
`customIcons[].displayTintHex`	`null \| string`	Required	Display Tint Hex.
`customIcons[].createdAt`	`number`	Required	Creation time.
`customIcons[].updatedAt`	`number`	Required	Most recent update time.
`customIcons[].url`	`null \| string`	Required	Url.
`customIcons[].iconRef`	`string`	Required	Icon Ref.
`membersById`	`object`	Required	Members By Id.
`memberProfileReadByMemberId`	`object`	Required	Member Profile Read By Member Id. Whether the viewer may open `/dashboard/friends/{owner}/members/{id}` for this member (`members.profile.read` + privacy buckets).
`stats`	`object`	Required	Stats.
`stats.childFolderCount`	`number`	Required	Child Folder Count.
`stats.headerMemberCount`	`number`	Required	Header Member Count.
`layoutScopeTags`	`object`	Required	Layout Scope Tags. Side / sub-system tags for the directory row whose layout is shown (owner scope).
`layoutScopeTags.side`	`null \| object`	Required	Side.
`layoutScopeTags.side.name`	`string`	Required	Name of the resource.
`layoutScopeTags.side.code`	`string`	Required	Code.
`layoutScopeTags.side.color`	`string`	Required	Color.
`layoutScopeTags.side.icon`	`string`	Optional	Icon.
`layoutScopeTags.sub`	`null \| object`	Required	Sub.
`layoutScopeTags.sub.name`	`string`	Required	Name of the resource.
`layoutScopeTags.sub.code`	`string`	Required	Code.
`layoutScopeTags.sub.color`	`string`	Required	Color.
`layoutScopeTags.sub.icon`	`string`	Optional	Icon.
`showFolderMemberSideTags`	`boolean`	Required	Show Folder Member Side Tags. Same rule as the owner dashboard groups table (`DirectoryListView`): when the owner has unified multi-side view, show per-folder / per-member side-system badges in the table.
`sideSystemTagBySideSystemId`	`object`	Required	Side System Tag By Side System Id.
`subSystemTagBySubSystemId`	`object`	Required	Sub System Tag By Sub System Id.
`subSystemSideSystemIdBySubSystemId`	`object`	Required	Sub System Side System Id By Sub System Id.
`folderSideSystemIdByFolderId`	`object`	Required	Folder Side System Id By Folder Id.
`folderSubSystemIdByFolderId`	`object`	Required	Folder Sub System Id By Folder Id.
`memberSideSystemIdByMemberId`	`object`	Required	Member Side System Id By Member Id.
`memberSubSystemIdByMemberId`	`object`	Required	Member Sub System Id By Member Id.
`directoryScopeSideSystems`	`array<object>`	Required	Directory Scope Side Systems. Ordered like the owner system switcher; used for friend directory scope UI only.
`directoryScopeSideSystems[]._id`	`string`	Required	Unique identifier.
`directoryScopeSideSystems[].name`	`string`	Required	Name of the resource.
`directoryScopeSideSystems[].icon`	`string`	Optional	Icon.
`directoryScopeSubSystems`	`array<object>`	Required	Directory Scope Sub Systems.
`directoryScopeSubSystems[]._id`	`string`	Required	Unique identifier.
`directoryScopeSubSystems[].sideSystemId`	`string`	Required	Side System Id.
`directoryScopeSubSystems[].parentSubSystemId`	`null \| string`	Required	Parent Sub System Id.
`directoryScopeSubSystems[].name`	`string`	Required	Name of the resource.
`directoryScopeSubSystems[].icon`	`string`	Optional	Icon.
`rows`	`array<object>`	Required	Rows.
`rows[].type`	`string`	Required	Type.
`rows[].id`	`string`	Optional	Unique identifier.
`rows[].name`	`string`	Optional	Name of the resource.
`rows[].description`	`null \| string`	Optional	Description of the resource. Optional folder / group blurb (`directories.description`); highlights via `[text]()`.
`rows[].icon`	`string`	Optional	Icon.
`rows[].iconColorPreset`	`string`	Optional	Icon Color Preset. Folder glyph colour preset; undefined = default (theme).
`rows[].displayName`	`string`	Optional	Display name. Display name (shown instead of name if set)
`rows[].isFronting`	`boolean`	Optional	Is Fronting.
`rows[].avatarUrl`	`null \| string`	Optional	Resolved avatar URL, or null when unavailable. Resolved avatar URL; undefined if none.
`rows[].backgroundUrl`	`null \| string`	Optional	Resolved background URL, or null when unavailable. Resolved profile background URL; undefined if none.
`rows[].isLinked`	`boolean`	Optional	Is Linked. True if the member's home folder is not the current directory Allowed values: false, true.
`rows[].layoutEntryId`	`string`	Optional	Layout Entry Id.
`rows[].label`	`string`	Optional	Label.
`rows[].colorPreset`	`string`	Optional	Color Preset. Tailwind color preset key (e.g. "slate", "zinc"). Omit = default.
`nextCursor`	`null \| object`	Required	Cursor for the next page; null when there are no further results.
`nextCursor.index`	`number`	Required	Index.
`totalRowCount`	`number`	Required	Total Row Count.

Errors

400 · JSON error

Missing friend user id.

401 · JSON error

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

403 · JSON error

Requires friends: read; ownership or feature restrictions may also deny access.

404 · JSON error

Request failed (NOT_FOUND).

409 · JSON error

Request failed (CONFLICT).

429 · JSON error

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

Request example

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

Shell

curl --request GET 'https://floralitys.com/api/v1/friends/11111111-1111-4111-8111-111111111111/groups/folder/page?limit=20&folderId=null' \
  --header "Authorization: Bearer $FLORALITY_KEY"

Responses

Successful response.

JSON

{
  "canonicalRootId": "11111111-1111-4111-8111-111111111111",
  "layoutDirectoryId": "11111111-1111-4111-8111-111111111111",
  "atSystemRoot": false,
  "subtreeMemberCountByFolderId": {},
  "folderDateModifiedById": {},
  "pathSegments": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "River"
    }
  ],
  "currentFrontMemberIds": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "customIcons": [
    {
      "_id": "11111111-1111-4111-8111-111111111111",
      "userId": "11111111-1111-4111-8111-111111111111",
      "storageId": "11111111-1111-4111-8111-111111111111",
      "name": null,
      "mimeType": "image/png",
      "isAnimated": false,
      "displayTintHex": null,
      "createdAt": 1767225600000,
      "updatedAt": 1767225600000,
      "url": null,
      "iconRef": "demo"
    }
  ],
  "membersById": {},
  "memberProfileReadByMemberId": {},
  "stats": {
    "childFolderCount": 0,
    "headerMemberCount": 0
  },
  "layoutScopeTags": {
    "side": null,
    "sub": null
  },
  "showFolderMemberSideTags": false,
  "sideSystemTagBySideSystemId": {},
  "subSystemTagBySubSystemId": {},
  "subSystemSideSystemIdBySubSystemId": {},
  "folderSideSystemIdByFolderId": {},
  "folderSubSystemIdByFolderId": {},
  "memberSideSystemIdByMemberId": {},
  "memberSubSystemIdByMemberId": {},
  "directoryScopeSideSystems": [
    {
      "_id": "11111111-1111-4111-8111-111111111111",
      "name": "River",
      "icon": "demo"
    }
  ],
  "directoryScopeSubSystems": [
    {
      "_id": "11111111-1111-4111-8111-111111111111",
      "sideSystemId": "11111111-1111-4111-8111-111111111111",
      "parentSubSystemId": null,
      "name": "River",
      "icon": "demo"
    }
  ],
  "rows": [
    {
      "type": "member",
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "River",
      "displayName": "River",
      "isFronting": false,
      "avatarUrl": null,
      "backgroundUrl": null,
      "isLinked": false,
      "layoutEntryId": "11111111-1111-4111-8111-111111111111"
    }
  ],
  "nextCursor": null,
  "totalRowCount": 0
}

Example values are illustrative demo data.

Get friend groups folder page

Parameters

Path parameters

Query parameters

Behaviour and pagination

Response schema

200

Errors

Request example

Responses

Get friend groups folder page

Parameters

Path parameters

Query parameters

Behaviour and pagination

Response schema

200

Errors

Request example

Responses