Skip to Content

User Groups

Group learners together for cohort management and access control.

Create a usergroup

POST/api/v1/usergroups/
API tokenusergroups:createor user session

Create a new usergroup within an organization. Requires admin/maintainer permissions on the organization.

Request bodyapplication/jsonrequired

namestringrequired
descriptionstringrequired
org_idinteger

Returns

UserGroupRead: Usergroup created successfully.

namestringrequired
descriptionstringrequired
idintegerrequired
org_idinteger
usergroup_uuidstringrequired
creation_datestringrequired
update_datestringrequired
Error responses
  • 401 Authentication required
  • 403 User lacks permission to create usergroups
  • 404 Organization not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "name": "Example name",
  "description": "An example description",
  "id": 1,
  "org_id": 1,
  "usergroup_uuid": "string",
  "creation_date": "string",
  "update_date": "string"
}

Import usergroups in bulk

POST/api/v1/usergroups/bulk
API tokenusergroups:createor user session

Create many usergroups from a text file (one name per line), a name,description spreadsheet, or a JSON list. Pass org_id as a query parameter as well as in the body so the plan gate can see it. Existing names are left untouched, including their members and linked resources. Groups that are not in the file are not deleted. Uploading the same file again changes nothing. Set dry_run to preview without writing. A plan limit blocks the whole batch.

Query parameters

org_idinteger | null

Request bodyapplication/jsonrequired

org_idintegerrequired
dry_runboolean
textstring | null
itemsUserGroupImportItem[] | null
Show child attributes
namestringrequired
descriptionstring

Returns

UserGroupBulkImportResult: Import classified, and applied unless dry_run.

dry_runbooleanrequired
created_countinteger
skipped_existing_countinteger
skipped_duplicate_countinteger
invalid_countinteger
ambiguous_countinteger
limit_blockedboolean
limit_detailstring | null
rowsUserGroupImportRowResult[]
Show child attributes
lineintegerrequired
namestringrequired
descriptionstring
statusstringrequired
detailstring
usergroup_idinteger | null
usergroup_uuidstring | null
member_countinteger
Error responses
  • 400 Empty file, or more names than the batch ceiling
  • 401 Authentication required
  • 403 Missing permission, wrong organization, or the plan cannot hold the new groups
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "dry_run": false,
  "created_count": 0,
  "skipped_existing_count": 0,
  "skipped_duplicate_count": 0,
  "invalid_count": 0,
  "ambiguous_count": 0,
  "limit_blocked": false,
  "limit_detail": "string",
  "rows": [
    {
      "line": 0,
      "name": "Example name",
      "description": "",
      "status": "string",
      "detail": "",
      "usergroup_id": 1,
      "usergroup_uuid": "string",
      "member_count": 0
    }
  ]
}

Delete usergroups in bulk

DELETE/api/v1/usergroups/bulk
API tokenusergroups:deleteor user session

Delete many usergroups in one organization. Membership rows and resource links for those groups are removed. User accounts are not deleted. Ids that are missing or belong to another organization are skipped. Pass org_id as a query parameter as well as in the body so the plan gate can see it.

Query parameters

org_idinteger | null

Request bodyapplication/jsonrequired

org_idintegerrequired
usergroup_idsinteger[]required

Returns

UserGroupBulkDeleteResult: Groups deleted, with any skipped ids counted.

deleted_countinteger
skipped_countinteger
deletedUserGroupBulkDeletedItem[]
Show child attributes
idintegerrequired
namestringrequired
usergroup_uuidstringrequired
Error responses
  • 400 No ids, the org_id query does not match, or the batch is too large
  • 401 Authentication required
  • 403 Missing permission, or the API token is for another organization
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "deleted_count": 0,
  "skipped_count": 0,
  "deleted": [
    {
      "id": 1,
      "name": "Example name",
      "usergroup_uuid": "string"
    }
  ]
}

Get a usergroup

GET/api/v1/usergroups/{usergroup_id}
API tokenusergroups:reador user session

Retrieve a usergroup by its numeric identifier.

Path parameters

usergroup_idintegerrequired

Returns

UserGroupRead: Usergroup retrieved.

namestringrequired
descriptionstringrequired
idintegerrequired
org_idinteger
usergroup_uuidstringrequired
creation_datestringrequired
update_datestringrequired
Error responses
  • 401 Authentication required
  • 403 User lacks permission to view this usergroup
  • 404 Usergroup not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "name": "Example name",
  "description": "An example description",
  "id": 1,
  "org_id": 1,
  "usergroup_uuid": "string",
  "creation_date": "string",
  "update_date": "string"
}

Update a usergroup

PUT/api/v1/usergroups/{usergroup_id}
API tokenusergroups:updateor user session

Update the name, description, or other attributes of a usergroup.

Path parameters

usergroup_idintegerrequired

Request bodyapplication/jsonrequired

namestring | null
descriptionstring | null

Returns

UserGroupRead: Usergroup updated successfully.

namestringrequired
descriptionstringrequired
idintegerrequired
org_idinteger
usergroup_uuidstringrequired
creation_datestringrequired
update_datestringrequired
Error responses
  • 401 Authentication required
  • 403 User lacks permission to update this usergroup
  • 404 Usergroup not found
  • 422 Validation Error: HTTPValidationError
Request
Response
{
  "name": "Example name",
  "description": "An example description",
  "id": 1,
  "org_id": 1,
  "usergroup_uuid": "string",
  "creation_date": "string",
  "update_date": "string"
}

Delete a usergroup

DELETE/api/v1/usergroups/{usergroup_id}
API tokenusergroups:deleteor user session

