Skip to content
Browse docscreate_group

create_group

Creates a new group with you as its first moderator.

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false

When to use it#

Only when asked to start a group, such as "make a group in Gravity for my family". Check list_groups first when the member may already have one. You are the new group’s first member and moderator. Invitees are optional; offer suggest_group_members and issue_invitations next. Creating a group contacts nobody.

Inputs#

InputRequiredTypeDescription
nameyesstringHow members will see the group, up to 100 characters.
descriptionnostringWhat the group is for, up to 500 characters.
websiteDomainnostringThe public website of the organization the group is about, such as ycombinator.com, whose logo marks the group. A full URL is reduced to its domain; an invalid or empty supplied website is rejected. Omit it when unknown.

Returns#

The group and founder membership commit together. The result is captured in that transaction; it does not depend on a later detail read. Group creation and invitation issuance are separate commits. If invitations fail, keep the returned group ID and continue from that group.

Success returns status, message, and group, the detailed group shape returned by get_group, plus the group's link.

If you already moderate a group with this name, ignoring case, nothing is created. The result is a request_rejected error whose group is that group. Concurrent creates by the same member use the same duplicate check under a lock. This is a name rule, not a replay key: renaming or deleting the earlier group can allow a later create with the old name. After an uncertain response, read list_groups before retrying. Errors use the common contract.

Examples#

json
{
  "name": "Synthetic family"
}

Example response (synthetic data):

json
{
  "status": "success",
  "message": "Synthetic family is ready. You are its first member and moderator. Nothing has been sent.",
  "group": {
    "publicId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "name": "Synthetic family",
    "description": null,
    "websiteDomain": null,
    "memberCount": 1,
    "role": "moderator"
  },
  "link": "https://www.meetgravity.ai/dashboard/groups/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}