Florality

GET

/api/v1/friends/{friendUserId}/social

social: 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.

Response schema

200

Successful response.

Name	Type	Required	Description
`bentoLayout`	`object`	Optional	Bento Layout.
`bentoLayout.schemaVersion`	`number`	Required	Schema Version. Allowed values: 1.
`bentoLayout.revision`	`number`	Required	Revision.
`bentoLayout.tiles`	`array<object>`	Required	Tiles.
`bentoLayout.tiles[].id`	`string`	Required	Unique identifier.
`bentoLayout.tiles[].label`	`string`	Required	Label.
`bentoLayout.tiles[].orderIndex`	`number`	Required	Order Index.
`bentoLayout.tiles[].colSpan`	`number`	Required	Col Span. Allowed values: 1, 2, 3.
`bentoLayout.tiles[].rowSpan`	`number`	Required	Row Span.
`bentoLayout.tiles[].kind`	`string`	Required	Kind. Allowed values: "about", "social", "legacy", "field", "local_time", "fronting", "links".
`bentoLayout.tiles[].visibility`	`string`	Required	Visibility. Allowed values: "public", "logged_in", "friends_only", "mutuals_only", "private".
`bentoLayout.tiles[].value`	`null \| string \| array<string>`	Optional	Value.
`bentoLayout.tiles[].description`	`string`	Optional	Description of the resource.
`bentoLayout.tiles[].icon`	`null \| string`	Optional	Icon.
`bentoLayout.tiles[].background`	`null \| string`	Optional	Background storage reference.
`bentoLayout.tiles[].legacy`	`JSON value`	Optional	Legacy.
`bentoLayout.tiles[].widget`	`JSON value`	Optional	Widget.
`bentoLayout.tiles[].legacyProjection`	`boolean`	Optional	Legacy Projection. Allowed values: false, true.
`bentoLayout.tiles[].fieldType`	`string`	Optional	Field Type. Allowed values: "date", "tags", "separator", "text", "markdown", "color", "birthday", "day_month", "month_year", "year", "url", "image", "photo_gallery", "featured_song", "featured_playlist".
`bentoLayout.tiles[].namesOnly`	`boolean`	Optional	Names Only. Allowed values: false, true.
`bentoLayout.tiles[].converted`	`boolean`	Optional	Converted. Allowed values: false, true.
`profileRevision`	`string`	Optional	Profile Revision.
`userId`	`string`	Required	Owning account identifier.
`links`	`array<object>`	Required	Links.
`links[].id`	`string`	Required	Unique identifier.
`links[].platform`	`string`	Required	Platform. Allowed values: "custom", "discord", "tiktok", "instagram", "x", "bluesky", "youtube", "twitch", "steam", "xbox", "playstation", "nintendo", "github", "reddit", "pinterest", "roblox", "vrchat", "anilist", "myanimelist", "letterboxd", "spotify".
`links[].displayName`	`string`	Required	Display name.
`links[].handle`	`null \| string`	Required	Handle.
`links[].url`	`null \| string`	Required	Url.
`links[].description`	`null \| string`	Required	Description of the resource.
`links[].badge`	`null \| string`	Required	Badge.
`links[].accentColor`	`null \| string`	Required	Accent Color.
`links[].avatarUrl`	`null \| string`	Required	Resolved avatar URL, or null when unavailable. OAuth provider profile image when linked via Clerk
`links[].visibility`	`string`	Required	Visibility. Allowed values: "public", "logged_in", "friends_only", "mutuals_only", "private".
`links[].featured`	`boolean`	Required	Featured.
`links[].sortOrder`	`number`	Required	Sort Order.
`links[].createdAt`	`number`	Required	Creation time.
`links[].updatedAt`	`number`	Required	Most recent update time.
`widgets`	`array<object>`	Required	Widgets.
`widgets[].id`	`string`	Required	Unique identifier.
`widgets[].type`	`string`	Required	Type. Allowed values: "status", "discord_server", "currently_playing", "music", "quote", "pronouns_identity", "mood", "custom_badge", "link_collection", "media_favourites", "guestbook", "mutuals", "countdown", "poll", "sticker_board", "shrine".
`widgets[].title`	`null \| string`	Required	Display title.
`widgets[].visibility`	`string`	Required	Visibility. Allowed values: "public", "logged_in", "friends_only", "mutuals_only", "private".
`widgets[].size`	`string`	Required	Size. Allowed values: "small", "medium", "large", "full".
`widgets[].sortOrder`	`number`	Required	Sort Order.
`widgets[].pinned`	`boolean`	Required	Pinned.
`widgets[].collapsed`	`boolean`	Required	Collapsed.
`widgets[].createdAt`	`number`	Required	Creation time.
`widgets[].updatedAt`	`number`	Required	Most recent update time.
`widgets[].config`	`object`	Required	Config.
`widgets[].config.kind`	`string`	Required	Kind.
`widgets[].config.statusText`	`string`	Optional	Status Text.
`widgets[].config.serverName`	`string`	Optional	Server Name.
`widgets[].config.inviteUrl`	`null \| string`	Optional	Invite Url.
`widgets[].config.provider`	`string`	Optional	Provider. Allowed values: "spotify".
`widgets[].config.trackTitle`	`string`	Optional	Track Title.
`widgets[].config.artistName`	`string`	Optional	Artist Name.
`widgets[].config.artworkUrl`	`null \| string`	Optional	Artwork Url.
`widgets[].config.widgetKind`	`string`	Optional	Widget Kind. Allowed values: "featured_playlist", "featured_track", "currently_listening", "top_tracks", "top_artists", "recently_played", "favourite_album", "mood_playlist", "song_that_describes_me", "per_front_playlist", "playlist_carousel".
`widgets[].config.displayStyle`	`string`	Optional	Display Style. Allowed values: "compact_card", "album_art_card", "playlist_shelf", "album_grid", "now_playing_bar".
`widgets[].config.spotifyResourceType`	`null \| string`	Optional	Spotify Resource Type.
`widgets[].config.spotifyResourceId`	`null \| string`	Optional	Spotify Resource Id.
`widgets[].config.playlistUrl`	`null \| string`	Optional	Playlist Url.
`widgets[].config.playlistName`	`null \| string`	Optional	Playlist Name.
`widgets[].config.playlistCoverUrl`	`null \| string`	Optional	Playlist Cover Url.
`widgets[].config.playlistTrackCount`	`null \| number`	Optional	Playlist Track Count.
`widgets[].config.playlistDurationMinutes`	`null \| number`	Optional	Playlist Duration Minutes.
`widgets[].config.memberId`	`null \| string`	Optional	Associated member identifier.
`widgets[].config.quote`	`string`	Optional	Quote.
`widgets[].config.author`	`null \| string`	Optional	Author.
`widgets[].config.pronouns`	`string`	Optional	Member pronouns.
`widgets[].config.identity`	`null \| string`	Optional	Identity.
`widgets[].config.mood`	`string`	Optional	Mood.
`widgets[].config.note`	`null \| string`	Optional	Note.
`widgets[].config.imageUrls`	`array<string>`	Optional	Image Urls. Repurposed as photo gallery while preserving widget kind for compatibility.
`widgets[].config.linkIds`	`array<string>`	Optional	Link Ids.
`widgets[].config.entries`	`array<object>`	Optional	Entries.
`widgets[].config.allowAnonymous`	`boolean`	Optional	Allow Anonymous.
`widgets[].config.maxItems`	`number`	Optional	Max Items.
`widgets[].config.targetAt`	`number`	Optional	Target At.
`widgets[].config.label`	`string`	Optional	Label.
`widgets[].config.question`	`string`	Optional	Question.
`widgets[].config.options`	`array<string>`	Optional	Options.
`widgets[].config.allowMultipleSelections`	`boolean`	Optional	Allow Multiple Selections. When true, voters may pick more than one option once voting exists.
`widgets[].config.stickerUrls`	`array<string>`	Optional	Sticker Urls.
`widgets[].config.title`	`string`	Optional	Display title.
`widgets[].config.body`	`string`	Optional	Body.
`musicConnections`	`array<object>`	Required	Music Connections.
`musicConnections[].id`	`string`	Required	Unique identifier.
`musicConnections[].provider`	`string`	Required	Provider. Allowed values: "spotify".
`musicConnections[].displayName`	`null \| string`	Required	Display name.
`musicConnections[].externalUserId`	`null \| string`	Required	External User Id.
`musicConnections[].status`	`string`	Required	Status. Allowed values: "mock", "connected", "connected_limited".
`musicConnections[].connectedAt`	`number`	Required	Connected At.
`musicConnections[].updatedAt`	`number`	Required	Most recent update time.
`theme`	`null \| object`	Required	Theme.
`theme.cardBackground`	`string`	Optional	Card Background.
`theme.accentColor`	`string`	Optional	Accent Color.
`theme.borderStyle`	`string`	Optional	Border Style. Allowed values: "default", "subtle", "strong".
`theme.cornerStyle`	`string`	Optional	Corner Style. Allowed values: "rounded", "sharp".
`theme.iconStyle`	`string`	Optional	Icon Style. Allowed values: "default", "minimal", "filled".
`theme.widgetPreset`	`string`	Optional	Widget Preset. Pro Plus widget chrome preset (guestbook, music blocks). Allowed values: "default", "accent-stripe", "glass-card", "polaroid".
`updatedAt`	`null \| number`	Required	Most recent update time.

