Sign in
Roles

Update a role

Update a custom role by its ID. At least one field must be provided. Predefined roles cannot be updated.

Payload Requirements

  • At least one of name, description, or permissions must be provided.
  • When permissions is provided, the existing permissions are fully replaced with the new set.
  • name, if provided, must be unique within the account.
  • System-managed fields (id, created_at, updated_at, is_predefined) cannot be modified.

Valid example

{
  "name": "Senior Data Scientist",
  "permissions": ["PROJECT_READ", "DATASET_READ", "DATASET_CREATE", "DATASET_DELETE"]
}

Invalid example (no fields provided)

{}

<Note>This endpoint is in beta, read more here.</Note>

patch/v2/roles/{role_id}

Path parameters

role_idstring required

A universally unique identifier (base64-encoded opaque string).

Example:RW50aXR5OjEyMzQ1

The unique role identifier (base64)

Request body

namestring

Updated name for the role. Must be unique within the account.

descriptionstring nullable

Updated description of the role. Set to null to clear it.

permissionsPermission[]

Replacement set of permissions. When provided, the existing permissions are fully replaced. Each value must be a valid permission identifier.

Response

A role object.

idstring required

Unique identifier for the role.

namestring required

Human-readable name of the role.

descriptionstring

A brief description of the role's purpose.

permissionsPermission[] required

List of permissions granted by this role. Each value corresponds to a permission identifier (e.g. PROJECT_READ, DATASET_CREATE). Returned only to callers with ROLE_READ.

is_predefinedboolean required

Whether this role is a system-defined predefined role. Predefined roles cannot be updated or deleted.

created_atstring date-time required

Timestamp when the role was created.

updated_atstring date-time required

Timestamp when the role was last updated.

Changes

Changed in 2 of the 16 revisions of this API.88

  • c26a00e9b31844See the full diff
    • ●

      added the new AGENT_ROLE_CREATE enum value to the permissions/items/ response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new AGENT_ROLE_DELETE enum value to the permissions/items/ response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new AGENT_ROLE_READ enum value to the permissions/items/ response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new AGENT_ROLE_UPDATE enum value to the permissions/items/ response property for the response status 200

      response-property-enum-value-added

    • ○

      added the new AGENT_ROLE_CREATE enum value to the request property permissions/items/

      request-property-enum-value-added

    • ○

      added the new AGENT_ROLE_DELETE enum value to the request property permissions/items/

      request-property-enum-value-added

    • ○

      added the new AGENT_ROLE_READ enum value to the request property permissions/items/

      request-property-enum-value-added

    • ○

      added the new AGENT_ROLE_UPDATE enum value to the request property permissions/items/

      request-property-enum-value-added

  • ddf93df2c29544See the full diff
    • ●

      added the new ROLE_CREATE enum value to the permissions/items/ response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new ROLE_DELETE enum value to the permissions/items/ response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new ROLE_READ enum value to the permissions/items/ response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new ROLE_UPDATE enum value to the permissions/items/ response property for the response status 200

      response-property-enum-value-added

    • ○

      added the new ROLE_CREATE enum value to the request property permissions/items/

      request-property-enum-value-added

    • ○

      added the new ROLE_DELETE enum value to the request property permissions/items/

      request-property-enum-value-added

    • ○

      added the new ROLE_READ enum value to the request property permissions/items/

      request-property-enum-value-added

    • ○

      added the new ROLE_UPDATE enum value to the request property permissions/items/

      request-property-enum-value-added

Of the 16 revisions, 1 has no diff computed.