Florality

POST

/api/v1/groups

groups: read_writedirectories: 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.

Groups and directories

The higher access level of groups and directories is used. Either scope can satisfy this requirement; both are not required. read_write includes read access.

Parameters

No path or query parameters.

Request body

application/json · required

Unknown properties are rejected.

Name	Type	Required	Description
`name`	`string`	Required	Name of the resource.
`parentId`	`string (uuid)`	Optional	Parent resource identifier.
`clientMutationId`	`string (uuid)`	Optional	Client Mutation Id.
`description`	`string`	Optional	Description of the resource.
`icon`	`string`	Optional	Icon.
`colorPreset`	`string`	Optional	Color Preset.
`sideSystemId`	`string (uuid)`	Optional	Side System Id.
`subSystemId`	`string (uuid) \| null`	Optional	Sub System Id.

Response schema

201

Created.

Name	Type	Required	Description
`group`	`object`	Optional	Group.
`group.parentId`	`string`	Optional	Parent resource identifier.
`group.icon`	`string`	Optional	Icon.
`group.iconColorPreset`	`string`	Optional	Icon Color Preset.
`group.createdAt`	`number`	Optional	Creation time.
`group.updatedAt`	`number`	Optional	Most recent update time.
`group.version`	`number`	Required	Version used for optimistic concurrency checks.
`group.sideSystemId`	`string`	Optional	Side System Id.
`group.subSystemId`	`string`	Optional	Sub System Id.
`group.deletedAt`	`number`	Optional	Deletion time; null when active.
`group.purgeAt`	`number`	Optional	Purge At.
`group.originalParentId`	`string`	Optional	Original Parent Id.
`group.archivedAt`	`number`	Optional	Archiving time; null when active.
`group.description`	`string`	Optional	Description of the resource.
`group._id`	`string`	Required	Unique identifier.
`group.userId`	`string`	Required	Owning account identifier.
`group.name`	`string`	Required	Name of the resource.
`receipt`	`object`	Optional	Receipt.
`receipt.entityId`	`string`	Required	Entity Id.
`receipt.entityVersion`	`number`	Required	Entity Version.
`receipt.operation`	`string`	Required	Operation.
`receipt.clientMutationId`	`string`	Optional	Client Mutation Id.
`receipt.serverTimestamp`	`number`	Required	Server Timestamp.
`receipt.replayKey`	`string`	Required	Replay Key.
`_id`	`string`	Optional	Unique identifier.
`name`	`string`	Optional	Name of the resource.
`description`	`string`	Optional	Description of the resource.
`icon`	`string`	Optional	Icon.
`colorPreset`	`string`	Optional	Color Preset.
`createdAt`	`number`	Optional	Creation time.
`updatedAt`	`number`	Optional	Most recent update time.
`memberCount`	`number`	Optional	Member Count.

Errors

400 · JSON error: Invalid JSON body.
401 · JSON error: Missing or invalid API key. Use Authorization: Bearer <token>.
403 · JSON error: Requires groups or directories: 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.
500 · JSON error: Group was created but could not be loaded.

Request example

Set FLORALITY_KEY in your environment. These examples use demo identifiers.

Shell

curl --request POST 'https://floralitys.com/api/v1/groups' \
  --header "Authorization: Bearer $FLORALITY_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "River"
}'

Responses

Created.

JSON

{
  "group": {
    "parentId": "11111111-1111-4111-8111-111111111111",
    "icon": "demo",
    "iconColorPreset": "#70846b",
    "createdAt": 1767225600000,
    "updatedAt": 1767225600000,
    "version": 0,
    "sideSystemId": "11111111-1111-4111-8111-111111111111",
    "subSystemId": "11111111-1111-4111-8111-111111111111",
    "originalParentId": "11111111-1111-4111-8111-111111111111",
    "description": "A note from our demo system.",
    "_id": "11111111-1111-4111-8111-111111111111",
    "userId": "11111111-1111-4111-8111-111111111111",
    "name": "River"
  },
  "receipt": {
    "entityId": "11111111-1111-4111-8111-111111111111",
    "entityVersion": 0,
    "operation": "demo",
    "clientMutationId": "11111111-1111-4111-8111-111111111111",
    "serverTimestamp": 0,
    "replayKey": "demo"
  }
}

