---
title: "Update a custom role."
method: PUT
path: "/api/v1/teams/roles/{roleId}"
tags: ["Team Roles"]
---

# Update a custom role.

`PUT /api/v1/teams/roles/{roleId}`

## Request

- Base URL: `https://app.customgpt.ai`
- URL: `https://app.customgpt.ai/api/v1/teams/roles/{roleId}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/poll-the-people/apis/customgpt-ai/docs/api/v1/teams/roles/:roleId/put.ts> (a function with typed inputs; its response is checked against the schema)

Updates an existing custom role's name, description, and permissions. Only roles belonging to this team can be updated.

## Path parameters

- `roleId` integer, required

## Request body

- object
  - `name` string: Role name. Cannot match a reserved system role name. Max 255 characters.
  - `description` string: Description of the role. Max 255 characters.
  - `type` 'local' | 'global': Role scope. Use local to restrict access to specific agents; use global to grant access to all team agents.
  - `is_chat_only` boolean: When true, members with this role can only use chat. The permissions field is ignored and set automatically.
  - `permissions` string[]: Permission names to grant to this role. Ignored when is_chat_only is true. Omit or pass an empty array for no permissions.
  - `agents` integer[]: Agent IDs this role grants access to. Required when type is local.
  - `allow_create_agents` boolean: Whether members with this role can create new agents.

## Response `200`

Team role retrieved successfully

- object
  - `status` 'error' | 'success': The status of the response
  - `data` TeamRole
    - `id` integer: Role ID
    - `name` string: Role name
    - `description` string: Role description
    - `type` 'local' | 'global': Role scope: local limits access to specific agents; global grants access to all team agents
    - `is_chat_only` boolean: If true, members can only use chat
    - `has_access_to_projects` boolean: Whether this role grants access to projects
    - `allow_create_agents` boolean: Whether this role can create new agents
    - `agents` integer[]: Agent IDs this role grants access to (only applies to local roles)
    - `permissions` string[]: Permission names granted by this role
    - `created_at` string, date-time: When was this role created?
    - `updated_at` string, date-time: When was this role updated?

## Other responses

- `400`: Bad Argument
- `401`: API Token is either missing or invalid
- `500`: Internal Server Error

## Changes

- **2026-11-03** `77aab4354382`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/poll-the-people/apis/customgpt-ai/changes/api/v1/teams/roles/:roleId/put.md)

---

[API](https://skmtc.dev/poll-the-people/apis/customgpt-ai.md) - [All operations](https://skmtc.dev/poll-the-people/apis/customgpt-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/poll-the-people/apis/customgpt-ai/revisions/77aab4354382?raw)