Groups

User-created groups/guilds with configurable visibility, member limits, and roles.

Groups let users form communities within your app. They support public/private visibility, configurable member limits, and role-based membership.

SDK usage

Create a group

const group = await client.groups.create({
  name: 'Fitness Warriors',
  description: 'A group for fitness enthusiasts',
  is_public: true,
  max_members: 50,
});

Search public groups

The SDK has no search method. Search over HTTP with the user's session:

GET /v1/client/groups/search?q=fitness&limit=20

It matches public group names and returns data with total, offset and limit.

Join/leave a group

await client.groups.join(groupId);
await client.groups.leave(groupId);

A private group is visible to its members only: for a caller outside it, join, the group detail and the member list answer 404 NOT_FOUND, the same answer as an unknown group.

Get my groups

The SDK has no method for this list. Read it over HTTP:

GET /v1/client/groups/mine

{ "data": [{ "role": "owner", "groups": { "name": "Fitness Warriors", "...": "..." } }] }

List group members

const members = await client.groups.getMembers(groupId);

Client API reference

Method	Path	Description
`POST`	`/v1/client/groups`	Create a group
`GET`	`/v1/client/groups/mine`	List user's groups
`GET`	`/v1/client/groups/search`	Search public groups
`GET`	`/v1/client/groups/:id`	Get a group
`POST`	`/v1/client/groups/:id/join`	Join a group
`POST`	`/v1/client/groups/:id/leave`	Leave a group
`GET`	`/v1/client/groups/:id/members`	List group members

MCP tools

Tool	Description
`amba_groups_create`	Create a group with name, visibility, and max members
`amba_groups_list`	List all groups in a project

Example

Agent: "Create a VIP group for premium users"

amba_groups_create({
  project_id: "proj_xxx",
  name: "VIP Lounge",
  owner_id: "admin_user_xxx",
  description: "Exclusive group for premium members",
  is_public: false,
  max_members: 500
})

On this page