groups.md

Groups API

Create, update, and manage Urbit groups including membership, roles, and navigation.

CRUD Operations

createGroup

async function createGroup(params: { group: db.Group; memberIds?: string[]; placeHolderTitle?: string }): Promise<db.Group>;

Creates a new group with the specified metadata and optionally invites initial members.

Example:

const newGroup = await createGroup({
  group: {
    id: '',  // Auto-generated by backend
    title: 'Book Club',
    description: 'A place to discuss our favorite books',
    privacy: 'private',
    iconImage: 'https://example.com/book-icon.png',
    coverImage: 'https://example.com/books-banner.jpg',
    currentUserIsMember: true,
    currentUserIsHost: true,
    hostUserId: '~sampel-palnet'
  },
  memberIds: ['~zod', '~bus', '~nec']
});
// Returns: { id: '~sampel-palnet/book-club', title: 'Book Club', ... }

---

getGroup

async function getGroup(groupId: string): Promise<db.Group>;

Retrieves a single group by its ID.

Example:

const group = await getGroup('~sampel-palnet/book-club');
// Returns: {
//   id: '~sampel-palnet/book-club',
//   title: 'Book Club',
//   description: 'A place to discuss books',
//   privacy: 'private',
//   hostUserId: '~sampel-palnet',
//   memberCount: 42,
//   channels: [...],
//   members: [...]
// }

---

getGroups

async function getGroups(): Promise<db.Group[]>;

Retrieves all groups the current user has joined.

Response Data: Array of Group objects containing:

• id - Group identifier (e.g., ~sampel-palnet/my-group)
• title - Display name
• description - Group description
• iconImage / coverImage - Image URLs
• privacy - 'public' | 'private' | 'secret'
• hostUserId - Ship that hosts the group
• currentUserIsMember / currentUserIsHost - Membership flags
• memberCount - Number of members
• lastPostAt - Timestamp of most recent post
• channels - Array of Channel objects
• members - Array of ChatMember objects
• roles - Array of GroupRole objects
• navSections - Navigation sections

Example:

const groups = await getGroups();
// Returns: [
//   { id: '~sampel-palnet/book-club', title: 'Book Club', privacy: 'private', ... },
//   { id: '~zod/public-chat', title: 'Public Chat', privacy: 'public', ... }
// ]

---

updateGroupMeta

async function updateGroupMeta(params: { groupId: string; meta: ub.GroupMeta }): Promise<void>;

Updates a group's metadata (title, description, image, cover).

Example:

await updateGroupMeta({
  groupId: '~sampel-palnet/book-club',
  meta: {
    title: 'Sci-Fi Book Club',
    description: 'Now focusing on science fiction novels',
    image: 'https://example.com/scifi-icon.png',
    cover: 'https://example.com/space-banner.jpg'
  }
});

---

deleteGroup

async function deleteGroup(groupId: string): Promise<void>;

Permanently deletes a group.

---

updateGroupPrivacy

async function updateGroupPrivacy(params: { groupId: string; oldPrivacy: GroupPrivacy; newPrivacy: GroupPrivacy }): Promise<void>;

Changes a group's privacy setting between 'public', 'private', and 'secret'.

---

Membership Management

inviteGroupMembers

async function inviteGroupMembers(params: { groupId: string; contactIds: string[] }): Promise<void>;

Sends invitations to the specified users to join a group.

Example:

await inviteGroupMembers({
  groupId: '~sampel-palnet/book-club',
  contactIds: ['~zod', '~bus', '~nec', '~littel-wolfur']
});

---

acceptGroupJoin

async function acceptGroupJoin(params: { groupId: string; contactIds: string[] }): Promise<void>;

Approves pending join requests from the specified users.

---

rejectGroupJoin

async function rejectGroupJoin(params: { groupId: string; contactIds: string[] }): Promise<void>;

Denies pending join requests from the specified users.

---

cancelGroupJoin

async function cancelGroupJoin(groupId: string): Promise<void>;

Cancels the current user's pending join request for a group.

---

leaveGroup

async function leaveGroup(groupId: string): Promise<void>;

Removes the current user from a group.

---

requestGroupInvitation

async function requestGroupInvitation(groupId: string): Promise<void>;

Sends a join request ("knock") to a private group.

---

rescindGroupInvitationRequest

async function rescindGroupInvitationRequest(groupId: string): Promise<void>;

Withdraws a previously sent join request for a group.

---

kickUsersFromGroup

async function kickUsersFromGroup(params: { groupId: string; contactIds: string[] }): Promise<void>;

Removes the specified users from a group without banning them.

Example:

await kickUsersFromGroup({
  groupId: '~sampel-palnet/book-club',
  contactIds: ['~misbehaving-user']
});

---

banUsersFromGroup

async function banUsersFromGroup(params: { groupId: string; contactIds: string[] }): Promise<void>;

Bans the specified users from a group, preventing them from rejoining.

---

unbanUsersFromGroup

async function unbanUsersFromGroup(params: { groupId: string; contactIds: string[] }): Promise<void>;

Removes a ban on the specified users.

---

Role Management

addGroupRole

async function addGroupRole(params: { groupId: string; roleId: string; meta: db.ClientMeta }): Promise<void>;

Creates a new role in a group.

Example:

await addGroupRole({
  groupId: '~sampel-palnet/book-club',
  roleId: 'moderator',
  meta: {
    title: 'Moderator',
    description: 'Can manage posts and members',
    iconImage: 'https://example.com/mod-badge.png'
  }
});

---

updateGroupRole

async function updateGroupRole(params: { groupId: string; roleId: string; meta: db.ClientMeta }): Promise<void>;

Updates an existing role's metadata.

---

deleteGroupRole

async function deleteGroupRole(params: { groupId: string; roleId: string }): Promise<void>;

Removes a role from a group.

---

addMembersToRole

async function addMembersToRole(params: { groupId: string; roleId: string; ships: string[] }): Promise<void>;

Assigns a role to the specified group members.

Example:

await addMembersToRole({
  groupId: '~sampel-palnet/book-club',
  roleId: 'moderator',
  ships: ['~zod', '~bus']
});

---

removeMembersFromRole

async function removeMembersFromRole(params: { groupId: string; roleId: string; ships: string[] }): Promise<void>;

Removes a role from the specified group members.

---

Navigation Sections

addNavSection

async function addNavSection(params: { groupId: string; navSection: db.GroupNavSection }): Promise<void>;

Creates a new navigation section for organizing channels.

Example:

await addNavSection({
  groupId: '~sampel-palnet/book-club',
  navSection: {
    id: 'section-resources',
    sectionId: 'resources',
    title: 'Resources',
    description: 'Helpful links and documents',
    sectionIndex: 2
  }
});

---

updateNavSection

async function updateNavSection(params: { groupId: string; navSection: db.GroupNavSection }): Promise<void>;

Updates an existing navigation section's metadata.

---

deleteNavSection

async function deleteNavSection(params: { sectionId: string; groupId: string }): Promise<void>;

Removes a navigation section from a group.

---

addChannelToNavSection

async function addChannelToNavSection(params: { groupId: string; navSectionId: string; channelId: string }): Promise<void>;

Moves or assigns a channel to a specific navigation section.

---

updateGroupNavigation

async function updateGroupNavigation(params: { groupId: string; navSections: db.GroupNavSection[] }): Promise<void>;

Batch update of all navigation sections and their channel orderings.

---

Channel Management in Groups

addChannelToGroup

async function addChannelToGroup(params: { channelId: string; groupId: string; sectionId: string }): Promise<void>;

Adds a channel to a group in the specified navigation section.

Example:

await addChannelToGroup({
  channelId: 'chat/~sampel-palnet/announcements',
  groupId: '~sampel-palnet/book-club',
  sectionId: 'default'
});

---

updateChannel

async function updateChannel(params: { groupId: string; channelId: string; channel: GroupChannelV7 }): Promise<void>;

Updates a channel's configuration including metadata and reader permissions.

---

deleteChannel

async function deleteChannel(params: { groupId: string; channelId: string }): Promise<void>;

Removes a channel from a group. All channel content will be deleted.

---

Pins and Previews

getPinnedItems

async function getPinnedItems(): Promise<db.Pin[]>;

Retrieves the current user's pinned items.

Response Data: Array of Pin objects:

• type - 'group' | 'channel' | 'dm' | 'groupDm'
• itemId - ID of the pinned item
• index - Display order position

---

pinItem

async function pinItem(itemId: string): Promise<void>;

Adds an item to the user's pinned items list.

---

unpinItem

async function unpinItem(itemId: string): Promise<void>;

Removes an item from the user's pinned items list.

---

getGroupPreview

async function getGroupPreview(groupId: string): Promise<db.Group>;

Retrieves preview information about a group without joining it.

---

getChannelPreview

async function getChannelPreview(channelId: string): Promise<db.Channel | null>;

Retrieves preview information about a channel without joining its group.

---

findGroupsHostedBy

async function findGroupsHostedBy(userId: string): Promise<db.Group[]>;

Discovers all groups hosted by a specific user that the current user can see.