Errors

400 · JSON error: Request failed (BAD_REQUEST).
401 · JSON error: Missing or invalid API key. Use Authorization: Bearer <token>.
403 · JSON error: Requires social: 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.
503 · JSON error: PostgreSQL is not configured (DATABASE_URL).

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/social' \
  --header "Authorization: Bearer $FLORALITY_KEY"

Responses

Successful response.

JSON

{
  "bentoLayout": {
    "schemaVersion": 1,
    "revision": 0,
    "tiles": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "label": "demo",
        "orderIndex": 0,
        "colSpan": 1,
        "rowSpan": 0,
        "kind": "about",
        "visibility": "public",
        "value": null,
        "description": "A note from our demo system.",
        "icon": null,
        "background": null,
        "legacy": {},
        "widget": {},
        "legacyProjection": false,
        "fieldType": "date",
        "namesOnly": false,
        "converted": false
      }
    ]
  },
  "profileRevision": "demo",
  "userId": "11111111-1111-4111-8111-111111111111",
  "links": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "platform": "custom",
      "displayName": "River",
      "handle": null,
      "url": null,
      "description": null,
      "badge": null,
      "accentColor": null,
      "avatarUrl": null,
      "visibility": "public",
      "featured": false,
      "sortOrder": 0,
      "createdAt": 1767225600000,
      "updatedAt": 1767225600000
    }
  ],
  "widgets": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "type": "status",
      "title": null,
      "visibility": "public",
      "size": "small",
      "sortOrder": 0,
      "pinned": false,
      "collapsed": false,
      "createdAt": 1767225600000,
      "updatedAt": 1767225600000,
      "config": {
        "kind": "music",
        "provider": "spotify",
        "widgetKind": "featured_playlist",
        "displayStyle": "compact_card",
        "spotifyResourceType": null,
        "spotifyResourceId": null,
        "playlistUrl": null,
        "playlistName": null,
        "playlistCoverUrl": null,
        "playlistTrackCount": null,
        "playlistDurationMinutes": null,
        "memberId": null
      }
    }
  ],
  "musicConnections": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "provider": "spotify",
      "displayName": null,
      "externalUserId": null,
      "status": "mock",
      "connectedAt": 1767225600000,
      "updatedAt": 1767225600000
    }
  ],
  "theme": null,
  "updatedAt": null
}

