---
title: "List roles."
method: GET
path: "/api/v1/teams/roles"
tags: ["Team Roles"]
---

# List roles.

`GET /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/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns all roles that can be assigned to members within this team. Includes both global assignable system roles (Administrator, Member, Chat-only) and the team's own custom roles. Super Admin and Owner are excluded as they are not assignable.

## Response `200`

List of roles for the team

- 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

- `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/get.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)