Florality

POST

/api/v1/social/widgets

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

Request body

application/json · required

Name	Type	Required	Description
`id`	`string (uuid)`	Optional	Unique identifier.
`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".
`title`	`string \| null`	Optional	Display title. Maximum length: 120.
`config`	`object`	Required	Config.
`config.kind`	`string`	Required	Kind.
`config.statusText`	`string`	Optional	Status Text. Minimum length: 1. Maximum length: 280.
`config.serverName`	`string`	Optional	Server Name. Minimum length: 1. Maximum length: 120.
`config.inviteUrl`	`string (uri) \| null`	Optional	Invite Url.
`config.provider`	`string`	Optional	Provider. Allowed values: "spotify".
`config.trackTitle`	`string`	Optional	Track Title. Minimum length: 1. Maximum length: 200.
`config.artistName`	`string`	Optional	Artist Name. Minimum length: 1. Maximum length: 200.
`config.artworkUrl`	`string (uri) \| null`	Optional	Artwork Url.
`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".
`config.displayStyle`	`string`	Optional	Display Style. Allowed values: "compact_card", "album_art_card", "playlist_shelf", "album_grid", "now_playing_bar".
`config.spotifyResourceType`	`string \| null`	Optional	Spotify Resource Type. Allowed values: "playlist", "album", "track". Default: null.
`config.spotifyResourceId`	`string \| null`	Optional	Spotify Resource Id. Pattern: ^[A-Za-z0-9]{22}$. Default: null.
`config.playlistUrl`	`string (uri) \| null`	Optional	Playlist Url. Default: null.
`config.playlistName`	`string \| null`	Optional	Playlist Name. Default: null. Maximum length: 160.
`config.playlistCoverUrl`	`string (uri) \| null`	Optional	Playlist Cover Url. Default: null.
`config.playlistTrackCount`	`integer \| null`	Optional	Playlist Track Count. Default: null. Minimum: 0. Maximum: 10000.
`config.playlistDurationMinutes`	`integer \| null`	Optional	Playlist Duration Minutes. Default: null. Minimum: 0. Maximum: 100000.
`config.memberId`	`string (uuid) \| null`	Optional	Associated member identifier.
`config.quote`	`string`	Optional	Quote. Minimum length: 1. Maximum length: 500.
`config.author`	`string \| null`	Optional	Author. Maximum length: 120.
`config.pronouns`	`string`	Optional	Member pronouns. Minimum length: 1. Maximum length: 120.
`config.identity`	`string \| null`	Optional	Identity. Maximum length: 200.
`config.mood`	`string`	Optional	Mood. Minimum length: 1. Maximum length: 120.
`config.note`	`string \| null`	Optional	Note. Maximum length: 280.
`config.imageUrls`	`array<string>`	Optional	Image Urls. Default: []. At most 24 items.
`config.label`	`string`	Optional	Label.
`config.color`	`string \| null`	Optional	Color. Maximum length: 32.
`config.linkIds`	`array<string (uuid)>`	Optional	Link Ids. At most 100 items.
`config.entries`	`array<object>`	Optional	Entries. At most 24 items.
`config.entries[].label`	`string`	Required	Label. Minimum length: 1. Maximum length: 80.
`config.entries[].value`	`string`	Required	Value. Minimum length: 1. Maximum length: 240.
`config.allowAnonymous`	`boolean`	Optional	Allow Anonymous.
`config.maxItems`	`integer`	Optional	Max Items. Minimum: 1. Maximum: 40.
`config.targetAt`	`integer`	Optional	Target At. Greater than 0.
`config.question`	`string`	Optional	Question. Minimum length: 1. Maximum length: 240.
`config.options`	`array<string>`	Optional	Options. At least 2 items. At most 8 items.
`config.allowMultipleSelections`	`boolean`	Optional	Allow Multiple Selections. Default: false.
`config.stickerUrls`	`array<string (uri)>`	Optional	Sticker Urls. At most 100 items.
`config.title`	`string`	Optional	Display title. Minimum length: 1. Maximum length: 120.
`config.body`	`string`	Optional	Body. Minimum length: 1.
`visibility`	`string`	Required	Visibility. Allowed values: "public", "logged_in", "friends_only", "mutuals_only", "private".
`size`	`string`	Required	Size. Allowed values: "small", "medium", "large", "full".
`pinned`	`boolean`	Optional	Pinned. Default: false.
`collapsed`	`boolean`	Optional	Collapsed. Default: false.
`sortOrder`	`integer`	Optional	Sort Order. Minimum: 0. Maximum: 2147483647.

Response schema

201

Created.

Name	Type	Required	Description
`widgetId`	`string`	Required	Widget Id.

Errors

400 · JSON error: Invalid JSON body.
401 · JSON error: Missing or invalid API key. Use Authorization: Bearer <token>.
403 · JSON error: Requires social: read_write; 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 POST 'https://floralitys.com/api/v1/social/widgets' \
  --header "Authorization: Bearer $FLORALITY_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "type": "status",
  "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
  },
  "visibility": "public",
  "size": "small"
}'

Responses

Created.

JSON

{
  "widgetId": "11111111-1111-4111-8111-111111111111"
}

