---
title: "Delete a role, with a JSON body"
method: POST
path: "/role/{id}/delete"
tags: ["Roles"]
---

# Delete a role, with a JSON body

`POST /role/{id}/delete`

## Request

- Base URL: `https://api.elaichi.ai`
- URL: `https://api.elaichi.ai/role/{id}/delete`
- Auth: HTTP bearer

Deletes a role, taking a JSON body. The same operation as `DELETE /role/{id}` — same authorization, same guards, same atomic transaction — with a JSON body instead of a query parameter, so a caller can also move SPECIFIC holders onto a role of their own choosing before the rest fall back to `reassign_to`. `reassignments` is capped at 200 entries; past it the call answers `400` naming the ceiling. Each entry's `role_id` is checked against the same grant ceiling as `reassign_to` (never the role being deleted), and each `user_id` must currently hold the role — one that no longer does answers `409` (`role_holder_changed`), so the caller can refresh and retry. `reassign_to` becomes optional once every holder is covered by `reassignments` AND no pending invite is for the role (invites are never individually overridden, and always fall back to `reassign_to`); short of that it is still required, exactly as on the plain DELETE form. The response adds `reassigned_by_role`: one row per DISTINCT target role actually used, bounded by how many roles the caller named.

## Path parameters

- `id` string, required

## Headers

- `X-Organization-Id` string

## Request body

- object
  - `reassign_to` string: Same as `DELETE /role/{id}`'s `reassign_to` query parameter — the default target.
  - `reassignments` object[]: Per-member overrides. Bounded, and never a substitute for `reassign_to` on invites.
    - `user_id` string, required: User id (`usr_…`) of a current holder of `id`.
    - `role_id` string, required: Role id (`role_…`) to move that one member onto.

## Response `200`

OK

- object
  - `success` boolean, required
  - `reassigned_member_count` integer, required
  - `reassigned_invite_count` integer, required
  - `reassigned_by_role` object[], required: One row per distinct target role that received at least one member.
    - `role_id` string
    - `role_name` string
    - `count` integer

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `429`: Rate limited

---

[API](https://skmtc.dev/elaichi/apis/elaichi-api.md) · [All operations](https://skmtc.dev/elaichi/apis/elaichi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/elaichi/apis/elaichi-api/revisions/b22cfb7b6d15?raw)