Group Membership

What is Group Membership?

Group membership determines which users belong to which groups in CampusMindAI. Managing membership allows administrators to control access to VTAs, agents, and resources by adding or removing users from groups.

Why Manage Group Membership?

• Access Control: Grant or revoke resource access efficiently

• Course Management: Add/remove students from course groups

• Dynamic Permissions: Adjust access as needs change

Add Users to Group

Add one or more users to one or more groups simultaneously.

Endpoint Details

• Method: POST

• URL: {{baseURL}}/api/v1/add_users_to_group

• Authentication: Required (JWT Bearer token)

Request Body

Example Requests

Single user to single group:

curl -X POST "https://<baseURL>/api/v1/add_users_to_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["student@example.com"],
    "group_ids": [1000007]
  }'

Multiple users to single group:

curl -X POST "https://<baseURL>/api/v1/add_users_to_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": [
      "student1@example.com",
      "student2@example.com",
      "student3@example.com"
    ],
    "group_ids": [1000007]
  }'

Response

Status Code: 200 OK

{
  "message": "success"
}

Remove Users from Group

Remove one or more users from one or more groups.

Endpoint Details

• Method: POST

• URL: {{baseURL}}/api/v1/remove_users_from_group

• Authentication: Required (JWT Bearer token)

Request Body

Example Request

curl -X POST "https://<baseURL>/api/v1/remove_users_from_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["student@example.com"],
    "group_ids": [1000007]
  }'

Response

Status Code: 200 OK

{
  "message": ""
}

List Group Users

View all users in a specific group with pagination support.

Endpoint Details

• Method: POST

• URL: {{baseURL}}/api/v1/list_group_users

• Authentication: Required (JWT Bearer token)

Request Body

Example Request

curl -X POST "https://<baseURL>/api/v1/list_group_users" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "offset": 0,
    "group_id": 1000385
  }'

Response

{
  "offset": 0,
  "limit": 50,
  "users": [
    {
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_name": "John Doe",
      "user_email": "john.doe@example.com",
      "user_create_at": "2024-01-15T10:30:00Z",
      "user_role": 1,
      "user_invited_by": "admin@example.com",
      "group_name": "CS101_Fall2024",
      "group_id": 1000385
    }
  ],
  "group_id": 1000385
}

Pagination

For next page, increment offset by limit value:

{
  "offset": 50,
  "group_id": 1000385
}

Common Use Cases

Bulk Enrollment

curl -X POST "https://<baseURL>/api/v1/add_users_to_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": [
      "student1@university.edu",
      "student2@university.edu",
      "student3@university.edu"
    ],
    "group_ids": [1000385]
  }'

Course Drop

curl -X POST "https://<baseURL>/api/v1/remove_users_from_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["droppedstudent@university.edu"],
    "group_ids": [1000385]
  }'

Add to Multiple Groups

curl -X POST "https://<baseURL>/api/v1/add_users_to_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["instructor@university.edu"],
    "group_ids": [1000385, 1000386, 1000387]
  }'

Error Responses

Best Practices

• Batch Operations: Add 10-50 users per request for optimal performance

• Verify Before Removing: List group users first to confirm membership

• Regular Audits: Review group membership weekly during active terms

• Immediate Updates: Remove access as soon as it's no longer needed

Troubleshooting

User Not Added

Causes:

• User email incorrect (case-sensitive)

• User doesn't exist in system

• Group ID invalid

Solutions:

1. Verify user exists using list_users endpoint

2. Confirm group ID using search_groups endpoint

3. Check email spelling and case

Cannot Remove User

Causes:

• User not in specified group

• Group ID incorrect

Solutions:

1. List group members to confirm presence

2. Verify group ID is correct