List friends page
Returns friends page accessible to the API key’s account.
GET
/api/v1/friends/pagefriends: read1,000 requests/minute/key · all plansActive API keys: Free 1, Pro 5, Pro+ 5. The request rate is the same on every plan.
Parameters
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | Required | Filter or option: limit. Minimum: 1. |
cursor | integer | Optional | Filter or option: cursor. |
query | string | Optional | Filter or option: query. |
status | string | Optional | Filter or option: status. Allowed values: "pending", "accepted", "blocked", "revoked". |
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 |
|---|---|---|---|
items | array<object> | Required | Items returned by this request. |
items[].id | string | Required | Unique identifier. |
items[].friendUserId | string | Required | Friend User Id. |
items[].status | string | Required | Status. Allowed values: "pending", "accepted", "blocked", "revoked". |
items[].name | string | Required | Name of the resource. |
items[].username | null | string | Required | Username. |
items[].imageUrl | null | string | Required | Image Url. |
items[].friendPronouns | null | string | Required | Friend Pronouns. |
items[].friendStatus | null | string | Required | Friend Status. |
items[].friendBannerUrl | null | string | Required | Friend Banner Url. Resolved banner for list rows; null if unset or not embeddable. |
items[].isAdmin | boolean | Required | Is Admin. |
items[].planKey | null | string | Required | Plan Key. |
items[].donorSupporterUnlocked | boolean | Required | Donor Supporter Unlocked. |
items[].closedBetaParticipantAt | null | number | Required | Closed Beta Participant At. |
items[].bugBountyUnlockedAt | null | number | Required | Bug Bounty Unlocked At. |
items[].privacyBucketIds | array<string> | Required | Privacy Bucket Ids. Owner-assigned privacy bucket ids for this friend (empty if legacy / not configured). |
items[].friendProfileStyle | null | object | Required | Friend Profile Style. |
items[].friendProfileStyle.avatarRing | object | Optional | Avatar Ring. |
items[].friendProfileStyle.bannerFrame | object | Optional | Banner Frame. |
items[].friendProfileStyle.memberName | object | Optional | Member Name. |
items[].friendProfileStyle.bannerImage | object | Optional | Banner Image. |
items[].friendProfileStyle.avatarImage | object | Optional | Avatar Image. |
items[].friendProfileStyle.bannerOverlay | string | Optional | Banner Overlay. Allowed values: "none", "vignette", "soft-gradient", "film-grain", "glass-blur", "pattern-dots", "pattern-grid". |
items[].friendProfileStyle.profileBackgroundPattern | string | Optional | Profile Background Pattern. Allowed values: "grid", "none", "dots", "noise". |
items[].friendProfileStyle.heroLayout | string | Optional | Hero Layout. Allowed values: "shell-default", "avatar-centered", "avatar-left". |
items[].friendProfileStyle.accentColorHex | null | string | Optional | Accent Color Hex. |
items[].friendProfileStyle.profileBackgroundFill | object | Optional | Profile Background Fill. |
items[].friendProfileStyle.pageBackgroundFill | object | Optional | Page Background Fill. Friend-only: full Friends viewport backdrop (solid/gradient). |
items[].friendProfileStyle.panelBackgroundFill | object | Optional | Panel Background Fill. Friend-only: profile card panel fill (free: preset solids; Pro+: custom solid/gradient). |
items[].friendProfileStyle.panelFillAccentHex | null | string | Optional | Panel Fill Accent Hex. Friend-only: optional accent mixed into the profile panel backdrop (Pro+). |
items[].friendProfileStyle.panelCardAccentHex | null | string | Optional | Panel Card Accent Hex. Friend-only: optional accent mixed into section cards (Pro+). |
items[].createdAt | number | Required | Creation time. |
items[].acceptedAt | null | number | Required | Accepted At. |
nextCursor | null | number | Required | Cursor for the next page; null when there are no further results. |
total | number | Required | Total. |
Errors
400· JSON errorlimit: Required
401· JSON errorMissing or invalid API key. Use Authorization: Bearer <token>.
403· JSON errorRequires friends: read; ownership or feature restrictions may also deny access.
429· JSON errorAPI rate limit exceeded (1000 requests per minute). Retry shortly.
Request example
Set FLORALITY_KEY in your environment. These examples use demo identifiers.
curl --request GET 'https://floralitys.com/api/v1/friends/page?limit=20' \
--header "Authorization: Bearer $FLORALITY_KEY"Responses
Successful response.
{
"items": [
{
"id": "11111111-1111-4111-8111-111111111111",
"friendUserId": "11111111-1111-4111-8111-111111111111",
"status": "pending",
"name": "River",
"username": null,
"imageUrl": null,
"friendPronouns": null,
"friendStatus": null,
"friendBannerUrl": null,
"isAdmin": false,
"planKey": null,
"donorSupporterUnlocked": false,
"closedBetaParticipantAt": null,
"bugBountyUnlockedAt": null,
"privacyBucketIds": [
"11111111-1111-4111-8111-111111111111"
],
"friendProfileStyle": null,
"createdAt": 1767225600000,
"acceptedAt": null
}
],
"nextCursor": null,
"total": 0
}Example values are illustrative demo data.