Manage Groups

Group management endpoints for creating, updating, and managing user groups.

List Groups

GET /api/groups

curl -X GET "https://your-domain.com/api/groups" \
  -H "Authorization: Bearer YOUR_TOKEN"

Retrieves all groups accessible to the authenticated user.

Query Parameters

share · boolean

Filter by share permission. For non-admin users, filters groups based on membership and share settings.

Response

groups · array

Array of group objects

Show Group Object

id · string

Unique group identifier

user_id · string

ID of user who created the group

name · string

Group name

description · string

Group description

data · object

Additional group data including configuration

Show Data Object

config · object

Configuration settings

share · string

Share permission: true, false, or members

meta · object

Metadata about the group

permissions · object

Group-specific permissions

member_count · integer

Number of members in the group

created_at · integer

Unix timestamp of creation

updated_at · integer

Unix timestamp of last update

---

Create Group

POST /api/groups/create

curl -X POST "https://your-domain.com/api/groups/create" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Team",
    "description": "Engineering department group",
    "permissions": {},
    "data": {
      "config": {
        "share": "members"
      }
    }
  }'

Creates a new group. Requires admin authentication.

Request Body

name · string · required

Group name

description · string · required

Group description

permissions · object

Group-specific permissions

data · object

Additional group data. If not provided, default share configuration is applied.

---

Get Group

GET /api/groups/id/{id}

curl -X GET "https://your-domain.com/api/groups/id/group-123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Retrieves detailed information about a specific group. Requires admin authentication.

Path Parameters

id · string · required

The unique identifier of the group

---

Update Group

POST /api/groups/id/{id}/update

curl -X POST "https://your-domain.com/api/groups/id/group-123/update" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Group Name",
    "description": "Updated description",
    "permissions": {}
  }'

Updates group information. Requires admin authentication.

Request Body

name · string · required

Updated group name

description · string · required

Updated group description

permissions · object

Updated permissions

data · object

Updated group data

---

Add Users to Group

POST /api/groups/id/{id}/users/add

curl -X POST "https://your-domain.com/api/groups/id/group-123/users/add" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["user-1", "user-2", "user-3"]
  }'

Adds users to a group. Requires admin authentication.

Request Body

user_ids · array

Array of user IDs to add to the group. Invalid user IDs are automatically filtered out.

---

Remove Users from Group

POST /api/groups/id/{id}/users/remove

curl -X POST "https://your-domain.com/api/groups/id/group-123/users/remove" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["user-1", "user-2"]
  }'

Removes users from a group. Requires admin authentication.

Request Body

user_ids · array

Array of user IDs to remove from the group

---

Get Group Users

POST /api/groups/id/{id}/users

curl -X POST "https://your-domain.com/api/groups/id/group-123/users" \
  -H "Authorization: Bearer YOUR_TOKEN"

Retrieves all users in a specific group. Requires admin authentication.

Response

Returns an array of user objects with basic information:

[
  {
    "id": "user-123",
    "name": "John Doe",
    "email": "[e-mail]",
    "role": "user",
    "bio": "Software developer",
    "groups": [],
    "is_active": true
  }
]

---

Export Group

GET /api/groups/id/{id}/export

curl -X GET "https://your-domain.com/api/groups/id/group-123/export" \
  -H "Authorization: Bearer YOUR_TOKEN"

Exports complete group information including all user IDs. Requires admin authentication.

Response

Returns group object with additional user_ids field:

user_ids · array

Array of all user IDs in the group

---

Delete Group

DELETE /api/groups/id/{id}/delete

curl -X DELETE "https://your-domain.com/api/groups/id/group-123/delete" \
  -H "Authorization: Bearer YOUR_TOKEN"

Deletes a group and all member associations. Requires admin authentication.

Response

Returns true if successful, error otherwise.

---

Notes

• Admin users can access all groups regardless of membership
• Non-admin users can only see groups they are members of (unless group share is set to true)
• Group share settings:
  • true or "true": Anyone can share to this group
  • false or "false": Nobody can share to this group
  • "members": Only group members can share to this group
• Adding duplicate users to a group is silently ignored
• Invalid user IDs are automatically filtered when adding users
• All group operations update the updated_at timestamp