Florality

GET

/api/v1/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

No path or query parameters.

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.
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/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.

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.

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 social

Parameters

Response schema

200

Errors

Request example

Responses

Get social

Parameters

Response schema

200

Errors

Request example

Responses