# delete_workspace_role

Source: https://modulify.ai/docs/api/workspaces/delete-workspace-role

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

- Title: Delete a role
- Scope: `workspaces:write`
- Access: Destructive
- Endpoint: `POST /v1/delete_workspace_role`

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](https://modulify.ai/docs/reference/members-and-roles#delete-a-custom-role).

## 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.

> **Warning**
>
> This method is marked destructive: it deletes or overwrites data. Check the inputs before you call it, and send an [Idempotency-Key](https://modulify.ai/docs/api/idempotency) header whenever you might retry it.

```bash
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](https://modulify.ai/docs/mcp/workspaces/delete-workspace-role).

## 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](https://modulify.ai/docs/api/requests-and-responses#the-response) 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](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) 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](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.