Manage Workspaces with the Admin API

Manage Workspaces and their members programmatically.

Information

Enterprise plans only

The Admin API is available only on Enterprise plans, and access isn't self-serve. On other plans, you can't create an Admin API key, and a standard API key doesn't work with admin endpoints. To request access, contact your Mistral account team or our sales team.

Before you start

All requests use the base URL https://api.mistral.ai/v1/admin and an Admin API key in the x-api-key header. See Authentication and Admin API keys.

Workspace roles

Assign Workspace roles with the plural role_names field. List every role and its UUID with GET /v1/admin/roles. See Manage groups and roles for the full role catalog.

Note

The singular role and role_name fields are deprecated. Prefer the plural roles / role_names.

List Workspaces

Supports the is_archived, page, page_size, and search query parameters.

curl "https://api.mistral.ai/v1/admin/workspaces?page=1&page_size=50" \
  -H "x-api-key: $ADMIN_API_KEY"

curl "https://api.mistral.ai/v1/admin/workspaces?page=1&page_size=50" \
  -H "x-api-key: $ADMIN_API_KEY"

Create a Workspace

name and admin_user_id are required. Optional: description, icon, and add_all_org_members.

curl -X POST https://api.mistral.ai/v1/admin/workspaces \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ADMIN_API_KEY" \
  -d '{
    "name": "MySpace",
    "description": "Small Workspace",
    "icon": "",
    "add_all_org_members": false,
    "admin_user_id": "<USER_UUID>"
  }'

curl -X POST https://api.mistral.ai/v1/admin/workspaces \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ADMIN_API_KEY" \
  -d '{
    "name": "MySpace",
    "description": "Small Workspace",
    "icon": "",
    "add_all_org_members": false,
    "admin_user_id": "<USER_UUID>"
  }'

The response includes the Workspace uuid.

Update a Workspace

curl -X PATCH https://api.mistral.ai/v1/admin/workspaces/<WORKSPACE_UUID> \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ADMIN_API_KEY" \
  -d '{"name": "Renamed Workspace", "description": "Updated description"}'

curl -X PATCH https://api.mistral.ai/v1/admin/workspaces/<WORKSPACE_UUID> \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ADMIN_API_KEY" \
  -d '{"name": "Renamed Workspace", "description": "Updated description"}'

Delete a Workspace

curl -X DELETE https://api.mistral.ai/v1/admin/workspaces/<WORKSPACE_UUID> \
  -H "x-api-key: $ADMIN_API_KEY"

curl -X DELETE https://api.mistral.ai/v1/admin/workspaces/<WORKSPACE_UUID> \
  -H "x-api-key: $ADMIN_API_KEY"

Manage members

Add or update members with a members array. Each entry takes a user_uuid and role_names.

# Add members
curl -X POST https://api.mistral.ai/v1/admin/workspaces/<WORKSPACE_UUID>/add-users \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ADMIN_API_KEY" \
  -d '{"members": [{"user_uuid": "<USER_UUID>", "role_names": ["user"]}]}'

# Add or update members (idempotent)
curl -X PATCH https://api.mistral.ai/v1/admin/workspaces/<WORKSPACE_UUID>/users \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ADMIN_API_KEY" \
  -d '{"members": [{"user_uuid": "<USER_UUID>", "role_names": ["workspace_admin"]}]}'

# Add members
curl -X POST https://api.mistral.ai/v1/admin/workspaces/<WORKSPACE_UUID>/add-users \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ADMIN_API_KEY" \
  -d '{"members": [{"user_uuid": "<USER_UUID>", "role_names": ["user"]}]}'

# Add or update members (idempotent)
curl -X PATCH https://api.mistral.ai/v1/admin/workspaces/<WORKSPACE_UUID>/users \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ADMIN_API_KEY" \
  -d '{"members": [{"user_uuid": "<USER_UUID>", "role_names": ["workspace_admin"]}]}'

Remove members

This removes the listed users from the Workspace and deletes their permissions in it.

curl -X DELETE https://api.mistral.ai/v1/admin/workspaces/<WORKSPACE_UUID>/remove-users \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ADMIN_API_KEY" \
  -d '{"members": [{"user_uuid": "<USER_UUID_1>"}, {"user_uuid": "<USER_UUID_2>"}]}'

curl -X DELETE https://api.mistral.ai/v1/admin/workspaces/<WORKSPACE_UUID>/remove-users \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ADMIN_API_KEY" \
  -d '{"members": [{"user_uuid": "<USER_UUID_1>"}, {"user_uuid": "<USER_UUID_2>"}]}'