Example values are illustrative demo data.

Name

Type

Required

Description

friendUserId

string (uuid)

Required

Identifier of the friend user.

Response schema

200

Successful response.

Name	Type	Required	Description
`bentoLayout`	`object`	Optional	Bento Layout.
`bentoLayout.schemaVersion`	`number`	Required	Schema Version. Allowed values: 1.
`bentoLayout.revision`	`number`	Required	Revision.
`bentoLayout.tiles`	`array<object>`	Required	Tiles.
`bentoLayout.tiles[].id`	`string`	Required	Unique identifier.
`bentoLayout.tiles[].label`	`string`	Required	Label.
`bentoLayout.tiles[].orderIndex`	`number`	Required	Order Index.
`bentoLayout.tiles[].colSpan`	`number`	Required	Col Span. Allowed values: 1, 2, 3.
`bentoLayout.tiles[].rowSpan`	`number`	Required	Row Span.
`bentoLayout.tiles[].kind`	`string`	Required	Kind. Allowed values: "about", "social", "legacy", "field", "local_time", "fronting", "links".
`bentoLayout.tiles[].visibility`	`string`	Required	Visibility. Allowed values: "public", "logged_in", "friends_only", "mutuals_only", "private".
`bentoLayout.tiles[].value`	`null \| string \| array<string>`	Optional	Value.
`bentoLayout.tiles[].description`	`string`	Optional	Description of the resource.
`bentoLayout.tiles[].icon`	`null \| string`	Optional	Icon.
`bentoLayout.tiles[].background`	`null \| string`	Optional	Background storage reference.
`bentoLayout.tiles[].legacy`	`JSON value`	Optional	Legacy.
`bentoLayout.tiles[].widget`	`JSON value`	Optional	Widget.
`bentoLayout.tiles[].legacyProjection`	`boolean`	Optional	Legacy Projection. Allowed values: false, true.
`bentoLayout.tiles[].fieldType`	`string`	Optional	Field Type. Allowed values: "date", "tags", "separator", "text", "markdown", "color", "birthday", "day_month", "month_year", "year", "url", "image", "photo_gallery", "featured_song", "featured_playlist".
`bentoLayout.tiles[].namesOnly`	`boolean`	Optional	Names Only. Allowed values: false, true.
`bentoLayout.tiles[].converted`	`boolean`	Optional	Converted. Allowed values: false, true.
`profileRevision`	`string`	Optional	Profile Revision.
`userId`	`string`	Required	Owning account identifier.
`links`	`array<object>`	Required	Links.
`links[].id`	`string`	Required	Unique identifier.
`links[].platform`	`string`	Required	Platform. Allowed values: "custom", "discord", "tiktok", "instagram", "x", "bluesky", "youtube", "twitch", "steam", "xbox", "playstation", "nintendo", "github", "reddit", "pinterest", "roblox", "vrchat", "anilist", "myanimelist", "letterboxd", "spotify".
`links[].displayName`	`string`	Required	Display name.
`links[].handle`	`null \| string`	Required	Handle.
`links[].url`	`null \| string`	Required	Url.
`links[].description`	`null \| string`	Required	Description of the resource.
`links[].badge`	`null \| string`	Required	Badge.
`links[].accentColor`	`null \| string`	Required	Accent Color.
`links[].avatarUrl`	`null \| string`	Required	Resolved avatar URL, or null when unavailable. OAuth provider profile image when linked via Clerk
`links[].visibility`	`string`	Required	Visibility. Allowed values: "public", "logged_in", "friends_only", "mutuals_only", "private".
`links[].featured`	`boolean`	Required	Featured.
`links[].sortOrder`	`number`	Required	Sort Order.
`links[].createdAt`	`number`	Required	Creation time.
`links[].updatedAt`	`number`	Required	Most recent update time.
`widgets`	`array<object>`	Required	Widgets.
`widgets[].id`	`string`	Required	Unique identifier.
`widgets[].type`	`string`	Required	Type. Allowed values: "status", "discord_server", "currently_playing", "music", "quote", "pronouns_identity", "mood", "custom_badge", "link_collection", "media_favourites", "guestbook", "mutuals", "countdown", "poll", "sticker_board", "shrine".
`widgets[].title`	`null \| string`	Required	Display title.
`widgets[].visibility`	`string`	Required	Visibility. Allowed values: "public", "logged_in", "friends_only", "mutuals_only", "private".
`widgets[].size`	`string`	Required	Size. Allowed values: "small", "medium", "large", "full".
`widgets[].sortOrder`	`number`	Required	Sort Order.
`widgets[].pinned`	`boolean`	Required	Pinned.
`widgets[].collapsed`	`boolean`	Required	Collapsed.
`widgets[].createdAt`	`number`	Required	Creation time.
`widgets[].updatedAt`	`number`	Required	Most recent update time.
`widgets[].config`	`object`	Required	Config.
`widgets[].config.kind`	`string`	Required	Kind.
`widgets[].config.statusText`	`string`	Optional	Status Text.
`widgets[].config.serverName`	`string`	Optional	Server Name.
`widgets[].config.inviteUrl`	`null \| string`	Optional	Invite Url.
`widgets[].config.provider`	`string`	Optional	Provider. Allowed values: "spotify".
`widgets[].config.trackTitle`	`string`	Optional	Track Title.
`widgets[].config.artistName`	`string`	Optional	Artist Name.
`widgets[].config.artworkUrl`	`null \| string`	Optional	Artwork Url.
`widgets[].config.widgetKind`	`string`	Optional	Widget Kind. Allowed values: "featured_playlist", "featured_track", "currently_listening", "top_tracks", "top_artists", "recently_played", "favourite_album", "mood_playlist", "song_that_describes_me", "per_front_playlist", "playlist_carousel".
`widgets[].config.displayStyle`	`string`	Optional	Display Style. Allowed values: "compact_card", "album_art_card", "playlist_shelf", "album_grid", "now_playing_bar".
`widgets[].config.spotifyResourceType`	`null \| string`	Optional	Spotify Resource Type.
`widgets[].config.spotifyResourceId`	`null \| string`	Optional	Spotify Resource Id.
`widgets[].config.playlistUrl`	`null \| string`	Optional	Playlist Url.
`widgets[].config.playlistName`	`null \| string`	Optional	Playlist Name.
`widgets[].config.playlistCoverUrl`	`null \| string`	Optional	Playlist Cover Url.
`widgets[].config.playlistTrackCount`	`null \| number`	Optional	Playlist Track Count.
`widgets[].config.playlistDurationMinutes`	`null \| number`	Optional	Playlist Duration Minutes.
`widgets[].config.memberId`	`null \| string`	Optional	Associated member identifier.
`widgets[].config.quote`	`string`	Optional	Quote.
`widgets[].config.author`	`null \| string`	Optional	Author.
`widgets[].config.pronouns`	`string`	Optional	Member pronouns.
`widgets[].config.identity`	`null \| string`	Optional	Identity.
`widgets[].config.mood`	`string`	Optional	Mood.
`widgets[].config.note`	`null \| string`	Optional	Note.
`widgets[].config.imageUrls`	`array<string>`	Optional	Image Urls. Repurposed as photo gallery while preserving widget kind for compatibility.
`widgets[].config.linkIds`	`array<string>`	Optional	Link Ids.
`widgets[].config.entries`	`array<object>`	Optional	Entries.
`widgets[].config.allowAnonymous`	`boolean`	Optional	Allow Anonymous.
`widgets[].config.maxItems`	`number`	Optional	Max Items.
`widgets[].config.targetAt`	`number`	Optional	Target At.
`widgets[].config.label`	`string`	Optional	Label.
`widgets[].config.question`	`string`	Optional	Question.
`widgets[].config.options`	`array<string>`	Optional	Options.
`widgets[].config.allowMultipleSelections`	`boolean`	Optional	Allow Multiple Selections. When true, voters may pick more than one option once voting exists.
`widgets[].config.stickerUrls`	`array<string>`	Optional	Sticker Urls.
`widgets[].config.title`	`string`	Optional	Display title.
`widgets[].config.body`	`string`	Optional	Body.
`musicConnections`	`array<object>`	Required	Music Connections.
`musicConnections[].id`	`string`	Required	Unique identifier.
`musicConnections[].provider`	`string`	Required	Provider. Allowed values: "spotify".
`musicConnections[].displayName`	`null \| string`	Required	Display name.
`musicConnections[].externalUserId`	`null \| string`	Required	External User Id.
`musicConnections[].status`	`string`	Required	Status. Allowed values: "mock", "connected", "connected_limited".
`musicConnections[].connectedAt`	`number`	Required	Connected At.
`musicConnections[].updatedAt`	`number`	Required	Most recent update time.
`theme`	`null \| object`	Required	Theme.
`theme.cardBackground`	`string`	Optional	Card Background.
`theme.accentColor`	`string`	Optional	Accent Color.
`theme.borderStyle`	`string`	Optional	Border Style. Allowed values: "default", "subtle", "strong".
`theme.cornerStyle`	`string`	Optional	Corner Style. Allowed values: "rounded", "sharp".
`theme.iconStyle`	`string`	Optional	Icon Style. Allowed values: "default", "minimal", "filled".
`theme.widgetPreset`	`string`	Optional	Widget Preset. Pro Plus widget chrome preset (guestbook, music blocks). Allowed values: "default", "accent-stripe", "glass-card", "polaroid".
`updatedAt`	`null \| number`	Required	Most recent update time.

