Searching & Listing Groups

Search by name, pagination, filtering

Written By jazilkalim

Last updated 3 months ago

What is Group Search?

Group search and listing operations allow you to find and browse groups in your CampusMindAI tenant.

Why Search and List Groups?

Quick Lookup: Find groups by name
Administration: Review group structure
Audit: Verify group configuration

Search Groups

Search for groups by name using a search term.

Endpoint Details

Method: GET
URL: {{baseURL}}/api/v1/groups?search_term=<term>
Authentication: Required (JWT Bearer token)

Query Parameters

			ParameterTypeRequiredDescription
`search_term`	string	Yes	Search term for group name

Example Request

curl -X GET "https://<baseURL>/api/v1/groups?search_term=CS101" \
  -H "Authorization: Bearer <jwt-token>"

Response

Status Code: 200 OK

{
  "current_page": 1,
  "next_page": 0,
  "total_pages": 1,
  "total_records": 3,
  "limit": 10,
  "search_term": "CS101",
  "groups": [
    {
      "group_id": 1000385,
      "group_name": "CS101_Fall2024",
      "group_description": "Introduction to Computer Science - Fall 2024",
      "group_updated_at": "2024-12-02T10:30:00Z",
      "group_tenant_global": "0",
      "group_created_by": "admin@example.com",
      "group_created_by_id": "550e8400-e29b-41d4-a716-446655440000",
      "role_id": 1
    }
  ]
}

Response Fields

		FieldTypeDescription
`current_page`	integer	Current page number
`next_page`	integer	Next page (0 if no more pages)
`total_pages`	integer	Total pages of results
`total_records`	integer	Total matching groups
`search_term`	string	Search term used
`groups`	array	Array of matching groups

List Groups

Retrieve a paginated list of all groups in your tenant.

Endpoint Details

Method: POST
URL: {{baseURL}}/api/v1/list_group
Authentication: Required (JWT Bearer token)

Request Body

			ParameterTypeRequiredDescription
`page`	integer	Yes	Page number (starts at 1)
`limit`	integer	Yes	Groups per page

Example Request

curl -X POST "https://<baseURL>/api/v1/list_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "limit": 10
  }'

Response

Status Code: 200 OK

{
  "current_page": 1,
  "next_page": 2,
  "total_pages": 5,
  "total_records": 47,
  "limit": 10,
  "groups": [
    {
      "group_id": 1000385,
      "group_name": "CS101_Fall2024",
      "group_description": "Introduction to Computer Science - Fall 2024",
      "group_updated_at": "2024-12-02T10:30:00Z",
      "group_tenant_global": "0",
      "group_created_by": "admin@example.com",
      "group_created_by_id": "550e8400-e29b-41d4-a716-446655440000",
      "role_id": 1
    }
  ]
}

Group Object Fields

		FieldTypeDescription
`group_id`	integer	Unique group identifier
`group_name`	string	Group name
`group_description`	string	Group description
`group_updated_at`	string	Last update timestamp (ISO 8601)
`group_tenant_global`	string	"0"=local, "1"=global
`group_created_by`	string	Creator's email
`group_created_by_id`	string	Creator's user ID
`role_id`	integer	Associated role (1=Student, 2=Instructor, 3=Admin)

Search Tips

Partial matching: Search term matches anywhere in group name
Case insensitive: Search is not case-sensitive
Common patterns: Use course codes, semesters, or department names

Pagination

Navigate through pages by incrementing the page parameter:

# Page 1
{"page": 1, "limit": 10}

# Page 2
{"page": 2, "limit": 10}

Continue until next_page is 0.

Error Responses

	Status CodeDescription
`400 Bad Request`	Invalid parameters (page < 1, limit < 1)
`401 Unauthorized`	Invalid or missing JWT token
`500 Internal Server Error`	Server error

Troubleshooting

No Search Results

Solutions:

Verify search term spelling
Try broader search terms
Use list_group to see all available groups

Empty Group List

Solutions:

Start with page 1
Verify groups exist in tenant
Check user permissions