Florality

GET

/api/v1/search

search: 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

Query parameters

Name	Type	Required	Description
`q`	`string`	Optional	Filter or option: q. Default: "".
`limitPerType`	`integer`	Optional	Filter or option: limit per type. Minimum: 1. Maximum: 50.

Response schema

200

Successful response.

Name	Type	Required	Description
`type`	`string`	Required	Type.
`id`	`string`	Required	Unique identifier.
`label`	`string`	Required	Label.
`subtitle`	`string`	Optional	Subtitle.
`href`	`string`	Required	Href.
`avatarUrl`	`null \| string`	Optional	Resolved avatar URL, or null when unavailable.
`backgroundUrl`	`null \| string`	Optional	Resolved background URL, or null when unavailable.
`profileStyle`	`null \| object`	Optional	Profile presentation settings.
`profileStyle.avatarRing`	`object`	Optional	Avatar Ring.
`profileStyle.avatarRing.show`	`JSON value`	Optional	Show.
`profileStyle.avatarRing.colorHex`	`JSON value`	Optional	Color Hex.
`profileStyle.avatarRing.shape`	`JSON value`	Optional	Shape.
`profileStyle.avatarRing.gradient`	`JSON value`	Optional	Gradient.
`profileStyle.avatarRing.animation`	`JSON value`	Optional	Animation.
`profileStyle.avatarRing.animationSpeed`	`JSON value`	Optional	Animation Speed.
`profileStyle.avatarRing.strokeStyle`	`JSON value`	Optional	Stroke Style.
`profileStyle.avatarRing.customMaskStorageId`	`JSON value`	Optional	Custom Mask Storage Id.
`profileStyle.avatarRing.customMaskPathD`	`JSON value`	Optional	Custom Mask Path D.
`profileStyle.bannerFrame`	`object`	Optional	Banner Frame.
`profileStyle.bannerFrame.colorHex`	`JSON value`	Optional	Color Hex.
`profileStyle.bannerFrame.showBorder`	`JSON value`	Optional	Show Border.
`profileStyle.bannerFrame.borderWidthPx`	`JSON value`	Optional	Border Width Px.
`profileStyle.bannerFrame.borderStyle`	`JSON value`	Optional	Border Style.
`profileStyle.bannerFrame.cornerStyle`	`JSON value`	Optional	Corner Style.
`profileStyle.memberName`	`object`	Optional	Member Name.
`profileStyle.memberName.fontFamily`	`JSON value`	Optional	Font Family.
`profileStyle.memberName.customFontId`	`JSON value`	Optional	Custom Font Id.
`profileStyle.memberName.colorHex`	`JSON value`	Optional	Color Hex.
`profileStyle.memberName.gradient`	`JSON value`	Optional	Gradient.
`profileStyle.memberName.letterSpacing`	`JSON value`	Optional	Letter Spacing.
`profileStyle.memberName.smallCaps`	`JSON value`	Optional	Small Caps.
`profileStyle.memberName.textShadow`	`JSON value`	Optional	Text Shadow.
`profileStyle.memberName.nameEffect`	`JSON value`	Optional	Name Effect.
`profileStyle.bannerImage`	`object`	Optional	Banner Image.
`profileStyle.bannerImage.brightness`	`JSON value`	Optional	Brightness.
`profileStyle.bannerImage.contrast`	`JSON value`	Optional	Contrast.
`profileStyle.bannerImage.tintHex`	`JSON value`	Optional	Tint Hex.
`profileStyle.bannerImage.tintOpacity`	`JSON value`	Optional	Tint Opacity.
`profileStyle.avatarImage`	`object`	Optional	Avatar Image.
`profileStyle.avatarImage.brightness`	`JSON value`	Optional	Brightness.
`profileStyle.avatarImage.contrast`	`JSON value`	Optional	Contrast.
`profileStyle.avatarImage.tintHex`	`JSON value`	Optional	Tint Hex.
`profileStyle.avatarImage.tintOpacity`	`JSON value`	Optional	Tint Opacity.
`profileStyle.bannerOverlay`	`string`	Optional	Banner Overlay. Allowed values: "none", "vignette", "soft-gradient", "film-grain", "glass-blur", "pattern-dots", "pattern-grid".
`profileStyle.profileBackgroundPattern`	`string`	Optional	Profile Background Pattern. Allowed values: "grid", "none", "dots", "noise".
`profileStyle.heroLayout`	`string`	Optional	Hero Layout. Allowed values: "shell-default", "avatar-centered", "avatar-left".
`profileStyle.accentColorHex`	`null \| string`	Optional	Accent Color Hex.
`profileStyle.profileBackgroundFill`	`object`	Optional	Profile Background Fill.
`profileStyle.profileBackgroundFill.mode`	`JSON value`	Optional	Mode.
`profileStyle.profileBackgroundFill.gradient`	`JSON value`	Optional	Gradient.
`profileStyle.profileBackgroundFill.solidHex`	`JSON value`	Optional	Solid Hex.
`profileStyle.pageBackgroundFill`	`object`	Optional	Page Background Fill. Friend-only: full Friends viewport backdrop (solid/gradient).
`profileStyle.pageBackgroundFill.mode`	`JSON value`	Optional	Mode.
`profileStyle.pageBackgroundFill.gradient`	`JSON value`	Optional	Gradient.
`profileStyle.pageBackgroundFill.solidHex`	`JSON value`	Optional	Solid Hex.
`profileStyle.panelBackgroundFill`	`object`	Optional	Panel Background Fill. Friend-only: profile card panel fill (free: preset solids; Pro+: custom solid/gradient).
`profileStyle.panelBackgroundFill.mode`	`JSON value`	Optional	Mode.
`profileStyle.panelBackgroundFill.gradient`	`JSON value`	Optional	Gradient.
`profileStyle.panelBackgroundFill.solidHex`	`JSON value`	Optional	Solid Hex.
`profileStyle.panelFillAccentHex`	`null \| string`	Optional	Panel Fill Accent Hex. Friend-only: optional accent mixed into the profile panel backdrop (Pro+).
`profileStyle.panelCardAccentHex`	`null \| string`	Optional	Panel Card Accent Hex. Friend-only: optional accent mixed into section cards (Pro+).
`archived`	`boolean`	Optional	Archived. Archived group matched by name; listed after active results. Allowed values: false, true.

