# Group Channels

API endpoints for managing channels within groups. Channels are specialized accounts that enable organized content distribution within groups. They support hierarchical organization with main and default channels, privacy controls inherited from parent groups, and both scoped (group-specific) and global usernames for discovery. Group administrators manage channels while members can follow them.

## List all group channels

 - [GET /api/v1/groups/{groupId}/channels](https://docs.wellesley.social/openapi/group-channels/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1channels/get.md): Retrieves a complete list of all channels within the specified group. Requires group membership to access. Returns both public and private channels visible to the authenticated user. The response includes channel metadata such as privacy settings, default status, and whether each channel is designated as the main channel. Channels are returned in creation order.

RBAC: requires GroupChannels.Read

## Create a new group channel

 - [POST /api/v1/groups/{groupId}/channels](https://docs.wellesley.social/openapi/group-channels/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1channels/post.md): Creates a new channel within the specified group. Requires group administrator privileges. The channel's privacy is constrained by the parent group's privacy settings (private groups can only have private channels). The first channel created is automatically designated as both main and default. Channels can have both scoped usernames (group-specific) and optional global usernames (platform-wide). Note: Avatar and header images must be set via the update endpoint after channel creation.

RBAC: requires GroupChannels.Manage

## List default channels

 - [GET /api/v1/groups/{groupId}/channels/default](https://docs.wellesley.social/openapi/group-channels/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1channels~1default/get.md): Retrieves all channels designated as default for the specified group. Default channels are automatically followed by new members upon joining. Requires group membership to access. Returns an empty array if no default channels are configured. The response includes full channel information including privacy settings and follow status.

RBAC: requires GroupChannels.Read

## Get group channel by scoped username

 - [GET /api/v1/groups/{groupId}/channels/lookup](https://docs.wellesley.social/openapi/group-channels/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1channels~1lookup/get.md): Retrieves a channel using its group-scoped username (slug). Useful for accessing channels without global usernames. Private channels and channels inside private groups require membership and otherwise return 404.

## Retrieve main channel

 - [GET /api/v1/groups/{groupId}/channels/main](https://docs.wellesley.social/openapi/group-channels/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1channels~1main/get.md): Retrieves the designated main channel for the specified group. Access control is based on both group and channel privacy settings. Public groups with public main channels are accessible to everyone. Private groups or private channels require group membership. Returns 404 if no main channel is designated or if access is denied due to privacy settings.

## Check if channel username is already in use

 - [GET /api/v1/groups/{groupId}/channels/namecheck/{channelUsername}](https://docs.wellesley.social/openapi/group-channels/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1channels~1namecheck~1%7Bchannelusername%7D/get.md): Used for inline validation during channel creation. Scoped to the group. Returns a result object indicating whether the username is taken within the specified group.

RBAC: requires GroupChannels.Manage

## List public channels

 - [GET /api/v1/groups/{groupId}/channels/public](https://docs.wellesley.social/openapi/group-channels/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1channels~1public/get.md): Retrieves all public channels from a public group. This endpoint is accessible to everyone, including non-members and unauthenticated users, but only works for public groups. Private groups will return an error regardless of their channels' privacy settings. Useful for discovery and browsing group content before joining. Channels with global usernames are included with their platform-wide identifiers.

## Update an existing group channel

 - [PUT /api/v1/groups/{groupId}/channels/{channelId}](https://docs.wellesley.social/openapi/group-channels/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1channels~1%7Bchannelid%7D/put.md): Modifies properties of an existing channel. Requires group administrator privileges. Only included fields are updated; null fields preserve existing values. Privacy changes are constrained by the parent group's privacy (cannot make a channel public in a private group). Changes to default status affect auto-follow behavior for new members.

RBAC: requires GroupChannels.Manage

## Get group channel by id

 - [GET /api/v1/groups/{groupId}/channels/{channelId}](https://docs.wellesley.social/openapi/group-channels/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1channels~1%7Bchannelid%7D/get.md): Retrieves a channel within the current group by its identifier. Access to private channels (or channels in private groups) is restricted to group members; outsiders receive a 404.

## Delete a group channel

 - [DELETE /api/v1/groups/{groupId}/channels/{channelId}](https://docs.wellesley.social/openapi/group-channels/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1channels~1%7Bchannelid%7D/delete.md): Removes the specified channel from the group. Requires group administrator privileges. The channel is marked as deleted immediately and background workers handle cleanup of posts, media, and follower relationships.

RBAC: requires GroupChannels.Manage

## Update channel default status

 - [PUT /api/v1/groups/{groupId}/channels/{channelId}/default](https://docs.wellesley.social/openapi/group-channels/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1channels~1%7Bchannelid%7D~1default/put.md): Toggles whether a channel is designated as a default channel. Requires group administrator privileges. Default channels are automatically followed by new group members upon joining. Multiple channels can be marked as default. This setting helps onboard new members by ensuring they receive content from essential channels immediately.

RBAC: requires GroupChannels.Manage

## Designate channel as main

 - [PUT /api/v1/groups/{groupId}/channels/{channelId}/main](https://docs.wellesley.social/openapi/group-channels/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1channels~1%7Bchannelid%7D~1main/put.md): Sets the specified channel as the main channel for the group. Requires group administrator privileges. Only one channel can be designated as main per group. The main channel serves as the primary communication channel and is prominently displayed in group interfaces. Any existing main channel designation is automatically removed.

RBAC: requires GroupChannels.Manage

## Assign or update global username

 - [PUT /api/v1/groups/{groupId}/channels/{channelId}/username](https://docs.wellesley.social/openapi/group-channels/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1channels~1%7Bchannelid%7D~1username/put.md): Assigns, updates, or removes a global username for a public channel. Requires group administrator privileges. Global usernames provide platform-wide discovery and must be unique across the entire system. Only public channels in public groups can have global usernames. Setting the username to null removes any existing global username assignment.

RBAC: requires GroupChannels.Manage