---
title: "Delete Role"
api: "DELETE /v1/api/roles-and-permissions/roles/{roleId}"
description: "Delete a custom role from your workspace."
lastUpdated: "2026-11-04"
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://trillet-ai.jamdesk.app/llms.txt). Append `.md` to any page URL for its markdown version.

Requires the `role:delete` permission in the workspace. Deleting a role also removes it from every user who held it.

System roles (`owner`, `admin`, `editor`, `viewer`) and roles from other workspaces can't be deleted; they return `404 Role not found`.

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="roleId" type="string" required>
The unique identifier of the role to delete.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the deletion was successful.
</ResponseField>

<ResponseField name="deletedRole" type="object">
The role that was deleted.
</ResponseField>

<ResponseExample>
```json
{
  "success": true,
  "deletedRole": {
    "_id": "a4a4a4a4a4a4a4a4a4a4a4a4",
    "workspaceId": "a1a1a1a1a1a1a1a1a1a1a1a1",
    "name": "Manager",
    "description": "Full access to agents and call history",
    "permissions": {
      "agent": ["agent:view", "agent:create", "agent:edit"],
      "call_history": ["call_history:view"]
    },
    "isSystem": false,
    "createdAt": "2024-06-01T09:00:00.000Z",
    "updatedAt": "2024-06-01T09:00:00.000Z",
    "__v": 0
  }
}
```
</ResponseExample>


---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://trillet-ai.jamdesk.app/api-specs.zip
