---
title: "Create or replace role"
method: PUT
path: "/v1/role"
tags: ["Roles"]
---

# Create or replace role

`PUT /v1/role`

Create or replace role. If there is an existing role with the same name as the one specified in the request, will replace the existing role with the provided fields

## Request body

- CreateRole
  - `name` string, required — Name of the role
  - `description` string, nullable — Textual description of the role
  - `member_permissions` object[], nullable — (permission, restrict_object_type) tuples which belong to this role
    - `permission` 'create' | 'read' | 'update' | 'delete' | 'create_acls' | 'read_acls' | 'update_acls' | 'delete_acls', required — Each permission permits a certain type of operation on an object in the system Permissions can be assigned to to objects on an individual basis, or grouped into roles
    - `restrict_object_type` 'organization' | 'project' | 'experiment' | 'dataset' | 'prompt' | 'prompt_session' | 'group' | 'role' | 'org_member' | 'project_log' | 'org_project', nullable — The object type that the ACL applies to
  - `member_roles` string[], nullable — Ids of the roles this role inherits from An inheriting role has all the permissions contained in its member roles, as well as all of their inherited permissions
  - `org_name` string, nullable — For nearly all users, this parameter should be unnecessary. But in the rare case that your API key belongs to multiple organizations, you may specify the name of the organization the role belongs in.

## Response `200`

Returns the new role object

- Role — A role is a collection of permissions which can be granted as part of an ACL Roles can consist of individual permissions, as well as a set of roles they inherit from
  - `id` string, uuid, required — Unique identifier for the role
  - `org_id` string, uuid, nullable — Unique id for the organization that the role belongs under A null org_id indicates a system role, which may be assigned to anybody and inherited by any other role, but cannot be edited. It is forbidden to change the org after creating a role
  - `user_id` string, uuid, nullable — Identifies the user who created the role
  - `created` string, date-time, nullable — Date of role creation
  - `name` string, required — Name of the role
  - `description` string, nullable — Textual description of the role
  - `deleted_at` string, date-time, nullable — Date of role deletion, or null if the role is still active
  - `member_permissions` object[], nullable — (permission, restrict_object_type) tuples which belong to this role
    - `permission` 'create' | 'read' | 'update' | 'delete' | 'create_acls' | 'read_acls' | 'update_acls' | 'delete_acls', required — Each permission permits a certain type of operation on an object in the system Permissions can be assigned to to objects on an individual basis, or grouped into roles
    - `restrict_object_type` 'organization' | 'project' | 'experiment' | 'dataset' | 'prompt' | 'prompt_session' | 'group' | 'role' | 'org_member' | 'project_log' | 'org_project', nullable — The object type that the ACL applies to
  - `member_roles` string[], nullable — Ids of the roles this role inherits from An inheriting role has all the permissions contained in its member roles, as well as all of their inherited permissions

## Other responses

- `400` — The request was unacceptable, often due to missing a required parameter
- `401` — No valid API key provided
- `403` — The API key doesn’t have permissions to perform the request
- `429` — Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
- `500` — Something went wrong on Braintrust's end. (These are rare.)

---

[API](https://skmtc.net/braintrustdata/apis/braintrust-api.md) · [All operations](https://skmtc.net/braintrustdata/apis/braintrust-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/braintrustdata/braintrust-api/revisions/9d216c8243fe/schema)