---
title: "Create a custom role."
method: POST
path: "/api/v1/teams/roles"
tags: ["Team Roles"]
---

# Create a custom role.

`POST /api/v1/teams/roles`

## Request

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

Creates a new custom role for the team with the specified permissions. Role names cannot match reserved role names (Owner, Administrator, Member).

## 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 `201`

Team role created 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/post.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)