Beta Admin User Groups Endpoints

(beta) Admin API - manage user groups. Requires an admin API key.

Get User Groups

GET /v1/admin/user-groups#

Get all user groups across the organization.

200

items#

*array<AdminUserGroupOut>

User groups on this page.

page#

*integer

Page number returned.

page_size#

*integer

Maximum number of results per page.

total#

*integer

Total number of user groups that match the request.

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/admin/user-groups \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

curl https://api.mistral.ai/v1/admin/user-groups \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

200

{
  "items": [
    {
      "description": null,
      "name": "Engineering Team",
      "uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
    }
  ],
  "page": "1",
  "page_size": "1000",
  "total": 56
}

{
  "items": [
    {
      "description": null,
      "name": "Engineering Team",
      "uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
    }
  ],
  "page": "1",
  "page_size": "1000",
  "total": 56
}

Create User Group

POST /v1/admin/user-groups#

Create a new user group.

200

description#

*string|null

Optional description of the user group.

externally_managed#

boolean|null

Whether the group is managed by an external system.

name#

*string

Name of the user group.

organization_role#

string|null

Organization role assigned to the group.

target_type#

"W"|"O"

Type of resources this group can access.

uuid#

*string

User group ID.

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/admin/user-groups \
 -X POST \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json' \
 -d '{
  "name": "Engineering Team"
}'

curl https://api.mistral.ai/v1/admin/user-groups \
 -X POST \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json' \
 -d '{
  "name": "Engineering Team"
}'

200

{
  "description": null,
  "name": "Engineering Team",
  "uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}

{
  "description": null,
  "name": "Engineering Team",
  "uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}

Provision Group To Workspace

POST /v1/admin/user-groups/provision-workspace#

Provision all users from a user group to a workspace with a specific role.

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/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/v1/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 /v1/admin/user-groups/{group_uuid}#

Get a specific user group.

200

description#

*string|null

Optional description of the user group.

externally_managed#

boolean|null

Whether the group is managed by an external system.

name#

*string

Name of the user group.

organization_role#

string|null

Organization role assigned to the group.

target_type#

"W"|"O"

Type of resources this group can access.

uuid#

*string

User group ID.

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/admin/user-groups/{group_uuid} \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

curl https://api.mistral.ai/v1/admin/user-groups/{group_uuid} \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

200

{
  "description": null,
  "name": "Engineering Team",
  "uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}

{
  "description": null,
  "name": "Engineering Team",
  "uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}

Delete User Group

DELETE /v1/admin/user-groups/{group_uuid}#

Delete a user group.

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/admin/user-groups/{group_uuid} \
 -X DELETE \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json'

curl https://api.mistral.ai/v1/admin/user-groups/{group_uuid} \
 -X DELETE \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json'

Update User Group

PATCH /v1/admin/user-groups/{group_uuid}#

Update a user group.

200

description#

*string|null

Optional description of the user group.

externally_managed#

boolean|null

Whether the group is managed by an external system.

name#

*string

Name of the user group.

organization_role#

string|null

Organization role assigned to the group.

target_type#

"W"|"O"

Type of resources this group can access.

uuid#

*string

User group ID.

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/admin/user-groups/{group_uuid} \
 -X PATCH \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json' \
 -d '{}'

curl https://api.mistral.ai/v1/admin/user-groups/{group_uuid} \
 -X PATCH \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json' \
 -d '{}'

200

{
  "description": null,
  "name": "Engineering Team",
  "uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}

{
  "description": null,
  "name": "Engineering Team",
  "uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}

Get User Group Members

GET /v1/admin/user-groups/{group_uuid}/members#

Get members of a user group.

200

members#

*array<AdminUserGroupMemberOut>

Group members on this page.

page#

*integer

Page number returned.

page_size#

*integer

Maximum number of results per page.

total#

*integer

Total number of group members that match the request.

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/admin/user-groups/{group_uuid}/members \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

curl https://api.mistral.ai/v1/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 /v1/admin/user-groups/{group_uuid}/members#

Assign users to a user group.

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/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/v1/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 /v1/admin/user-groups/{group_uuid}/members#

Remove users from a user group.

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/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/v1/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 /v1/admin/user-groups/{group_uuid}/workspaces#

List workspace assignments for a user group.

200

items#

*array<GroupWorkspaceAssignmentOut>

Workspace assignments on this page.

page#

*integer

Page number returned.

page_size#

*integer

Maximum number of results per page.

total#

*integer

Total number of Workspace assignments that match the request.

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/admin/user-groups/{group_uuid}/workspaces \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

curl https://api.mistral.ai/v1/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": "Product Team",
      "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": "Product Team",
      "workspace_uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
    }
  ],
  "page": "1",
  "page_size": "1000",
  "total": 56
}

Assign Group To Workspace

POST /v1/admin/user-groups/{group_uuid}/workspaces#

Assign a user group to a workspace.

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/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/v1/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 /v1/admin/user-groups/{group_uuid}/workspaces/{workspace_uuid}#

Remove a user group from a workspace.

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/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/v1/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 /v1/admin/user-groups/{group_uuid}/workspaces/{workspace_uuid}#

Update the workspace role assignment for a user group.

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/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/v1/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 /v1/admin/user-groups/{group_uuid}/organization-role#

Update the organization role for a user group.

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/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/v1/admin/user-groups/{group_uuid}/organization-role \
 -X PATCH \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json' \
 -d '{
  "organization_role": "A"
}'

Beta Admin User Groups Endpoints

Examples

GET /v1/admin/user-groups#

Security#

AdminApiKey#

Parameters#

page#

page_size#

search#

items#

page#

page_size#

total#

Playground

POST /v1/admin/user-groups#

Security#

AdminApiKey#

Request Body#

description#

name#

target_type#

description#

externally_managed#

name#

organization_role#

target_type#

uuid#

Playground

POST /v1/admin/user-groups/provision-workspace#

Security#

AdminApiKey#

Request Body#

user_group_uuid#

workspace_role#

workspace_role_name#

workspace_uuid#

Playground

GET /v1/admin/user-groups/{group_uuid}#

Security#

AdminApiKey#

Parameters#

group_uuid#

description#

externally_managed#

name#

organization_role#

target_type#

uuid#

Playground

DELETE /v1/admin/user-groups/{group_uuid}#

Security#

AdminApiKey#

Parameters#

group_uuid#

Playground

PATCH /v1/admin/user-groups/{group_uuid}#

Security#

AdminApiKey#

Parameters#

group_uuid#

Request Body#

description#

name#

target_type#

description#

externally_managed#

name#

organization_role#

target_type#

uuid#

Playground

GET /v1/admin/user-groups/{group_uuid}/members#

Security#

AdminApiKey#

Parameters#

group_uuid#

page#

page_size#

members#

page#