---
title: "Delete a custom role"
method: POST
path: "/teams/{team_id}/delete_custom_role"
tags: ["Custom Roles"]
---

# Delete a custom role

`POST /teams/{team_id}/delete_custom_role`

Deletes a custom role from the team. Fails with `CustomRoleInUse` if
the role is still attached to any team members; reassign those members
(e.g. via `update_team_member_role`) before retrying.

## Path parameters

- `team_id` integer, required

## Request body

- DeleteCustomRoleArgs
  - `id` integer, required

## Response `200`

## Changes

- **2026-08-25** `d6dde3ef057c` — 1 info
  - the endpoint scheme security `OAuth Team Token` was removed from the API

[Change history](https://skmtc.dev/convex/apis/convex-management-api/changes/teams/:team_id/delete_custom_role/post.md)

---

[API](https://skmtc.dev/convex/apis/convex-management-api.md) · [All operations](https://skmtc.dev/convex/apis/convex-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/convex/convex-management-api/revisions/8107cc743e0b/schema)