Page number to return.
Beta Admin User Groups Endpoints
(beta) Admin API - manage user groups. Requires an admin API key.
Examples
Real world code examples
Get User Groups
GET /api/admin/user-groups
Get all user groups across the organization.
AdminApiKey
page
page_size
Maximum number of results per page.
search
Search term used to filter user groups by name.
200
OK
page
Page number returned.
page_size
Maximum number of results per page.
total
Total number of user groups that match the request.
Playground
Test the endpoints live
curl https://api.mistral.ai/api/admin/user-groups \
-X GET \
-H 'Authorization: Bearer YOUR_APIKEY_HERE'curl https://api.mistral.ai/api/admin/user-groups \
-X GET \
-H 'Authorization: Bearer YOUR_APIKEY_HERE'200
{
"items": [
{
"description": null,
"name": "My resource",
"uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}
],
"page": "1",
"page_size": "1000",
"total": 56
}{
"items": [
{
"description": null,
"name": "My resource",
"uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}
],
"page": "1",
"page_size": "1000",
"total": 56
}Create User Group
POST /api/admin/user-groups
Create a new user group.
AdminApiKey
description
Optional description of the user group.
name
Name of the user group.
target_type
Type of resources this group can access.
200
OK
description
Optional description of the user group.
externally_managed
Whether the group is managed by an external system.
name
Name of the user group.
organization_role
Organization role assigned to the group.
target_type
Type of resources this group can access.
uuid
User group ID.
Playground
Test the endpoints live
curl https://api.mistral.ai/api/admin/user-groups \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"name": "My resource"
}'curl https://api.mistral.ai/api/admin/user-groups \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"name": "My resource"
}'200
{
"description": null,
"name": "My resource",
"uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}{
"description": null,
"name": "My resource",
"uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}Provision Group To Workspace
POST /api/admin/user-groups/provision-workspace
Provision all users from a user group to a workspace with a specific role.
AdminApiKey
user_group_uuid
User group ID to provision.
workspace_role
Workspace role value to assign to the group. Mutually exclusive with 'workspace_role_name'.
workspace_role_name
Workspace role name to assign to the group. Mutually exclusive with 'workspace_role'.
workspace_uuid
Workspace ID where the group is provisioned.
Playground
Test the endpoints live
curl https://api.mistral.ai/api/admin/user-groups/provision-workspace \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"user_group_uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"workspace_uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}'curl https://api.mistral.ai/api/admin/user-groups/provision-workspace \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"user_group_uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"workspace_uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}'Get User Group
GET /api/admin/user-groups/{group_uuid}
Get a specific user group.
AdminApiKey
group_uuid
User group ID.
200
OK
description
Optional description of the user group.
externally_managed
Whether the group is managed by an external system.
name
Name of the user group.
organization_role
Organization role assigned to the group.
target_type
Type of resources this group can access.
uuid
User group ID.
Playground
Test the endpoints live
curl https://api.mistral.ai/api/admin/user-groups/{group_uuid} \
-X GET \
-H 'Authorization: Bearer YOUR_APIKEY_HERE'curl https://api.mistral.ai/api/admin/user-groups/{group_uuid} \
-X GET \
-H 'Authorization: Bearer YOUR_APIKEY_HERE'200
{
"description": null,
"name": "My resource",
"uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}{
"description": null,
"name": "My resource",
"uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}Delete User Group
DELETE /api/admin/user-groups/{group_uuid}
Delete a user group.
AdminApiKey
group_uuid
User group ID.
Playground
Test the endpoints live
curl https://api.mistral.ai/api/admin/user-groups/{group_uuid} \
-X DELETE \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json'curl https://api.mistral.ai/api/admin/user-groups/{group_uuid} \
-X DELETE \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json'Update User Group
PATCH /api/admin/user-groups/{group_uuid}
Update a user group.
AdminApiKey
group_uuid
description
Updated description of the user group.
name
Updated name of the user group.
target_type
Type of resources this group can access.
200
OK
description
Optional description of the user group.
externally_managed
Whether the group is managed by an external system.
name
Name of the user group.
organization_role
Organization role assigned to the group.
target_type
Type of resources this group can access.
uuid
User group ID.
Playground
Test the endpoints live
curl https://api.mistral.ai/api/admin/user-groups/{group_uuid} \
-X PATCH \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{}'curl https://api.mistral.ai/api/admin/user-groups/{group_uuid} \
-X PATCH \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{}'200
{
"description": null,
"name": "My resource",
"uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}{
"description": null,
"name": "My resource",
"uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}Get User Group Members
GET /api/admin/user-groups/{group_uuid}/members
Get members of a user group.
AdminApiKey
group_uuid
User group ID.
page
Page number to return.
page_size
Maximum number of results per page.
200
OK
page
Page number returned.
page_size
Maximum number of results per page.
total
Total number of group members that match the request.
Playground
Test the endpoints live
curl https://api.mistral.ai/api/admin/user-groups/{group_uuid}/members \
-X GET \
-H 'Authorization: Bearer YOUR_APIKEY_HERE'curl https://api.mistral.ai/api/admin/user-groups/{group_uuid}/members \
-X GET \
-H 'Authorization: Bearer YOUR_APIKEY_HERE'200
{
"members": [
{
"email": null,
"name": null,
"user_uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}
],
"page": "1",
"page_size": "1000",
"total": 56
}{
"members": [
{
"email": null,
"name": null,
"user_uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}
],
"page": "1",
"page_size": "1000",
"total": 56
}Assign Users To Group
POST /api/admin/user-groups/{group_uuid}/members
Assign users to a user group.
AdminApiKey
group_uuid
user_uuids
User IDs to add to the group.
Playground
Test the endpoints live
curl https://api.mistral.ai/api/admin/user-groups/{group_uuid}/members \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"user_uuids": [
"019b2bd7-96e7-7219-8c0b-45a73da50088"
]
}'curl https://api.mistral.ai/api/admin/user-groups/{group_uuid}/members \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"user_uuids": [
"019b2bd7-96e7-7219-8c0b-45a73da50088"
]
}'Remove Users From Group
DELETE /api/admin/user-groups/{group_uuid}/members
Remove users from a user group.
AdminApiKey
group_uuid
user_uuids
User IDs to add to the group.
Playground
Test the endpoints live
curl https://api.mistral.ai/api/admin/user-groups/{group_uuid}/members \
-X DELETE \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"user_uuids": [
"019b2bd7-96e7-7219-8c0b-45a73da50088"
]
}'curl https://api.mistral.ai/api/admin/user-groups/{group_uuid}/members \
-X DELETE \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"user_uuids": [
"019b2bd7-96e7-7219-8c0b-45a73da50088"
]
}'Get Group Workspace Assignments
GET /api/admin/user-groups/{group_uuid}/workspaces
List workspace assignments for a user group.
AdminApiKey
group_uuid
User group ID.
page
Page number to return.
page_size
Maximum number of results per page.
200
OK
page
Page number returned.
page_size
Maximum number of results per page.
total
Total number of Workspace assignments that match the request.
Playground
Test the endpoints live
curl https://api.mistral.ai/api/admin/user-groups/{group_uuid}/workspaces \
-X GET \
-H 'Authorization: Bearer YOUR_APIKEY_HERE'curl https://api.mistral.ai/api/admin/user-groups/{group_uuid}/workspaces \
-X GET \
-H 'Authorization: Bearer YOUR_APIKEY_HERE'200
{
"items": [
{
"created": "2025-10-07T20:56:01.974Z",
"roles": [
{
"name": "My resource",
"uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}
],
"workspace_name": "reprehenderit ut dolore",
"workspace_uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}
],
"page": "1",
"page_size": "1000",
"total": 56
}{
"items": [
{
"created": "2025-10-07T20:56:01.974Z",
"roles": [
{
"name": "My resource",
"uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}
],
"workspace_name": "reprehenderit ut dolore",
"workspace_uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}
],
"page": "1",
"page_size": "1000",
"total": 56
}Assign Group To Workspace
POST /api/admin/user-groups/{group_uuid}/workspaces
Assign a user group to a workspace.
AdminApiKey
group_uuid
User group ID.
role
Deprecated single role value. Use 'role_names' instead.
role_names
Simplified role names to assign. Mutually exclusive with 'roles'.
roles
Role values to assign. Mutually exclusive with 'role_names'.
workspace_uuid
Playground
Test the endpoints live
curl https://api.mistral.ai/api/admin/user-groups/{group_uuid}/workspaces \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"workspace_uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}'curl https://api.mistral.ai/api/admin/user-groups/{group_uuid}/workspaces \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"workspace_uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}'Remove Group From Workspace
DELETE /api/admin/user-groups/{group_uuid}/workspaces/{workspace_uuid}
Remove a user group from a workspace.
AdminApiKey
group_uuid
User group ID.
workspace_uuid
Workspace ID.
Playground
Test the endpoints live
curl https://api.mistral.ai/api/admin/user-groups/{group_uuid}/workspaces/{workspace_uuid} \
-X DELETE \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json'curl https://api.mistral.ai/api/admin/user-groups/{group_uuid}/workspaces/{workspace_uuid} \
-X DELETE \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json'Update Group Workspace Assignment
PATCH /api/admin/user-groups/{group_uuid}/workspaces/{workspace_uuid}
Update the workspace role assignment for a user group.
AdminApiKey
group_uuid
User group ID.
workspace_uuid
Workspace ID.
role
Deprecated single role value. Use 'role_names' instead.
role_names
Simplified role names to assign. Mutually exclusive with 'roles'.
roles
Role values to assign. Mutually exclusive with 'role_names'.
Playground
Test the endpoints live
curl https://api.mistral.ai/api/admin/user-groups/{group_uuid}/workspaces/{workspace_uuid} \
-X PATCH \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{}'curl https://api.mistral.ai/api/admin/user-groups/{group_uuid}/workspaces/{workspace_uuid} \
-X PATCH \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{}'Update User Group Organization Role
PATCH /api/admin/user-groups/{group_uuid}/organization-role
Update the organization role for a user group.
AdminApiKey
group_uuid
User group ID.
organization_role
Organization role to assign to the group.
Playground
Test the endpoints live
curl https://api.mistral.ai/api/admin/user-groups/{group_uuid}/organization-role \
-X PATCH \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"organization_role": "A"
}'curl https://api.mistral.ai/api/admin/user-groups/{group_uuid}/organization-role \
-X PATCH \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"organization_role": "A"
}'