GroupsClient

Client for /api/v1/groups/. The broadcast markers EVERYONE / EVERYONE_IN_THREAD are NOT addressable through these endpoints — they only appear as members of direct_group_mentions / groups lists on thread/comment writes.

getone / update / remove and the member-management ops all require workspace_id alongside the group id.

Extends

• BaseClient

Constructors

Constructor

new GroupsClient(config: ClientConfig): GroupsClient;

Parameters

Parameter	Type
config	ClientConfig

Returns

GroupsClient

Inherited from

BaseClient.constructor

Properties

Property	Modifier	Type
apiToken	readonly	string
baseUrl?	readonly	string
customFetch?	readonly	CustomFetch
defaultVersion	readonly	"v1"

Methods

addUser()

addUser(args: AddGroupUserArgs): Promise<{
  status: "ok";
}>;

Adds a user to a group.

Parameters

Parameter	Type	Description
args	AddGroupUserArgs	The arguments for adding a user.

Returns

Promise<{ status: "ok"; }>

---

addUsers()

addUsers(args: AddGroupUsersArgs): Promise<{
  status: "ok";
}>;

Adds multiple users to a group.

Parameters

Parameter	Type	Description
args	AddGroupUsersArgs	The arguments for adding users.

Returns

Promise<{ status: "ok"; }>

Example

await api.groups.addUsers({
  id: '7YpL3oZ4kZ9vP7Q1tR2sX45',
  workspaceId: 123,
  userIds: [101, 202, 303],
})

---

createGroup()

createGroup(args: {
  description?: string;
  id?: string;
  name: string;
  userIds?: number[];
  workspaceId: number;
}): Promise<{
  description?: string | null;
  id: string;
  name: string;
  userIds: number[];
  version: number;
  workspaceId: number;
}>;

Creates a new group. id is auto-generated if not supplied.

Parameters

Parameter	Type	Description
args	{ description?: string; id?: string; name: string; userIds?: number[]; workspaceId: number; }	The arguments for creating a group.
args.description?	string	Optional group description.
args.id?	string	Optional caller-supplied group ID (for optimistic-UI workflows).
args.name	string	The group name.
args.userIds?	number[]	Optional array of user IDs to add to the group.
args.workspaceId	number	The workspace ID.

Returns

Promise<{ description?: string | null; id: string; name: string; userIds: number[]; version: number; workspaceId: number; }>

The created group object.

Example

const group = await api.groups.createGroup({
  workspaceId: 123,
  name: 'Engineering Team',
  userIds: [1, 2, 3],
})

---

deleteGroup()

deleteGroup(args: {
  id: string;
  workspaceId: number;
}): Promise<{
  status: "ok";
}>;

Permanently deletes a group. Requires workspaceId.

Parameters

Parameter	Type	Description
args	{ id: string; workspaceId: number; }	The arguments for deleting a group.
args.id	string	The group ID.
args.workspaceId	number	The workspace ID.

Returns

Promise<{ status: "ok"; }>

---

getBaseUri()

protected getBaseUri(): string;

Returns the base URI for an API request, with a guaranteed trailing slash so relative paths resolve cleanly through URL.

Returns

string

Inherited from

BaseClient.getBaseUri

---

getGroup()

getGroup(args: {
  id: string;
  workspaceId: number;
}): Promise<{
  description?: string | null;
  id: string;
  name: string;
  userIds: number[];
  version: number;
  workspaceId: number;
}>;

Gets a single group object by id. Requires workspaceId.

Parameters

Parameter	Type	Description
args	{ id: string; workspaceId: number; }	The arguments for getting a group.
args.id	string	The group ID.
args.workspaceId	number	The workspace ID.

Returns

Promise<{ description?: string | null; id: string; name: string; userIds: number[]; version: number; workspaceId: number; }>

The group object.

---

getGroups()

getGroups(workspaceId: number): Promise<{
  description?: string | null;
  id: string;
  name: string;
  userIds: number[];
  version: number;
  workspaceId: number;
}[]>;

Gets all groups for a given workspace.

Parameters

Parameter	Type	Description
workspaceId	number	The workspace ID.

Returns

Promise<{ description?: string | null; id: string; name: string; userIds: number[]; version: number; workspaceId: number; }[]>

An array of group objects.

Example

const groups = await api.groups.getGroups(123)
groups.forEach(g => console.log(g.name))

---

getLinkBaseUrl()

protected getLinkBaseUrl(): string | undefined;

Base URL for entity web links, or undefined to use getFullCommsURL's default web app. Trailing-slash normalization happens in getFullCommsURL, so the configured value is returned verbatim.

Returns

string | undefined

Inherited from

BaseClient.getLinkBaseUrl

---

removeUser()

removeUser(args: RemoveGroupUserArgs): Promise<{
  status: "ok";
}>;

Removes a user from a group.

Parameters

Parameter	Type	Description
args	RemoveGroupUserArgs	The arguments for removing a user.

Returns

Promise<{ status: "ok"; }>

---

removeUsers()

removeUsers(args: RemoveGroupUsersArgs): Promise<{
  status: "ok";
}>;

Removes multiple users from a group.

Parameters

Parameter	Type	Description
args	RemoveGroupUsersArgs	The arguments for removing users.

Returns

Promise<{ status: "ok"; }>

---

updateGroup()

updateGroup(args: {
  description?: string;
  id: string;
  name?: string;
  workspaceId: number;
}): Promise<{
  description?: string | null;
  id: string;
  name: string;
  userIds: number[];
  version: number;
  workspaceId: number;
}>;

Updates a group's properties. Requires workspaceId.

Parameters

Parameter	Type	Description
args	{ description?: string; id: string; name?: string; workspaceId: number; }	The arguments for updating a group.
args.description?	string	Optional new group description.
args.id	string	The group ID.
args.name?	string	Optional new group name.
args.workspaceId	number	The workspace ID.

Returns

Promise<{ description?: string | null; id: string; name: string; userIds: number[]; version: number; workspaceId: number; }>

The updated group object.