Example values are illustrative demo data.

Request body

application/json · required

Name	Type	Required	Description
`id`	`string (uuid)`	Optional	Unique identifier.
`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".
`title`	`string \| null`	Optional	Display title. Maximum length: 120.
`config`	`object`	Required	Config.
`config.kind`	`string`	Required	Kind.
`config.statusText`	`string`	Optional	Status Text. Minimum length: 1. Maximum length: 280.
`config.serverName`	`string`	Optional	Server Name. Minimum length: 1. Maximum length: 120.
`config.inviteUrl`	`string (uri) \| null`	Optional	Invite Url.
`config.provider`	`string`	Optional	Provider. Allowed values: "spotify".
`config.trackTitle`	`string`	Optional	Track Title. Minimum length: 1. Maximum length: 200.
`config.artistName`	`string`	Optional	Artist Name. Minimum length: 1. Maximum length: 200.
`config.artworkUrl`	`string (uri) \| null`	Optional	Artwork Url.
`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".
`config.displayStyle`	`string`	Optional	Display Style. Allowed values: "compact_card", "album_art_card", "playlist_shelf", "album_grid", "now_playing_bar".
`config.spotifyResourceType`	`string \| null`	Optional	Spotify Resource Type. Allowed values: "playlist", "album", "track". Default: null.
`config.spotifyResourceId`	`string \| null`	Optional	Spotify Resource Id. Pattern: ^[A-Za-z0-9]{22}$. Default: null.
`config.playlistUrl`	`string (uri) \| null`	Optional	Playlist Url. Default: null.
`config.playlistName`	`string \| null`	Optional	Playlist Name. Default: null. Maximum length: 160.
`config.playlistCoverUrl`	`string (uri) \| null`	Optional	Playlist Cover Url. Default: null.
`config.playlistTrackCount`	`integer \| null`	Optional	Playlist Track Count. Default: null. Minimum: 0. Maximum: 10000.
`config.playlistDurationMinutes`	`integer \| null`	Optional	Playlist Duration Minutes. Default: null. Minimum: 0. Maximum: 100000.
`config.memberId`	`string (uuid) \| null`	Optional	Associated member identifier.
`config.quote`	`string`	Optional	Quote. Minimum length: 1. Maximum length: 500.
`config.author`	`string \| null`	Optional	Author. Maximum length: 120.
`config.pronouns`	`string`	Optional	Member pronouns. Minimum length: 1. Maximum length: 120.
`config.identity`	`string \| null`	Optional	Identity. Maximum length: 200.
`config.mood`	`string`	Optional	Mood. Minimum length: 1. Maximum length: 120.
`config.note`	`string \| null`	Optional	Note. Maximum length: 280.
`config.imageUrls`	`array<string>`	Optional	Image Urls. Default: []. At most 24 items.
`config.label`	`string`	Optional	Label.
`config.color`	`string \| null`	Optional	Color. Maximum length: 32.
`config.linkIds`	`array<string (uuid)>`	Optional	Link Ids. At most 100 items.
`config.entries`	`array<object>`	Optional	Entries. At most 24 items.
`config.entries[].label`	`string`	Required	Label. Minimum length: 1. Maximum length: 80.
`config.entries[].value`	`string`	Required	Value. Minimum length: 1. Maximum length: 240.
`config.allowAnonymous`	`boolean`	Optional	Allow Anonymous.
`config.maxItems`	`integer`	Optional	Max Items. Minimum: 1. Maximum: 40.
`config.targetAt`	`integer`	Optional	Target At. Greater than 0.
`config.question`	`string`	Optional	Question. Minimum length: 1. Maximum length: 240.
`config.options`	`array<string>`	Optional	Options. At least 2 items. At most 8 items.
`config.allowMultipleSelections`	`boolean`	Optional	Allow Multiple Selections. Default: false.
`config.stickerUrls`	`array<string (uri)>`	Optional	Sticker Urls. At most 100 items.
`config.title`	`string`	Optional	Display title. Minimum length: 1. Maximum length: 120.
`config.body`	`string`	Optional	Body. Minimum length: 1.
`visibility`	`string`	Required	Visibility. Allowed values: "public", "logged_in", "friends_only", "mutuals_only", "private".
`size`	`string`	Required	Size. Allowed values: "small", "medium", "large", "full".
`pinned`	`boolean`	Optional	Pinned. Default: false.
`collapsed`	`boolean`	Optional	Collapsed. Default: false.
`sortOrder`	`integer`	Optional	Sort Order. Minimum: 0. Maximum: 2147483647.

Name

Type

Required

Description

widgetId

string

Required

Widget Id.

Errors

400 · JSON error

Invalid JSON body.

401 · JSON error

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

403 · JSON error

Requires social: read_write; 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 POST 'https://floralitys.com/api/v1/social/widgets' \
  --header "Authorization: Bearer $FLORALITY_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "type": "status",
  "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
  },
  "visibility": "public",
  "size": "small"
}'

Create social widget

Parameters

Request body

Response schema

201

Errors

Request example

Responses

Create social widget

Parameters

Request body

Response schema

201

Errors

Request example

Responses