---
title: "Create role"
method: POST
path: "/role"
tags: ["Roles"]
---

# Create role

`POST /role`

## Request

- Base URL: `https://api.elaichi.ai`
- URL: `https://api.elaichi.ai/role`
- Auth: HTTP bearer

Authoring custom roles requires the `role:manage` permission and the `custom_roles` plan feature; the predefined system roles stay readable and assignable on every plan. You may only grant permissions you hold yourself — otherwise an admin could mint a role carrying `billing:manage` and assign it to themselves. Validate names against `GET /permission`.

## Headers

- `X-Organization-Id` string

## Request body

- object
  - `name` string, required
  - `description` string, nullable
  - `permissions` string[], required: Permission names from `GET /permission`. The complete set for this role.

## Response `201`

Created

- Role
  - `id` string: Role id (`role_…`).
  - `name` string
  - `description` string, nullable
  - `is_system` boolean: Predefined roles ship with every organization and cannot be edited away.
  - `seat_class` 'billable' | 'free_admin': Whether members holding only this role count toward billable seats.
  - `permissions` string[]: Every permission the role holds, including any `GET /permission` does not list for this organization (for example the Apps permissions while Apps are unavailable). `PATCH /role/{id}` replaces this list wholesale, so send back the entries you did not mean to remove.
  - `permission_count` integer: How many of `permissions` `GET /permission` lists for this organization: the number to show beside the role. Can be lower than `permissions.length`.
  - `member_count` integer: How many members hold this role right now. `GET /member?role_id={id}` lists them; while it is above zero, `DELETE /role/{id}` needs `reassign_to` (or, on `POST /role/{id}/delete`, `reassign_to` and/or a `reassignments` entry for every holder).
  - `pending_invite_count` integer: Pending invites issued for this role. Present only on roles you can manage. While above zero, `DELETE /role/{id}` and `POST /role/{id}/delete` need `reassign_to`, which re-points them.
  - `group_mapping_count` integer: SCIM group mappings that assign this role. Present only on roles you can manage. While above zero, `DELETE /role/{id}` is refused (`409 role_mapped`) until the mappings change.
  - `can_reassign_holders` boolean: Whether you may move this role's holders and pending invites to another role (`DELETE /role/{id}?reassign_to=` or `POST /role/{id}/delete`): you hold `member:manage` and do not hold this role yourself.
  - `created_at` string, date-time
  - `updated_at` string, date-time

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