Errors

400 · JSON error

Request failed (BAD_REQUEST).

401 · JSON error

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

403 · JSON error

Requires social: 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.

503 · JSON error

PostgreSQL is not configured (DATABASE_URL).

Responses

Successful response.

JSON

{
  "bentoLayout": {
    "schemaVersion": 1,
    "revision": 0,
    "tiles": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "label": "demo",
        "orderIndex": 0,
        "colSpan": 1,
        "rowSpan": 0,
        "kind": "about",
        "visibility": "public",
        "value": null,
        "description": "A note from our demo system.",
        "icon": null,
        "background": null,
        "legacy": {},
        "widget": {},
        "legacyProjection": false,
        "fieldType": "date",
        "namesOnly": false,
        "converted": false
      }
    ]
  },
  "profileRevision": "demo",
  "userId": "11111111-1111-4111-8111-111111111111",
  "links": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "platform": "custom",
      "displayName": "River",
      "handle": null,
      "url": null,
      "description": null,
      "badge": null,
      "accentColor": null,
      "avatarUrl": null,
      "visibility": "public",
      "featured": false,
      "sortOrder": 0,
      "createdAt": 1767225600000,
      "updatedAt": 1767225600000
    }
  ],
  "widgets": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "type": "status",
      "title": null,
      "visibility": "public",
      "size": "small",
      "sortOrder": 0,
      "pinned": false,
      "collapsed": false,
      "createdAt": 1767225600000,
      "updatedAt": 1767225600000,
      "config": {
        "kind": "music",
        "provider": "spotify",
        "widgetKind": "featured_playlist",
        "displayStyle": "compact_card",
        "spotifyResourceType": null,
        "spotifyResourceId": null,
        "playlistUrl": null,
        "playlistName": null,
        "playlistCoverUrl": null,
        "playlistTrackCount": null,
        "playlistDurationMinutes": null,
        "memberId": null
      }
    }
  ],
  "musicConnections": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "provider": "spotify",
      "displayName": null,
      "externalUserId": null,
      "status": "mock",
      "connectedAt": 1767225600000,
      "updatedAt": 1767225600000
    }
  ],
  "theme": null,
  "updatedAt": null
}

Example values are illustrative demo data.

Get friend social

Parameters

Path parameters

Response schema

200

Errors

Request example

Responses

Get friend social

Parameters

Path parameters

Response schema

200

Errors

Request example

Responses