# Create a new group

Creates a new group owned by the currently authenticated user. The user becomes the group owner with full administrative privileges. The group name must be unique across the platform. A forum is automatically created for the group with default categories.

Endpoint: POST /api/v1/groups
Version: 1.0
Security: header

## Request fields (application/json):

  - `privacy` (string, required)
    who can access the group's content
    Enum: "PUBLIC", "PRIVATE"

  - `visibility` (string, required)
    how discoverable the group is
    Enum: "VISIBLE", "UNLISTED", "HIDDEN"

  - `joinMode` (string, required)
    how users can join the group
    Enum: "OPEN", "APPROVAL", "INVITE_ONLY"

  - `bannerId` (string,null)
    Banner upload id or null to remove
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `avatarId` (string,null)
    Avatar upload id or null to remove
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `location` (object,null)
    group's location

  - `location.geo` (object,null)
    Coordinates and other geo data

  - `location.geo.latitude` (number)

  - `location.geo.longitude` (number)

  - `location.geo.altitude` (number,null)

  - `location.geo.accuracy` (number,null)

  - `location.geo.verticalAccuracy` (number,null)

  - `location.geo.speed` (number,null)

  - `location.geo.bearing` (number,null)

  - `location.geo.timestamp` (integer,null)

  - `location.name` (string,null)

  - `location.autoUpdate` (boolean)

  - `location.show` (boolean)

  - `timezone` (object,null)
    group's timezone

  - `timezone.ianaTimezone` (string,null)

  - `name` (string, required)
    Unique group name used in URLs. Must be alphanumeric with underscores/hyphens, 3-30 characters.

  - `displayName` (string, required)
    Human-readable display name for the group. Can contain spaces and special characters.

  - `description` (string,null)
    Detailed description of the group's purpose and activities. Supports markdown formatting.

  - `fields` (object, required)
    Custom fields for the group

  - `meta` (object, required)
    Additional metadata for the group including rules, guidelines, and custom fields

  - `meta.color` (string, required)
    Group color in HEX format

  - `type` (string, required)
    The type/category of the group (ORGANIZATION, COMMUNITY, PROJECT, etc.)
    Enum: "CHANNEL", "INTEREST_GROUP", "ORGANIZATION"

## Response 200 fields (application/json):

  - `meta` (object, required)
    group metadata including color

  - `meta.color` (string, required)
    Group color in HEX format

  - `privacy` (string, required)
    who can access the group's content
    Enum: "PUBLIC", "PRIVATE"

  - `visibility` (string, required)
    how discoverable the group is
    Enum: "VISIBLE", "UNLISTED", "HIDDEN"

  - `joinMode` (string, required)
    how users can join the group
    Enum: "OPEN", "APPROVAL", "INVITE_ONLY"

  - `location` (object,null)
    group's location

  - `location.geo` (object,null)
    Coordinates and other geo data

  - `location.geo.latitude` (number)

  - `location.geo.longitude` (number)

  - `location.geo.altitude` (number,null)

  - `location.geo.accuracy` (number,null)

  - `location.geo.verticalAccuracy` (number,null)

  - `location.geo.speed` (number,null)

  - `location.geo.bearing` (number,null)

  - `location.geo.timestamp` (integer,null)

  - `location.name` (string,null)

  - `location.autoUpdate` (boolean)

  - `location.show` (boolean)

  - `timezone` (object,null)
    group's timezone

  - `timezone.ianaTimezone` (string,null)

  - `groupId` (string, required)
    internal id of this group
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `groupName` (string, required)
    unique group name

  - `domain` (string, required)
    group's domain, remote only, empty for local

  - `displayName` (string, required)
    full name of the group

  - `summary` (string, required)
    Group description

  - `uri` (string, required)
    URI of this group

  - `publicKey` (string, required)
    Group's public key for ActivityPub

  - `privateKey` (string,null)
    Group's private key for ActivityPub

  - `forumId` (string,null)
    ID of the forum associated with this group
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `stats` (object, required)
    Group statistics

  - `fields` (object, required)
    Custom fields for the group

  - `type` (string, required)
    the type of this group
    Enum: "CHANNEL", "INTEREST_GROUP", "ORGANIZATION"

  - `membersUrl` (string, required)
    URL to group members

  - `banner` (object,null)
    Group's header/banner upload

  - `banner.uploadId` (string, required)
    Internal id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `banner.userId` (string, required)
    User id this upload belongs to
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `banner.uploadType` (string, required)
    Type of the upload
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `banner.meta` (object, required)
    Meta data

  - `banner.meta.blurhash` (string,null)

  - `banner.meta.altText` (string,null)

  - `banner.size` (integer, required)
    Size in bytes of all the files in this upload

  - `banner.files` (array, required)
    List of all the files this upload has

  - `banner.files.uri` (string,null, required)
    Full url of the file

  - `banner.files.fileId` (string, required)
    File id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `banner.files.extension` (string, required)
    File extension
    Example: "mp4"

  - `banner.files.original` (boolean, required)
    true if this file is original, false if it is a derivative

  - `banner.files.meta` (object, required)
    File metadata. Contains optional values for width, height etc.

  - `banner.files.meta.duration` (number,null)
    Video duration in seconds

  - `banner.files.meta.width` (integer,null)
    Media width

  - `banner.files.meta.height` (integer,null)
    Media height

  - `banner.files.meta.codec` (string,null)
    Video codec

  - `banner.files.meta.rotate` (integer,null)
    Rotation in degrees

  - `banner.files.size` (integer, required)
    File size in bytes

  - `banner.files.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `banner.files.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `banner.files.type` (string, required)
    File type
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `banner.tags` (array, required)
    List of tags attached to upload
    Enum: "Post", "Avatar", "Header", "Album", "Emoji", "Event"

  - `banner.error` (string,null)
    Upload processing error

  - `banner.cached` (boolean)
    true if cached

  - `banner.logs` (string,null)
    Logs

  - `banner.remote` (boolean)
    true if this upload is remote

  - `avatar` (object,null)
    Group's avatar

  - `deletedAt` (string,null)
    Group deletion timestamp
    Example: "2022-03-10T16:15:50Z"

  - `createdAt` (string, required)
    Group's creation timestamp
    Example: "2022-03-10T16:15:50Z"

  - `updatedAt` (string, required)
    Group's last update timestamp
    Example: "2022-03-10T16:15:50Z"

  - `membersCount` (integer)
    Cached count of active members in the group

## Response 401 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation

## Response 403 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation


## Response 400 fields