# Add a new member to a group

Adds a user as a member of the specified group. For local groups, the membership is created immediately. For federated groups, an ActivityPub message is sent to the remote server. The requesting user must have GroupMembers.Manage permission for the target group. The groupId is provided in the URL path.

RBAC: requires GroupMembers.Manage

Endpoint: POST /api/v1/groups/{groupId}/members
Version: 1.0
Security: header

## Path parameters:

  - `groupId` (string, required)
    The unique identifier of the group
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

## Request fields (application/json):

  - `memberId` (string, required)
    User who will be added as a member of the group
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `role` (string,null)
    The initial role to assign to the new member. Defaults to GROUP_VIEWER if not specified

  - `meta` (object,null)
    Optional metadata to attach to this membership

  - `meta.description` (string, required)
    Optional description or note about this member's role or participation in the group

  - `status` (string, required)
    Initial status of the membership. Defaults to MEMBER if not specified
    Enum: "INVITED", "MEMBER", "PENDING"

## Response 200 fields (application/json):

  - `groupName` (string, required)
    Group name

  - `groupDisplayName` (string, required)
    Group display name

  - `userName` (string, required)
    User name (username)

  - `userDisplayName` (string, required)
    User display name

  - `userDomain` (string,null)
    User domain (null for local users)

  - `groupAvatar` (object,null)
    Group avatar upload object

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

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

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

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

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

  - `groupAvatar.meta.name` (string,null)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  - `userAvatar` (object,null)
    User avatar upload object

  - `groupId` (string, required)
    Group ID
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `memberId` (string, required)
    User who is a member of the group
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `role` (string,null)
    The role identifier that determines the member's permissions within the group.
            Common roles include GROUP_VIEWER, GROUP_EDITOR, GROUP_ADMIN

  - `meta` (object,null)
    Additional metadata about this membership

  - `meta.description` (string, required)
    Optional description or note about this member's role or participation in the group

  - `status` (string, required)
    Current status of the membership (INVITED, MEMBER, or PENDING)
    Enum: "INVITED", "MEMBER", "PENDING"

## 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 404 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation


## Response 400 fields