Example values are illustrative demo data.

Request body

application/json · required

Unknown properties are rejected.

Name	Type	Required	Description
`name`	`string`	Required	Name of the resource.
`parentId`	`string (uuid)`	Optional	Parent resource identifier.
`clientMutationId`	`string (uuid)`	Optional	Client Mutation Id.
`description`	`string`	Optional	Description of the resource.
`icon`	`string`	Optional	Icon.
`colorPreset`	`string`	Optional	Color Preset.
`sideSystemId`	`string (uuid)`	Optional	Side System Id.
`subSystemId`	`string (uuid) \| null`	Optional	Sub System Id.

Response schema

201

Created.

Name	Type	Required	Description
`group`	`object`	Optional	Group.
`group.parentId`	`string`	Optional	Parent resource identifier.
`group.icon`	`string`	Optional	Icon.
`group.iconColorPreset`	`string`	Optional	Icon Color Preset.
`group.createdAt`	`number`	Optional	Creation time.
`group.updatedAt`	`number`	Optional	Most recent update time.
`group.version`	`number`	Required	Version used for optimistic concurrency checks.
`group.sideSystemId`	`string`	Optional	Side System Id.
`group.subSystemId`	`string`	Optional	Sub System Id.
`group.deletedAt`	`number`	Optional	Deletion time; null when active.
`group.purgeAt`	`number`	Optional	Purge At.
`group.originalParentId`	`string`	Optional	Original Parent Id.
`group.archivedAt`	`number`	Optional	Archiving time; null when active.
`group.description`	`string`	Optional	Description of the resource.
`group._id`	`string`	Required	Unique identifier.
`group.userId`	`string`	Required	Owning account identifier.
`group.name`	`string`	Required	Name of the resource.
`receipt`	`object`	Optional	Receipt.
`receipt.entityId`	`string`	Required	Entity Id.
`receipt.entityVersion`	`number`	Required	Entity Version.
`receipt.operation`	`string`	Required	Operation.
`receipt.clientMutationId`	`string`	Optional	Client Mutation Id.
`receipt.serverTimestamp`	`number`	Required	Server Timestamp.
`receipt.replayKey`	`string`	Required	Replay Key.
`_id`	`string`	Optional	Unique identifier.
`name`	`string`	Optional	Name of the resource.
`description`	`string`	Optional	Description of the resource.
`icon`	`string`	Optional	Icon.
`colorPreset`	`string`	Optional	Color Preset.
`createdAt`	`number`	Optional	Creation time.
`updatedAt`	`number`	Optional	Most recent update time.
`memberCount`	`number`	Optional	Member Count.

Errors

400 · JSON error

Invalid JSON body.

401 · JSON error

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

403 · JSON error

Requires groups or directories: 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.

500 · JSON error

Group was created but could not be loaded.

Request example

Set FLORALITY_KEY in your environment. These examples use demo identifiers.

Shell

curl --request POST 'https://floralitys.com/api/v1/groups' \
  --header "Authorization: Bearer $FLORALITY_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "River"
}'

Responses

Created.

JSON

{
  "group": {
    "parentId": "11111111-1111-4111-8111-111111111111",
    "icon": "demo",
    "iconColorPreset": "#70846b",
    "createdAt": 1767225600000,
    "updatedAt": 1767225600000,
    "version": 0,
    "sideSystemId": "11111111-1111-4111-8111-111111111111",
    "subSystemId": "11111111-1111-4111-8111-111111111111",
    "originalParentId": "11111111-1111-4111-8111-111111111111",
    "description": "A note from our demo system.",
    "_id": "11111111-1111-4111-8111-111111111111",
    "userId": "11111111-1111-4111-8111-111111111111",
    "name": "River"
  },
  "receipt": {
    "entityId": "11111111-1111-4111-8111-111111111111",
    "entityVersion": 0,
    "operation": "demo",
    "clientMutationId": "11111111-1111-4111-8111-111111111111",
    "serverTimestamp": 0,
    "replayKey": "demo"
  }
}

Example values are illustrative demo data.

Create group

Parameters

Request body

Response schema

201

Errors

Request example

Responses

Create group

Parameters

Request body

Response schema

201

Errors

Request example

Responses