Errors

400 · JSON error: Request failed (BAD_REQUEST).
401 · JSON error: Missing or invalid API key. Use Authorization: Bearer <token>.
403 · JSON error: Requires search: 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/search' \
  --header "Authorization: Bearer $FLORALITY_KEY"

Responses

Successful response.

JSON

[
  {
    "type": "member",
    "id": "11111111-1111-4111-8111-111111111111",
    "label": "demo",
    "subtitle": "River",
    "href": "demo",
    "avatarUrl": null,
    "backgroundUrl": null,
    "profileStyle": null
  }
]

Example values are illustrative demo data.

Name

Type

Required

Description

q

string

Optional

Filter or option: q. Default: "".

limitPerType

integer

Optional

Filter or option: limit per type. Minimum: 1. Maximum: 50.

Response schema

200

Successful response.

Name	Type	Required	Description
`type`	`string`	Required	Type.
`id`	`string`	Required	Unique identifier.
`label`	`string`	Required	Label.
`subtitle`	`string`	Optional	Subtitle.
`href`	`string`	Required	Href.
`avatarUrl`	`null \| string`	Optional	Resolved avatar URL, or null when unavailable.
`backgroundUrl`	`null \| string`	Optional	Resolved background URL, or null when unavailable.
`profileStyle`	`null \| object`	Optional	Profile presentation settings.
`profileStyle.avatarRing`	`object`	Optional	Avatar Ring.
`profileStyle.avatarRing.show`	`JSON value`	Optional	Show.
`profileStyle.avatarRing.colorHex`	`JSON value`	Optional	Color Hex.
`profileStyle.avatarRing.shape`	`JSON value`	Optional	Shape.
`profileStyle.avatarRing.gradient`	`JSON value`	Optional	Gradient.
`profileStyle.avatarRing.animation`	`JSON value`	Optional	Animation.
`profileStyle.avatarRing.animationSpeed`	`JSON value`	Optional	Animation Speed.
`profileStyle.avatarRing.strokeStyle`	`JSON value`	Optional	Stroke Style.
`profileStyle.avatarRing.customMaskStorageId`	`JSON value`	Optional	Custom Mask Storage Id.
`profileStyle.avatarRing.customMaskPathD`	`JSON value`	Optional	Custom Mask Path D.
`profileStyle.bannerFrame`	`object`	Optional	Banner Frame.
`profileStyle.bannerFrame.colorHex`	`JSON value`	Optional	Color Hex.
`profileStyle.bannerFrame.showBorder`	`JSON value`	Optional	Show Border.
`profileStyle.bannerFrame.borderWidthPx`	`JSON value`	Optional	Border Width Px.
`profileStyle.bannerFrame.borderStyle`	`JSON value`	Optional	Border Style.
`profileStyle.bannerFrame.cornerStyle`	`JSON value`	Optional	Corner Style.
`profileStyle.memberName`	`object`	Optional	Member Name.
`profileStyle.memberName.fontFamily`	`JSON value`	Optional	Font Family.
`profileStyle.memberName.customFontId`	`JSON value`	Optional	Custom Font Id.
`profileStyle.memberName.colorHex`	`JSON value`	Optional	Color Hex.
`profileStyle.memberName.gradient`	`JSON value`	Optional	Gradient.
`profileStyle.memberName.letterSpacing`	`JSON value`	Optional	Letter Spacing.
`profileStyle.memberName.smallCaps`	`JSON value`	Optional	Small Caps.
`profileStyle.memberName.textShadow`	`JSON value`	Optional	Text Shadow.
`profileStyle.memberName.nameEffect`	`JSON value`	Optional	Name Effect.
`profileStyle.bannerImage`	`object`	Optional	Banner Image.
`profileStyle.bannerImage.brightness`	`JSON value`	Optional	Brightness.
`profileStyle.bannerImage.contrast`	`JSON value`	Optional	Contrast.
`profileStyle.bannerImage.tintHex`	`JSON value`	Optional	Tint Hex.
`profileStyle.bannerImage.tintOpacity`	`JSON value`	Optional	Tint Opacity.
`profileStyle.avatarImage`	`object`	Optional	Avatar Image.
`profileStyle.avatarImage.brightness`	`JSON value`	Optional	Brightness.
`profileStyle.avatarImage.contrast`	`JSON value`	Optional	Contrast.
`profileStyle.avatarImage.tintHex`	`JSON value`	Optional	Tint Hex.
`profileStyle.avatarImage.tintOpacity`	`JSON value`	Optional	Tint Opacity.
`profileStyle.bannerOverlay`	`string`	Optional	Banner Overlay. Allowed values: "none", "vignette", "soft-gradient", "film-grain", "glass-blur", "pattern-dots", "pattern-grid".
`profileStyle.profileBackgroundPattern`	`string`	Optional	Profile Background Pattern. Allowed values: "grid", "none", "dots", "noise".
`profileStyle.heroLayout`	`string`	Optional	Hero Layout. Allowed values: "shell-default", "avatar-centered", "avatar-left".
`profileStyle.accentColorHex`	`null \| string`	Optional	Accent Color Hex.
`profileStyle.profileBackgroundFill`	`object`	Optional	Profile Background Fill.
`profileStyle.profileBackgroundFill.mode`	`JSON value`	Optional	Mode.
`profileStyle.profileBackgroundFill.gradient`	`JSON value`	Optional	Gradient.
`profileStyle.profileBackgroundFill.solidHex`	`JSON value`	Optional	Solid Hex.
`profileStyle.pageBackgroundFill`	`object`	Optional	Page Background Fill. Friend-only: full Friends viewport backdrop (solid/gradient).
`profileStyle.pageBackgroundFill.mode`	`JSON value`	Optional	Mode.
`profileStyle.pageBackgroundFill.gradient`	`JSON value`	Optional	Gradient.
`profileStyle.pageBackgroundFill.solidHex`	`JSON value`	Optional	Solid Hex.
`profileStyle.panelBackgroundFill`	`object`	Optional	Panel Background Fill. Friend-only: profile card panel fill (free: preset solids; Pro+: custom solid/gradient).
`profileStyle.panelBackgroundFill.mode`	`JSON value`	Optional	Mode.
`profileStyle.panelBackgroundFill.gradient`	`JSON value`	Optional	Gradient.
`profileStyle.panelBackgroundFill.solidHex`	`JSON value`	Optional	Solid Hex.
`profileStyle.panelFillAccentHex`	`null \| string`	Optional	Panel Fill Accent Hex. Friend-only: optional accent mixed into the profile panel backdrop (Pro+).
`profileStyle.panelCardAccentHex`	`null \| string`	Optional	Panel Card Accent Hex. Friend-only: optional accent mixed into section cards (Pro+).
`archived`	`boolean`	Optional	Archived. Archived group matched by name; listed after active results. Allowed values: false, true.

Errors

400 · JSON error

Request failed (BAD_REQUEST).

401 · JSON error

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

403 · JSON error

Requires search: 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

[
  {
    "type": "member",
    "id": "11111111-1111-4111-8111-111111111111",
    "label": "demo",
    "subtitle": "River",
    "href": "demo",
    "avatarUrl": null,
    "backgroundUrl": null,
    "profileStyle": null
  }
]

Example values are illustrative demo data.

Search unified

Parameters

Query parameters

Response schema

200

Errors

Request example

Responses

Search unified

Parameters

Query parameters

Response schema

200

Errors

Request example

Responses