Permanently delete a usergroup along with its user and resource links.

Path parameters

usergroup_idintegerrequired
Error responses
  • 401 Authentication required
  • 403 User lacks permission to delete this usergroup
  • 404 Usergroup not found
  • 422 Validation Error: HTTPValidationError
Request
Response
"string"

List users in a usergroup

GET/api/v1/usergroups/{usergroup_id}/users
API tokenusergroups:reador user session

Retrieve the list of users that belong to a specific usergroup. Sensitive fields (is_superadmin, signup_method) are excluded.

Path parameters

usergroup_idintegerrequired

Returns

UserReadPublic[]: Users linked to the usergroup.

idintegerrequired
user_uuidstringrequired
usernamestringrequired
first_namestringrequired
last_namestringrequired
email_verifiedboolean
avatar_imagestring | null
biostring | null
detailsDetails | null
profileProfile | null
Error responses
  • 401 Authentication required
  • 403 User lacks permission to view usergroup members
  • 404 Usergroup not found
  • 422 Validation Error: HTTPValidationError
Request
Response
[
  {
    "id": 1,
    "user_uuid": "string",
    "username": "string",
    "first_name": "Example name",
    "last_name": "Example name",
    "email_verified": false,
    "avatar_image": "string",
    "bio": "string",
    "details": {},
    "profile": {}
  }
]

List usergroups for an organization

GET/api/v1/usergroups/org/{org_id}
API tokenusergroups:reador user session

Retrieve every usergroup that belongs to a given organization.

Path parameters

org_idintegerrequired

Returns

UserGroupRead[]: Usergroups for the organization.

namestringrequired
descriptionstringrequired
idintegerrequired
org_idinteger
usergroup_uuidstringrequired
creation_datestringrequired
update_datestringrequired
Error responses
  • 401 Authentication required
  • 403 User lacks permission to view usergroups for this organization
  • 404 Organization not found
  • 422 Validation Error: HTTPValidationError
Request
Response
[
  {
    "name": "Example name",
    "description": "An example description",
    "id": 1,
    "org_id": 1,
    "usergroup_uuid": "string",
    "creation_date": "string",
    "update_date": "string"
  }
]

List resources linked to a usergroup

GET/api/v1/usergroups/{usergroup_id}/resources
API tokenusergroups:reador user session

Return the UUIDs of resources (courses, folders, etc.) that are linked to a usergroup.

Path parameters

usergroup_idintegerrequired
Error responses
  • 401 Authentication required
  • 403 User lacks permission to view this usergroup
  • 404 Usergroup not found
  • 422 Validation Error: HTTPValidationError
Request
Response
[
  "string"
]

List usergroups linked to a resource

GET/api/v1/usergroups/resource/{resource_uuid}
API tokenusergroups:reador user session

Retrieve every usergroup that is linked to a given resource UUID.

Path parameters

resource_uuidstringrequired

Returns

UserGroupRead[]: Usergroups linked to the resource.

namestringrequired
descriptionstringrequired
idintegerrequired
org_idinteger
usergroup_uuidstringrequired
creation_datestringrequired
update_datestringrequired
Error responses
  • 401 Authentication required
  • 403 User lacks permission to view usergroups for this resource
  • 404 Resource not found
  • 422 Validation Error: HTTPValidationError
Request
Response
[
  {
    "name": "Example name",
    "description": "An example description",
    "id": 1,
    "org_id": 1,
    "usergroup_uuid": "string",
    "creation_date": "string",
    "update_date": "string"
  }
]

Add users to a usergroup

POST/api/v1/usergroups/{usergroup_id}/add_users
API tokenusergroups:createor user session

Add one or more users to a usergroup. User IDs should be provided as a comma-separated string.

Path parameters

usergroup_idintegerrequired

Query parameters

user_idsstringrequired
Error responses
  • 401 Authentication required
  • 403 User lacks permission to modify this usergroup
  • 404 Usergroup or user not found
  • 422 Validation Error: HTTPValidationError
Request
Response
"string"

Remove users from a usergroup

DELETE/api/v1/usergroups/{usergroup_id}/remove_users
API tokenusergroups:deleteor user session

Remove one or more users from a usergroup. User IDs should be provided as a comma-separated string.

Path parameters

usergroup_idintegerrequired

Query parameters

user_idsstringrequired
Error responses
  • 401 Authentication required
  • 403 User lacks permission to modify this usergroup
  • 404 Usergroup or user not found
  • 422 Validation Error: HTTPValidationError
Request
Response
"string"

Add resources to a usergroup

POST/api/v1/usergroups/{usergroup_id}/add_resources
API tokenusergroups:createor user session

Link one or more resources (courses, folders, etc.) to a usergroup. Resource UUIDs should be provided as a comma-separated string.

Path parameters

usergroup_idintegerrequired

Query parameters

resource_uuidsstringrequired
Error responses
  • 401 Authentication required
  • 403 User lacks permission to modify this usergroup
  • 404 Usergroup or resource not found
  • 422 Validation Error: HTTPValidationError
Request
Response
"string"

Remove resources from a usergroup

DELETE/api/v1/usergroups/{usergroup_id}/remove_resources
API tokenusergroups:deleteor user session

Unlink one or more resources from a usergroup. Resource UUIDs should be provided as a comma-separated string.

Path parameters

usergroup_idintegerrequired

Query parameters

resource_uuidsstringrequired
Error responses
  • 401 Authentication required
  • 403 User lacks permission to modify this usergroup
  • 404 Usergroup or resource not found
  • 422 Validation Error: HTTPValidationError
Request
Response
"string"