Delete a role

delete_workspace_role

Deletes a custom role from a workspace and moves everyone holding it back to the stock Member role.

POST /v1/delete_workspace_roleScopeworkspaces:writeDestructive

The role is gone for good, and the access of everyone who held it changes the moment this runs. Recreating the role does not undo that. The tool tells the client to read get_role_member_counts first and tell you how many people it affects before calling it.

It needs the Manage roles permission (roles.manage) and the workspace on Pro or Enterprise, otherwise it is refused with You must upgrade to the Pro plan to manage roles! The built-in owner and member roles cannot be deleted. See Members and roles.

Request

Call it with a POST to https://api.modulify.ai/v1/delete_workspace_role, sending the inputs below as a JSON object. The token needs the workspaces:write scope.

This method is marked destructive: it deletes or overwrites data. Check the inputs before you call it, and send an Idempotency-Key header whenever you might retry it.

curl -X POST https://api.modulify.ai/v1/delete_workspace_role \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"WORKSPACE_ID","roleId":"ROLE_ID"}'

Over MCP, the same method is the delete_workspace_role tool.

Inputs

Input	Type	Required	Description
`workspaceId`	string	Yes	The workspace id.
`roleId`	string	Yes	The role id.

Response

Every call answers with the JSON envelope of success, message, data, code and version. data holds the result described above, and on a method that returns a total, count carries it. The response headers carry the call's X-Request-Id and what is left of your per-minute budget in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Errors explains every status code a call can answer with.